Skip to main content

Naming prefixes

The variant pattern

Components encode variants as a private enum + named constructors, never a public variant parameter:
Benefits: invalid parameter combinations are unrepresentable (each constructor only exposes what its variant supports — e.g. elevation exists only on the elevated StyledCard), and call sites read naturally. StyledListTile takes it further: variant-only, no default constructor.

Token discipline

  1. Never hardcode colors or text styles — everything comes from context.colorTheme / context.textTheme.
  2. Semantic over primitive — colors.surfaceBg, not SundialRef.sandLight[1]. Direct primitive use is reserved for deliberate cases (wallpaper palettes, the solid-wallpaper dark-text rule).
  3. Accent for persona branding — persona-responsive UI reads colors.accent.*; never a specific palette’s colors.
  4. Test both brightness modes — tokens make it work; you still verify contrast.

Component reuse

Before building a custom widget:
And check how existing call sites use a component: grep -r "StyledTextField" lib/.

State management in components

Design-system components are StatelessWidget wherever possible. Only StyledTabBar uses hooks (HookWidget) — and only to bridge a TabController. No Riverpod inside lib/design_system/ — providers belong to app-level widgets.

Accessibility

  • Composite tappables get SemanticButton — one semantics node, button: true.
  • Icons are decorative by default (semanticLabel: null on AshIcon); label at the button layer.
  • Nav taps give haptic feedback (HapticFeedback.selectionClick() in NavDestination).

Wallpaper legibility

Solid wallpaper → dark sand-12 ink (contentOnBrand), no scrim. Textured wallpaper → ThemeOverride(brightness: dark) + gradient scrim. Canonical implementation: StyledListTile.

Modern Flutter idioms

The codebase tracks recent Flutter/Dart features — patterns you’ll see inside components:
  • Column(spacing: 8) / Row(spacing: 12) instead of SizedBox separators
  • switch expressions for variant dispatch
  • Null-aware collection elements (?child inside children lists)
  • Dot-shorthands for enum/static access (e.g. mainAxisSize: .min)
  • Color.withValues(alpha: …) instead of deprecated withOpacity
Match these idioms when contributing — and check pubspec.yaml’s Flutter constraint before assuming an API’s availability.