Flutter Duskmoon Design

Flutter DuskMoon UI — Design Principles & Usage Rules

Architecture Overview

Package Dependency Graph (import direction →)

duskmoon-dev/design (YAML → codegen)
  → duskmoon_theme
      ├ DmDesignTokens (generated const data)
      ├ DmTheme (InheritedWidget)
      ├ DmPlatformStyle { material, cupertino, fluent }
      └ toMaterial() / toCupertino() / toFluent()

duskmoon_theme
  → duskmoon_widgets
      ├ DuskmoonApp (root shell)
      ├ DmAdaptiveWidget (base class)
      └ Dm* widgets (Button, TextField, Switch, etc.)

duskmoon_widgets
  → duskmoon_settings
  → duskmoon_feedback
  → duskmoon_ui (umbrella re-export)

Rule: Never import downstream. duskmoon_theme must never import from duskmoon_widgets. duskmoon_widgets must never import from duskmoon_settings.

Widget Tree (Runtime)

DuskmoonApp(tokens: .sunshine, darkTokens: .moonlight, platformStyle: .cupertino)
  └→ DmTheme (InheritedWidget — .of(context) available everywhere below)
       └→ CupertinoApp(theme: tokens.toCupertino())
            └→ user's widget tree
                 └→ DmButton(label: "Save")  // dispatches to CupertinoButton

Rule 1: Theme Setup

Correct App Root

// ✅ ALWAYS — use DuskmoonApp as the root widget
void main() {
  runApp(
    DuskmoonApp(
      tokens: DmDesignTokens.sunshine,
      darkTokens: DmDesignTokens.moonlight,
      themeMode: ThemeMode.system,
      platformStyle: DmPlatformStyle.material,
      home: const MyHomePage(),
    ),
  );
}

❌ NEVER — bypass DuskmoonApp

// ❌ NEVER wrap MaterialApp/CupertinoApp directly
void main() {
  runApp(MaterialApp(
    theme: DmDesignTokens.sunshine.toMaterial(), // wrong — skips DmTheme
    home: MyHomePage(),
  ));
}

Why: DuskmoonApp injects DmTheme above the platform app. Without it, DmTheme.of(context) returns null and all Dm* widgets fail to resolve tokens.

Rule 2: Accessing Design Tokens

Always use DmTheme.of(context)

// ✅ Read tokens from the widget tree
Widget build(BuildContext context) {
  final tokens = DmTheme.of(context).tokens;
  return Container(
    color: tokens.primaryContainer,
    child: Text('Hello', style: TextStyle(color: tokens.onPrimaryContainer)),
  );
}

❌ NEVER reference generated constants directly in widget builds

// ❌ This ignores dark mode, theme overrides, and subtree overrides
Widget build(BuildContext context) {
  return Container(color: DmDesignTokens.sunshine.primaryContainer);
}

Why: The resolved tokens depend on ThemeMode, platform brightness, and possible DmThemeOverride ancestors. Only DmTheme.of(context) returns the correct resolved set.

Exception — static adapter methods

DuskmoonApp itself must convert tokens to platform ThemeData before DmTheme exists in the tree. For this case only, use the static adapters:

// Inside DuskmoonApp.build() — acceptable
MaterialApp(theme: DmTheme.staticToMaterial(resolvedTokens));

Rule 3: Color System

Token Structure (61 color tokens per theme)

Color Format: OKLCH

All colors are defined in OKLCH in the source CSS. The Dart codegen converts to Color objects via inline OKLCH→sRGB math (zero external deps).

❌ NEVER hardcode color values

// ❌ Hardcoded hex
Container(color: Color(0xFF60A5FA))

// ❌ Hardcoded Material color
Container(color: Colors.blue)

// ✅ Use design tokens
Container(color: DmTheme.of(context).tokens.primary)

Semantic color pairing rule

Every background token has a corresponding foreground token. Always pair them:

// ✅ Correct pairing
Container(
  color: tokens.primaryContainer,
  child: Text('Label', style: TextStyle(color: tokens.onPrimaryContainer)),
)

// ❌ Mismatched — onSurface on primaryContainer may fail contrast
Container(
  color: tokens.primaryContainer,
  child: Text('Label', style: TextStyle(color: tokens.onSurface)),
)

Surface elevation hierarchy

Use surface container tokens for visual depth, not opacity or shadows alone:

