@windforge/ui 0.1.0

package/src/layouts/app-bar.tsx

@@ -0,0 +1,95 @@
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { Menu, Sun, Moon, MonitorSmartphone } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { Button } from '../components/button'
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from '../components/tooltip'
+import { useTheme, type ColorMode } from './theme-provider'
+import { useAppShell } from './app-shell'
+
+// `variant` picks the surface treatment: `glass` is the translucent, blurred bar
+// (content scrolls frostily behind it — the default); `solid` is a flat, opaque
+// bar for a calmer, cleaner chrome. `color` overrides which surface token the bar
+// sits on (e.g. `inset`) under either treatment. Class strings are spelled out in
+// full so Tailwind's content scanner keeps them.
+const appBarVariants = cva(
+  'sticky top-0 z-30 flex h-16 items-center gap-2 border-b border-border px-4',
+  {
+    variants: {
+      variant: { glass: 'backdrop-blur-md', solid: '' },
+      color: { surface: '', subtle: '', inset: '' },
+    },
+    compoundVariants: [
+      { variant: 'glass', color: 'surface', class: 'bg-surface/80' },
+      { variant: 'glass', color: 'subtle',  class: 'bg-surface-subtle/80' },
+      { variant: 'glass', color: 'inset',   class: 'bg-surface-inset/80' },
+      { variant: 'solid', color: 'surface', class: 'bg-surface' },
+      { variant: 'solid', color: 'subtle',  class: 'bg-surface-subtle' },
+      { variant: 'solid', color: 'inset',   class: 'bg-surface-inset' },
+    ],
+    defaultVariants: { variant: 'glass', color: 'surface' },
+  },
+)
+
+export interface AppBarProps extends VariantProps<typeof appBarVariants> {
+  title?: string
+  logo?: React.ReactNode
+  actions?: React.ReactNode
+  /** Override the menu-button handler. Inside an AppShell it defaults to toggling the nav. */
+  onMenuClick?: () => void
+}
+
+const modeIcon: Record<ColorMode, React.ReactNode> = {
+  light: <Sun className="h-5 w-5" />,
+  dark: <Moon className="h-5 w-5" />,
+  system: <MonitorSmartphone className="h-5 w-5" />,
+}
+const modeLabel: Record<ColorMode, string> = {
+  light: 'Light — switch to dark',
+  dark: 'Dark — switch to system',
+  system: 'System — switch to light',
+}
+
+/**
+ * ModeToggle — the light/dark/system switch, as a standalone control. Drop it
+ * into an AppBar's `actions` (or anywhere else); it reads and cycles the theme
+ * from the surrounding ThemeProvider.
+ */
+export function ModeToggle() {
+  const { mode, cycleMode } = useTheme()
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="tertiary" size="icon" onClick={cycleMode} aria-label={modeLabel[mode]}>
+            {modeIcon[mode]}
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>{modeLabel[mode]}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}
+
+export function AppBar({
+  title, logo, actions, onMenuClick, variant, color,
+}: AppBarProps) {
+  const appShell = useAppShell()
+  const handleMenu = onMenuClick ?? appShell?.toggleNav
+
+  return (
+    <header className={cn(appBarVariants({ variant, color }))}>
+      {handleMenu && (
+        <Button variant="tertiary" size="icon" onClick={handleMenu} aria-label="Toggle navigation">
+          <Menu className="h-5 w-5" />
+        </Button>
+      )}
+      {logo}
+      {title && <span className="text-sm font-semibold text-secondary">{title}</span>}
+
+      <div className="ml-auto flex items-center gap-1">
+        {actions}
+      </div>
+    </header>
+  )
+}

package/src/layouts/app-shell.tsx

