@gradeui/ui 0.9.0 → 1.0.0

package/components/ui/card.md

@@ -0,0 +1,40 @@
+---
+name: Card
+import: "@gradeui/ui"
+subcomponents: [CardHeader, CardTitle, CardDescription, CardContent, CardFooter]
+props:
+  - Each subcomponent accepts native div HTML attrs (className, etc.)
+  - No variants — Card is a flexible container surface; shape via data-card-style and depth via shadow-elevation-* utilities
+when_to_use: Grouped content with a distinct surface — settings panels, dashboard tiles, list-of-cards layouts. Pair CardHeader (title + description) with CardContent and optional CardFooter (actions).
+composes_with: [Button (in CardFooter), Badge, Separator, Avatar, any form controls]
+aliases: [card, group box, groupbox, panel, tile, surface]
+---
+
+Canonical structure — do NOT skip CardHeader if the card has a title:
+
+```jsx
+<Card>
+  <CardHeader>
+    <CardTitle>Billing</CardTitle>
+    <CardDescription>Manage your subscription.</CardDescription>
+  </CardHeader>
+  <CardContent>…</CardContent>
+  <CardFooter>
+    <Button>Save</Button>
+  </CardFooter>
+</Card>
+```
+
+Card is the most common host for Presence affordances. Three independent axes:
+
+```jsx
+// Elevation — pick a depth level (1=minimal, 3=raised, 4=popover, 5=dialog).
+<Card className="shadow-elevation-4">…</Card>
+
+// Surface — opt into glass / translucent backgrounds.
+<Card className="gds-surface-glass shadow-elevation-4">…</Card>
+
+// Aura — radiate AI-attention state. Combinable.
+<Card className="gds-aura-ring">Studio is reviewing this</Card>
+<Card className="gds-aura-ring gds-aura-shimmer">Generating…</Card>
+```

package/components/ui/carousel.md

@@ -0,0 +1,56 @@
+---
+name: Carousel
+import: "@gradeui/ui"
+subcomponents: [Carousel.Slide, Carousel.VideoSlide, Carousel.Dots, Carousel.Arrows]
+props:
+  - Carousel: loop?: boolean — wrap last → first (default true)
+  - Carousel: align?: "start" | "center" | "end" — slide alignment (default start)
+  - Carousel: slidesPerView?: number — how many slides visible at once (default 1)
+  - Carousel: autoplay?: boolean | { delay?: number; pauseOnHover?: boolean; pauseWhenOffscreen?: boolean } — true for defaults (5s, hover/offscreen aware)
+  - Carousel: draggable?: boolean — drag-to-swipe (default true)
+  - Carousel: onSlideChange?: (index: number) => void
+  - Carousel.Slide: duration?: number — per-slide autoplay duration in ms; overrides the carousel default for this slide only
+  - Carousel.VideoSlide: src: string — video URL
+  - Carousel.VideoSlide: poster?: string — image shown until the slide is active
+  - Carousel.VideoSlide: alt?: string — accessible label for the video
+  - Carousel.VideoSlide: loop?: boolean — default true (the chosen video-default behaviour)
+  - Carousel.VideoSlide: controls?: boolean — default false (chosen default = no controls)
+  - Carousel.VideoSlide: fit?: "cover" | "contain" — object-fit (default cover)
+  - Carousel.VideoSlide: duration?: number — same as Carousel.Slide; overrides autoplay timing for THIS slide
+  - Carousel.Dots: position?: "below" | "overlay"
+  - Carousel.Arrows: position?: "overlay" | "outside"
+when_to_use: Anywhere a horizontal stack of slides cycles automatically or on user input — marketing hero rotations, featured rails on a TV / streaming app, onboarding tours, image galleries, product carousels, testimonial cycles. Mixed video + still slides are a first-class case; the VideoSlide handles muted-autoplay + poster swap on activation.
+composes_with: [MediaSurface, Card, Stack, Row]
+aliases: [carousel, slideshow, slider, hero rotation, image gallery, featured row, swipe deck, paged view, page tabview, page view, swiper, react native swiper, page control]
+---
+
+```jsx
+<Carousel autoplay={{ delay: 6000 }} loop>
+  <Carousel.Slide duration={15000}>
+    <MediaSurface aspect="wide" hint="poster" alt="Featured: Severance S2" />
+  </Carousel.Slide>
+
+  <Carousel.VideoSlide
+    src="/trailers/the-studio.mp4"
+    poster="/posters/the-studio.jpg"
+    alt="The Studio — official trailer"
+  />
+
+  <Carousel.Slide>
+    <MediaSurface aspect="wide" hint="poster" alt="Coming soon: Foundation S3" />
+  </Carousel.Slide>
+
+  <Carousel.Arrows />
+  <Carousel.Dots position="overlay" />
+</Carousel>
+```
+
+### Anti-patterns
+
+DO NOT confuse `<Carousel>` with `<Slider>`. `Slider` is the range input (a draggable thumb on a track) — the colloquial "slider" you'd put on a marketing page is a `Carousel`. When the user says "add a slider", check whether they want a range control or a slideshow before reaching for either.
+
+DO NOT pass real `<img>` or `<video>` tags directly as `Carousel.Slide` children when the slide is meant to be a hero media tile. Use `<MediaSurface>` (still slots) or `<Carousel.VideoSlide>` (video slots) so themes, aspect ratios, and the future image-generation pipeline stay consistent. Raw `<img>` inside a slide is fine for fully-authored content (logo strips, certificates), but for "media that might get regenerated" the surface primitive is mandatory.
+
+DO NOT set very short `duration` values (sub-2000ms) on still slides — the autoplay timer ignores the request implicitly when the carousel is paused (hover, offscreen) but very fast cycles read as broken to users. 5-15 seconds per slide is the natural range.
+
+DO NOT mount the autoplay timer inside individual slides via `setInterval` and forget to clean up — use `<Carousel.Slide duration>` instead. The carousel root owns the single timer; per-slide overrides feed into it through a context-shared ref.