surfaceContainerLowest  →  bottom layer (behind everything)
surfaceContainerLow     →  low-elevation cards
surfaceContainer        →  standard cards/containers
surfaceContainerHigh    →  elevated cards, menus
surfaceContainerHighest →  dialogs, tooltips, top layer

Rule 4: Available Themes

5 themes defined in duskmoon-dev/design, codegen'd to Dart:

Access via DmDesignTokens.sunshine, DmDesignTokens.moonlight, etc.

Rule 5: Platform Adaptive Widgets

Resolution Stack (highest priority first)

L1: Per-widget `platformOverride` parameter
L2: Nearest DmPlatformOverride ancestor (subtree override)
L3: DmTheme.of(context).platformStyle (from DuskmoonApp)
L4: defaultTargetPlatform (auto-detect)

Writing an adaptive widget

All adaptive widgets extend DmAdaptiveWidget:

class DmButton extends DmAdaptiveWidget {
  const DmButton({super.key, required this.label, super.platformOverride});
  final String label;

  @override
  Widget buildMaterial(BuildContext context, DmDesignTokens tokens) {
    return FilledButton(onPressed: () {}, child: Text(label));
  }

  @override
  Widget buildCupertino(BuildContext context, DmDesignTokens tokens) {
    return CupertinoButton.filled(onPressed: () {}, child: Text(label));
  }

  // buildFluent defaults to buildMaterial unless overridden
}

❌ NEVER check platform manually

// ❌ Manual platform switching
if (Platform.isIOS) {
  return CupertinoButton(...);
} else {
  return ElevatedButton(...);
}

// ✅ Use DmAdaptiveWidget dispatch or DmPlatformStyle resolution
class MyWidget extends DmAdaptiveWidget { ... }

File structure for adaptive widgets

dm_button/
├── dm_button.dart            # Public API, extends DmAdaptiveWidget
├── dm_button_material.dart   # buildMaterial implementation
├── dm_button_cupertino.dart  # buildCupertino implementation
└── dm_button_fluent.dart     # buildFluent (optional, falls through to material)

Rule 6: Shared Design Enums

All Dm* widgets share these semantic enums. Use them consistently — never invent ad-hoc parameters.

enum DmColorRole { primary, secondary, tertiary, error, neutral }
enum DmSize { xs, sm, md, lg, xl }
enum DmButtonVariant { filled, outlined, ghost, tonal }
enum DmInputVariant { outlined, filled, underlined }

Color resolution from DmColorRole

Every widget that takes DmColorRole resolves tokens identically:

Size scale

Rule 7: Component Design — Actions

DmButton

Default: variant: filled, color: primary, size: md

Color role assignment convention:

// ✅ Typical action group
Row(children: [
  DmButton(variant: .ghost, color: .neutral, child: Text('Cancel')),
  DmButton(variant: .outlined, color: .secondary, child: Text('Save Draft')),
  DmButton(variant: .filled, color: .primary, child: Text('Publish')),
])

DmIconButton

Same color/size system as DmButton. Must always have semanticLabel.

DmIconButton(
  icon: Icons.delete,
  color: DmColorRole.error,
  semanticLabel: 'Delete item',
  onPressed: () {},
)

DmFab (Floating Action Button)

• Default color: primary — the single most important action on the screen
• Surface: primaryContainer background, onPrimaryContainer icon
• Rule: Maximum one FAB per screen. If you need multiple actions, use DmActionList.

DmFab(
  onPressed: () {},
  icon: Icons.add,
  // FAB always uses primaryContainer/onPrimaryContainer — no color param
)

DmActionList

Adapts rendering to available space:

DmActionList(
  actions: [
    DmAction(icon: Icons.edit, label: 'Edit', onPressed: ...),
    DmAction(icon: Icons.share, label: 'Share', onPressed: ...),
    DmAction(icon: Icons.delete, label: 'Delete', color: DmColorRole.error, onPressed: ...),
  ],
)

Rule 8: Component Design — Navigation

DmAppBar

Default token mapping:

Scrolled/elevated state: Background transitions to primaryContainer, text to onPrimaryContainer.

DmAppBar(
  title: Text('Settings'),
  leading: DmIconButton(icon: Icons.arrow_back, semanticLabel: 'Back'),
  actions: [
    DmIconButton(icon: Icons.search, semanticLabel: 'Search'),
    DmIconButton(icon: Icons.more_vert, semanticLabel: 'More options'),
  ],
)