@@ -0,0 +1,80 @@
+import * as React from 'react'
+import { Sheet, SheetContent } from '../components/sheet'
+import { Box } from '../components/layout'
+import { useMediaQuery } from '../lib/use-media-query'
+import { cn } from '../lib/utils'
+
+const NAV_WIDTH = 256
+
+interface AppShellContextValue {
+  /** Toggle the sidebar — collapses it on desktop, opens/closes the drawer on mobile. */
+  toggleNav: () => void
+  /** Close the mobile drawer (no-op on desktop). */
+  closeNav: () => void
+}
+const AppShellContext = React.createContext<AppShellContextValue | null>(null)
+
+/** Read the AppShell coordination handles. Returns null outside an AppShell. */
+export const useAppShell = () => React.useContext(AppShellContext)
+
+export interface AppShellProps {
+  /** The top bar slot — typically an `<AppBar>`. Rendered inside the shell so it
+   *  can drive the nav via {@link useAppShell}. */
+  header?: React.ReactNode
+  /** The side navigation slot — typically a `<SideNav>`. */
+  sidebar?: React.ReactNode
+  children: React.ReactNode
+  fullBleed?: boolean
+  /** Whether the desktop sidebar starts expanded. Set `false` to open collapsed
+   *  — e.g. a personal site where the nav is secondary. The menu button (and
+   *  `useAppShell().toggleNav`) flips it. Defaults to `true`. */
+  defaultNavOpen?: boolean
+}
+
+/**
+ * AppShell — the guaranteed-layout chrome: a fixed sidebar on desktop, a Sheet
+ * drawer on mobile, a sticky bar, and a scrollable main. `header` and `sidebar`
+ * are slots (their own components, `AppBar` and `SideNav`); AppShell only owns
+ * the responsive frame and exposes toggle/close handles via {@link useAppShell}.
+ */
+export function AppShell({ header, sidebar, children, fullBleed = false, defaultNavOpen = true }: AppShellProps) {
+  const isMobile = useMediaQuery('(max-width: 1023px)')
+  const [navOpen, setNavOpen] = React.useState(defaultNavOpen)
+  const [drawerOpen, setDrawerOpen] = React.useState(false)
+
+  const ctx = React.useMemo<AppShellContextValue>(
+    () => ({
+      toggleNav: () => (isMobile ? setDrawerOpen((o) => !o) : setNavOpen((o) => !o)),
+      closeNav: () => setDrawerOpen(false),
+    }),
+    [isMobile],
+  )
+
+  const desktopNavVisible = !isMobile && navOpen
+
+  return (
+    <AppShellContext.Provider value={ctx}>
+      <div className="flex min-h-screen bg-background text-primary">
+        {desktopNavVisible && sidebar && (
+          <aside className="fixed inset-y-0 left-0 z-20 shrink-0" style={{ width: NAV_WIDTH }}>
+            {sidebar}
+          </aside>
+        )}
+
+        <Sheet open={isMobile && drawerOpen} onOpenChange={setDrawerOpen}>
+          <SheetContent side="left">
+            <Box className="-m-6 h-[calc(100%+3rem)] w-64">{sidebar}</Box>
+          </SheetContent>
+        </Sheet>
+
+        <div
+          className="flex min-w-0 flex-1 flex-col transition-[margin] duration-normal"
+          style={{ marginLeft: desktopNavVisible ? NAV_WIDTH : 0 }}
+        >
+          {header}
+          <main className={cn('flex-1 overflow-auto', !fullBleed && 'px-gutter py-lg md:px-xl')}>{children}</main>
+        </div>
+      </div>
+    </AppShellContext.Provider>
+  )
+}

package/src/layouts/side-nav.tsx