package/components/ui/chart.md

@@ -0,0 +1,48 @@
+---
+name: ChartContainer
+import: "@gradeui/ui"
+subcomponents: [ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartStyle]
+notes: ChartContainer wraps a Recharts chart — bring your own Bar/Line/Area/Pie/Radar from "recharts" and place it inside. The wrapper threads design-system tokens through Recharts' style props and provides a styled tooltip + legend.
+props:
+  - ChartContainer: config: ChartConfig — `{ [seriesKey]: { label: string; color?: string; theme?: { light: string; dark: string } } }`; the keys here are the names you reference in your Recharts <Bar dataKey="…" /> calls
+  - ChartContainer: id?: string — used for the inlined <style> tag
+  - ChartContainer: children: React.ReactNode — typically a single Recharts ResponsiveContainer or chart
+  - ChartTooltip: passes through to Recharts <Tooltip> — pair with `content={<ChartTooltipContent />}`
+  - ChartTooltipContent: indicator? "dot" | "line" | "dashed"; hideLabel?, hideIndicator?, nameKey?, labelKey?
+  - ChartLegend / ChartLegendContent: pair the same way for the legend
+when_to_use: Reporting dashboards, single-purpose analytics cards (revenue, conversions, active users), or anywhere you'd otherwise hand-roll a Recharts setup. Bring the actual chart type from `recharts` — ChartContainer doesn't pick the chart shape for you, it themes whatever you nest. For sparkline-style decorative trends consider just rendering a small SVG line directly; ChartContainer is overkill for non-interactive ornament.
+composes_with: [Card (chart-in-a-card pattern), Tabs (multi-metric switcher), Recharts components (Bar, Line, Area, Pie, Radar from "recharts")]
+aliases: [chart, charts, graph, bar chart, line chart, area chart, recharts, analytics chart, swift chart, swiftui chart, victory chart, victory native]
+---
+
+```jsx
+// Revenue-by-month bar chart inside a Card.
+import { Bar, BarChart, CartesianGrid, XAxis } from "recharts";
+
+const data = [
+  { month: "Jan", revenue: 12400 },
+  { month: "Feb", revenue: 14210 },
+  { month: "Mar", revenue: 15880 },
+  { month: "Apr", revenue: 17050 },
+];
+
+const config = {
+  revenue: { label: "Revenue", color: "hsl(var(--primary))" },
+} satisfies ChartConfig;
+
+<Card>
+  <CardHeader>
+    <CardTitle>Revenue</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <ChartContainer config={config} className="h-64">
+      <BarChart data={data}>
+        <CartesianGrid vertical={false} />
+        <XAxis dataKey="month" tickLine={false} axisLine={false} />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Bar dataKey="revenue" fill="var(--color-revenue)" radius={4} />
+      </BarChart>
+    </ChartContainer>
+  </CardContent>
+</Card>
+```

