feat: design-system component library + view rewrite

CLAUDE.md

@@ -12,7 +12,7 @@ Flutter starter kit for the Magic Framework. Pre-built Auth, Profile, Teams & No
 
 | Command | Description |
 |---------|-------------|
-| `flutter test --coverage` | Run all tests (~52 files, ~752 cases) with coverage |
+| `flutter test --coverage` | Run all tests (~62 files, ~996 cases) with coverage |
 | `flutter test test/http/controllers/` | Run controller tests only |
 | `flutter test --name "pattern"` | Run tests matching pattern |
 | `flutter analyze --no-fatal-infos` | Static analysis (flutter_lints ^6.0) |

README.md

@@ -52,7 +52,7 @@ Stop rebuilding authentication, profile management, and team features from scrat
 | :bell: | **Notifications** | Real-time polling, mark read/unread, preference matrix |
 | :iphone: | **OTP Login** | Phone-based guest authentication with send/verify flow |
 | :art: | **Wind UI** | Tailwind-like className system — no Material widgets, dark mode built-in |
-| :package: | **Reusable Widgets** | PageHeader, Card (3 variants), ConfirmDialog (3 variants), PasswordConfirmDialog, TwoFactorModal — all standalone |
+| :package: | **Design-System Components** | 29 atomic components (MSButton, MSInput, MSBadge, MSDialog, MSToast, MSTabs, MSAccordion, and more) plus `MagicStarterTokens` semantic alias layer |
 | :gear: | **13 Feature Toggles** | All opt-in, configure only what you need |
 | :jigsaw: | **View Registry** | Override any screen or layout from the host app |
 | :hammer_and_wrench: | **CLI Tools** | install, configure, doctor, publish, uninstall |