@@ -0,0 +1,196 @@
+import * as React from 'react'
+import * as AccordionPrimitive from '@radix-ui/react-accordion'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '../lib/utils'
+import { focusRingInset } from '../lib/recipes'
+import { useAppShell } from './app-shell'
+
+// ─── Nav row primitives (private to SideNav) ────────────────────────────────────
+// Every row here is a clickable nav target — that's a menu, not a list — so these
+// minimal helpers live with their only consumer instead of being a public `List`.
+const NavList = ({ className, ...props }: React.HTMLAttributes<HTMLUListElement>) => (
+  <ul className={cn('flex flex-col', className)} {...props} />
+)
+
+const navButtonBase =
+  'group relative flex w-full items-center gap-2.5 rounded-md px-3 py-1.5 text-left text-sm font-medium ' +
+  'transition-colors disabled:opacity-40 disabled:pointer-events-none ' +
+  '[&_svg]:size-[18px] [&_svg]:shrink-0 focus-visible:ring-inset ' + focusRingInset
+
+interface NavButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  active?: boolean
+}
+
+const NavButton = React.forwardRef<HTMLButtonElement, NavButtonProps>(
+  ({ className, active, ...props }, ref) => (
+    <button
+      ref={ref}
+      type="button"
+      className={cn(
+        navButtonBase,
+        active ? 'bg-surface-inset text-primary' : 'text-secondary hover:bg-surface-inset hover:text-primary',
+        className,
+      )}
+      {...props}
+    />
+  ),
+)
+NavButton.displayName = 'NavButton'
+
+const NavSubheader = ({ className, ...props }: React.HTMLAttributes<HTMLLIElement>) => (
+  <li
+    className={cn(
+      'mt-md px-3 pb-1.5 pt-1 text-sm font-semibold uppercase tracking-wider text-tertiary first:mt-none',
+      className,
+    )}
+    {...props}
+  />
+)
+
+// ─── Nav config types (compatible with the MUI Windforge shape) ─────────────────
+export interface NavLeafItem {
+  type?: 'item'
+  label: string
+  path?: string
+  icon?: React.ReactNode
+  badge?: React.ReactNode
+  onClick?: () => void
+  disabled?: boolean
+}
+export interface NavGroupItem {
+  type: 'group'
+  label: string
+  icon?: React.ReactNode
+  children: NavItem[]
+  defaultOpen?: boolean
+}
+export interface NavSectionItem {
+  type: 'section'
+  label: string
+  items: NavItem[]
+}
+export interface NavDividerItem {
+  type: 'divider'
+}
+export type NavItem = NavLeafItem | NavGroupItem | NavSectionItem | NavDividerItem
+
+export interface SideNavProps {
+  items: NavItem[]
+  activePath?: string
+  onNavigate?: (path: string) => void
+  logo?: React.ReactNode
+}
+
+// Indent nested rows by one spacing step per level, starting from the row's own
+// left padding (px-3). The per-level unit is a token; depth 0 keeps the base.
+const indent = (depth: number) => ({
+  paddingLeft: depth > 0 ? `calc(0.75rem + ${depth} * var(--wf-spacing-md))` : undefined,
+})
+
+function NavLeaf({
+  item, active, depth, onNavigate,
+}: { item: NavLeafItem; active: boolean; depth: number; onNavigate: (path: string) => void }) {
+  return (
+    <li>
+      <NavButton
+        active={active}
+        disabled={item.disabled}
+        aria-current={active ? 'page' : undefined}
+        style={indent(depth)}
+        onClick={() => {
+          item.onClick?.()
+          if (item.path) onNavigate(item.path)
+        }}
+      >
+        {active && <span className="absolute left-0 top-1/2 h-5 w-0.5 -translate-y-1/2 rounded-full bg-surface-inverse" />}
+        {item.icon}
+        <span className="truncate">{item.label}</span>
+        {item.badge && <span className="ml-auto">{item.badge}</span>}
+      </NavButton>
+    </li>
+  )
+}
+
+function NavGroup({
+  item, activePath, depth, onNavigate,
+}: { item: NavGroupItem; activePath: string; depth: number; onNavigate: (path: string) => void }) {
+  const containsActive = React.useMemo(() => hasActivePath(item.children, activePath), [item.children, activePath])
+  const defaultValue = (item.defaultOpen ?? containsActive) ? 'group' : undefined
+
+  return (
+    <li>
+      <AccordionPrimitive.Root type="single" collapsible defaultValue={defaultValue}>
+        <AccordionPrimitive.Item value="group">
+          <AccordionPrimitive.Header className="flex">
+            <AccordionPrimitive.Trigger asChild>
+              <NavButton
+                style={indent(depth)}
+                className="data-[state=open]:[&_svg:last-of-type]:rotate-180"
+              >
+                {item.icon}
+                <span className="truncate">{item.label}</span>
+                <ChevronDown className="ml-auto !size-4 transition-transform duration-200" />
+              </NavButton>
+            </AccordionPrimitive.Trigger>
+          </AccordionPrimitive.Header>
+          <AccordionPrimitive.Content className="overflow-hidden data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down">
+            <NavList>
+              {item.children.map((child, index) => (
+                <NavRenderer key={index} item={child} activePath={activePath} depth={depth + 1} onNavigate={onNavigate} />
+              ))}
+            </NavList>
+          </AccordionPrimitive.Content>
+        </AccordionPrimitive.Item>
+      </AccordionPrimitive.Root>
+    </li>
+  )
+}
+
+function NavRenderer({
+  item, activePath, depth, onNavigate,
+}: { item: NavItem; activePath: string; depth: number; onNavigate: (path: string) => void }) {
+  if (item.type === 'divider') return <li role="separator" className="my-sm h-px bg-border" />
+  if (item.type === 'section') {
+    return (
+      <>
+        <NavSubheader>{item.label}</NavSubheader>
+        {item.items.map((child, index) => (
+          <NavRenderer key={index} item={child} activePath={activePath} depth={depth} onNavigate={onNavigate} />
+        ))}
+      </>
+    )
+  }
+  if (item.type === 'group') {
+    return <NavGroup item={item} activePath={activePath} depth={depth} onNavigate={onNavigate} />
+  }
+  return <NavLeaf item={item} active={!!item.path && activePath === item.path} depth={depth} onNavigate={onNavigate} />
+}
+
+function hasActivePath(items: NavItem[], activePath: string): boolean {
+  return items.some((item) => {
+    if (item.type === 'group') return hasActivePath(item.children, activePath)
+    if (item.type === 'section') return hasActivePath(item.items, activePath)
+    if (!item.type || item.type === 'item') return item.path === activePath
+    return false
+  })
+}
+
+export function SideNav({ items, activePath = '/', onNavigate = () => {}, logo }: SideNavProps) {
+  const appShell = useAppShell()
+  const handleNavigate = (path: string) => {
+    onNavigate(path)
+    appShell?.closeNav()
+  }
+  return (
+    <nav aria-label="Main navigation" className="flex h-full flex-col border-r border-border bg-surface-subtle">
+      {logo && (
+        <div className="flex h-16 shrink-0 items-center border-b border-border px-4">{logo}</div>
+      )}
+      <NavList className="flex-1 overflow-y-auto px-sm py-sm">
+        {items.map((item, index) => (
+          <NavRenderer key={index} item={item} activePath={activePath} depth={0} onNavigate={handleNavigate} />
+        ))}
+      </NavList>
+    </nav>
+  )
+}