package/components/ui/checkbox.md

@@ -0,0 +1,20 @@
+---
+name: Checkbox
+import: "@gradeui/ui"
+props:
+  - checked?: boolean | "indeterminate"
+  - onCheckedChange?: (checked: boolean) => void
+  - defaultChecked?: boolean
+  - disabled?: boolean
+  - id?: string — bind a Label's htmlFor to this
+when_to_use: Binary on/off tied to a list (select multiple, agree to terms). Single on/off that controls a setting is better with Switch.
+composes_with: [Label (via htmlFor), Card, Form rows, Table (for row selection)]
+aliases: [checkbox, tickbox, tick box, check, multi-select item]
+---
+
+```jsx
+<div className="flex items-center gap-2">
+  <Checkbox id="terms" />
+  <Label htmlFor="terms">I agree to the terms</Label>
+</div>
+```

package/components/ui/collapsible.md

@@ -0,0 +1,28 @@
+---
+name: Collapsible
+import: "@gradeui/ui"
+subcomponents: [CollapsibleTrigger, CollapsibleContent]
+props:
+  - Collapsible: open?: boolean — controlled open state
+  - Collapsible: defaultOpen?: boolean — uncontrolled initial state
+  - Collapsible: onOpenChange?: (open: boolean) => void
+  - CollapsibleTrigger: children: React.ReactNode — the clickable header (often a Button asChild)
+  - CollapsibleContent: children: React.ReactNode — the content that animates in/out
+when_to_use: A single show/hide reveal — "Show advanced settings" rows, expandable inline help, "More details" sections inside cards. For multiple rows of expandable content where one-at-a-time matters, reach for Accordion. For a separate panel that floats above content, use Popover.
+composes_with: [Button (as the trigger, asChild), Card (expandable settings group), Row (header + chevron)]
+aliases: [collapsible, expand, show more, disclosure, advanced settings, disclosure group, expandable section, expandable view, show hide]
+---
+
+```jsx
+<Collapsible defaultOpen={false}>
+  <CollapsibleTrigger asChild>
+    <Button variant="ghost" size="sm">
+      Advanced settings <ChevronDown />
+    </Button>
+  </CollapsibleTrigger>
+  <CollapsibleContent className="space-y-2 pt-2">
+    <Label htmlFor="cors">CORS origins</Label>
+    <Input id="cors" placeholder="https://example.com" />
+  </CollapsibleContent>
+</Collapsible>
+```

package/components/ui/command.md

@@ -0,0 +1,38 @@
+---
+name: Command
+import: "@gradeui/ui"
+subcomponents: [CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut, CommandDialog]
+props:
+  - Command: value?: string — controlled active item value
+  - Command: onValueChange?: (value: string) => void
+  - CommandInput: placeholder?: string
+  - CommandList: children: React.ReactNode — wraps groups and empty state
+  - CommandEmpty: children: React.ReactNode — fallback when no items match
+  - CommandGroup: heading?: string
+  - CommandItem: value?: string — used for filter matching and selection emit
+  - CommandItem: onSelect?: (value: string) => void
+  - CommandItem: disabled?: boolean
+  - CommandShortcut: children: React.ReactNode — right-aligned keyboard hint (⌘K, ⌥F)
+  - CommandDialog: open, onOpenChange — when you want the command palette mounted in a modal (cmd+k pattern)
+when_to_use: A searchable list of actions or destinations — global ⌘K palettes, "jump to" inputs, account switchers with filter. Wrap in CommandDialog when it should pop over the entire app on a hotkey. For straight forms with filter, prefer a Select with a search input. For free-text autocomplete tied to a single value, prefer Combobox built on Popover + Command.
+composes_with: [Dialog (CommandDialog wraps it), Popover (inline combobox), Tooltip]
+aliases: [command palette, command menu, cmd k, quick switcher, action menu, spotlight, spotlight search, quick open, fuzzy finder]
+---
+
+```jsx
+// Global ⌘K palette — toggled with a keydown listener at the app root.
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <CommandInput placeholder="Type a command…" />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Navigate">
+      <CommandItem onSelect={() => router.push("/docs")}>
+        <Book /> Docs <CommandShortcut>⌘D</CommandShortcut>
+      </CommandItem>
+      <CommandItem onSelect={() => router.push("/studio")}>
+        <Sparkles /> Studio <CommandShortcut>⌘S</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandDialog>
+```

