Design-System Components

Introduction#

Magic Starter ships a complete atomic design-system component library under lib/src/ui/components/. Every component is driven by a WindRecipe that resolves colors through the MagicStarterTokens semantic alias layer, so a single brand configuration flows into all built-in screens and every component your host app composes directly.

All 46 components are exported from package:magic_starter/magic_starter.dart.

Semantic Token Layer#

MagicStarterTokens#

MagicStarterTokens is a single const class with one public member: defaultAliases. It is a Map<String, String> of 17 semantic roles to light+dark Wind className pairs following the bg-/text-/border-color- prefix convention:

final aliases = MagicStarterTokens.defaultAliases;
// {
//   'surface':                  'bg-white dark:bg-gray-950',
//   'surface-container':        'bg-gray-50 dark:bg-gray-900',
//   'surface-container-high':   'bg-gray-100 dark:bg-gray-800',
//   'fg':                       'text-gray-900 dark:text-gray-50',
//   'fg-muted':                 'text-gray-500 dark:text-gray-400',
//   'fg-disabled':              'text-gray-300 dark:text-gray-600',
//   'primary':                  'bg-primary-600 dark:bg-primary-500',
//   'on-primary':               'text-white dark:text-white',
//   'primary-container':        'bg-primary-50 dark:bg-primary-950',
//   'accent':                   'bg-accent-600 dark:bg-accent-500',
//   'border':                   'border-gray-200 dark:border-gray-800',
//   'border-subtle':            'border-gray-100 dark:border-gray-900',
//   'destructive':              'bg-red-600 dark:bg-red-500',
//   'on-destructive':           'text-white dark:text-white',
//   'destructive-container':    'bg-red-50 dark:bg-red-950',
//   'success':                  'bg-green-600 dark:bg-green-500',
//   'warning':                  'bg-amber-500 dark:bg-amber-400',
// }

Wiring into WindThemeData#

Pass MagicStarterTokens.defaultAliases as the aliases argument when constructing your WindThemeData:

WindApp(
  theme: WindThemeData(
    aliases: MagicStarterTokens.defaultAliases,
  ),
  child: const MyApp(),
)

Components that reference a semantic role (e.g. bg-surface, text-fg, bg-primary) will resolve through this map at render time. Without the aliases wired in, the semantic class names are silently skipped by Wind, so your brand color and surface tokens will not apply.

Token Reference#

These keys are written as the full class they replace (bg-ai-soft, border-ai), not as a bare role. The support screens use the AI pair and border-ai for the assistant's avatar, its bubble (a 2px left edge) and its chip, and the soft warning and success pairs for the "Team answering" and "Resolved" pills. A host theme that defines the same keys supplies its own map and wins.

To override individual roles, spread defaultAliases and replace specific keys:

WindThemeData(
  aliases: {
    ...MagicStarterTokens.defaultAliases,
    'primary': 'bg-indigo-600 dark:bg-indigo-500',
    'on-primary': 'text-white dark:text-white',
  },
)

Atomic Folder Shape#

Every component lives in a 4-file atomic folder:

lib/src/ui/components/<name>/
  <name>.dart          # The widget class (StatelessWidget or StatefulWidget)
  <name>.recipe.dart   # WindRecipe function: resolves className from theme tokens
  <name>.preview.dart  # Standalone preview widget for interactive inspection
  index.dart           # Barrel: re-exports the public API for this component

The .recipe.dart file contains a top-level function (e.g. buildButtonRecipe, buildInputRecipe, cardRecipe) that accepts variant/state arguments and returns a Wind className string. The widget delegates its className derivation to the recipe so the visual contract is inspectable and testable in isolation.

Component Families#

Form Controls#

Display and Feedback#

Selection and Navigation#

Overlay#

Composition and App Chrome#

Import Collisions#

Every component carries an MS prefix (MSButton, MSDialog, MSSwitch, ...), so none of the barrel's component exports collide with package:material_ui/material_ui.dart. You can import both without a hide clause:

import 'package:material_ui/material_ui.dart';
import 'package:magic_starter/magic_starter.dart';

// No ambiguity: MSSwitch is the component, Switch is Material's.

Earlier releases exported unprefixed names (Switch, Dialog, ...) and required a hide clause. See the migration table in the package README to update from the pre-MS names.

Or hide the specific colliding names:

import 'package:material_ui/material_ui.dart' hide MSSwitch, MSDialog, MSCheckbox;
import 'package:magic_starter/magic_starter.dart';

Widget tests that need both Material and magic_starter types must do the same.

design.md.stub#

assets/stubs/design.md.stub is a DESIGN.md template that covers all 17 semantic roles, typography on the 4px logical scale, rounded/spacing scales, and key component entries with {{ placeholder }} tokens.

Consumers copy it into their project root:

cp $(flutter pub cache list magic_starter)/assets/stubs/design.md.stub DESIGN.md

Then fill in brand hex values and fonts, and run the CLI commands:

# Validate your DESIGN.md against the schema
dart run magic:dowel design:lint

# Generate the Wind theme from your DESIGN.md
dart run magic:dowel design:sync

design:sync regenerates the WindThemeData(aliases: ...) map, replacing MagicStarterTokens.defaultAliases with your brand-specific values so every component reflects your brand automatically.