package/src/layouts/theme-provider.tsx

@@ -0,0 +1,128 @@
+import * as React from 'react'
+
+export type ColorMode = 'light' | 'dark' | 'system'
+export type ResolvedMode = 'light' | 'dark'
+
+const MODE_KEY = 'wf-mode'
+
+/**
+ * Inline this in <head> BEFORE the app bundle to set the color mode on first
+ * paint and avoid a flash of the wrong theme (SSR/SPA alike). Mirrors the mode
+ * resolution below; reads the persisted `wf-mode`, falls back to system.
+ *
+ *   <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />
+ */
+export function themeInitScript(storageKey: string = MODE_KEY): string {
+  return `(function(){try{var m=localStorage.getItem('${storageKey}')||'system';var d=m==='dark'||(m==='system'&&window.matchMedia('(prefers-color-scheme: dark)').matches);var e=document.documentElement;e.classList.toggle('dark',d);e.style.colorScheme=d?'dark':'light';}catch(e){}})()`
+}
+
+const canUseDOM = typeof window !== 'undefined'
+const readStoredMode = (): ColorMode | null => {
+  try {
+    return canUseDOM ? (localStorage.getItem(MODE_KEY) as ColorMode | null) : null
+  } catch {
+    return null
+  }
+}
+
+const prefersDark = () =>
+  canUseDOM && window.matchMedia('(prefers-color-scheme: dark)').matches
+const resolveMode = (mode: ColorMode): ResolvedMode =>
+  mode === 'system' ? (prefersDark() ? 'dark' : 'light') : mode
+const nextMode = (mode: ColorMode): ColorMode =>
+  mode === 'light' ? 'dark' : mode === 'dark' ? 'system' : 'light'
+
+interface ThemeContextValue {
+  mode: ColorMode
+  resolvedMode: ResolvedMode
+  setMode: (mode: ColorMode) => void
+  cycleMode: () => void
+}
+const ThemeContext = React.createContext<ThemeContextValue | null>(null)
+
+export interface ThemeProviderProps {
+  children: React.ReactNode
+  defaultMode?: ColorMode
+  /**
+   * Runtime token overrides — a `--wf-*` → value map applied as custom properties
+   * on the document root, so the whole app (including portaled overlays) re-skins
+   * with no rebuild. Pass a function to stay mode-aware:
+   * `tokens={(mode) => brandVars(ramp, mode)}`. For more than color, use
+   * `themeVars({ brand, fontSans, radius, … }, mode)`. For a site's fixed identity,
+   * prefer a static CSS `:root` override instead.
+   */
+  tokens?: Record<string, string> | ((mode: ResolvedMode) => Record<string, string>)
+  persist?: boolean
+}
+
+export function ThemeProvider({ children, defaultMode = 'system', tokens, persist = true }: ThemeProviderProps) {
+  const [mode, setModeState] = React.useState<ColorMode>(
+    () => (persist && readStoredMode()) || defaultMode,
+  )
+  const [resolvedMode, setResolvedMode] = React.useState<ResolvedMode>(() => resolveMode(mode))
+
+  const applyMode = (mode: ColorMode) => {
+    const resolved = resolveMode(mode)
+    setResolvedMode(resolved)
+    if (!canUseDOM) return
+    const root = document.documentElement
+
+    const noTransitions = document.createElement('style')
+    noTransitions.textContent = '*,*::before,*::after{transition:none!important}'
+    document.head.appendChild(noTransitions)
+
+    root.classList.toggle('dark', resolved === 'dark')
+    root.style.colorScheme = resolved
+
+    void root.offsetHeight
+    window.setTimeout(() => noTransitions.remove(), 1)
+  }
+
+  const setMode = (mode: ColorMode) => {
+    setModeState(mode)
+    if (persist) {
+      try {
+        localStorage.setItem(MODE_KEY, mode)
+      } catch {
+        /* storage unavailable (private mode / SSR) — mode still applies in memory */
+      }
+    }
+    applyMode(mode)
+  }
+
+  React.useEffect(() => {
+    if (mode !== 'system') return
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+    const onSystemChange = () => applyMode('system')
+    mediaQuery.addEventListener('change', onSystemChange)
+    return () => mediaQuery.removeEventListener('change', onSystemChange)
+  }, [mode])
+
+  const value: ThemeContextValue = { mode, resolvedMode, setMode, cycleMode: () => setMode(nextMode(mode)) }
+  const resolvedTokens = typeof tokens === 'function' ? tokens(resolvedMode) : tokens
+  // Stable signature so the effect only re-applies when the values actually change.
+  const tokenSig = resolvedTokens ? JSON.stringify(resolvedTokens) : ''
+
+  // Apply runtime token overrides to the document ROOT (not an in-tree wrapper) so
+  // they reach portaled overlays too — Dialog/DropdownMenu/Tooltip/Select/Toast/Sheet
+  // render into document.body, outside any React subtree. Custom properties on
+  // :root cascade everywhere. We track and remove exactly the keys we set.
+  React.useLayoutEffect(() => {
+    if (!canUseDOM || !tokenSig) return
+    const map = JSON.parse(tokenSig) as Record<string, string>
+    const root = document.documentElement
+    const keys = Object.keys(map)
+    for (const key of keys) root.style.setProperty(key, map[key])
+    return () => {
+      for (const key of keys) root.style.removeProperty(key)
+    }
+  }, [tokenSig])
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+}
+
+export function useTheme() {
+  const ctx = React.useContext(ThemeContext)
+  if (!ctx) throw new Error('useTheme must be used within a <ThemeProvider>')
+  return ctx
+}

