bjornmelin/dmc-best-practices

DMC Best Practices

Definitive best practices for building Dash applications with Dash Mantine Components. Rules are organized by impact level and category.

Priority Categories

| Priority | Category | Impact | Prefix | Rules | |----------|----------|--------|--------|-------| | 1 | Architecture | CRITICAL | arch- | 4 | | 2 | Callbacks | CRITICAL/HIGH | callback- | 6 | | 3 | Styling | HIGH/MEDIUM | style- | 5 | | 4 | Data Management | HIGH | data- | 4 | | 5 | Performance | MEDIUM-HIGH | perf- | 3 | | 6 | Forms & Validation | MEDIUM | form- | 2 | | 7 | Theming | MEDIUM | theme- | 3 | | 8 | DMC v2.x Migrations | MEDIUM | v2- | 2 | | 9 | Accessibility | MEDIUM | a11y- | 1 |

Top 10 Critical Rules

1. Wrap layout in MantineProvider - All DMC components require it
2. Never modify global variables in callbacks - Breaks multi-worker deployments
3. Use State not Input for values that shouldn't trigger callbacks
4. Define callbacks before app.run() - Registration must happen first
5. Prevent circular callbacks - Outputs feeding inputs cause infinite loops
6. Return JSON-serializable values - Only dict, list, str, number, bool, None
7. Use static CSS selectors - Never target .m_* dynamic classes
8. Custom colors need 10 shades - Exactly 10 (0=lightest, 9=darkest)
9. Use dcc.Store for client data - Not global variables
10. Debounce text inputs - Limit callback firing on rapid changes

Rules Index

Architecture (CRITICAL)

• arch-mantine-provider - Wrap Layout in MantineProvider
• arch-callback-order - Define Callbacks Before app.run()
• arch-circular-callbacks - Prevent Circular Callbacks
• arch-global-variables - Never Modify Global Variables

Callbacks (CRITICAL/HIGH)

• callback-input-vs-state - Use State for Non-Triggering Values
• callback-json-serializable - Return JSON-Serializable Values
• callback-prevent-update - PreventUpdate vs no_update
• callback-debounce - Debounce Text Inputs
• callback-context - Use ctx.triggered_id Correctly
• callback-prevent-initial - Use prevent_initial_call Appropriately

Styling (HIGH/MEDIUM)

• style-static-selectors - Use Static Selectors Only
• style-props-limit - Limit Style Props to 3-4 Per Component
• style-responsive-css - Use CSS Media Queries for Responsive
• style-css-variables - Prefer CSS Variables Over Hardcoded
• style-classnames-over-styles - Use classNames Over styles Prop

Data Management (HIGH)

• data-dcc-store - Use dcc.Store for Client-Side Data
• data-server-caching - Use Server-Side Caching for Large Data
• data-session-isolation - Isolate Cache by Session ID
• data-signaling-pattern - Use Signaling Pattern for Expensive Ops

Performance (MEDIUM-HIGH)

• perf-clientside-callbacks - Use Clientside Callbacks for Frequent Updates
• perf-memoization - Memoize Expensive Functions
• perf-webgl-charts - Use WebGL for Large Scatter Plots

Forms & Validation (MEDIUM)

• form-validation-pattern - Validate Early, Fail Fast
• form-error-handling - Return User-Friendly Error Messages

Theming (MEDIUM)

• theme-custom-colors - Custom Colors Need 10 Shades
• theme-light-dark-mode - Test Both Light and Dark Modes
• theme-component-defaults - Set Component Defaults in Theme

DMC v2.x Migrations (MEDIUM)

• v2-breaking-changes - DMC v2.x Breaking Changes
• v2-notification-container - Use NotificationContainer Not Provider

Accessibility (MEDIUM)

• a11y-labels-required - Always Provide Labels for Inputs

Full Reference

See AGENTS.md for the complete compiled reference with all rules expanded.

UI Audit Contract

When DMC review output needs machine-readable evidence, shape findings as ui_audit.v1:

• target.framework: dmc
• id: dmc.<rule-id> such as dmc.arch-mantine-provider
• category: map DMC rule families deterministically: architecture -> layout, callbacks -> state, styling -> layout, data -> state, performance -> performance, forms -> interaction, theming -> visual, migration -> migration, and accessibility -> accessibility
• severity: CRITICAL and HIGH rules become error; MEDIUM-HIGH and MEDIUM rules become warning; lower-risk notes become info
• locations: repo-relative files or components when known
• docs: the relevant rule markdown path plus external component docs when the rule cites them

Use observations for inventory facts such as detected DMC version, theme configuration, or callback counts that do not by themselves require a fix.