package/components/ui/date-picker.md

@@ -0,0 +1,52 @@
+---
+name: DatePicker
+import: "@gradeui/ui"
+props:
+  - value?: Date (single) | DateRange (range)
+  - onChange?: (value) => void — called on select or clear
+  - placeholder?: string — trigger label when empty (default "Pick a date" / "Pick a date range")
+  - disabled?: boolean
+  - format?: string — date-fns format token for the trigger label (default "PPP" single, "LLL dd, y" range)
+  - align?: "start" | "center" | "end" — popover align (default "start")
+  - side?: "top" | "right" | "bottom" | "left" — popover side
+  - captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years"
+  - className?: string — on the trigger button
+  - contentClassName?: string — on the PopoverContent
+  - icon?: ReactNode — replaces the default CalendarIcon
+  - numberOfMonths?: number — DateRangePicker only, default 2
+when_to_use: Any date or date-range entry. Use DatePicker for a single date (DOB, due date, booking). Use DateRangePicker for a span (report period, stay dates, filter window). Prefer these over <Input type="date"> — consistent theming, keyboard nav, a11y, and no browser-native UI drift.
+composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
+subcomponents: [DateRangePicker]
+aliases: [datepicker, calendar input, date field, date range, datepickerios, react native date picker, calendar input field, date field control]
+---
+
+```jsx
+// Single date
+<div className="grid gap-1.5">
+  <Label htmlFor="dob">Date of birth</Label>
+  <DatePicker
+    value={date}
+    onChange={setDate}
+    placeholder="Select your birthday"
+  />
+</div>
+```
+
+```jsx
+// Date range
+<DateRangePicker
+  value={range}
+  onChange={setRange}
+  numberOfMonths={2}
+/>
+```
+
+```jsx
+// With presets — pair with Button shortcuts
+<div className="flex items-center gap-2">
+  <DatePicker value={date} onChange={setDate} />
+  <Button variant="outline" size="sm" onClick={() => setDate(new Date())}>Today</Button>
+</div>
+```
+
+Built internally from Popover + Button + Calendar. If you need a custom trigger or different popover positioning, compose the primitives directly — Calendar and Popover are exported from the same barrel.

package/components/ui/dialog.md

@@ -0,0 +1,40 @@
+---
+name: Dialog
+import: "@gradeui/ui"
+subcomponents: [DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose]
+props:
+  - Dialog: open?, onOpenChange? — Radix controlled/uncontrolled pattern
+  - DialogTrigger: asChild? (wrap a Button)
+  - DialogContent: accepts native div HTML attrs
+  - DialogFooter: used for action rows
+when_to_use: Modal interruptions — confirmations, focused forms, detail views. Dialog is the right primitive for Apple HIG / React Native "Alert" (modal) semantics. For non-blocking inline messaging use Callout; for transient notifications use Toaster (Sonner). Always include DialogTitle (a11y requirement).
+composes_with: [Button (as DialogTrigger asChild, and inside DialogFooter), Input/Textarea/Select inside DialogContent]
+aliases: [modal, popup, overlay, alert, system alert, alert dialog, modal dialog, confirm dialog, react native modal, rn alert]
+---
+
+```jsx
+<Dialog>
+  <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Delete project?</DialogTitle>
+      <DialogDescription>This cannot be undone.</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button variant="destructive">Delete</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+DialogContent ships at elevation-5. Reach for the raised Button variant inside DialogFooter when the action carries weight ("Delete", "Publish", "Ship"):
+
+```jsx
+<DialogFooter>
+  <Button variant="outline">Cancel</Button>
+  <Button variant="raised" style={{ "--btn-glow": "var(--destructive)" }}>
+    Delete forever
+  </Button>
+</DialogFooter>
+```

package/components/ui/dropdown-menu.md

@@ -0,0 +1,45 @@
+---
+name: DropdownMenu
+import: "@gradeui/ui"
+subcomponents: [DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuGroup, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent]
+props:
+  - DropdownMenu: open?, defaultOpen?, onOpenChange?, modal? (default true)
+  - DropdownMenuTrigger: asChild?: boolean — usually wraps a Button
+  - DropdownMenuContent: align? "start" | "center" | "end"; side? "top" | "right" | "bottom" | "left"; sideOffset? number
+  - DropdownMenuItem: onSelect?, disabled?, asChild?, inset?
+  - DropdownMenuCheckboxItem / DropdownMenuRadioItem: checked? / value, onCheckedChange? / onValueChange? (radio is on the group)
+  - DropdownMenuSub / DropdownMenuSubTrigger / DropdownMenuSubContent: nested menu — sub-trigger shows children, sub-content holds the deeper items
+  - DropdownMenuShortcut: children — right-aligned kbd hint
+when_to_use: A small action menu attached to a trigger — overflow "…" buttons on cards, user-avatar menus in headers, "Insert" menus in editors. For a full searchable list, use Command. For ONE primary action plus a secondary, use a Button next to a smaller ghost Button instead of a dropdown.
+composes_with: [Button (as trigger asChild), Avatar (user menu), Card (overflow on a tile), Tooltip (on the trigger)]
+aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action menu, context-style menu, menu, pull-down menu, pulldown menu, context menu, popup menu, actions menu]
+---
+
+```jsx
+// Overflow menu on a card/row — trigger an icon-only Button.
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon" aria-label="Open menu">
+      <MoreHorizontal />
+    </Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="end">
+    <DropdownMenuItem onSelect={onDuplicate}>
+      <Copy /> Duplicate
+    </DropdownMenuItem>
+    <DropdownMenuItem onSelect={onShare}>
+      <Share2 /> Share
+    </DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem onSelect={onDelete} className="text-destructive">
+      <Trash /> Delete
+    </DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+DropdownMenuContent ships at elevation-4. For frosted overlays on rich canvases, opt into glass:
+
+```jsx
+<DropdownMenuContent className="gds-surface-glass">…</DropdownMenuContent>
+```