package/src/lib/recipes.ts

@@ -0,0 +1,50 @@
+/**
+ * RECIPES — named class-fragment bundles shared across components.
+ *
+ * These collapse the utility groups that repeat verbatim across many primitives
+ * (focus rings, floating surfaces, menu rows, overlays) into one named class
+ * each, so a component reads as `cn(floatingPanel, '…specifics…')` instead of a
+ * wall of utilities. Compose them with `cn()` — because `cn` runs tailwind-merge,
+ * a component can override any piece simply by adding the conflicting utility
+ * after the recipe (e.g. `cn(floatingPanel, 'rounded-xl shadow-lg')`).
+ *
+ * Every utility here resolves to a token (`var(--wf-*)`), so these stay
+ * theme- and accent-aware: the class is stable, the values move underneath it.
+ */
+
+/** Keyboard focus ring for standalone interactive controls (buttons, triggers, thumbs). */
+export const focusRing =
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ' +
+  'focus-visible:ring-offset-2 focus-visible:ring-offset-background'
+
+/** Focus ring with no offset — for controls that sit flush inside a container. */
+export const focusRingInset =
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring'
+
+/** Focus treatment for text fields — recolors the border and adds a ring. */
+export const focusRingField =
+  'focus-visible:outline-none focus-visible:border-focus focus-visible:ring-2 focus-visible:ring-ring'
+
+/**
+ * Floating surface for popovers / menus / listboxes. Radius (`rounded-lg`) and
+ * shadow (`shadow-md`) are sensible defaults — override per component via `cn`.
+ * Padding, width, max-height and entrance animation are left to the caller.
+ */
+export const floatingPanel =
+  'z-50 rounded-lg border border-border bg-surface text-primary shadow-md outline-none'
+
+/**
+ * Structural recipe for a selectable row inside a menu / listbox. Intentionally
+ * carries no focus colors or padding — those differ per surface (dropdown and
+ * select both use `focus:bg-surface-inset`; autocomplete highlights the same way).
+ */
+export const menuItem =
+  'relative flex cursor-pointer select-none items-center rounded-md text-sm outline-none ' +
+  'transition-colors data-[disabled]:pointer-events-none data-[disabled]:opacity-50'
+
+/** Full-screen scrim behind modal surfaces (dialog, sheet). */
+export const overlayBackdrop = 'fixed inset-0 z-50 bg-overlay animate-fade-in'
+
+/** The corner dismiss (×) button shared by dialog and sheet. Pair with `focusRingInset`. */
+export const dismissButton =
+  'absolute right-4 top-4 rounded-md p-1 text-secondary opacity-70 transition-opacity hover:opacity-100'

