Wind UI

Wind UI 1.5

Utility-first Flutter styling. Every visual decision lives in a className: String? parsed at build time into an immutable WindStyle and composed into a native Flutter widget tree. Tailwind syntax (flex, p-4, dark:bg-gray-800, hover:shadow-lg), Flutter physics.

This skill assumes the host app already depends on fluttersdk_wind and has WindTheme wrapping MaterialApp. If a fresh project needs setup (rare; the skill normally triggers on an already-installed project), see Quick install at the bottom.

0. Before writing UI in this project

Three quick checks. Each pays off across the whole session.

1. Confirm Wind is installed. Look at pubspec.yaml for fluttersdk_wind:. If absent, jump to §13 first.
2. Read the project's WindThemeData setup. Usually in lib/main.dart or lib/config/wind.dart. Note any custom color families (primary, accent, incident, etc.): those become available as bg-primary-500, text-incident-700, etc. without registration. Skip this and the agent risks writing tokens that silently no-op, or missing the brand palette entirely.
3. Scan one existing view in lib/ for the project's className idioms. Triple-quoted style? Single-line preferred? Custom states (pressed:, expanded:)? Match the surrounding code, don't invent a new dialect.

After these, the agent has the project's color landscape, breakpoint set, and className voice loaded.

The parser cache is near-100% hit-rate in production. Do not worry about className parse overhead; the same className parses exactly once for its (breakpoint, brightness, platform, states) tuple. Prefer expressive className over inline BoxDecoration / EdgeInsets for "performance" reasons; the cache handles it.

1. Core Laws

These hold for every line of Wind code. Apply each as a hard constraint, not a suggestion.

1. className is the styling surface. Inline Dart props (backgroundColor on WDiv, foregroundColor on WText) exist only as runtime-dynamic escape hatches for values the cache key cannot represent. Default to className. Never reach for BoxDecoration, EdgeInsets, TextStyle when a token covers it.

2. Every bg- / text- / border- / ring- / shadow- / fill- carries a dark: peer in the same className. Missing pair is a bug, not a style choice. Pair bg-white dark:bg-gray-800 on the same line, not at the top and bottom of a multi-line className. Wind's dark-mode contract: the agent never opts in; every color opts in by default.

3. Conditional styling routes through states: Set<String>? plus prefixed classes. Never interpolate Dart expressions into className. 'bg-${isOn ? "blue" : "gray"}-500' breaks the parser cache and is a bug. The right shape:

   WDiv(
     className: '''
       rounded-lg p-4 border-2
       border-gray-200 dark:border-gray-700
       bg-white dark:bg-gray-800
       selected:border-blue-500 selected:bg-blue-50
       dark:selected:border-blue-400 dark:selected:bg-blue-950
     ''',
     states: isSelected ? const {'selected'} : const {},
     child: ...,
   );
   

4. Inside a Row (flex flex-row), prefer flex-1 for a fill-the-row child. A bare w-full on a direct Row child is now treated as flex-1 (the row wraps it in Expanded), so it fills the available width instead of asserting RenderBox was not laid out; flex-1 stays the idiomatic, explicit choice and is what to reach for. (A prefixed md:w-full is NOT auto-expanded; use md:flex-1.) Inside a Column (flex flex-col), scrollable children use flex-1 overflow-y-auto plus the constructor prop scrollPrimary: true for iOS tap-to-top. h-full inside a scrollable parent still triggers "Vertical viewport was given unbounded height".

5. child XOR children on every W-widget that accepts both. Passing both fails an assertion at construction. Passing neither renders an empty SizedBox.

