qt-material3-widget

Material 3 widget toolkit for Qt Widgets.

This documentation is split into two complementary parts:

• narrative guides for users and contributors

• generated C++ API reference for the public headers

Use the narrative pages to understand concepts, layering, and supported workflows. Use the API reference when you need exact class and member names.

Start here

For application developers

• Public API guide

• C++ API reference

• Material 3 upstream references

• Migration from Qt Material Widgets

For contributors

• Architecture overview

• Development rules

• Accessibility and keyboard rules

• Release process

Installation and downstream usage

The project exports a CMake package named QtMaterial3Widgets.

find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Core Gui Widgets)
find_package(Qt${QT_VERSION_MAJOR} REQUIRED COMPONENTS Core Gui Widgets)
find_package(QtMaterial3Widgets REQUIRED)

add_executable(my-app main.cpp)
target_link_libraries(my-app
  PRIVATE
    Qt${QT_VERSION_MAJOR}::Core
    Qt${QT_VERSION_MAJOR}::Gui
    Qt${QT_VERSION_MAJOR}::Widgets
    QtMaterial3::Theme
    QtMaterial3::Widgets
)

Documentation structure

User guide

• Public API guide
  • Main API areas
  • Include style
  • Pages
• C++ API reference
  • Theme API
  • Core widget API
  • Buttons API
  • Guidance for maintainers
• Material 3 references
  • Start here
  • Theme and design tokens
  • Components
  • How to use these references in this repository
  • Documentation policy suggestion
• Migration from qt-material-widgets

Architecture

• Architecture overview
  • Core architecture
  • Theme-to-widget flow
• Theme layer
• Core layer
• Spec layer
• Effects layer
• Widgets layer
• Advanced components
  • Current architecture notes
  • Planned advanced component areas

Development

• Coding rules
• Accessibility and Keyboard Rules
  • Core rules
  • Family rules
• Advanced component rules
• Rendering Rules
  • 1. Core Principle
  • 2. Use Qt Primitives for Behavior
  • 3. Never Reimplement Text Editing
  • 4. Paint Only from Resolved Specs
  • 5. No Magic Visual Constants in Paint Code
  • 6. Keep Paint Functions Dumb
  • 7. Cache Geometry That Depends on Size
  • 8. Cache Text Layout Inputs
  • 9. Effects Must Be Reusable Infrastructure
  • 10. Repaint the Smallest Reasonable Region
  • 11. Shadow Rendering Must Be Cached
  • 12. Separate Visual Rect from Touch Target
  • 13. Disabled State Must Be Spec-Driven
  • 14. Focus Rendering Must Be Keyboard-Correct
  • 15. Animation State Must Be Outside Paint
  • 16. Compose Before Rebuilding Complex Behavior
  • 17. Public Headers Must Not Leak Rendering Internals
  • 18. Share Paint Helpers Across Families
  • 19. Render Tests Are Part of the Rendering Contract
  • 20. Optimize After Correctness, But Optimize on Purpose
  • Widget-Specific Rules
  • Forbidden Patterns
  • Project Mantra
• Testing rules
• Build Reconciliation Checklist
  • 1. Configure pass
  • 2. Library compile pass
  • 3. Public header audit
  • 4. Dependency audit
  • 5. Examples pass
  • 6. Test pass
  • 7. Install/export pass
  • 8. Warnings pass
  • 9. First release-quality checkpoint
• Compile-Fix Reconciliation Pass
  • Goals
  • Changes in this pass
  • Remaining likely friction points
  • Recommended next local sequence
• Release process

Material 3 note

This project follows Material 3 guidance, but the upstream Material 3 site remains the source for design-system semantics and visual rationale. The pages in this repository describe how those ideas are mapped into the Qt Widgets implementation.