package/src/lib/types.ts

@@ -0,0 +1,3 @@
+/** Strip the styling escape hatch. Applied to every component except the
+ *  layout/building-block primitives (Box, Stack, Grid). */
+export type NoStyle<T> = Omit<T, 'className' | 'style'>

package/src/lib/use-media-query.ts

@@ -0,0 +1,18 @@
+import * as React from 'react'
+
+/** Subscribe to a media query; SSR-safe (returns false until mounted). */
+export function useMediaQuery(query: string): boolean {
+  const subscribe = React.useCallback(
+    (onChange: () => void) => {
+      const mq = window.matchMedia(query)
+      mq.addEventListener('change', onChange)
+      return () => mq.removeEventListener('change', onChange)
+    },
+    [query],
+  )
+  return React.useSyncExternalStore(
+    subscribe,
+    () => window.matchMedia(query).matches,
+    () => false,
+  )
+}

package/src/lib/utils.ts

@@ -0,0 +1,10 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * `cn` — merge conditional class lists and resolve Tailwind conflicts.
+ * The one utility every component uses to compose token-driven classes.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/tailwind-preset.cjs

@@ -0,0 +1,77 @@
+/**
+ * @windforge/ui — the shippable Tailwind PRESET.
+ *
+ * This is the single thing a consumer needs to be guaranteed-on-system. It wires
+ * the generated token map into Tailwind's theme (colors, radius, shadow, spacing,
+ * type, icon sizes), supplies every keyframe/animation the components reference,
+ * and bundles the `tailwindcss-animate` plugin. Drop it into a project's
+ * `tailwind.config` and the components render correctly with zero hand-copied config:
+ *
+ *   // tailwind.config.cjs
+ *   module.exports = {
+ *     presets: [require('@windforge/ui/tailwind')],
+ *     content: [
+ *       './src/**\/*.{ts,tsx}',
+ *       './node_modules/@windforge/ui/src/**\/*.{ts,tsx}', // scan the lib's classes
+ *     ],
+ *   }
+ *
+ * The token VALUES are CSS variables, so a brand/font/radius swap happens by
+ * overriding `--wf-*` (see @windforge/tokens) — never by editing this preset.
+ */
+const tokens = require('@windforge/tokens/tailwind')
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: 'class',
+  theme: {
+    // Tokens fully REPLACE Tailwind's default palette/scales — the design system
+    // is the only source of truth. No raw Tailwind colors leak into components.
+    colors: {
+      transparent: 'transparent',
+      current: 'currentColor',
+      white: '#ffffff',
+      black: '#000000',
+      ...tokens.colors,
+    },
+    borderRadius: tokens.borderRadius,
+    boxShadow: { none: 'none', ...tokens.boxShadow },
+    fontFamily: tokens.fontFamily,
+    fontSize: tokens.fontSize,
+    // Flat border-color utilities (border-strong, border-subtle, border-focus, …).
+    borderColor: tokens.borderColor,
+    extend: {
+      spacing: tokens.spacing,
+      size: tokens.size,
+      borderWidth: tokens.borderWidth,
+      ringColor: { DEFAULT: 'var(--wf-color-border-focus)' },
+      keyframes: {
+        'accordion-down': {
+          from: { height: '0' },
+          to: { height: 'var(--radix-accordion-content-height)' },
+        },
+        'accordion-up': {
+          from: { height: 'var(--radix-accordion-content-height)' },
+          to: { height: '0' },
+        },
+        'fade-in': { from: { opacity: '0' }, to: { opacity: '1' } },
+        'scale-in': {
+          from: { opacity: '0', scale: '0.96' },
+          to: { opacity: '1', scale: '1' },
+        },
+        'progress-indeterminate': {
+          '0%': { transform: 'translateX(-100%)' },
+          '100%': { transform: 'translateX(250%)' },
+        },
+      },
+      animation: {
+        'accordion-down': 'accordion-down 200ms ease-out',
+        'accordion-up': 'accordion-up 200ms ease-out',
+        'fade-in': 'fade-in 160ms ease-out',
+        'scale-in': 'scale-in 160ms cubic-bezier(0.175,0.885,0.32,1.275)',
+        'progress-indeterminate': 'progress-indeterminate 1.4s ease-in-out infinite',
+      },
+    },
+  },
+  plugins: [require('tailwindcss-animate')],
+}