Neutral variant: For screens where the app bar should not compete with content (e.g., content-heavy reading views), pass color: DmColorRole.neutral to fall back to surface/onSurface.

DmBottomNav

Rule: 3–5 destinations maximum. Labels always visible (not icon-only).

DmTabBar

DmDrawer

Side menus and drawers use the secondary color family to visually distinguish navigation chrome from the primary-branded top bar.

DmBreadcrumbs

Rule 9: Component Design — Layout & Cards

DmCard

Elevation hierarchy via surface tokens:

Interior layout convention:

┌─────────────────────────────────┐
│ [optional media/image]          │
├─────────────────────────────────┤
│ Title         (onSurface)       │
│ Subtitle      (onSurfaceVariant)│
│                                 │
│ Body text     (onSurface)       │
│                                 │
│ ┌─────────────────────────────┐ │
│ │ Actions: ghost/outlined btns│ │
│ └─────────────────────────────┘ │
└─────────────────────────────────┘

DmCard(
  style: DmCardStyle.elevated,
  child: Column(children: [
    Image(...),
    Padding(
      padding: EdgeInsets.all(16),
      child: Column(children: [
        Text('Title', style: TextStyle(color: tokens.onSurface)),
        Text('Subtitle', style: TextStyle(color: tokens.onSurfaceVariant)),
        Row(children: [
          DmButton(variant: .ghost, child: Text('Cancel')),
          DmButton(variant: .filled, child: Text('Confirm')),
        ]),
      ]),
    ),
  ]),
)

❌ NEVER put a filled primary card background with onPrimary text for regular content cards. Primary/secondary/tertiary containers are for interactive highlights (selected state, feature callout), not default card backgrounds.

DmDivider

DmScaffold

Responsive layout dispatch:

Page body background: surface. Rail/side nav background: secondary.

Rule 10: Component Design — Data Display (Bricks)

DmBadge

Small status/count indicator. Takes DmColorRole.

Default: color: error (notification convention), size: sm

DmBadge(count: 3)                                  // red notification dot
DmBadge(label: 'New', color: .tertiary, variant: .tonal)  // soft accent tag
DmBadge(label: 'Draft', color: .neutral, variant: .tonal) // muted status

DmChip

Selectable/filterable labels. Takes DmColorRole.

Default selection color: secondary — secondary containers are for selection states.

DmAvatar

Sizes follow DmSize enum. Default: md (40dp diameter).

DmStat (Data Brick)

Statistics display block:

┌───────────────┐
│ 1,234         │  ← value: onSurface, large/bold
│ Active Users  │  ← label: onSurfaceVariant, small
│ ▲ 12.5%       │  ← trend: success or error token
└───────────────┘

DmTable / Data Grid

Rule 11: Component Design — Feedback

DmAlert

Convention: Alerts use semantic container tokens with full-width layout. For inline indicators, use DmBadge.

DmDialog

DmSnackbar

Uses inverse tokens for contrast against current theme:

DmProgress

Linear and circular variants. Default color: primary.

DmSkeleton

Loading placeholder. Uses surfaceContainerHigh with shimmer animation toward surfaceContainerLow.

Rule 12: Component Design — Inputs

DmTextField

Default variant: outlined

DmCheckbox / DmSwitch / DmSlider

Rule 13: Visual Design Principles

Hierarchy through token roles, not through ad-hoc colors

Primary   → THE action (one per screen section)
Secondary → supporting actions, selection states
Tertiary  → accents, highlights, special callouts
Surface   → everything else (backgrounds, text, structure)

If you need emphasis, promote the token role — don't invent a color.

Density and spacing

DuskMoon follows MD3 density: default padding 16dp, compact 12dp, comfortable 24dp. Widget padding follows the DmSize scale.

Elevation = surface tokens, not shadows

Use surfaceContainerLowest → surfaceContainerHighest for visual hierarchy. Shadows (shadow token) are supplementary, not the primary depth cue.

// ✅ Surface-token elevation
Container(color: tokens.surfaceContainerHigh)  // elevated
Container(color: tokens.surface)                // base level

// ❌ Shadow-only elevation
Container(
  decoration: BoxDecoration(
    color: tokens.surface,
    boxShadow: [BoxShadow(blurRadius: 8)],  // shadow without surface distinction
  ),
)

Dark mode is not "invert everything"