@@ -191,9 +191,84 @@ MagicStarter.useSidebarFooter((context) {
 
 ---
 
+## Design-System Components
+
+Magic Starter ships a full atomic design-system component library exported from `package:magic_starter/magic_starter.dart`. Every component lives in a canonical 4-file atomic folder (`<name>.dart`, `<name>.recipe.dart`, `<name>.preview.dart`, `index.dart`) under `lib/src/ui/components/` and is driven by a `WindRecipe` that reads from `MagicStarterTokens.defaultAliases`.
+
+### MagicStarterTokens
+
+`MagicStarterTokens.defaultAliases` is a map of 17 semantic roles to light+dark Wind className pairs:
+
+| Role | Example className pair |
+|------|----------------------|
+| `surface` | `bg-white dark:bg-gray-950` |
+| `fg` | `text-gray-900 dark:text-gray-50` |
+| `primary` | `bg-primary-600 dark:bg-primary-500` |
+| `destructive` | `bg-red-600 dark:bg-red-500` |
+| `border` | `border-gray-200 dark:border-gray-800` |
+
+Pass the map when configuring your Wind theme so all components resolve against semantic roles rather than raw palette utilities:
+
+```dart
+WindApp(
+  theme: WindThemeData(
+    aliases: MagicStarterTokens.defaultAliases,
+  ),
+  child: const MyApp(),
+)
+```
+
+> **`MS` prefix (breaking)**: every design-system component now carries an `MS` prefix (`MSButton`, `MSDialog`, `MSSwitch`, ...). This removes the Material collision entirely, so importing both `package:flutter/material.dart` and `package:magic_starter/magic_starter.dart` no longer needs a `hide` clause. See the [migration table](#migration-ms-prefix) below to update from the pre-`MS` names.
+
+### Component families
+
+| Family | Components |
+|--------|-----------|
+| Form controls | `MSButton`, `MSInput`, `MSTextarea`, `MSCheckbox`, `MSSwitch`, `MSRadio`, `MSSelect`, `MSCombobox` |
+| Display | `MSBadge`, `MSTypography`, `MSSkeleton`, `MSToast`, `MSTooltip`, `MSEmptyState`, `MSErrorState` |
+| Selection / navigation | `MSSegmentedControl`, `MSTabs`, `MSAccordion`, `MSNavbar`, `MSDropdownMenu` |
+| Overlay | `MSDialog`, `MSBottomSheet` |
+| Composition | `MSFormField`, `MSCard`, `MSPageHeader`, `MSSocialDivider` |
+| App chrome | `MSNotificationDropdown`, `MSUserProfileDropdown`, `MSTeamSelector` |
+
+All components accept Wind `className` strings and resolve colors through the semantic alias layer when configured. `MSButton`, `MSInput`, and `MSTextarea` also accept a `bool fullWidth = false` prop; setting it to `true` fills the parent width (wraps the rendered widget in a `SizedBox(width: double.infinity)` rather than a `className` token, since Material widgets ignore cross-axis stretch — see [flutter/flutter#19399](https://github.com/flutter/flutter/issues/19399)).
+
+<a name="migration-ms-prefix"></a>
+### Migration: the `MS` prefix
+
+Earlier previews exported these components under bare names. They now carry an
+`MS` prefix (and the old names are gone, no compat shim). Replace each old name
+with its `MS` counterpart and drop any `hide` clause you added for the Material
+collision:
+
+| Old | New | Old | New |
+|-----|-----|-----|-----|
+| `Button` | `MSButton` | `DropdownMenu` | `MSDropdownMenu` |
+| `Input` | `MSInput` | `DropdownMenuItem` | `MSDropdownMenuItem` |
+| `Textarea` | `MSTextarea` | `MagicFormField` | `MSFormField` |
+| `Checkbox` | `MSCheckbox` | `Navbar` | `MSNavbar` |
+| `Switch` | `MSSwitch` | `EmptyState` | `MSEmptyState` |
+| `Radio` | `MSRadio` | `ErrorState` | `MSErrorState` |
+| `Badge` | `MSBadge` | `SettingsSection` | `MSSettingsSection` |
+| `Typography` | `MSTypography` | `SettingsRow` | `MSSettingsRow` |
+| `Skeleton` | `MSSkeleton` | `SettingsNavRow` | `MSSettingsNavRow` |
+| `Select` | `MSSelect` | `SettingsScaffold` | `MSSettingsScaffold` |
+| `Combobox` | `MSCombobox` | `Card` | `MSCard` |
+| `SegmentedControl` | `MSSegmentedControl` | `PageHeader` | `MSPageHeader` |
+| `Tabs` | `MSTabs` | `SocialDivider` | `MSSocialDivider` |
+| `Accordion` | `MSAccordion` | `NotificationDropdown` | `MSNotificationDropdown` |
+| `AccordionItem` | `MSAccordionItem` | `UserProfileDropdown` | `MSUserProfileDropdown` |
+| `Dialog` | `MSDialog` | `TeamSelector` | `MSTeamSelector` |
+| `BottomSheet` | `MSBottomSheet` | `ConfirmDialog` | `MSConfirmDialog` |
+| `Toast` | `MSToast` | `Tooltip` | `MSTooltip` |
+
+The `MagicStarter*` public widgets (`MagicStarterCard`, `MagicStarterPageHeader`, ...), the per-axis enums (`ButtonIntent`, `InputState`, ...), and the recipe functions are unchanged.
+
+---
+
 ## Reusable Widgets
 
-Magic Starter exports a set of standalone UI widgets that consumer apps can use directly — no internal controller coupling required.
+Magic Starter also exports a set of standalone UI widgets that consumer apps can use directly. No internal controller coupling required.
 
 ### MagicStarterPageHeader
 
@@ -379,6 +454,21 @@ MagicStarter.useTheme(
 
 `MagicStarterTheme` has 7 sub-themes: `form`, `card`, `navigation`, `modal`, `layout`, `pageHeader`, `auth`. All fields are optional.
 
+#### One-call adoption from a `WindThemeData`
+
+If your app already defines a Wind semantic palette (the 17 alias roles, e.g. via `MagicStarterTokens.defaultAliases` or a `design:sync`-generated map), skip building sub-theme structs entirely and adopt the whole palette in one call:
+
+```dart
+MagicStarter.useWindTheme(
+  WindThemeData(
+    colors: {'primary': myBrandColor},
+    aliases: MagicStarterTokens.defaultAliases, // or a design:sync map
+  ),
+);
+```
+
+`useWindTheme()` derives all 7 sub-themes from the theme's semantic roles (`bg-surface`, `text-fg`, `bg-primary`, `border-color-border`, `bg-destructive`, ...) and delegates to `useTheme()`. Each alias carries its own `dark:` pair, so one token re-skins both light and dark. It is additive: `useTheme()` and any `use*Theme()` setter still override afterward. A role you do not define keeps the shipped default (never an invisible surface). See [doc/guides/wind-theme-adoption.md](doc/guides/wind-theme-adoption.md) for the full alias-to-property mapping.
+
 ### Level 3: Builder Slots
 
 Override specific sections of a screen without replacing the full view. Use `MagicStarter.view.slot()` to register a partial builder for a named slot:

assets/stubs/design.md.stub

@@ -0,0 +1,176 @@
+---
+name: {{ app_name }}
+description: >
+  Design system for {{ app_name }}. Single-brand, Wind semantic tokens,
+  M3-role palette. Generate the Wind theme with:
+    dart run {{ app_package }}:artisan design:sync
+colors:
+  surface:
+    light: "#FFFFFF"
+    dark: "#030712"
+  surface-container:
+    light: "#F9FAFB"
+    dark: "#111827"
+  surface-container-high:
+    light: "#F3F4F6"
+    dark: "#1F2937"
+  fg:
+    light: "#111827"
+    dark: "#F9FAFB"
+  fg-muted:
+    light: "#6B7280"
+    dark: "#9CA3AF"
+  fg-disabled:
+    light: "#D1D5DB"
+    dark: "#4B5563"
+  primary:
+    light: "#{{ primary_hex_light }}"
+    dark: "#{{ primary_hex_dark }}"
+  on-primary:
+    light: "#FFFFFF"
+    dark: "#FFFFFF"
+  primary-container:
+    light: "#{{ primary_container_light }}"
+    dark: "#{{ primary_container_dark }}"
+  accent:
+    light: "#{{ accent_hex_light }}"
+    dark: "#{{ accent_hex_dark }}"
+  border:
+    light: "#E5E7EB"
+    dark: "#374151"
+  border-subtle:
+    light: "#F3F4F6"
+    dark: "#1F2937"
+  destructive:
+    light: "#DC2626"
+    dark: "#EF4444"
+  on-destructive:
+    light: "#FFFFFF"
+    dark: "#FFFFFF"
+  destructive-container:
+    light: "#FEE2E2"
+    dark: "#7F1D1D"
+  success:
+    light: "#15803D"
+    dark: "#16A34A"
+  warning:
+    light: "#D97706"
+    dark: "#B45309"
+typography:
+  display:
+    fontFamily: {{ font_family }}
+    fontSize: 36px
+    fontWeight: "700"
+    lineHeight: 44px
+    letterSpacing: -0.02em
+  headline-lg:
+    fontFamily: {{ font_family }}
+    fontSize: 28px
+    fontWeight: "700"
+    lineHeight: 36px
+    letterSpacing: -0.01em
+  headline-md:
+    fontFamily: {{ font_family }}
+    fontSize: 22px
+    fontWeight: "600"
+    lineHeight: 30px
+  title-lg:
+    fontFamily: {{ font_family }}
+    fontSize: 18px
+    fontWeight: "600"
+    lineHeight: 26px
+  body-lg:
+    fontFamily: {{ font_family }}
+    fontSize: 16px
+    fontWeight: "400"
+    lineHeight: 26px
+  body-md:
+    fontFamily: {{ font_family }}
+    fontSize: 14px
+    fontWeight: "400"
+    lineHeight: 22px
+  label-md:
+    fontFamily: {{ font_family }}
+    fontSize: 14px
+    fontWeight: "600"
+    lineHeight: 20px
+    letterSpacing: 0.01em
+  label-sm:
+    fontFamily: {{ font_family }}
+    fontSize: 12px
+    fontWeight: "500"
+    lineHeight: 16px
+rounded:
+  sm: 4px
+  DEFAULT: 8px
+  md: 12px
+  lg: 16px
+  xl: 24px
+  full: 9999px
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 16px
+  lg: 24px
+  xl: 40px
+  gutter: 16px
+  section: 32px
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.on-primary}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.md}"
+  button-destructive:
+    backgroundColor: "{colors.destructive}"
+    textColor: "{colors.on-destructive}"
+    rounded: "{rounded.md}"
+    padding: "{spacing.md}"
+  card-surface:
+    backgroundColor: "{colors.surface-container}"
+    rounded: "{rounded.lg}"
+    padding: "{spacing.lg}"
+  input-field:
+    backgroundColor: "{colors.surface-container-high}"
+    rounded: "{rounded.DEFAULT}"
+    padding: "{spacing.md}"
+---
+
+## Overview
+
+[Describe the brand personality, product purpose, and style direction for
+{{ app_name }}. What does this design system represent?]
+
+For responsive and accessible usage patterns, see
+[docs/design-culture/](docs/design-culture/).
+
+## Colors
+
+[Explain the palette rationale: why these colors, what roles they serve, how
+light and dark modes differ. Reference WCAG contrast requirements for
+on-X / X pairs.]
+
+## Typography
+
+[Describe the chosen font and why it fits the brand. List the scale levels and
+their intended usage contexts (display, body, label).]
+
+## Layout
+
+[Describe the responsive grid: breakpoints, column model, gutter and section
+spacing. Reference the wind-responsive doc for breakpoint-specific guidance.]
+
+## Elevation & Depth
+
+[Describe the elevation model: tonal backgrounds, shadows (if any), and how
+depth signals hierarchy to the user.]
+
+## Shapes
+
+[Map corner-radius values to use cases: inputs, buttons, cards, dialogs,
+badges.]
+
+## Components
+
+[List the key components and their token bindings. Variant matrices are visible
+at `/preview` in debug builds. Run `design:lint` to validate token usage.]

assets/stubs/install/en.stub

@@ -63,6 +63,8 @@
     "cancel": "Cancel",
     "confirm": "Confirm",
     "go_to_dashboard": "Go to Dashboard",
+    "off": "Off",
+    "on": "On",
     "remove": "Remove",
     "save": "Save",
     "toggle_theme": "Toggle theme",
@@ -106,8 +108,12 @@
       "description": "Create a permanent account to keep your data and unlock all features.",
       "title": "Upgrade Your Guest Account"
     },
+    "nav": {
+      "settings": "Settings"
+    },
     "notifications": {
-      "fetch_error": "Failed to load notification preferences."
+      "fetch_error": "Failed to load notification preferences.",
+      "preferences_title": "Notification Preferences"
     },
     "newsletter": {
       "fetch_error": "Failed to load newsletter preferences.",
@@ -133,6 +139,20 @@
       "verify_button": "Verify Code",
       "verify_error": "Failed to verify code. Please try again."
     },
+    "appearance": {
+      "dark": "Dark",
+      "dark_description": "Always use the dark theme.",
+      "light": "Light",
+      "light_description": "Always use the light theme.",
+      "section_footer": "Choosing System follows your device display settings.",
+      "subtitle": "Choose your preferred color scheme.",
+      "system": "System",
+      "system_description": "Follow the system display setting.",
+      "title": "Appearance"
+    },
+    "language": {
+      "subtitle": "Choose the language used throughout the app."
+    },
     "profile": {
       "delete_account": {
         "button": "Delete Account",
@@ -142,6 +162,14 @@
         "password_label": "Confirm your password",
         "title": "Delete Account"
       }
+    },
+    "settings": {
+      "account_section": "Account",
+      "preferences_section": "Preferences",
+      "security_section": "Security"
+    },
+    "timezone": {
+      "subtitle": "Set the timezone used for displaying dates and times."
     }
   },
   "nav": {