package/components/ui/flex.md

@@ -0,0 +1,41 @@
+---
+name: Flex
+import: "@gradeui/ui"
+role: layout
+props:
+  - direction?: "row" | "col" | "row-reverse" | "col-reverse" (default "row") — main-axis direction
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "none") — gap between children
+  - align?: "start" | "center" | "end" | "stretch" | "baseline" (default "stretch") — cross-axis alignment
+  - justify?: "start" | "center" | "end" | "between" | "around" | "evenly" (default "start") — main-axis distribution
+  - wrap?: "nowrap" | "wrap" | "wrap-reverse" (default "nowrap") — wrap behaviour when children overflow
+  - asChild?: boolean (default false) — render as the child element via Slot
+  - className?: string
+  - children: React.ReactNode
+when_to_use: The unopinionated flexbox primitive — reach for Flex when Stack, Row, or Grid don't quite fit. Specifically when you need reverse direction (`row-reverse` / `col-reverse`), CSS defaults instead of Row's baked-in `items-center gap-md`, or baseline alignment. Otherwise prefer Stack / Row / Grid — they're easier to read and tuned for the 95% case. Flex is the escape hatch, not the default.
+composes_with: [any content component]
+aliases: [flex, flexbox, flex container, hstack, vstack, horizontal, vertical, generic container, layout view]
+---
+
+```jsx
+// Reverse direction — last child appears first (e.g. timestamp before avatar).
+<Flex direction="row-reverse" gap="sm" align="center">
+  <Avatar />
+  <span>2m ago</span>
+</Flex>
+```
+
+```jsx
+// CSS-default Flex — no rhythm baked in, opt into each axis deliberately.
+<Flex direction="col" justify="between" className="h-full">
+  <Header />
+  <Footer />
+</Flex>
+```
+
+```jsx
+// Baseline alignment for icon + text where the caps line should line up.
+<Flex gap="sm" align="baseline">
+  <Icon />
+  <h2 className="text-2xl">Heading</h2>
+</Flex>
+```

package/components/ui/grid.md

