wimui 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -15,4 +15,5 @@ export * from './icon';
 export { setWimLocale, getWimLocale } from './i18n/instance';
 export { setWimDensity, getWimDensity, type WimDensity } from './density';
 export { setWimTheme, getWimTheme, type WimTheme } from './theme';
+export { setWimPreset, getWimPreset, WIM_PRESETS, type WimPreset, type WimPresetName, } from './preset';
 export { WimProvider, useWim, type WimProviderProps, type WimContextValue } from './WimProvider';

package/dist/index.js

@@ -263,5 +263,7 @@ import { ChatAvatar as ho, ChatContainer as go, ChatInput as _o, ChatInputArea a
 import { useMediaQuery as xo } from "./hooks/useMediaQuery.js";
 import { BREAKPOINTS as So, useBreakpoint as Co, useBreakpointDown as wo, useBreakpointUp as To } from "./hooks/useBreakpoint.js";
 import { getWimDensity as Eo, setWimDensity as Do } from "./density.js";
-import { WimProvider as Oo, useWim as ko } from "./WimProvider.js";
-export { no as AIResponseFeedback, Ct as ALL_ICONS, ii as Accordion, ai as AccordionContent, oi as AccordionItem, si as AccordionTrigger, kr as Affix, so as AgentStatus, sr as Alert, ae as AlertCircleIcon, oe as AlignJustifyIcon, Ar as Anchor, e as AppShell, t as AppShellBody, n as AppShellFooter, r as AppShellHeader, i as AppShellMain, a as AppShellNavbar, o as AppShellRoot, s as AppShellSidebar, c as AspectRatio, Ha as Audio, Or as Autosave, ci as Avatar, li as AvatarGroup, So as BREAKPOINTS, jr as BackTop, Lt as Badge, cr as Banner, se as BellIcon, l as BentoGrid, u as BentoGridItem, za as Blockquote, oa as BottomSheet, sa as BottomSheetBody, ca as BottomSheetClose, la as BottomSheetContent, ua as BottomSheetDescription, da as BottomSheetFooter, fa as BottomSheetHeader, pa as BottomSheetTitle, ma as BottomSheetTrigger, d as Box, Nr as Breadcrumb, kt as Button, Ft as ButtonGroup, Yt as Calendar, ta as CalendarHeatmap, ce as CalendarIcon, Tt as Card, Et as CardBody, Dt as CardFooter, Ot as CardHeader, di as Carousel, Ht as Cascader, f as Center, le as ChartIcon, ho as ChatAvatar, go as ChatContainer, _o as ChatInput, vo as ChatInputArea, yo as ChatMessage, bo as ChatMessageList, ue as CheckCircleIcon, de as CheckIcon, Ut as Checkbox, Wt as CheckboxGroup, fe as ChevronDownIcon, pe as ChevronLeftIcon, me as ChevronRightIcon, he as ChevronUpIcon, sn as Chip, ge as CircleIcon, _e as ClockIcon, ye as CloseIcon, ve as CloseSmallIcon, Ia as Code, ao as CodeBlock, Kt as ColorInput, qt as ColorPicker, be as ColumnsIcon, Jt as Combobox, Pr as CommandPalette, Fr as CommandPaletteContent, Ir as CommandPaletteEmpty, Lr as CommandPaletteFooter, Rr as CommandPaletteGroup, zr as CommandPaletteInput, Br as CommandPaletteItem, Vr as CommandPaletteList, Hr as CommandPaletteTrigger, p as Container, ha as ContextMenu, ga as ContextMenuDivider, _a as ContextMenuGroup, va as ContextMenuItem, uo as ConversationList, Kn as CopyButton, xe as CopyIcon, aa as Countdown, rr as CounterTextarea, Se as CreditCardIcon, nr as CreditCardInput, At as Dashboard, jt as DashboardWidgetCard, xi as DataGrid, Xt as DatePicker, Zt as DateRangePicker, Si as DescriptionList, Ci as DescriptionListDetails, wi as DescriptionListItem, Ti as DescriptionListTerm, hn as Dialog, gn as DialogClose, _n as DialogContent, vn as DialogDescription, yn as DialogFooter, bn as DialogHeader, xn as DialogTitle, Sn as DialogTrigger, m as Divider, Ce as DocumentIcon, we as DownloadIcon, j as Drawer, M as DrawerClose, N as DrawerContent, P as DrawerDescription, F as DrawerFooter, I as DrawerHeader, L as DrawerTitle, R as DrawerTrigger, ya as Dropdown, ba as DropdownItem, xa as DropdownMenu, Sa as DropdownTrigger, Qt as Dropzone, Te as EditIcon, Ee as EmailIcon, Ei as EmptyState, lr as ErrorBoundary, De as ExternalLinkIcon, ke as EyeIcon, Oe as EyeOffIcon, qi as FAQSection, Bt as FieldError, Vt as FieldTemplate, $t as Fieldset, en as FileUpload, Ae as FilterIcon, h as Flex, Yn as FloatButton, A as FocusTrap, g as Footer, _ as FooterBottom, v as FooterSection, Za as Gallery, y as Grid, je as GripVerticalIcon, b as Group, D as HamburgerMenu, x as Header, S as HeaderSection, Me as HelpCircleIcon, La as Highlight, Ne as HomeIcon, Pe as HourglassIcon, Ca as HoverCard, wa as HoverCardContent, Ta as HoverCardTrigger, wt as Icon, qn as IconButton, Ua as Image, Qa as ImageCompare, $n as ImageCropper, Fe as ImageIcon, ur as Indicator, Ji as InfiniteScroll, Ie as InfoCircleIcon, Zn as InlineEdit, Gt as Input, It as InputBase, tn as InputGroup, nn as InputGroupText, rn as InputMask, C as InteractiveArea, ea as JsonViewer, Di as Kanban, Oi as KanbanBoard, ki as KanbanCard, Ai as KanbanColumn, ti as Kbd, ni as KeyboardShortcuts, Rt as Label, ra as Leaderboard, Ra as Legend, Ga as Lightbox, Ka as LightboxContent, qa as LightboxGallery, Ja as LightboxRoot, Ya as LightboxTrigger, Mr as Link, Jn as LinkButton, ji as List, Mi as ListItem, dr as Loader, Le as LoadingIcon, pr as LoadingOverlay, Re as LogInIcon, ze as LogOutIcon, Ni as Marquee, w as Masonry, Be as MaximizeIcon, on as Mentions, Ea as Menu, Da as MenuDivider, Oa as MenuItem, ka as MenuItemGroup, ri as Menubar, Ve as MinimizeIcon, He as MinusIcon, lo as ModelSelector, Ue as MonitorIcon, We as MoonIcon, Ge as MoreHorizontalIcon, Ke as MoreVerticalIcon, cn as MultiSelect, qe as MuteIcon, B as Navbar, V as NavbarBrand, H as NavbarContent, U as NavbarItem, W as NavbarLink, G as NavbarMenu, K as NavbarMenuItem, q as NavbarToggle, mr as Notification, hr as NotificationProvider, ln as NumberInput, un as OtpInput, Ur as Pagination, Wr as PaginationPage, Je as PaperclipIcon, dn as PasswordInput, Qn as PasswordStrength, Ye as PauseIcon, Xe as PdfIcon, Ze as PhoneIcon, fn as PhoneInput, Qe as PipIcon, $e as PlayIcon, et as PlusIcon, Fa as Popconfirm, ja as Popover, Ma as PopoverClose, Na as PopoverContent, Pa as PopoverTrigger, O as Portal, _r as Progress, tt as ProjectIcon, $a as PromptInput, $i as PullToRefresh, Xn as QueryBuilder, pn as Radio, mn as RadioGroup, ui as RangeCalendar, Tn as RangeSlider, En as Rating, na as Reaction, nt as RefreshIcon, ia as RelativeTime, rt as RepeatIcon, vr as Result, wn as RichTextEditor, J as ScrollArea, yr as ScrollProgress, it as SearchIcon, Dn as SearchInput, An as SegmentedControl, jn as Select, at as SendIcon, ot as SettingsIcon, st as ShareIcon, ct as ShuffleIcon, Q as Sidebar, $ as SidebarContent, ee as SidebarFooter, te as SidebarHeader, ne as SidebarItem, Mn as SignaturePad, Y as SimpleGrid, br as Skeleton, lt as SkipBackIcon, ut as SkipForwardIcon, Nn as Slider, kn as SmartSearchInput, dt as SmartphoneIcon, xr as Snackbar, Sr as SnackbarProvider, Yi as SortableList, Xi as SortableListDragHandle, Zi as SortableListItem, ro as SourceCitation, io as SourceCitationList, Ba as Span, ei as SpeedDial, fr as Spinner, ft as SpinnerIcon, X as Splitter, Va as Spoiler, pt as SquareIcon, Z as Stack, mt as StarIcon, Pi as Stats, Fi as StatsDescription, Ii as StatsLabel, Li as StatsTrend, Ri as StatsValue, Gr as Stepper, Aa as SubMenu, ht as SunIcon, Qi as SwipeAction, Pn as Switch, Fn as SwitchGroup, Kr as TabBar, qr as TabBarItem, Jr as TabNavigation, Yr as TabNavigationItem, mi as Table, hi as TableBody, gi as TableCell, _i as TableFooter, vi as TableHead, yi as TableHeader, bi as TableRow, Xr as Tabs, Zr as TabsContent, Qr as TabsList, $r as TabsTrigger, er as Tag, tr as TagInput, oo as Terminal, zt as Text, an as Textarea, or as ThemeToggle, eo as ThoughtProcess, to as ThoughtStep, fo as ThreadList, gt as ThumbDownIcon, _t as ThumbUpIcon, In as TimePicker, zi as Timeline, Bi as TimelineConnector, Vi as TimelineContent, Hi as TimelineItem, Ui as TimelineOppositeContent, Wi as TimelinePoint, Gi as TimelineSeparator, Ki as Title, wr as Toast, Tr as ToastProvider, Ln as ToggleGroup, po as TokenCounter, Mt as Toolbar, Nt as ToolbarGroup, Pt as ToolbarSeparator, Un as Tooltip, Wn as TooltipContent, Gn as TooltipTrigger, Dr as Tour, zn as Transfer, k as Transition, vt as TrashIcon, Hn as TreeSelect, Bn as TreeView, Vn as TreeViewItem, yt as UploadIcon, mo as UsageMeter, bt as UserIcon, Wa as Video, xt as VideoIcon, Rn as VirtualList, re as VisuallyHidden, co as VoiceVisualizer, St as VolumeIcon, ie as Watermark, Oo as WimProvider, fi as getNextSortDirection, Eo as getWimDensity, T as getWimLocale, ir as getWimTheme, Do as setWimDensity, E as setWimLocale, ar as setWimTheme, On as useAutoResize, Co as useBreakpoint, wo as useBreakpointDown, To as useBreakpointUp, Cn as useDialog, z as useDrawer, Xa as useLightbox, xo as useMediaQuery, gr as useNotification, Cr as useSnackbar, pi as useTableSort, Er as useToast, ko as useWim };
+import { WIM_PRESETS as Oo } from "./tokens/generated/presets.js";
+import { getWimPreset as ko, setWimPreset as Ao } from "./preset.js";
+import { WimProvider as jo, useWim as Mo } from "./WimProvider.js";
+export { no as AIResponseFeedback, Ct as ALL_ICONS, ii as Accordion, ai as AccordionContent, oi as AccordionItem, si as AccordionTrigger, kr as Affix, so as AgentStatus, sr as Alert, ae as AlertCircleIcon, oe as AlignJustifyIcon, Ar as Anchor, e as AppShell, t as AppShellBody, n as AppShellFooter, r as AppShellHeader, i as AppShellMain, a as AppShellNavbar, o as AppShellRoot, s as AppShellSidebar, c as AspectRatio, Ha as Audio, Or as Autosave, ci as Avatar, li as AvatarGroup, So as BREAKPOINTS, jr as BackTop, Lt as Badge, cr as Banner, se as BellIcon, l as BentoGrid, u as BentoGridItem, za as Blockquote, oa as BottomSheet, sa as BottomSheetBody, ca as BottomSheetClose, la as BottomSheetContent, ua as BottomSheetDescription, da as BottomSheetFooter, fa as BottomSheetHeader, pa as BottomSheetTitle, ma as BottomSheetTrigger, d as Box, Nr as Breadcrumb, kt as Button, Ft as ButtonGroup, Yt as Calendar, ta as CalendarHeatmap, ce as CalendarIcon, Tt as Card, Et as CardBody, Dt as CardFooter, Ot as CardHeader, di as Carousel, Ht as Cascader, f as Center, le as ChartIcon, ho as ChatAvatar, go as ChatContainer, _o as ChatInput, vo as ChatInputArea, yo as ChatMessage, bo as ChatMessageList, ue as CheckCircleIcon, de as CheckIcon, Ut as Checkbox, Wt as CheckboxGroup, fe as ChevronDownIcon, pe as ChevronLeftIcon, me as ChevronRightIcon, he as ChevronUpIcon, sn as Chip, ge as CircleIcon, _e as ClockIcon, ye as CloseIcon, ve as CloseSmallIcon, Ia as Code, ao as CodeBlock, Kt as ColorInput, qt as ColorPicker, be as ColumnsIcon, Jt as Combobox, Pr as CommandPalette, Fr as CommandPaletteContent, Ir as CommandPaletteEmpty, Lr as CommandPaletteFooter, Rr as CommandPaletteGroup, zr as CommandPaletteInput, Br as CommandPaletteItem, Vr as CommandPaletteList, Hr as CommandPaletteTrigger, p as Container, ha as ContextMenu, ga as ContextMenuDivider, _a as ContextMenuGroup, va as ContextMenuItem, uo as ConversationList, Kn as CopyButton, xe as CopyIcon, aa as Countdown, rr as CounterTextarea, Se as CreditCardIcon, nr as CreditCardInput, At as Dashboard, jt as DashboardWidgetCard, xi as DataGrid, Xt as DatePicker, Zt as DateRangePicker, Si as DescriptionList, Ci as DescriptionListDetails, wi as DescriptionListItem, Ti as DescriptionListTerm, hn as Dialog, gn as DialogClose, _n as DialogContent, vn as DialogDescription, yn as DialogFooter, bn as DialogHeader, xn as DialogTitle, Sn as DialogTrigger, m as Divider, Ce as DocumentIcon, we as DownloadIcon, j as Drawer, M as DrawerClose, N as DrawerContent, P as DrawerDescription, F as DrawerFooter, I as DrawerHeader, L as DrawerTitle, R as DrawerTrigger, ya as Dropdown, ba as DropdownItem, xa as DropdownMenu, Sa as DropdownTrigger, Qt as Dropzone, Te as EditIcon, Ee as EmailIcon, Ei as EmptyState, lr as ErrorBoundary, De as ExternalLinkIcon, ke as EyeIcon, Oe as EyeOffIcon, qi as FAQSection, Bt as FieldError, Vt as FieldTemplate, $t as Fieldset, en as FileUpload, Ae as FilterIcon, h as Flex, Yn as FloatButton, A as FocusTrap, g as Footer, _ as FooterBottom, v as FooterSection, Za as Gallery, y as Grid, je as GripVerticalIcon, b as Group, D as HamburgerMenu, x as Header, S as HeaderSection, Me as HelpCircleIcon, La as Highlight, Ne as HomeIcon, Pe as HourglassIcon, Ca as HoverCard, wa as HoverCardContent, Ta as HoverCardTrigger, wt as Icon, qn as IconButton, Ua as Image, Qa as ImageCompare, $n as ImageCropper, Fe as ImageIcon, ur as Indicator, Ji as InfiniteScroll, Ie as InfoCircleIcon, Zn as InlineEdit, Gt as Input, It as InputBase, tn as InputGroup, nn as InputGroupText, rn as InputMask, C as InteractiveArea, ea as JsonViewer, Di as Kanban, Oi as KanbanBoard, ki as KanbanCard, Ai as KanbanColumn, ti as Kbd, ni as KeyboardShortcuts, Rt as Label, ra as Leaderboard, Ra as Legend, Ga as Lightbox, Ka as LightboxContent, qa as LightboxGallery, Ja as LightboxRoot, Ya as LightboxTrigger, Mr as Link, Jn as LinkButton, ji as List, Mi as ListItem, dr as Loader, Le as LoadingIcon, pr as LoadingOverlay, Re as LogInIcon, ze as LogOutIcon, Ni as Marquee, w as Masonry, Be as MaximizeIcon, on as Mentions, Ea as Menu, Da as MenuDivider, Oa as MenuItem, ka as MenuItemGroup, ri as Menubar, Ve as MinimizeIcon, He as MinusIcon, lo as ModelSelector, Ue as MonitorIcon, We as MoonIcon, Ge as MoreHorizontalIcon, Ke as MoreVerticalIcon, cn as MultiSelect, qe as MuteIcon, B as Navbar, V as NavbarBrand, H as NavbarContent, U as NavbarItem, W as NavbarLink, G as NavbarMenu, K as NavbarMenuItem, q as NavbarToggle, mr as Notification, hr as NotificationProvider, ln as NumberInput, un as OtpInput, Ur as Pagination, Wr as PaginationPage, Je as PaperclipIcon, dn as PasswordInput, Qn as PasswordStrength, Ye as PauseIcon, Xe as PdfIcon, Ze as PhoneIcon, fn as PhoneInput, Qe as PipIcon, $e as PlayIcon, et as PlusIcon, Fa as Popconfirm, ja as Popover, Ma as PopoverClose, Na as PopoverContent, Pa as PopoverTrigger, O as Portal, _r as Progress, tt as ProjectIcon, $a as PromptInput, $i as PullToRefresh, Xn as QueryBuilder, pn as Radio, mn as RadioGroup, ui as RangeCalendar, Tn as RangeSlider, En as Rating, na as Reaction, nt as RefreshIcon, ia as RelativeTime, rt as RepeatIcon, vr as Result, wn as RichTextEditor, J as ScrollArea, yr as ScrollProgress, it as SearchIcon, Dn as SearchInput, An as SegmentedControl, jn as Select, at as SendIcon, ot as SettingsIcon, st as ShareIcon, ct as ShuffleIcon, Q as Sidebar, $ as SidebarContent, ee as SidebarFooter, te as SidebarHeader, ne as SidebarItem, Mn as SignaturePad, Y as SimpleGrid, br as Skeleton, lt as SkipBackIcon, ut as SkipForwardIcon, Nn as Slider, kn as SmartSearchInput, dt as SmartphoneIcon, xr as Snackbar, Sr as SnackbarProvider, Yi as SortableList, Xi as SortableListDragHandle, Zi as SortableListItem, ro as SourceCitation, io as SourceCitationList, Ba as Span, ei as SpeedDial, fr as Spinner, ft as SpinnerIcon, X as Splitter, Va as Spoiler, pt as SquareIcon, Z as Stack, mt as StarIcon, Pi as Stats, Fi as StatsDescription, Ii as StatsLabel, Li as StatsTrend, Ri as StatsValue, Gr as Stepper, Aa as SubMenu, ht as SunIcon, Qi as SwipeAction, Pn as Switch, Fn as SwitchGroup, Kr as TabBar, qr as TabBarItem, Jr as TabNavigation, Yr as TabNavigationItem, mi as Table, hi as TableBody, gi as TableCell, _i as TableFooter, vi as TableHead, yi as TableHeader, bi as TableRow, Xr as Tabs, Zr as TabsContent, Qr as TabsList, $r as TabsTrigger, er as Tag, tr as TagInput, oo as Terminal, zt as Text, an as Textarea, or as ThemeToggle, eo as ThoughtProcess, to as ThoughtStep, fo as ThreadList, gt as ThumbDownIcon, _t as ThumbUpIcon, In as TimePicker, zi as Timeline, Bi as TimelineConnector, Vi as TimelineContent, Hi as TimelineItem, Ui as TimelineOppositeContent, Wi as TimelinePoint, Gi as TimelineSeparator, Ki as Title, wr as Toast, Tr as ToastProvider, Ln as ToggleGroup, po as TokenCounter, Mt as Toolbar, Nt as ToolbarGroup, Pt as ToolbarSeparator, Un as Tooltip, Wn as TooltipContent, Gn as TooltipTrigger, Dr as Tour, zn as Transfer, k as Transition, vt as TrashIcon, Hn as TreeSelect, Bn as TreeView, Vn as TreeViewItem, yt as UploadIcon, mo as UsageMeter, bt as UserIcon, Wa as Video, xt as VideoIcon, Rn as VirtualList, re as VisuallyHidden, co as VoiceVisualizer, St as VolumeIcon, Oo as WIM_PRESETS, ie as Watermark, jo as WimProvider, fi as getNextSortDirection, Eo as getWimDensity, T as getWimLocale, ko as getWimPreset, ir as getWimTheme, Do as setWimDensity, E as setWimLocale, Ao as setWimPreset, ar as setWimTheme, On as useAutoResize, Co as useBreakpoint, wo as useBreakpointDown, To as useBreakpointUp, Cn as useDialog, z as useDrawer, Xa as useLightbox, xo as useMediaQuery, gr as useNotification, Cr as useSnackbar, pi as useTableSort, Er as useToast, Mo as useWim };

package/dist/llms-full.txt

@@ -4,7 +4,7 @@
 
 ## What this is
 
-**wimui** v0.3.0 — a React 19 component library: 216 documented components across 10 categories, with design tokens, dark mode, i18n (en/ja/pt-BR) and WAI-ARIA compliant a11y. Peer deps: react ^19, react-dom ^19 (plus optional peers for specific components — see package.json).
+**wimui** v0.5.0 — a React 19 component library: 216 documented components across 10 categories, with design tokens, dark mode, i18n (en/ja/pt-BR) and WAI-ARIA compliant a11y. Peer deps: react ^19, react-dom ^19 (plus optional peers for specific components — see package.json).
 
 ## Install & required setup
 
@@ -55,12 +55,17 @@ Single components are judged by state/a11y/token compliance. **Composed screens*
 - Emoji used as UI icons (☰ ★ ✓) → use `src/icon/` components. (Emoji as functional markers in docs/README is fine; as UI icons it is not.)
 - Skeleton used as anything but loading (fake screenshots) → real-looking content or an actual mini UI.
 - Every section center-aligned → default to left-aligned; at most one centered section per page.
-- Round numbers ("1000+", "99%") + generic copy ("Get started", "seamless/powerful/effortless") → jagged realistic numbers (4,281) and product-specific voice.
+- Round numbers ("1000+", "99%") + generic copy ("Get started") → jagged realistic numbers (4,281) and product-specific voice.
 - Sequential/alphabetical dummy names (Alice/Bob/Charlie, User 1/2) → culturally diverse, unordered, real-feeling names.
 - Rainbow color-per-category → color carries state only (success/warning/danger); everything else neutral.
 - Perfectly even grids (2×2, 3×3 all same size) → break the grid (span the protagonist cell, size differences, hero+sidebar asymmetry).
 - Filling every slot / uniform gaps everywhere → leave whitespace; group by proximity (tight within a group, loose between groups).
 
+**Machine-enforced banned vocabulary** (a linter, `check:slop`, fails builds that use these in demo copy — say concrete actions/numbers instead):
+- Hype adjectives/verbs: seamless, powerful, effortless, cutting-edge, next-gen, next-generation, revolutionary, game-changing, state-of-the-art, world-class, best-in-class, unparalleled, lightning-fast, blazing-fast, supercharge, innovative, disruptive, harness, leverage, elevate, empower, reimagine, unleash, delight, magical, 圧倒的, 革新的, 次世代, 究極, 最先端.
+- Hype phrases: "in today's digital landscape", "built for the modern team", "supercharge your", "unleash your", "reimagine the way", "experience the power of", "innovative solutions".
+- Stock placeholder names: John Doe, Jane Doe, John Smith, Jane Smith, Lorem Ipsum, Example User, Acme (a realistic example name in an input placeholder is fine).
+
 **Must rules:**
 1. One visual protagonist per screen (jump in size/weight/color creates the entry point).
 2. Contrast density: hero/showcase sparse, data regions (tables/lists) dense. Uniform "medium density" reads as AI.
@@ -71,6 +76,528 @@ Single components are judged by state/a11y/token compliance. **Composed screens*
 7. Give demo content real substance (product-context copy, internally consistent numbers/dates/names — active ≤ total, dates not evenly spaced).
 8. Add intentional "wobble": mix in 1–2 incomplete rows (a truncated long name, a missing optional field, an extreme value, an error/unread state) and show non-happy-path states (hover/focus/disabled/error/empty/loading).
 
+## Recipes — copy-paste starting points
+
+### 1. Required setup (the contract)
+
+Without `styles.css` nothing is styled — this is the one step Storybook hides from you. Import it once at the app entry, wrap the tree in `WimProvider`, then build screens inside.
+
+```tsx
+// main.tsx — app entry
+import { createRoot } from "react-dom/client";
+import "wimui/styles.css"; // REQUIRED: design tokens + component styles
+import "wimui/reset.css";  // optional base reset
+import { WimProvider } from "wimui";
+import { App } from "./App";
+
+// theme: "light" | "dark" | "system" (default). density: "comfortable" | "compact".
+createRoot(document.getElementById("root")!).render(
+  <WimProvider theme="system" density="comfortable">
+    <App />
+  </WimProvider>,
+);
+```
+
+```tsx
+// App.tsx — app frame. AppShell wires header/sidebar; page content is children.
+import { AppShell, Header, Sidebar, Stack, Title, Text, Button } from "wimui";
+
+export function App() {
+  return (
+    <AppShell
+      header={<Header sticky bordered><Title tag="h1" size="md">Larkfield</Title></Header>}
+      sidebar={
+        <Sidebar width={240}>
+          <Stack gap="2xs" p="md">
+            <Button variant="ghost" justify="start" fullWidth>Overview</Button>
+            <Button variant="ghost" justify="start" fullWidth>Customers</Button>
+            <Button variant="ghost" justify="start" fullWidth>Settings</Button>
+          </Stack>
+        </Sidebar>
+      }
+    >
+      <Stack gap="lg">
+        <Title tag="h2" size="lg">Overview</Title>
+        <Text color="secondary">Spacing/size/color come from --wim-* tokens via props — never hardcode px/hex.</Text>
+      </Stack>
+    </AppShell>
+  );
+}
+```
+
+### 2. A composed content screen
+
+One protagonist (the KPI row), a dense table below, tokens via props, jagged real data, and one deliberately incomplete row. Note the compound components (`Stats.Value`, `Table.Head`) and that `Grid` uses `cols` (not `columns`).
+
+```tsx
+import { Stack, Grid, Card, Stats, Table, Badge, Title, Text } from "wimui";
+
+const rows = [
+  { id: "in_9f2a", name: "Marisol Okonkwo", plan: "Scale", amount: "$4,610.50", status: "paid" },
+  { id: "in_7b41", name: "Dmitri Sørensen", plan: "Enterprise", amount: "$12,199.00", status: "failed" },
+  { id: "in_2a90", name: "Thomas O'Reilly", plan: null, amount: "$89.00", status: "pending" }, // incomplete row
+];
+const intent = { paid: "success", failed: "danger", pending: undefined } as const;
+
+export function BillingOverview() {
+  return (
+    <Stack gap="lg">
+      <Title tag="h2" size="lg">Billing</Title>
+
+      {/* Protagonist: KPI row. Uneven content per tile — not three clones. */}
+      <Grid cols={{ base: 1, sm: 2, lg: 3 }} gap="md">
+        <Stats><Stats.Label>MRR</Stats.Label><Stats.Value>$48,210</Stats.Value><Stats.Trend>+6.4%</Stats.Trend></Stats>
+        <Stats><Stats.Label>Active workspaces</Stats.Label><Stats.Value>1,204</Stats.Value><Stats.Description>176 idle over 30 days</Stats.Description></Stats>
+        <Stats><Stats.Label>Failed webhooks</Stats.Label><Stats.Value>137</Stats.Value><Stats.Trend>+23 today</Stats.Trend></Stats>
+      </Grid>
+
+      {/* Dense data region */}
+      <Card padding="none">
+        <Table hoverable fullWidth>
+          <Table.Header>
+            <Table.Row>
+              <Table.Head>Customer</Table.Head><Table.Head>Plan</Table.Head>
+              <Table.Head>Amount</Table.Head><Table.Head>Status</Table.Head>
+            </Table.Row>
+          </Table.Header>
+          <Table.Body>
+            {rows.map((r) => (
+              <Table.Row key={r.id}>
+                <Table.Cell>{r.name}</Table.Cell>
+                <Table.Cell>{r.plan ?? <Text color="tertiary">—</Text>}</Table.Cell>
+                <Table.Cell>{r.amount}</Table.Cell>
+                <Table.Cell><Badge variant="subtle" intent={intent[r.status]}>{r.status}</Badge></Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+        </Table>
+      </Card>
+    </Stack>
+  );
+}
+```
+
+### 3. Auth — sign-in screen
+
+A focused single-protagonist screen: one centered card, a left-aligned form. Not the generic badge→heading→two-buttons hero. Real product context in the copy.
+
+```tsx
+import { Center, Card, Stack, Group, Title, Text, Input, PasswordInput, Checkbox, Button, Link } from "wimui";
+
+export function SignIn() {
+  return (
+    <Center h="100dvh" p="lg">
+      <Card padding="lg" style={{ width: "min(380px, 100%)" }}>
+        <Stack gap="lg">
+          <Stack gap="2xs">
+            <Title tag="h1" size="lg">Sign in to Larkfield</Title>
+            <Text color="secondary">Use your work email — SSO is enabled for Enterprise workspaces.</Text>
+          </Stack>
+          <form onSubmit={(e) => e.preventDefault()}>
+            <Stack gap="md">
+              <Input label="Work email" type="email" placeholder="you@company.com" fullWidth />
+              <PasswordInput label="Password" fullWidth />
+              <Group justify="between" align="center">
+                <Checkbox>Keep me signed in</Checkbox>
+                <Link href="#" priority="secondary">Forgot password?</Link>
+              </Group>
+              <Button type="submit" variant="solid" fullWidth>Sign in</Button>
+            </Stack>
+          </form>
+          <Text size="sm" color="tertiary">No account? <Link href="#">Start a 14-day trial</Link></Text>
+        </Stack>
+      </Card>
+    </Center>
+  );
+}
+```
+
+### 4. Settings — sectioned form
+
+Dense label-left / control-right rows grouped in one card, separated by `Divider`. Density comes from token gaps, not hardcoded spacing. Actions right-aligned at the bottom.
+
+```tsx
+import { Stack, Group, Title, Text, Card, Divider, Select, Switch, Button } from "wimui";
+
+export function NotificationSettings() {
+  return (
+    <Stack gap="lg" style={{ maxWidth: 720 }}>
+      <Stack gap="2xs">
+        <Title tag="h1" size="lg">Notifications</Title>
+        <Text color="secondary">Control what Larkfield emails you about. Changes apply immediately.</Text>
+      </Stack>
+
+      <Card padding="lg">
+        <Stack gap="md">
+          <SettingRow label="Deliverability alerts" hint="Bounce-rate spikes and blocklist hits.">
+            <Switch defaultChecked />
+          </SettingRow>
+          <Divider />
+          <SettingRow label="Weekly summary" hint="Every Monday, 09:00 in your timezone.">
+            <Switch />
+          </SettingRow>
+          <Divider />
+          <SettingRow label="Digest timezone">
+            <Select
+              aria-label="Digest timezone"
+              value="jst"
+              options={[
+                { label: "Asia/Tokyo (JST)", value: "jst" },
+                { label: "Europe/Berlin (CET)", value: "cet" },
+                { label: "UTC", value: "utc" },
+              ]}
+            />
+          </SettingRow>
+        </Stack>
+      </Card>
+
+      <Group justify="end" gap="sm">
+        <Button variant="ghost">Reset</Button>
+        <Button variant="solid">Save changes</Button>
+      </Group>
+    </Stack>
+  );
+}
+
+// Local helper: label-left / control-right row. One protagonist per row = the control.
+function SettingRow({ label, hint, children }: { label: string; hint?: string; children: React.ReactNode }) {
+  return (
+    <Group justify="between" align="center" gap="md">
+      <Stack gap="3xs">
+        <Text weight="medium">{label}</Text>
+        {hint ? <Text size="sm" color="secondary">{hint}</Text> : null}
+      </Stack>
+      {children}
+    </Group>
+  );
+}
+```
+
+### 5. Empty state — a real zero state, not a shrug
+
+One protagonist (the primary action), calm copy that says *why* it's empty and what happens next. Reuse the `EmptyState` component instead of hand-rolling centered divs.
+
+```tsx
+import { Center, EmptyState, Button } from "wimui";
+import { DocumentIcon } from "wimui/icons";
+
+export function NoInvoices() {
+  return (
+    <Center h="60dvh" p="lg">
+      <EmptyState
+        icon={<DocumentIcon />}
+        title="No invoices yet"
+        description="Invoices show up here after your first billing cycle closes. Nothing is due today."
+        extra={<Button variant="solid">Create a manual invoice</Button>}
+      />
+    </Center>
+  );
+}
+```
+
+### 6. Filtered data table — toolbar + table
+
+A search/filter toolbar as the sparse region above a dense table. Filtering is client-side here; swap in your query. Note the deliberately jagged data: a failed row, a member with no team (incomplete), and a long name.
+
+```tsx
+import { Stack, Group, SearchInput, Select, Table, Badge, Text } from "wimui";
+import { useMemo, useState } from "react";
+
+const members = [
+  { id: "u_1", name: "Marisol Okonkwo", team: "Growth", role: "admin", status: "active" },
+  { id: "u_2", name: "Dmitri Sørensen", team: "Platform", role: "member", status: "invited" },
+  { id: "u_3", name: "Aleksandra Wiśniewska-Nowak", team: null, role: "member", status: "active" }, // no team
+  { id: "u_4", name: "Thomas O'Reilly", team: "Growth", role: "member", status: "suspended" }, // non-happy path
+];
+const roleIntent = { admin: "primary", member: undefined } as const;
+const statusIntent = { active: "success", invited: undefined, suspended: "danger" } as const;
+
+export function MembersTable() {
+  const [q, setQ] = useState("");
+  const [role, setRole] = useState("all");
+
+  const rows = useMemo(
+    () =>
+      members.filter(
+        (m) =>
+          (role === "all" || m.role === role) &&
+          m.name.toLowerCase().includes(q.trim().toLowerCase()),
+      ),
+    [q, role],
+  );
+
+  return (
+    <Stack gap="md">
+      {/* Sparse toolbar */}
+      <Group justify="between" align="center" gap="md">
+        <SearchInput
+          placeholder="Search members"
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          allowClear
+          width={280}
+        />
+        <Select
+          aria-label="Filter by role"
+          value={role}
+          onChange={setRole}
+          options={[
+            { label: "All roles", value: "all" },
+            { label: "Admins", value: "admin" },
+            { label: "Members", value: "member" },
+          ]}
+        />
+      </Group>
+
+      {/* Dense data region */}
+      <Table hoverable fullWidth>
+        <Table.Header>
+          <Table.Row>
+            <Table.Head>Member</Table.Head><Table.Head>Team</Table.Head>
+            <Table.Head>Role</Table.Head><Table.Head>Status</Table.Head>
+          </Table.Row>
+        </Table.Header>
+        <Table.Body>
+          {rows.map((m) => (
+            <Table.Row key={m.id}>
+              <Table.Cell>{m.name}</Table.Cell>
+              <Table.Cell>{m.team ?? <Text color="tertiary">No team</Text>}</Table.Cell>
+              <Table.Cell><Badge variant="subtle" intent={roleIntent[m.role]}>{m.role}</Badge></Table.Cell>
+              <Table.Cell><Badge variant="subtle" intent={statusIntent[m.status]}>{m.status}</Badge></Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table>
+    </Stack>
+  );
+}
+```
+
+### 7. Onboarding — a stepper flow
+
+The `Stepper` shows where you are; the card is the single focused task for the current step. Starts mid-flow (step 1) so it reads like a real session, not a fresh render.
+
+```tsx
+import { Stack, Card, Stepper, Title, Text, Group, Button, Input } from "wimui";
+import { useState } from "react";
+
+const steps = [
+  { title: "Account", description: "Your details" },
+  { title: "Workspace", description: "Name & URL" },
+  { title: "Invite", description: "Optional" },
+];
+
+export function Onboarding() {
+  const [current, setCurrent] = useState(1); // mid-flow
+  const back = () => setCurrent((c) => Math.max(0, c - 1));
+  const next = () => setCurrent((c) => Math.min(steps.length - 1, c + 1));
+
+  return (
+    <Stack gap="lg" style={{ maxWidth: 640 }}>
+      <Stepper steps={steps} current={current} onChange={setCurrent} />
+
+      <Card padding="lg">
+        <Stack gap="md">
+          <Stack gap="2xs">
+            <Title tag="h2" size="md">Name your workspace</Title>
+            <Text color="secondary">You can change this later in Settings — existing links keep working.</Text>
+          </Stack>
+          <Input label="Workspace name" placeholder="Acme Inc." fullWidth />
+        </Stack>
+      </Card>
+
+      <Group justify="between" align="center">
+        <Button variant="ghost" onClick={back} disabled={current === 0}>Back</Button>
+        <Button variant="solid" onClick={next}>Continue</Button>
+      </Group>
+    </Stack>
+  );
+}
+```
+
+## Idioms — per-category minimal combinations
+
+Smaller than the full-screen recipes above: the canonical way to wire one
+category together. Same rules apply (tokens via props, real copy, show a
+non-happy-path state).
+
+### Form — field + validation + submit
+
+The field owns its own label and error: pass `error` a **string** to render the message and the danger state together. No wrapper component needed.
+
+```tsx
+import { Stack, Input, Textarea, Button } from "wimui";
+import { useState } from "react";
+
+export function ContactForm() {
+  const [email, setEmail] = useState("");
+  const [error, setError] = useState<string>();
+
+  function submit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(email.includes("@") ? undefined : "Enter a valid work email.");
+  }
+
+  return (
+    <form onSubmit={submit} noValidate>
+      <Stack gap="md" style={{ maxWidth: 420 }}>
+        <Input
+          label="Work email"
+          type="email"
+          required
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          error={error}          // string → message + danger intent
+          fullWidth
+        />
+        <Textarea label="What do you need help with?" fullWidth />
+        <Button type="submit" variant="solid">Send</Button>
+      </Stack>
+    </form>
+  );
+}
+```
+
+### Navigation — sidebar (desktop) ⇄ tab bar (mobile)
+
+Same destinations, two shells. `AppShell` takes a `sidebar` for wide viewports; `TabBar` (fixed, bottom) is the mobile equivalent — show/hide each with your breakpoint CSS. Active state is data, not duplicated markup.
+
+```tsx
+import { AppShell, Sidebar, Stack, Button, TabBar } from "wimui";
+import { HomeIcon, UserIcon, SettingsIcon } from "wimui/icons";
+
+const nav = [
+  { id: "home", label: "Home", icon: <HomeIcon /> },
+  { id: "people", label: "People", icon: <UserIcon /> },
+  { id: "settings", label: "Settings", icon: <SettingsIcon /> },
+];
+
+export function Shell({
+  tab,
+  onTab,
+  children,
+}: {
+  tab: string;
+  onTab: (id: string) => void;
+  children: React.ReactNode;
+}) {
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar width={240}>
+          <Stack gap="2xs" p="md">
+            {nav.map((n) => (
+              <Button
+                key={n.id}
+                variant={tab === n.id ? "solid" : "ghost"}
+                justify="start"
+                icon={n.icon}
+                fullWidth
+                onClick={() => onTab(n.id)}
+              >
+                {n.label}
+              </Button>
+            ))}
+          </Stack>
+        </Sidebar>
+      }
+    >
+      {children}
+      {/* Mobile: same destinations as a fixed bottom bar */}
+      <TabBar>
+        {nav.map((n) => (
+          <TabBar.Item
+            key={n.id}
+            active={tab === n.id}
+            icon={n.icon}
+            label={n.label}
+            onClick={() => onTab(n.id)}
+          />
+        ))}
+      </TabBar>
+    </AppShell>
+  );
+}
+```
+
+### Feedback — persistent Alert vs. transient toast
+
+Use an inline `Alert` for state that stays true (a limit, an outage); use a toast (`useToast().show`) for a one-off confirmation. Wrap the app once in `ToastProvider`.
+
+```tsx
+import { ToastProvider, useToast, Alert, Button, Stack } from "wimui";
+
+// once, at the app root
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <ToastProvider position="top-right">{children}</ToastProvider>;
+}
+
+export function InvitePanel() {
+  const { show } = useToast();
+  return (
+    <Stack gap="md" style={{ maxWidth: 480 }}>
+      <Alert
+        intent="warning"
+        title="Seat limit reached"
+        description="Your plan includes 5 seats. Remove a member or upgrade to invite more."
+      />
+      <Button
+        variant="solid"
+        onClick={() =>
+          show({
+            intent: "success",
+            title: "Invitation sent",
+            description: "We emailed marisol@okonkwo.dev.",
+          })
+        }
+      >
+        Resend invite
+      </Button>
+    </Stack>
+  );
+}
+```
+
+### Overlay — Dialog wrapping a form
+
+`Dialog` is compound: a `DialogTrigger asChild` around your own button, and `DialogClose asChild` around the cancel action so it dismisses without wiring state. Keep the form inside `DialogContent`.
+
+```tsx
+import {
+  Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle,
+  DialogDescription, DialogFooter, DialogClose, Button, Stack, Input,
+} from "wimui";
+
+export function RenameWorkspace() {
+  return (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button variant="outline">Rename workspace</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Rename workspace</DialogTitle>
+          <DialogDescription>
+            This changes the URL. Existing links keep working via a redirect.
+          </DialogDescription>
+        </DialogHeader>
+        <form onSubmit={(e) => e.preventDefault()}>
+          <Stack gap="md" p="md">
+            <Input label="Workspace name" defaultValue="Larkfield" fullWidth />
+          </Stack>
+          <DialogFooter>
+            <DialogClose asChild>
+              <Button variant="ghost">Cancel</Button>
+            </DialogClose>
+            <Button type="submit" variant="solid">Save</Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}
+```
+
 ## Components
 
 ### layout — `import { … } from "wimui/layout"`
@@ -88,6 +615,7 @@ Single components are judged by state/a11y/token compliance. **Composed screens*
     - `children: React.ReactNode` (required) — Child content
 - **BentoGrid** — Modern card grid
     - `children: React.ReactNode` — Grid items (typically BentoGrid.Item elements)
+    - `rowHeight: string` — Fixed height of each grid row (`grid-auto-rows`). Any CSS length; defaults to `18rem`. Lower it when tiles hold compact content so they don't read as mostly-empty panels.
 - **Box** — Polymorphic box
     - `as: C` — The component used for the root node. Either a string to use a HTML element or a component.
     - `asChild: boolean` = false — If true, the box will be rendered as its child, merging its props onto that child.
@@ -237,6 +765,7 @@ The container-query wrapper div is preserved to maintain responsive column behav
     - `transparent: boolean` — Whether the navbar background is transparent
     - `glass: boolean` — Whether to apply the frosted-glass effect
     - `bordered: boolean` — Whether to show a bottom border
+    - `fluid: boolean` — Expand content to full width (disable the centered max-width container)
     - `defaultMenuOpen: boolean` = false — Initial open state of the mobile menu (uncontrolled)
     - `isMenuOpen: boolean` — Open state of the mobile menu (controlled)
     - `onMenuOpenChange: (isOpen: boolean) => void` — Callback when the mobile menu open state changes