Wind theme adoption (MagicStarter.useWindTheme)

The one-call adoption path#

import 'package:magic_starter/magic_starter.dart';

// In your service provider boot(), before any UI is painted:
MagicStarter.useWindTheme(
  WindThemeData(
    colors: {'primary': myBrandColor},
    aliases: MagicStarterTokens.defaultAliases, // or a design:sync-generated map
  ),
);

useWindTheme builds a MagicStarterTheme via MagicStarterTheme.fromWind(...) and delegates to the existing MagicStarter.useTheme(...) hook. It is purely additive:

• MagicStarter.useTheme(MagicStarterTheme) still works unchanged.
• Every individual use*Theme() setter (useCardTheme, useFormTheme, ...) still works and overrides the derived value afterward, so you can adopt the whole palette and then fine-tune one surface.

How derivation works#

Every color-bearing className fragment in the sub-theme defaults is rebuilt from the 17 semantic roles. Because each alias carries its own dark: counterpart (for example bg-surface expands to bg-white dark:bg-gray-950), a single semantic token replaces every hand-written bg-white dark:bg-gray-800 pair. No manual dark: palette utility is emitted.

A role is emitted as a semantic token only when the passed WindThemeData defines it, either as a key in its aliases map or as the backing color key in its colors map (bg-primary is backed by the primary color). When the theme does not define a role, the property keeps the shipped default palette pair for that role, so a partially-configured theme never produces a silent no-op (invisible) surface. Pair useWindTheme with a full alias map to re-skin every surface.

The 17 semantic roles#

The role tokens match the MagicStarterTokens.defaultAliases contract:

A host that defines text-destructive (as an alias, or through a destructive colour) re-skins the outlined danger buttons, the destructive MSSettingsRow title and the inline error text; without it they fall back to the red pair. MagicStarterTokens.role(theme, token) is the lookup they share.

MSToast is the one place that reads text-on-success and text-on-warning: its success and warning variants paint the message, the action label and the focus ring in them (the error variant reads text-on-destructive). The alias contract ships the fills and not these two roles, so a host that defines its own bg-success and bg-warning defines them beside the fills, and a host whose dark fills are light (a pale green on a dark surface) writes dark text for the dark half. A role the host does not define is not assumed to suit the stock fills: the toast resolves the fill it paints in the current mode and takes the better of white and near-black by WCAG contrast, so the stock green and amber get near-black and a mid-dark green gets white. A role the host defines is used as written, poor contrast included.

Alias-to-property mapping#

Each sub-theme property below is rebuilt from the listed semantic roles. Layout, spacing, radius, and dimension tokens are preserved as-is.

Navigation#

Modal#

Form#

Card#

Page header#

Layout#

Numeric dimensions (sidebarWidth, headerHeight) and the wColor() content/drawer background color-key fields keep their defaults; they are not expressed as semantic className tokens.

Dropdown#

The panels of MSTeamSelector and MSUserProfileDropdown. This is its own sub-theme, not more fields on navigation, because a host that sets useNavigationTheme() after useWindTheme() replaces the navigation theme whole and would hand any field it omitted back to the stock grey.

The tile takes bg-surface rather than bg-surface-container-high because the hovered row is already bg-surface-container-high; a tile with that fill would disappear into it. Geometry, including the overflow-hidden that keeps a hovered row inside the panel's rounded corners, stays in the widgets.

Keep a border in panelClassName, even an invisible one (border border-transparent), for the panel's shadow to survive: Wind clips a bordered box inside the border, while a borderless one gets a ClipRRect around the decorated container, which cuts the box shadow off.

Button#

Nothing is derived. MSButton's recipe already writes the semantic aliases (bg-primary, text-on-primary, border-color-border, ...) itself, so an alias map re-skins every button, and MagicStarterButtonTheme carries only what an alias cannot: the corner radius, the padding, minimum height and label type of each size, and the secondary border. useWindTheme() and useTheme() reset it to its defaults, so set it after them.

One 44 px capsule for every intent and size:

const standard = 'px-5 py-[11px] text-[17px] leading-[22px] font-semibold';

MagicStarter.useButtonTheme(
  MagicStarterButtonTheme(
    shapeClassName: 'rounded-full',
    smClassName: standard,
    mdClassName: standard,
    lgClassName: standard,
    secondaryBorderClassName: '',
  ),
);

Three things to know:

• Use vertical padding around a fixed line height, not min-h-11. A Wind button gives its box the minimum height and no alignment (items-center is ignored for a single child, and justify-center would stretch the button to fill its parent), so the label sits at the top of a min-h-11 box. py-[11px] around leading-[22px] is 44 px with the label centred, and still grows with the platform text size.
• Drop the secondary border in a fixed-height design. A border adds its width to the box, so a secondary that keeps it is 2 px taller than the rest. '' removes it; border-0 would leave a hairline. buttonDangerOutlineClassName only recolours that border.
• A className on a button wins, so two things never follow the theme. The className is appended after it. The auth screens pass the form theme's primaryButtonClassName to an lg button, and the social and step-up buttons its secondaryButtonClassName and the guest button the auth theme's guestButtonClassName to a secondary md one. Those strings, stock and as useWindTheme() derives them, carry no rounded-*, py-*, text-<size> or border token, only the full width, the colours, the label weight of the primary and the hover opacity of the secondary ones, so the auth screens follow the button theme. The first exception is a host's OWN strings: a useFormTheme() or useAuthTheme() call whose button strings name a shape, a padding or a label size keeps it, because the string wins. Leave those out, and change one string through copyWith rather than a new MagicStarterFormTheme, which would hand the other seven fields back to their defaults: MagicStarter.useFormTheme(MagicStarter.formTheme.copyWith(primaryButtonClassName: ...)). The second is the dialogs, and the invite button of the team settings page: they draw raw WButtons on the strings of MagicStarterModalTheme and do not read the button theme at all.