@@ -0,0 +1,44 @@
+---
+name: Grid
+import: "@gradeui/ui"
+role: layout
+props:
+  - cols?: "1" | "2" | "3" | "4" | "5" | "6" | "12" (default "3") — desktop column count; each value has a baked-in responsive ladder (e.g. "4" → 1 col mobile, 2 tablet, 4 desktop)
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "md") — gap between grid cells (same scale as Stack/Row)
+  - align?: "start" | "center" | "end" | "stretch" (default "stretch") — cross-axis alignment of cells
+  - asChild?: boolean (default false) — render as the child element via Slot
+  - className?: string
+  - children: React.ReactNode
+when_to_use: 2D layouts where Stack (vertical) and Row (horizontal) don't fit — stat-card grids, feature tiles, pricing columns, photo grids. Reach for Grid over hand-rolled `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4` so the column count is a prop the settings panel can mutate and the responsive ladder stays consistent across designs.
+composes_with: [Card, Stack (inside each cell), Row, Button, any content component]
+aliases: [grid, tiles, cards grid, stat grid, columns, feature grid, grid view, lazy v grid, lazyvgrid, lazy h grid, lazyhgrid, tile grid, masonry]
+notes: |
+  `cols` values and their responsive ladders:
+    "1"  → grid-cols-1 (single column at all breakpoints)
+    "2"  → grid-cols-1 md:grid-cols-2
+    "3"  → grid-cols-1 sm:grid-cols-2 md:grid-cols-3
+    "4"  → grid-cols-1 sm:grid-cols-2 lg:grid-cols-4  (the canonical stat-card grid)
+    "5"  → grid-cols-1 sm:grid-cols-2 lg:grid-cols-5
+    "6"  → grid-cols-2 sm:grid-cols-3 lg:grid-cols-6
+    "12" → grid-cols-4 md:grid-cols-6 lg:grid-cols-12
+  Prefer Grid over bespoke Tailwind grid classes — "gap-md" etc. are NOT real Tailwind classes (the gap scale is numeric: gap-4, gap-6) so hand-rolled grids often end up with zero gap.
+---
+
+```jsx
+// Stat-card grid — the canonical 4-up.
+<Grid cols="4" gap="md">
+  <Card>…</Card>
+  <Card>…</Card>
+  <Card>…</Card>
+  <Card>…</Card>
+</Grid>
+```
+
+```jsx
+// Three-column feature grid with larger gaps.
+<Grid cols="3" gap="lg">
+  <FeatureCard />
+  <FeatureCard />
+  <FeatureCard />
+</Grid>
+```

package/components/ui/hover-card.md

@@ -0,0 +1,35 @@
+---
+name: HoverCard
+import: "@gradeui/ui"
+subcomponents: [HoverCardTrigger, HoverCardContent]
+props:
+  - HoverCard: open?, defaultOpen?, onOpenChange?, openDelay? (default 700), closeDelay? (default 300)
+  - HoverCardTrigger: asChild?: boolean — usually a Link or Button
+  - HoverCardContent: side?, align?, sideOffset?, alignOffset?, className?
+when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
+composes_with: [Avatar (user preview), Card (richer content), Link (the trigger)]
+aliases: [hover card, hover preview, mention preview, profile peek, link preview, rich tooltip, link preview card, profile hover, peek card]
+---
+
+```jsx
+// User mention preview — pointer-only enrichment.
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <a href="/u/elena" className="font-medium underline">@elena</a>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-72">
+    <Row gap="sm" align="start">
+      <Avatar>
+        <AvatarImage src="/avatars/elena.png" />
+        <AvatarFallback>EO</AvatarFallback>
+      </Avatar>
+      <Stack gap="xs">
+        <span className="font-semibold">Elena Okafor</span>
+        <span className="text-sm text-muted-foreground">
+          Design lead · Joined Mar 2025
+        </span>
+      </Stack>
+    </Row>
+  </HoverCardContent>
+</HoverCard>
+```

package/components/ui/input.md

@@ -0,0 +1,17 @@
+---
+name: Input
+import: "@gradeui/ui"
+props:
+  - type?: string (text | email | password | number | search | url | tel | date)
+  - All native input HTML attrs (value, onChange, placeholder, disabled, required)
+when_to_use: Any single-line text entry. Always pair with a Label for accessibility.
+composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
+aliases: [text field, textbox, textfield, form field, text input, secure field, search field, url field, number field, textinput, text input field, react native textinput]
+---
+
+```jsx
+<div className="grid gap-1.5">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" placeholder="you@example.com" />
+</div>
+```

package/components/ui/label.md

@@ -0,0 +1,15 @@
+---
+name: Label
+import: "@gradeui/ui"
+props:
+  - htmlFor?: string — binds to the input's id
+  - All native label HTML attrs
+when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control.
+composes_with: [Input, Textarea, Checkbox, Switch, RadioGroup, Select]
+aliases: [label, form label, field label, caption]
+---
+
+```jsx
+<Label htmlFor="name">Full name</Label>
+<Input id="name" />
+```

package/components/ui/map.md

