wind

# fluttersdk_wind

> Tailwind CSS for Flutter. A utility-first styling framework that maps `className` strings to optimized Flutter widget trees, with 24-field `WindThemeData` theming, responsive prefixes (`sm:` / `md:` / `lg:` / `xl:` / `2xl:`), `dark:`, state prefixes (`hover:` / `focus:` / `disabled:` / `loading:` / `selected:`), platform prefixes (`ios:` / `android:` / `web:` / `mobile:`), 27 W-prefix widgets, `WindRecipe` / `WindSlotRecipe` variant composition, server-driven UI via `WDynamic`, and three AI integration layers (hosted MCP server, Claude Code skill, and a skill distributed to 8+ AI clients via fluttersdk/ai). Open Source. Tailwind syntax. Flutter native. Version 1.7.0 stable.

**Stack**: Flutter >=3.27.0 · Dart >=3.4.0 · Runtime deps: `flutter_svg`, `fluttersdk_wind_diagnostics_contracts`. No `mockito`, no state management library, no router.

**Setup**:

```bash
flutter pub add fluttersdk_wind
```

```dart
import 'package:fluttersdk_wind/fluttersdk_wind.dart';

WindTheme(
  data: WindThemeData(),
  builder: (ctx, controller) => MaterialApp(
    theme: controller.toThemeData(),
    home: HomePage(),
  ),
)

// Build with className
WDiv(
  className: 'p-6 bg-white dark:bg-gray-800 rounded-xl shadow-lg',
  child: WText('Hello', className: 'text-xl font-bold dark:text-white'),
)

// Debug only: expose 7-field debug data to inspectors via fluttersdk_wind_diagnostics_contracts
if (kDebugMode) Wind.installDebugResolver();
```

**Prefix stack** in className: `<state>:<breakpoint>:<dark>:<platform>:<utility>`. Last class wins; unknown tokens are dropped and a one-time `kDebugMode` hint names each (release builds stay silent). Every color token (`bg-` / `text-` / `border-` / `fill-` / `ring-` / `shadow-`) carries a `dark:` pair in the same className.

**Parser cache key**: `className + activeBreakpoint + brightness + platform + sorted(activeStates)`. Stable across rebuilds; invalidate via `WindParser.clearCache()` in test `setUp` only, never in production.

## Widgets

### Layout & container