Each theme has its own curated token set. The codegen produces distinct values per theme. Never compute dark colors by inverting or dimming light colors at runtime.

// ❌ Never compute dark variants
final darkBg = Color.lerp(tokens.surface, Colors.black, 0.3);

// ✅ Use the dark theme's own tokens
DuskmoonApp(tokens: .sunshine, darkTokens: .moonlight)  // moonlight has its own curated values

Rule 14: Package Boundaries

(Architecture rules — same as above, renumbered for continuity)

What goes where

❌ NEVER add duskmoon_widgets as dependency of duskmoon_theme

This creates a circular dependency. If duskmoon_theme needs to reference a widget concept, use an abstract interface or callback, not a concrete widget import.

Rule 15: Code Engine Integration

duskmoon_code_engine has zero dependency on duskmoon_theme. The theme adapter lives as an extension method in duskmoon_theme:

// In duskmoon_theme — NOT in duskmoon_code_engine
extension DmCodeEngineTheme on DmDesignTokens {
  CodeEditorTheme toCodeEditorTheme() => CodeEditorTheme(
    background: surface,
    foreground: onSurface,
    // ...
  );
}

Rule 16: Codegen Pipeline

duskmoon-dev/design YAML
  → Bun/TypeScript emitter
    → CSS (duskmoonui consumption)
    → TypeScript (duskmoonui/duskmoon-elements)
    → Dart (flutter_duskmoon_ui — committed, CI never needs Bun)
    → JSON (documentation/tooling)

Generated Dart files are committed to git. CI must never require Bun or Node to build the Flutter packages.

❌ NEVER hand-edit generated files

Files in packages/duskmoon_theme/lib/src/generated/ are produced by codegen. Edit the YAML source in duskmoon-dev/design and re-run the pipeline.

Rule 17: Accessibility

• All color pairings must meet WCAG 2.1 AA contrast (4.5:1 normal text, 3:1 large text)
• Every interactive Dm* widget must support keyboard navigation
• Semantic labels required on all icon-only buttons
• Focus indicators must be visible on all themes

Rule 18: Testing Patterns

Widget tests must verify all three platforms

for (final style in DmPlatformStyle.values) {
  testWidgets('DmButton renders on $style', (tester) async {
    await tester.pumpWidget(
      DuskmoonApp(
        tokens: DmDesignTokens.sunshine,
        platformStyle: style,
        home: const DmButton(label: 'Test'),
      ),
    );
    expect(find.text('Test'), findsOneWidget);
  });
}

Theme tests must verify token resolution

testWidgets('DmTheme.of resolves correct tokens', (tester) async {
  late DmDesignTokens resolved;
  await tester.pumpWidget(
    DuskmoonApp(
      tokens: DmDesignTokens.sunshine,
      home: Builder(builder: (context) {
        resolved = DmTheme.of(context).tokens;
        return const SizedBox();
      }),
    ),
  );
  expect(resolved.primary, equals(DmDesignTokens.sunshine.primary));
});

Quick Reference: Anti-Patterns

Checklist for Code Review

When reviewing Flutter code that uses DuskMoon UI, verify:

Architecture:

• App root is DuskmoonApp, not MaterialApp/CupertinoApp directly
• Package imports flow downstream only (theme → widgets → settings)
• No generated files were hand-edited
• No duskmoon_theme dependency in duskmoon_code_engine
• Adaptive widgets extend DmAdaptiveWidget, not manual platform checks

Color & Tokens:

• All color values come from DmTheme.of(context).tokens, not hardcoded
• Background/foreground token pairs match (primary↔onPrimary, etc.)
• No Colors.* or Color(0x...) literals
• Dark mode uses separate theme tokens, no runtime color computation

Component Design:

• Buttons use DmColorRole convention (primary=main CTA, error=destructive, etc.)
• AppBar and BottomNav use primary/onPrimary defaults
• Drawer and side menu use secondary/onSecondary defaults
• Cards use surface container tokens, not primary/secondary containers for default bg
• Selection states use secondaryContainer tokens
• Surface elevation via container tokens, not shadow-only
• Maximum one FAB per screen section
• DmActionList for multiple actions, not ad-hoc button rows
• Snackbar uses inverse tokens
• Dialog scrim uses scrim token with alpha

Accessibility:

• Semantic labels on all icon-only buttons
• Focus indicators visible on all themes
• Widget tests cover all three DmPlatformStyle values
• WCAG AA contrast on all bg/fg pairings