@@ -0,0 +1,80 @@
+---
+name: Map
+import: "@gradeui/ui"
+subcomponents: [MapMarker]
+aliases: [map, maps, mapbox, maplibre, google maps, geo, location, latlng, coordinates, marker, pin, airbnb, listings, fleet, real estate, logistics, map view, mapkit, mapview, react native maps, rn maps]
+props:
+  - provider — "maplibre" (default, free, no key) | "mapbox" (needs accessToken) | "google" (needs apiKey). Switching is one prop change.
+  - center — `[lng, lat]` tuple. ALWAYS lng first. Required.
+  - zoom — number, 0–22. Required.
+  - bounds — `[[swLng, swLat], [neLng, neLat]]`. When set, takes precedence over center+zoom.
+  - appearance — "light" | "dark" | "satellite" | "auto" (default "auto", follows GradeThemeProvider mode).
+  - hoveredId — controlled string id, pairs with onHoveredIdChange. The matching MapMarker gets `data-gds-state="hovered"` automatically. This is how you build list ↔ map two-way sync.
+  - interactive — false freezes pan/zoom, useful for static cards.
+  - onLoad(handle) / onError(error) — handle exposes flyTo, panTo, fitBounds, getCenter, getZoom, getBounds, instance.
+  - tilerKey (maplibre) — only needed off `gradeui.com`/`localhost`. Default key is referrer-locked.
+  - accessToken (mapbox), apiKey (google) — required for those providers.
+when_to_use: Any layout that needs a real map — listings (real estate, Airbnb-style), fleet/logistics dashboards, store locators, anywhere a user picks a location from a viewport. Reach for the controlled `hoveredId` prop when a sibling list and the map need to highlight each other.
+composes_with: [Card (as marker content), Badge, Avatar, Button, Row, Stack, Skeleton]
+---
+
+Default — zero config, MapLibre + MapTiler demo tiles. Works on `gradeui.com` and `localhost` with no setup:
+
+```jsx
+<Map center={[-122.42, 37.78]} zoom={12}>
+  <MapMarker id="hq" at={[-122.42, 37.78]}>
+    <Badge>HQ</Badge>
+  </MapMarker>
+</Map>
+```
+
+Two-way list ↔ map hover sync — the canonical pattern. ALWAYS use the controlled `hoveredId` prop, do NOT call `mapRef.current.flyTo` on every list-item hover yourself:
+
+```jsx
+const [hoveredId, setHoveredId] = useState(null);
+
+<Row>
+  <Stack>
+    {listings.map(l => (
+      <Card
+        key={l.id}
+        onMouseEnter={() => setHoveredId(l.id)}
+        onMouseLeave={() => setHoveredId(null)}
+      >
+        <CardHeader><CardTitle>{l.title}</CardTitle></CardHeader>
+        <CardContent>${l.price}/night</CardContent>
+      </Card>
+    ))}
+  </Stack>
+
+  <Map
+    center={[-122.42, 37.78]}
+    zoom={12}
+    hoveredId={hoveredId}
+    onHoveredIdChange={setHoveredId}
+  >
+    {listings.map(l => (
+      <MapMarker key={l.id} id={l.id} at={l.coords}>
+        <Badge>${l.price}</Badge>
+      </MapMarker>
+    ))}
+  </Map>
+</Row>
+```
+
+Provider swap — one line:
+
+```jsx
+<Map provider="mapbox" accessToken={env.MAPBOX_TOKEN} center={[-0.1, 51.5]} zoom={11} />
+<Map provider="google" apiKey={env.GOOGLE_MAPS_KEY} center={[-0.1, 51.5]} zoom={11} />
+```
+
+ANTI-PATTERNS — don't do these:
+
+- DO NOT pass `{ lat, lng }` objects. Coordinates are ALWAYS `[lng, lat]` tuples. Google's adapter handles the object conversion internally.
+- DO NOT hand-roll an iframe with a Google Maps embed URL. Use `<Map provider="google" apiKey={...}>`.
+- DO NOT use `useRef` + `mapRef.current.flyTo(id)` on list-hover when `hoveredId` already does it controlled.
+- DO NOT call `setStyle` or reach for `mapboxgl.Marker` directly — use `appearance` and `<MapMarker>`. The escape hatch (`mapRef.current.instance`) is for things the wrapper genuinely doesn't expose (3D extrusions, drawing tools, heatmaps).
+- DO NOT render >500 markers without clustering. The component warns in dev. For larger datasets, drop to `.instance` and use the provider's clustering layer.
+
+Markers are DOM — children inherit `--gds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.