Below lg every MSButton sits in a 44 x 44 hit area. A size the theme makes 44 px tall or more is not widened by it, so there is no extra layout and no extra reach.

Field#

Nothing is derived either. The recipes of MSInput, MSSelect, MSCombobox and MSSegmentedControl write their colours, borders and radius as semantic aliases, and MagicStarterFieldTheme carries only the height and the type: one string per control, each the run of padding, minimum height and text size the recipe used to spell out. useWindTheme() and useTheme() reset it to its defaults, so set it after them.

One 44 px standard with 17 on 22 type for every control:

MagicStarter.useFieldTheme(
  MagicStarterFieldTheme(
    inputSizeClassName: 'py-[11px] text-[17px] leading-[22px]',
    selectSizeClassName: 'py-2.5 text-[17px] leading-[22px]',
    segmentedSmClassName: 'py-[7px] text-[17px] leading-[22px]',
    segmentedMdClassName: 'py-[7px] text-[17px] leading-[22px]',
    segmentedPaddingClassName: 'px-1 py-0 lg:py-1',
  ),
);

Four things to know:

• The string replaces the run, so state all of it. The default input string is py-3 lg:py-2.5 text-sm leading-5; a host string that names py-[11px] only would leave text-sm and leading-5 out of the box, not inherit them. The side padding (px-3), the colours and the border stay in the recipe.
• Each control needs its own padding for 44 px. A text input paints its border inside its padding, so it adds no height: py-[11px] around leading-[22px] is 44, and py-2.5 is 42. A select or combobox trigger is a Wind box whose border adds to its size, so py-2.5 around the same line plus the two border pixels is 44. Reach both with vertical padding around a fixed leading-*, which also centres the text, rather than with min-h-11 alone.
• The placeholder follows the input. It inherits the field's text size and line height, so inputSizeClassName sets the placeholder and the typed value together and there is no placeholder field.
• The segmented root needs segmentedPaddingClassName for 44 px at every width. Below lg each segment sits in a 44 px hit cell, so a control with the default p-1 root is 52 px tall on a phone whatever the pill size. A 36 px pill (py-[7px] around the line) in a root of px-1 py-0 lg:py-1 is 44 px everywhere: the hit cell supplies the 4 px above and below the pill on a phone, and the root does from lg up.

A className (or the classNames of a slot) handed to a control is appended after the theme and wins on any family it names. MSTextarea and the option rows of the select and combobox menus are outside the field theme.

The auth, profile and settings forms are outside it too. They draw WFormInputs on MagicStarterFormTheme.inputClassName, whose default carries py-3, and the starter's own WFormSelects read the same string for their trigger: the role select of the team settings page (magic_starter_team_settings_view.dart), the language select of the profile settings view (magic_starter_profile_settings_view.dart) and the language preference view (magic_starter_language_view.dart). A host sets that one string with MagicStarter.useFormTheme(MagicStarter.formTheme.copyWith(inputClassName: ...)), and one string has to serve an input and a select, which reach 44 px differently: an input paints its border inside its padding and a select trigger adds it. With 17 on 22 type:

The third is the one string that gives both 44 px: the select is 10 + 22 + 10 + 2 and the minimum height lifts the input from 42 to 44, where it centres its single line (the line box measures dead centre in the test font; a real font's glyphs can sit a pixel off the middle of a taller box). The heights are line boxes measured in a widget test (test/configuration/magic_starter_form_theme_input_test.dart), which pins all three rows of the table, and the 22 px line centred in the 44 px box at 390 and 1440 in light and dark. A bare min-h-11 does pin the label of a WButton to the top of its box, which is why buttons reach 44 px with padding around a fixed line height; a WInput and a WFormSelect trigger centre their one line, so for them the minimum height is safe. The two agree at the default text size only: once a larger text setting lifts the line past the minimum height, the select trigger is 2 px taller than the input, because its border adds to the padding where the input's sits inside it.

Auth#

Note: install the same WindThemeData as the ambient theme#

useWindTheme derives className strings that reference semantic alias tokens (bg-surface, text-fg, bg-primary, ...). Those tokens only resolve to your palette when the SAME WindThemeData is installed as the ambient WindTheme that renders the app. useWindTheme maps the roles onto the component properties; the ambient WindTheme is what expands the tokens at paint time. For any role the passed theme does not define, the derivation falls back to the shipped default palette pair (so an omitted role never produces an invisible surface), but a defined role that is missing from the ambient WindTheme will render its bare token unresolved.