- [WDiv](https://fluttersdk.com/wind/widgets/w-div.md): Flutter `Container` replacement; consumes `className` for spacing, color, border, shadow, layout.
- [WText](https://fluttersdk.com/wind/widgets/w-text.md): Text widget with `className`-driven font, color, alignment, decoration.
- [WSpacer](https://fluttersdk.com/wind/widgets/w-spacer.md): Flex-aware spacer that obeys responsive prefixes.
- [WBreakpoint](https://fluttersdk.com/wind/widgets/w-breakpoint.md): Declarative per-breakpoint widget tree switcher; escape hatch when prefixes are not enough.
- [WCard](https://fluttersdk.com/wind/widgets/w-card.md): Surface container with optional `header` and `footer` slots; all styling `className`-driven.
- [WBadge](https://fluttersdk.com/wind/widgets/w-badge.md): Inline status/label pill; composes a rounded-full `WDiv` around a `WText`.

### Interactive

- [WButton](https://fluttersdk.com/wind/widgets/w-button.md): Button with `hover:` / `focus:` / `active:` / `loading:` / `disabled:` state prefixes.
- [WAnchor](https://fluttersdk.com/wind/widgets/w-anchor.md): Inline interactive wrapper; auto-wraps `WDiv` / `WButton` when hover/focus prefixes are detected.
- [WPopover](https://fluttersdk.com/wind/widgets/w-popover.md): Overlay container with alignment + trigger / content builders.
- [WTabs](https://fluttersdk.com/wind/widgets/w-tabs.md): Controlled tabs; `selected:` state prefix marks the active tab, `panelBuilder` renders the active panel.
- [WKeyboardActions](https://fluttersdk.com/wind/widgets/w-keyboard-actions.md): Above-keyboard toolbar with Done button and field navigation for iOS numeric keyboards; platform-targeted via `platform: 'ios'`.
- [WindAnimationWrapper](https://fluttersdk.com/wind/widgets/wind-animation-wrapper.md): Low-level animation engine; wraps a child in spin, ping, pulse, or bounce with configurable `duration` and `curve`. Used internally by `animate-*` className tokens.

### Form

- [WInput](https://fluttersdk.com/wind/widgets/w-input.md): TextField with `className` styling + `InputType` (text, email, number, password, multiline, search).
- [WSelect](https://fluttersdk.com/wind/widgets/w-select.md): Dropdown with optional search, multi-select, pagination.
- [WCheckbox](https://fluttersdk.com/wind/widgets/w-checkbox.md): Checkbox or switch with `className`.
- [WSwitch](https://fluttersdk.com/wind/widgets/w-switch.md): Controlled toggle switch; pushes the `checked:` state prefix, thumb positioned via `justify-*` on the track.
- [WRadio](https://fluttersdk.com/wind/widgets/w-radio.md): Controlled radio button; drives the `selected:` state prefix when `value == groupValue`.
- [WDatePicker](https://fluttersdk.com/wind/widgets/w-date-picker.md): Single-date, date-range and date-with-time picker.
- [WFormInput](https://fluttersdk.com/wind/widgets/w-form-input.md): Form-bound `WInput` wrapper with validator.
- [WFormSelect](https://fluttersdk.com/wind/widgets/w-form-select.md): Form-bound `WSelect` wrapper with validator.
- [WFormMultiSelect](https://fluttersdk.com/wind/widgets/w-form-select.md): Multi-select variant of `WFormSelect`, documented in the same page.
- [WFormCheckbox](https://fluttersdk.com/wind/widgets/w-form-checkbox.md): Form-bound `WCheckbox` wrapper.
- [WFormDatePicker](https://fluttersdk.com/wind/widgets/w-form-date-picker.md): Form-bound `WDatePicker` wrapper.

### Media

- [WIcon](https://fluttersdk.com/wind/widgets/w-icon.md): `IconData` with `className` size and color.
- [WImage](https://fluttersdk.com/wind/widgets/w-image.md): Image with `className`-driven sizing, object-fit, border, opacity.
- [WSvg](https://fluttersdk.com/wind/widgets/w-svg.md): SVG via `flutter_svg` with `className` fill / stroke + `preserve-colors` opt-in.

### Dynamic

- [WDynamic](https://fluttersdk.com/wind/widgets/w-dynamic.md): JSON-to-widget renderer for server-driven UI; whitelisted 13 Wind widgets + 16 Flutter core widgets.

## Core concepts

- [Installation](https://fluttersdk.com/wind/getting-started/installation.md): pubspec add + WindTheme wrap + first className.
- [Utility-first](https://fluttersdk.com/wind/core-concepts/utility-first.md): why className beats nested widgets.
- [Theming](https://fluttersdk.com/wind/core-concepts/theming.md): 24 `WindThemeData` fields, override patterns.
- [Theme binding](https://fluttersdk.com/wind/core-concepts/theme-binding.md): `WindTheme` placement, `OverlayEntry` caveat.
- [Dark mode](https://fluttersdk.com/wind/core-concepts/dark-mode.md): `dark:` prefix, runtime toggle, system sync.
- [Responsive design](https://fluttersdk.com/wind/core-concepts/responsive-design.md): breakpoint prefixes + `WBreakpoint` escape hatch.
- [State management](https://fluttersdk.com/wind/core-concepts/state-management.md): `hover:`, `focus:`, `disabled:`, `loading:`, `selected:`, custom states.
- [Dynamic rendering](https://fluttersdk.com/wind/core-concepts/dynamic-rendering.md): `WDynamic` JSON schema + security model.
- [Debugging](https://fluttersdk.com/wind/core-concepts/debugging.md): `WindLogger`, `Wind.installDebugResolver()`, `Wind.installPerfResolver()` + `WindPerfCounters` (opt-in hit/miss/bypass and build counters), cache inspection, unknown-className debug hint.
- [Recipes](https://fluttersdk.com/wind/styling/wind-recipe.md): `WindRecipe` / `WindSlotRecipe` variant composition (base + axes + compoundVariants + caller className) in strict emission order, no dedupe / sort / twMerge.

## Utility families

- [Layout](https://fluttersdk.com/wind/layout): flex, grid, position, overflow, aspect-ratio, z-index, order.
- [Sizing](https://fluttersdk.com/wind/layout/sizing.md): `w-*`, `h-*`, `size-*` (width + height shorthand), `min-*`, `max-*`, arbitrary `w-[200px]`.
- [Spacing](https://fluttersdk.com/wind/layout/spacing.md): padding (`p-*`, `px-*`, `pt-*`), margin (`m-*`, `-mt-*`), gap (`gap-*`, `space-x-*`).
- [Typography](https://fluttersdk.com/wind/typography): `text-*` (size + color + alignment overload), `font-*`, `leading-*`, `tracking-*`, `truncate`.
- [Backgrounds](https://fluttersdk.com/wind/styling/background-color.md): `bg-*`, gradients, images.
- [Borders & ring](https://fluttersdk.com/wind/borders): `border-*`, `rounded-*`, `ring-*`, `divide-*` (not implemented).
- [Shadows](https://fluttersdk.com/wind/styling/shadow.md): `shadow`, `shadow-md`, colored shadows (`shadow-blue-500/20`).
- [Opacity](https://fluttersdk.com/wind/styling/opacity.md): `opacity-*` + opacity modifiers (`bg-red-500/50`).
- [Transitions & animations](https://fluttersdk.com/wind/interactivity): `duration-*`, `ease-*`, `animate-spin` / `pulse` / `bounce` / `ping`.
- [Cursor](https://fluttersdk.com/wind/interactivity/cursor.md): `cursor-pointer`, `cursor-not-allowed`, `cursor-text`, grab / zoom / resize families mapped to `SystemMouseCursors` via `MouseRegion`.

## Utility helpers (Dart APIs)

- [Color helpers](https://fluttersdk.com/wind/utilities/color-helpers.md): `wColor(context, 'blue', shade: 500)`, theme-aware color lookups.
- [Context extensions](https://fluttersdk.com/wind/utilities/context-extensions.md): `context.windTheme`, `context.windBreakpoint`, `context.windBrightness`.
- [Responsive helpers](https://fluttersdk.com/wind/utilities/responsive-helpers.md): programmatic breakpoint queries.
- [Spacing helpers](https://fluttersdk.com/wind/utilities/spacing-helpers.md): `wSpacing(context, 4)` resolves the same tokens as `p-4`.
- [Style parser](https://fluttersdk.com/wind/utilities/style-parser.md): `WindParser.parse(className, context, states:)` direct access.
- [Typography helpers](https://fluttersdk.com/wind/utilities/typography-helpers.md): `wFontSize(context, 'lg')` etc.

## AI & Tooling

- [fluttersdk/ai](https://github.com/fluttersdk/ai): canonical distribution channel. One-command install via `npx skills add fluttersdk/ai --skill wind-ui` covers Claude Code, Cursor, OpenCode, Gemini CLI, VS Code Copilot, Codex CLI, Cline, Roo Code.
- [Wind skill source](https://github.com/fluttersdk/wind/tree/master/skills/wind-ui): canonical `SKILL.md` + references; `fluttersdk/ai` mirrors this directory.
- [Hosted MCP server](https://mcp.fluttersdk.com): Streamable HTTP, single `search-docs` tool, no auth required.
- [Stdio MCP bridge](https://www.npmjs.com/package/@fluttersdk/mcp): `npx @fluttersdk/mcp` for clients without HTTP MCP transport.

## Source

- [GitHub](https://github.com/fluttersdk/wind)
- [pub.dev](https://pub.dev/packages/fluttersdk_wind)
- [CHANGELOG](https://github.com/fluttersdk/wind/blob/master/CHANGELOG.md)
- [ARCHITECTURE](https://github.com/fluttersdk/wind/blob/master/ARCHITECTURE.md)

## Optional

- [LICENSE](https://github.com/fluttersdk/wind/blob/master/LICENSE)
- [Issues](https://github.com/fluttersdk/wind/issues)
- [Star on GitHub](https://github.com/fluttersdk/wind/stargazers)