Design-System Components

Introduction#

Magic Starter ships an atomic design-system component library under lib/src/ui/components/. Each component is driven by a recipe that resolves colours 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.

The components are exported from package:magic_starter/magic_starter.dart. The families below cover the form, display, navigation, overlay and layout components; the barrel also exports MSAvatar, MSConfirmDialog, the settings rows (MSSettingsSection, MSSettingsRow, MSSettingsNavRow), MSUpdateBanner, MSUpgradeDialog, MSUpgradeNudge and MSUsageMeter.

Semantic Token Layer#

MagicStarterTokens#

MagicStarterTokens is a final class with a const map, defaultAliases, and two helpers. defaultAliases maps semantic class names to light and dark Wind className pairs. Each key is the full class it replaces (bg-surface, text-fg, border-color-border), not a bare role name, because Wind expands an alias only when a whole token matches a key:

final aliases = MagicStarterTokens.defaultAliases;
// {
//   'bg-surface':               'bg-white dark:bg-gray-950',
//   'text-fg':                  'text-gray-900 dark:text-gray-50',
//   'bg-primary':               'bg-primary-600 dark:bg-primary-500',
//   'border-color-border':      'border-gray-200 dark:border-gray-700',
//   'bg-destructive':           'bg-red-600 dark:bg-red-500',
//   ...
// }

Wiring into WindThemeData#

Pass MagicStarterTokens.defaultAliases as the aliases argument of the WindThemeData you give MagicApplication, and hand the same theme to MagicStarter.useWindTheme so the navigation, modal, form, card, page header, layout, auth and dropdown themes are derived from it:

final windTheme = WindThemeData(
  colors: {'primary': myBrandColor},
  aliases: MagicStarterTokens.defaultAliases,
);

MagicApplication(
  title: 'Acme',
  windTheme: windTheme,
);

// In AppServiceProvider.boot():
MagicStarter.useWindTheme(windTheme);

Components that reference a semantic class (bg-surface, text-fg, bg-primary) resolve through this map at render time. Without the aliases wired in, those class names are silently skipped by Wind, so your brand colour and surface tokens do not apply. useWindTheme keeps the button and field themes you set, on either side of it; useTheme resets them, so call MagicStarter.useButtonTheme and useFieldTheme after that.

Token Reference#

text-destructive, text-primary, text-on-success and text-on-warning are not alias keys: MagicStarterTokens.role answers them with a fallback pair when the host theme does not define them. 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,
    'bg-primary': 'bg-indigo-600 dark:bg-indigo-500',
    'text-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   # Recipe: 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 holds the recipe: a top-level WindRecipe or slot recipe (badgeRecipe, textareaRecipe), or a function that builds a recipe or a slot-to-className map from a theme or state (buildButtonRecipe, buildInputRecipe, buildCardRecipe, selectRecipe). 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 class carries an MS prefix (MSButton, MSDialog, MSSwitch, ...), so the barrel's component exports do not collide with package:material_ui/material_ui.dart (Switch, Dialog, ...). 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.

design.md.stub#

assets/stubs/design.md.stub is a DESIGN.md template covering the colour roles, typography, rounded and spacing scales, and key component entries, with {{ placeholder }} tokens for the app name, brand colours and font family.

Copy it from the package source into your project root as DESIGN.md (a hosted dependency sits in the pub cache; .dart_tool/package_config.json lists its rootUri), fill in the brand hex values and fonts, then run the core 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 writes a Dart file (lib/config/wind_theme.g.dart by default, --output changes it) with an alias map for WindThemeData(aliases: ...) and a brand primary colour ramp. Pass that map where this page passes MagicStarterTokens.defaultAliases. See Magic CLI for the command reference.

Component Previews#

package:magic_starter/previews.dart is a dev-only library, kept out of the runtime barrel. starterComponentPreviews() returns one StarterComponentPreview record per component: a label, a URL-safe slug (the component folder name) and a WidgetBuilder that renders the component's variants. Feed it to your own preview catalog behind a release guard, so a release build that never reaches the call tree-shakes every preview:

import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:magic_starter/previews.dart';

List<StarterComponentPreview> catalogPreviews() {
  if (kReleaseMode) return const <StarterComponentPreview>[];

  return starterComponentPreviews();
}

Widget buildPreview(BuildContext context, String slug) {
  final StarterComponentPreview preview = catalogPreviews().firstWhere(
    (StarterComponentPreview entry) => entry.slug == slug,
  );

  return preview.builder(context);
}

buildPreview here throws a StateError when slug matches no entry. In a release build catalogPreviews() is empty, so every call throws; the release guard (a route, a menu entry or a flag that a release build never reaches) is what keeps release builds away from this call.

Gotchas#

Related Documentation#

• Views and Layouts: the screens these components compose into.
• Manager: the sub-themes (useTheme, useButtonTheme, useFieldTheme) and the page container.
• Wind Theme Adoption: moving a host's palette onto the semantic aliases.
• Notifications: the bell dropdown that lives in magic_notifications.