6. Unknown tokens are dropped; the debug hint fires only for tokens no parser recognizes. Two cases, and they behave differently. A token whose prefix matches NO parser (ps-4 logical-inline, -m-4 negative margin, a mistyped family like wibble-4) is dropped and, in kDebugMode, prints a one-time debugPrint naming it (deduped per unique token per session; release builds stay silent). A token whose family IS recognized but whose value is unsupported (text-7xl, past wind's text-6xl cap; flex-cow, which still matches flex-*) is claimed by that parser and drops SILENTLY, with no hint. So the hint catches unknown-family typos, not bad-value ones; spell-check values by hand or load references/tokens.md to verify the family.

7. Last class wins within a parser family. p-4 p-8 resolves to p-8. bg-red-500 bg-blue-500 resolves to bg-blue-500. Conflicts inside the same property are stable but silent; conflicts across properties (text-red-500 color + text-center alignment) coexist because they target different fields.

8. WindTheme lives BELOW MaterialApp in the runtime tree. The builder pattern inverts apparent order: WindTheme(data: ..., builder: (ctx, controller) => MaterialApp(...)). Consequence: OverlayEntry.builder contexts cannot reach WindTheme via ancestor walk. Capture the State's context before showing an overlay, then pass it to WindParser.parse from inside the overlay builder. WPopover / WSelect already handle this internally.

9. Wind composes with Flutter, not against it. Scaffold, AppBar, Dialog, BottomSheet, Drawer, SnackBar, Navigator, Hero, FutureBuilder, StreamBuilder, ValueListenableBuilder remain canonical. ListView / GridView.builder / CustomScrollView are the right choice for virtualised lists; WDiv with grid-cols-N produces a static Wrap (or, with items-stretch, equal-height rows), not a virtualised grid. See Wind ≠ Flutter rules of thumb.

10. active: prefix is reserved but not wired. WAnchor tracks hover and focus only; there is no onTapDown/onTapUp tracking. Don't rely on active:bg-blue-700 for press feedback. Use a transient state in the consumer's controller and states: {'pressed'} if you genuinely need press feedback today.

2. The 27 public widgets (+ WindRecipe) at a glance

fluttersdk_wind v1 ships 27 public widgets plus the WindRecipe / WindSlotRecipe variant-composition primitives, all imported from the single barrel package:fluttersdk_wind/fluttersdk_wind.dart. No sub-barrels exist; do not write import 'package:fluttersdk_wind/widgets.dart'.

The headline 25 (table below) are the ones an agent reaches for daily. Two more cover narrow surfaces and live outside the table: WKeyboardActions (iOS keyboard toolbar overlay for Done / Next actions on a focused TextField) and WindAnimationWrapper (the internal stateful wrapper that drives looping animate-* tokens; consumers normally do not instantiate it directly).

Full constructor surface, every named parameter, every default: ${CLAUDE_SKILL_DIR}/references/widgets.md.

WindRecipe / WindSlotRecipe (variant-composition primitives)

WindRecipe and WindSlotRecipe are callable objects (not widgets) that compose className strings from variant axes. Use them to centralise multi-variant component styling instead of scattering conditional className strings across the call sites.

final button = WindRecipe(
  base: 'flex flex-row items-center rounded-lg font-medium',
  variants: {
    'intent': {'primary': 'bg-blue-600 dark:bg-blue-500 text-white', 'ghost': 'bg-transparent text-blue-600 dark:text-blue-400'},
    'size':   {'sm': 'px-3 py-1.5 text-sm', 'md': 'px-4 py-2 text-base', 'lg': 'px-6 py-3 text-lg'},
  },
  compoundVariants: [
    WindCompoundVariant(conditions: {'intent': 'primary', 'size': 'lg'}, className: 'shadow-lg'),
  ],
  defaultVariants: {'intent': 'primary', 'size': 'md'},
);

button()                                       // uses defaults
button(variants: {'intent': 'ghost'})          // override one axis
button(variants: {'size': null})               // null clears the default (no size classes)
button(className: 'w-full')                    // caller suffix, appended last

Resolution order (strict, never sorted): base ++ variant-classes(definition order) ++ matched-compound(array order) ++ caller.

Same-granularity contract: a variant must override a base token at the same granularity. Mixing p-4 (base) and px-2 (variant) is silent: the parser's per-family last-wins keeps the shorthand. Override px-* with px-* or p-* with p-*.

WindSlotRecipe returns Map<String, String> (slot -> className). Use the slot keys directly on widget className: props.

Core Law addition for recipes: pass enum variant values as .name (ButtonIntent.ghost.name); recipe axes are plain strings.

Caller-append contract (no twMerge): the recipe only appends the caller's className last; it never dedupes or resolves conflicts itself. WindRecipe(base: 'w-1/2')(className: 'w-full') emits 'w-1/2 w-full', both tokens intact. The conflict resolves one layer down: WindParser groups same-family classes and each parser applies last-class-wins, so the appended w-full wins at parse time. Wind deliberately has no Dart twMerge/cn port; see doc/styling/wind-recipe.md "The Caller-Append Contract (No twMerge)". A component that treats an incoming className as a full replacement instead of appending it is a consumer bug, not a wind defect.

3. The state system (three layers)

WDiv and WButton auto-wrap themselves in WAnchor whenever className contains the literal substrings hover:, focus:, or active:. Other widgets do not. If you need hover detection on a WText, wrap it in WDiv or WAnchor explicitly.

All active states merge into a single Set<String> inside WindContext.activeStates and contribute to the parser cache key. Manual states: {'hover'} and a real pointer hover produce the same cache entry by design.

Combining prefixes:

md:hover:bg-blue-500          // breakpoint AND hover
dark:md:hover:bg-blue-400     // dark AND breakpoint AND hover
ios:focus:ring-blue-500       // iOS only AND focused
md:dark:selected:border-2     // breakpoint AND dark AND selected

Prefix order does not matter at the parser level; all stacked prefixes must match for the class to activate.

4. The token landscape (high-frequency subset)

Inline this catalog as your default reach-for set. For the full per-parser regex catalog (every flag, every arbitrary-value pattern): ${CLAUDE_SKILL_DIR}/references/tokens.md.

Layout: flex flex-row flex-col flex-row-reverse flex-col-reverse wrap grid grid-cols-N block hidden. justify-start -center -end -between -around -evenly. items-start -center -end -baseline -stretch. axis-min axis-max (Wind-only, sets MainAxisSize). On a grid, items-stretch opts into equal-height rows (cells match the tallest per row); the default grid sizes each cell to its own content.

Flex child: flex-1 flex-auto flex-none flex-N (numeric). shrink-0 grow. self-start / -end / -center / -stretch / -auto (align-self shorthand; align-self-* long form also works). order-0 through order-12, order-first / order-last / order-none, arbitrary order-[-5].

Spacing: p-N px-N py-N pt-N pr-N pb-N pl-N (no ps-/pe-). m-N and axes (no negative margin, no ms-/me-, mx-auto for horizontal centering). gap-N gap-x-N gap-y-N space-x-N space-y-N. Arbitrary p-[18px], gap-[3.5] (no % for spacing). Default unit: 4 px per step. p-4 = 16 px.

Sizing: w-N h-N (theme scale). w-1/2 w-1/3 w-2/3 w-1/4 w-3/4 w-full w-screen. h-full h-screen. size-N sets BOTH width and height (size-2, size-full, size-1/2, size-[20px]); works on a childless WDiv (status dot). Arbitrary w-[300px] h-[50%]. min-w-0 min-w-full min-h-screen. max-w-xs through max-w-7xl, max-w-prose, max-w-full. No w-auto / h-auto (silently skipped).

Position: relative absolute. top-N right-N bottom-N left-N inset-N inset-x-N inset-y-N, negative -top-N -inset-N, arbitrary top-[24px] (no % for offsets). fixed / sticky are recognised by the parser but produce no visual effect.

Colors (every line needs a dark: peer): bg-{family}-{shade} bg-[#hex] bg-transparent bg-white bg-black. Opacity modifier /N (0-100): bg-red-500/50. Same shape for text-* border-* ring-* shadow-* fill-* stroke-*. Bare shade defaults to 500: bg-red = bg-red-500. Gradients: bg-gradient-to-{t|tr|r|br|b|bl|l|tl} + from-{c}-{shade} via-{c}-{shade} to-{c}-{shade}.

Borders: border border-N border-t border-r border-b border-l border-x border-y. border-solid border-none (only these two; border-dashed / border-dotted are recognised but not wired). rounded rounded-{sm|md|lg|xl|2xl|3xl|full|none}, directional rounded-t-lg rounded-tl-xl, arbitrary rounded-[8px].

Typography (order of resolution inside text-*): color → align → size → weight → style. text-xs text-sm text-base text-lg text-xl text-2xl through text-6xl (60 px). text-7xl / text-8xl / text-9xl are no-ops; do not write them. font-thin through font-black. text-left text-center text-right text-justify text-start text-end (RTL-aware). truncate (= text-ellipsis + maxLines: 1 + softWrap: false). line-clamp-N. whitespace-nowrap / text-nowrap. uppercase lowercase capitalize normal-case (capitalize raises the first letter of every word and leaves the rest as typed, so the HTTP client is The HTTP Client and well-known is Well-Known, while a digit, an underscore, an apostrophe or a combining mark continues the word, so 3rd party, l'orange and decomposed NFD text keep theirs; casing follows the ambient locale, so tr/az get the dotted/dotless i right, and it falls back to locale-independent casing with no Localizations ancestor). italic / not-italic. underline line-through no-underline, plus decoration-{color}/{style}/{thickness}. leading-tight leading-snug leading-normal leading-relaxed leading-loose or arbitrary leading-[24px]. tracking-tighter through tracking-widest. Font size + line height combined: text-xl/8.

Effects: opacity-N (5-step scale, plus arbitrary opacity-[0.5]). shadow-sm shadow shadow-md shadow-lg shadow-xl shadow-2xl shadow-inner shadow-none. Colored shadow shadow-blue-500/20. ring-N ring-{color} ring-offset-N ring-inset. aspect-square aspect-video aspect-[4/3]. z-0 z-10 through z-50, arbitrary z-[100], z-auto.

Overflow: overflow-hidden overflow-visible overflow-scroll overflow-auto, axis-specific overflow-x-auto overflow-y-auto. Scrolling requires the constructor prop scrollPrimary: true for iOS tap-to-top (there is no className for it).

Cursor (web/desktop; WDiv adds a MouseRegion, inert on touch): cursor-pointer cursor-default cursor-text cursor-wait cursor-progress cursor-help cursor-not-allowed cursor-none cursor-move cursor-grab cursor-grabbing cursor-zoom-in cursor-zoom-out cursor-col-resize cursor-row-resize cursor-{n,e,s,w,ne,nw,se,sw,ew,ns,nesw,nwse}-resize plus cursor-context-menu cursor-cell cursor-crosshair cursor-alias cursor-copy cursor-no-drop cursor-all-scroll. Last token wins; unknown names no-op.

Transitions / animations: duration-{75|100|150|200|300|500|700|1000} plus arbitrary duration-[500ms]. ease-linear ease-in ease-out ease-in-out. animate-spin animate-pulse animate-ping animate-bounce animate-none. The bare transition / transition-all / transition-colors tokens are recognised in docs but NOT wired in the parser; pair duration-* + ease-* to enable transitions on opacity and color changes.

Prefixes: Responsive sm: md: lg: xl: 2xl: (default 640 / 768 / 1024 / 1280 / 1536 px, customizable via WindThemeData.screens). Dark dark:. Platform ios: android: macos: web: mobile: windows: linux:. State (Core Laws §3). Stackable freely.

5. Wind ≠ Tailwind (the cheat sheet a web developer needs first)

A developer fluent in Tailwind v3 or v4 will default to assumptions Wind partially honours, partially rejects. Full divergence catalog: ${CLAUDE_SKILL_DIR}/references/tailwind-divergence.md.

Wind-only additions Tailwind lacks: ios: android: macos: windows: linux: web: mobile: platform prefixes. axis-min / axis-max for Flutter MainAxisSize. Inline color props (WDiv.backgroundColor, WText.foregroundColor) that bypass the cache key. WBreakpoint for per-breakpoint widget builders. WDynamic for JSON-driven trees. preserve-colors token for WSvg.

6. Flutter constraint reality (the six layout rules CSS does not have)

Wind hides most boilerplate but never changes Flutter's "constraints down, sizes up, parent sets position" model. Six rules cover ~90% of overflow errors. Full recipe catalog + assertion-to-fix mapping: ${CLAUDE_SKILL_DIR}/references/layouts.md.

items-stretch inside a SingleChildScrollView needs an IntrinsicHeight wrapper from native Flutter; Wind has no token for it. Rare; reach for it when row children inside a scroll must match heights.

Intrinsic sizing limitation. Wrapping Wind content in IntrinsicHeight / IntrinsicWidth (or a Row/Column that needs child intrinsic heights for equal-height columns) throws LayoutBuilder does not support returning intrinsic dimensions WHEN that content contains a grid, which composes a Wrap inside a LayoutBuilder to compute its column width. LayoutBuilder cannot answer intrinsic queries (a Flutter constraint, not a Wind bug). h-full and flex basis-* are NO LONGER triggers: both resolve through render objects (WindFullHeightBox, WindMainExtentProvider), and a render object answers intrinsics. Escape hatches for the grid case: explicit h-* / size-* cells, or a Stack + Positioned(top:0,bottom:0); Wind's own items-stretch grid equalizes row heights with real layout, so reach for it INSTEAD of IntrinsicHeight.

7. className formatting

Multi-line triple-quoted when the className covers 3+ concerns. One concern per line. Group dark: peers beside their light variant, not at the bottom.

Wrong (one long line, hard to scan, easy to miss a missing dark: peer):

className: 'rounded-lg p-4 border-2 border-gray-200 bg-white text-gray-900 hover:bg-gray-50',

Right (concerns visible, dark pairs paired inline, hover state grouped):

WDiv(
  className: '''
    rounded-lg p-4 border-2
    border-gray-200 dark:border-gray-700
    bg-white dark:bg-gray-800
    text-gray-900 dark:text-white
    hover:bg-gray-50 dark:hover:bg-gray-700
  ''',
  child: ...,
);

Single line is fine when the className is genuinely short (1-2 concerns, ≤ 60 chars). Don't force triple-quoting on 'text-lg font-bold'.

Never embed Dart expressions in className. Route every dynamic visual through states: plus prefixed classes (Core Law §3), or through backgroundColor / foregroundColor inline props for runtime-dynamic colors.

8. Forms (when to reach for WForm*)

Two widget families, parallel surface, different scope.

Idiomatic form:

final _formKey = GlobalKey<FormState>();

Form(
  key: _formKey,
  child: WDiv(
    className: 'flex flex-col gap-4 p-6',
    children: [
      WFormInput(
        label: 'Email',
        type: InputType.email,
        autovalidateMode: AutovalidateMode.onUserInteraction,
        className: '''
          rounded-lg p-3 border
          border-gray-300 dark:border-gray-600
          bg-white dark:bg-gray-800
          focus:ring-2 focus:ring-blue-500
          error:border-red-500
        ''',
        validator: (value) {
          if (value == null || value.isEmpty) return 'Required';
          if (!value.contains('@')) return 'Invalid email';
          return null;
        },
        onSaved: (value) => _email = value ?? '',
      ),
      WButton(
        className: 'bg-blue-600 dark:bg-blue-500 hover:bg-blue-700 dark:hover:bg-blue-600 text-white px-6 py-3 rounded-lg',
        onTap: () {
          if (_formKey.currentState!.validate()) {
            _formKey.currentState!.save();
            _submit();
          }
        },
        child: const Text('Submit'),
      ),
    ],
  ),
);

For server-side / async validation, use FormField.forceErrorText: run the async work after _formKey.currentState!.validate() returns true, then setState(() => _serverError = result.message) and pass forceErrorText: _serverError on the relevant field. Wind's WForm* widgets inherit forceErrorText from FormField.

WFormDatePicker range mode gotcha: the FormFieldState<DateTime> stores only range.start. A validator inspecting "is the range complete" must reach for the controller's internal state separately.

Full Form patterns + validation recipes + async error flow: ${CLAUDE_SKILL_DIR}/references/forms.md.

9. Wind ≠ Flutter rules of thumb

WDynamic is the JSON-driven alternative when a server, A/B framework, or remote-config service supplies the widget tree at runtime. Whitelisted by default (13 Wind + 16 Flutter core types); extend with builders: / customIcons:; restrict with denyWidgets:. Reach for it only when remote rendering is a hard requirement; for static UI write Dart.

10. Definition of done for a Wind change

Per change (every UI edit), verify all seven:

1. Every color token has a dark: peer in the same className block. Grep your diff for bg-, text-, border-, ring-, fill-, shadow- and confirm a dark: peer on each.
2. Every multi-concern className (3+ token families) is triple-quoted, one concern per line, dark pairs grouped beside their light variant.
3. Every interactive surface has hover: and focus: states (web/desktop targets) on WButton, WAnchor, WInput, WSelect, WCheckbox, WDatePicker, plus disabled: styling wherever the widget exposes an enabled / disabled parameter.
4. Every child XOR children: never both. Construction-time assertion.
5. Every scrollable root WDiv has scrollPrimary: true on at least one ancestor in the scroll chain so iOS status-bar-tap scrolls to top.
6. No Dart string interpolation inside className, no inline BoxDecoration / TextStyle / EdgeInsets when a token covers it, no Icons.* (non-outlined) without a deliberate reason, no WIcon without Icons.*_outlined.
7. Every icon-only WButton / WAnchor has a semanticLabel: without it the control is nameless to screen readers and getByRole('button', { name }). When set, the child subtree is excluded from semantics, so semanticLabel overrides any child text rather than concatenating with it. Prefer it for icon-only controls; omit it when the child already carries readable text. Do not put the word "button" in the label; the role appends it.

Run dart analyze on the touched files and visually verify the change in light AND dark mode (toggle via context.windTheme.toggleTheme() if there is no UI for it yet) before reporting done. Missing dark pairs only surface when the app is actually in dark mode.

11. Common patterns (the agent will reach for these first)

…(truncated)