@gradeui/ui 0.9.0 → 1.0.0

package/components/ui/sidebar.md

@@ -0,0 +1,121 @@
+---
+name: Sidebar
+import: "@gradeui/ui"
+subcomponents: [SidebarHeader, SidebarContent, SidebarFooter, SidebarSection, SidebarItem]
+props:
+  - Sidebar: collapsed?: boolean — controlled collapsed state (wire onCollapsedChange when set)
+  - Sidebar: defaultCollapsed?: boolean — uncontrolled initial value (default false)
+  - Sidebar: onCollapsedChange?: (next: boolean) => void
+  - Sidebar: collapsible?: boolean — show the affordance for the user to collapse (default true)
+  - Sidebar: variant?: 'rail' | 'panel' — outer chrome treatment. `rail` (default) is the classic nav rail with a single right-border + tracked width via `--gds-sidebar-width`; drops cleanly into `<AppShellNav placement="side">`. `panel` is a card-style floating sidebar with full border + rounded corners + parent-controlled width; use when the sidebar is one of several adjacent panes in a body row (e.g. Projects | Canvas | Settings). The compound children (Header/Content/Footer/Section/Item) are identical in both treatments.
+  - SidebarHeader: any children — brand / logo / org switcher; hides nothing when collapsed (centred)
+  - SidebarContent: any children — scrollable body
+  - SidebarFooter: any children — user block, settings link, pinned chrome
+  - SidebarSection: title?: ReactNode — group label; **uppercase tracking-wide muted** styling auto-applied (Notion / Linear / Slack-style "GAMES", "FAVORITES", "WORKSPACE" headers); hidden when sidebar is collapsed
+  - SidebarSection: icon?: ReactNode — optional icon beside the title
+  - SidebarSection: trailing?: ReactNode — **action(s) on the right edge of the header** — the canonical "+" / "..." slot (Notion's "+ Add page" next to Pages, Linear's "+" next to Favorites, Slack's "+" next to Channels). Pointer events isolated so a Button here doesn't toggle collapse.
+  - SidebarSection: collapsible?: boolean — title acts as expand/collapse trigger with a **chevron indicator** (default true). Set `false` for a static, non-clickable header.
+  - SidebarSection: defaultExpanded?: boolean — initial open state (default true)
+  - SidebarItem: icon?: ReactNode — leading icon
+  - SidebarItem: badge?: ReactNode — trailing count / label (hidden when collapsed)
+  - SidebarItem: active?: boolean — current route; adds aria-current="page"
+  - SidebarItem: href?: string — renders as <a>; for routing use `asChild` with your link component
+  - SidebarItem: asChild?: boolean — wrap a custom link (<Link href> from Next.js etc.) via Radix Slot
+  - SidebarItem: asButton?: boolean — render as <button> for action rows (open dialog, log out)
+  - SidebarItem: disabled?: boolean
+  - SidebarItem: collapsedLabel?: ReactNode — tooltip override when sidebar is collapsed (defaults to children text)
+  - SidebarItem: size?: 'sm' | 'md' — row size. `md` (default) is the standard `text-sm font-medium` nav row; `sm` is `text-xs` + lighter weight + tighter padding for visually subordinate rows (nested screens under a project, sub-pages under a section). Active state still wins on color + weight so the current row pops at either size.
+  - SidebarItem: description?: ReactNode — secondary line beneath the label (metadata like 'Edited 2m ago', '12 items', a brief description). Row layout adapts: label + description stacked vertically; icon vertically-centered against the stack; badge stays on trailing edge. Hidden when sidebar collapsed.
+  - SidebarTreeItem: description?: ReactNode — secondary line beneath the label, same shape as SidebarItem.description. Useful when a branch needs more than just a name (last-edited timestamp, item count, owner).
+  - SidebarTreeItem: trailing?: ReactNode — right-edge action slot (settings cog, more-actions overflow, "+ add child"). Rendered as a SIBLING of the branch button (not nested inside it, so `<button>` children in `trailing` stay valid HTML). Vertically centered against the row; click events are stopPropagation'd so a tap on a trailing button doesn't toggle expand/collapse. The branch row wrapper carries a `group/row` named-group, so consumer-provided trailing can opt into hover-only visibility via `hidden group-hover/row:flex` — the hover state is scoped to the branch row alone, not the nested children.
+when_to_use: Vertical app navigation. Drop inside `<AppShellNav placement="side">` for full-page layouts. Compound API — `<SidebarHeader>` for brand, `<SidebarContent>` for the scrollable body of `<SidebarSection>` + `<SidebarItem>` rows, `<SidebarFooter>` for user / settings chrome. For top nav reach for TopMenu; for command-palette style search reach for Command.
+composes_with: [AppShell (inside AppShellNav), Avatar (in Footer), Tooltip (auto-wrapped on collapsed items), Button (asChild for custom routing)]
+aliases: [sidebar, side menu, sidemenu, navigation sidebar, app sidebar, side nav, side nav rail, master pane, sidebarmenu, navigation rail, react native drawer]
+---
+
+```jsx
+<Sidebar defaultCollapsed={false}>
+  <SidebarHeader>
+    <div className="flex items-center gap-2 font-semibold">
+      <Logo className="h-5 w-5" />
+      <span>Acme</span>
+    </div>
+  </SidebarHeader>
+
+  <SidebarContent>
+    <SidebarSection title="Workspace">
+      <SidebarItem href="/" icon={<Home />} active>Dashboard</SidebarItem>
+      <SidebarItem href="/inbox" icon={<Inbox />} badge={3}>Inbox</SidebarItem>
+      <SidebarItem href="/team" icon={<Users />}>Team</SidebarItem>
+    </SidebarSection>
+    <SidebarSection title="Personal">
+      <SidebarItem href="/settings" icon={<Settings />}>Settings</SidebarItem>
+    </SidebarSection>
+  </SidebarContent>
+
+  <SidebarFooter>
+    <Row gap="sm" align="center">
+      <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
+      <Stack gap="none" className="text-xs">
+        <span className="font-medium">Ali</span>
+        <span className="text-muted-foreground">Pro plan</span>
+      </Stack>
+    </Row>
+  </SidebarFooter>
+</Sidebar>
+```
+
+```jsx
+// With Next.js routing — wrap any link component via `asChild`.
+import Link from "next/link";
+
+<SidebarItem asChild icon={<Home />} active={pathname === "/"}>
+  <Link href="/">Dashboard</Link>
+</SidebarItem>
+```
+
+```jsx
+// Action row — `asButton` renders a <button> instead of an <a>.
+<SidebarItem asButton icon={<LogOut />} onClick={signOut}>
+  Sign out
+</SidebarItem>
+```
+
+```jsx
+// Section header with a trailing action — the Notion / Linear / Slack
+// "+" next to a section name. The trailing slot isolates pointer events
+// from the collapse toggle, so the Button doesn't also flip expand.
+<SidebarSection
+  title="Pages"
+  trailing={
+    <Button variant="ghost" size="icon" className="h-5 w-5">
+      <Plus className="h-3 w-3" />
+    </Button>
+  }
+>
+  <SidebarItem>Notes</SidebarItem>
+  <SidebarItem>Drafts</SidebarItem>
+</SidebarSection>
+```
+
+```jsx
+// Non-collapsible static header — for sections the user shouldn't
+// be able to fold. `collapsible={false}` hides the chevron.
+<SidebarSection title="Workspace" collapsible={false}>
+  <SidebarItem>...</SidebarItem>
+</SidebarSection>
+```
+
+### Anti-patterns
+
+DO NOT pass a `sections={[...]}` data array — that was the old SideMenu shape (retired May 2026). Compose `<SidebarSection>` and `<SidebarItem>` directly so any non-list-shaped chrome (search input, drag handle, custom brand block) can sit alongside the nav.
+
+DO NOT set `href` AND `onClick` AND `asChild` at once — pick one mode per row. `href` = anchor, `asButton` = button, `asChild` = wrap your own link component. Mixing modes makes the DOM ambiguous.
+
+DO NOT use Sidebar for primary marketing-style top navigation — that's TopMenu. Sidebar is for app chrome (logged-in product surfaces), not landing pages.
+
+DO NOT rely on the collapsed-state tooltip to convey critical-only information. When the sidebar is collapsed, only the icon is visible by default; the label is in the tooltip on hover, but mobile users + screen readers won't reliably see it. Keep icons recognisable and ship the label as actual text on hover/focus, not just as a tooltip.
+
+DO NOT hand-roll an uppercase "SECTION NAME" header above your items. `<SidebarSection title="…">` already gives you the uppercase + tracking-wide + muted styling, plus the chevron + expand/collapse behaviour. If your design has a "+" or "..." next to the section name, use the `trailing` prop — don't render the action as a separate SidebarItem below the section.
+
+DO NOT bypass `<Sidebar>` and compose an icon rail or projects pane from raw `<Stack>` + buttons. You lose the collapsed-state handling, the per-item tooltip, the `data-gds-part` markers that Studio's selection layer reads, and the consistent padding/gap CSS vars (`--gds-sidebar-*`). If you find yourself writing `<button className="flex items-center gap-3 rounded-md px-3 py-2 hover:bg-muted">{icon}{label}</button>`, that's a SidebarItem.

package/components/ui/skeleton.md

@@ -0,0 +1,17 @@
+---
+name: Skeleton
+import: "@gradeui/ui"
+props:
+  - className?: string — required in practice; supply width/height utilities
+  - All native div HTML attrs
+when_to_use: Loading placeholder for content whose shape you know. Set width/height via className to mimic the real content (e.g. "h-4 w-32"). Not a spinner — use it where the real thing will drop in.
+composes_with: [Card, Avatar (inside a Skeleton for avatar loading), any layout]
+aliases: [placeholder, shimmer, loader, loading state, redacted, redacted placeholder, shimmer placeholder, content placeholder, lottie placeholder]
+---
+
+```jsx
+<div className="space-y-2">
+  <Skeleton className="h-4 w-3/4" />
+  <Skeleton className="h-4 w-1/2" />
+</div>
+```

package/components/ui/slider.md

@@ -0,0 +1,48 @@
+---
+name: Slider
+import: "@gradeui/ui"
+props:
+  - value?: number[] — controlled value; ALWAYS an array even for a single-thumb slider (`[50]`)
+  - defaultValue?: number[] — uncontrolled initial; `[20, 80]` for a two-thumb range
+  - onValueChange?: (value: number[]) => void
+  - min?: number (default 0)
+  - max?: number (default 100)
+  - step?: number (default 1)
+  - disabled?: boolean
+  - orientation? "horizontal" | "vertical" (default "horizontal")
+  - dir? "ltr" | "rtl"
+  - inverted?: boolean — flip the visual direction
+  - name?: string — form name when posting natively
+when_to_use: A continuous-ish numeric pick — volume, opacity, font size, price-range filters. Use a single-thumb slider for one value, two-thumb for a range. For a small set of discrete options (1-5 stars, sm/md/lg) prefer ToggleGroup. For free-text numeric entry use an Input type="number".
+composes_with: [Label (mandatory above), Row (label + current value display), Card (settings rows)]
+aliases: [slider, range slider, range input, volume, opacity slider, scrub, drag value, slider control, value slider, react native slider]
+---
+
+```jsx
+// Single-thumb slider with the current value shown alongside.
+<Stack gap="xs">
+  <Row justify="between" align="center">
+    <Label htmlFor="opacity">Opacity</Label>
+    <span className="text-sm text-muted-foreground tabular-nums">{value[0]}%</span>
+  </Row>
+  <Slider
+    id="opacity"
+    min={0}
+    max={100}
+    step={1}
+    value={value}
+    onValueChange={setValue}
+  />
+</Stack>
+```
+
+```jsx
+// Two-thumb price-range filter.
+<Slider
+  min={0}
+  max={500}
+  step={5}
+  defaultValue={[50, 250]}
+  onValueChange={setRange}
+/>
+```

package/components/ui/sortable.md

@@ -0,0 +1,101 @@
+---
+name: Sortable
+import: "@gradeui/ui"
+subcomponents: [Sortable.Item, Sortable.Handle]
+props:
+  - Sortable: values: (string | number)[] — ordered list of unique ids; the source of truth for the order
+  - Sortable: onReorder?: (next: (string | number)[]) => void — fires with the new order after a drag that changed it
+  - Sortable: strategy?: "vertical" | "horizontal" | "grid" (default "vertical") — match the layout your items render in
+  - Sortable: disabled?: boolean — disable drag on every item
+  - Sortable.Item: value: string | number — must match one entry in the parent `values` array (identity, not React key)
+  - Sortable.Item: asChild?: boolean — render as the child element via Radix Slot
+  - Sortable.Item: disabled?: boolean — disable drag for this item only
+  - Sortable.Handle: asChild?: boolean — wrap a Button / icon as the drag grip
+when_to_use: Drag-to-reorder lists, kanban-column reordering, sortable shelves, tab strips the user can rearrange. Pairs with any layout primitive — Stack for vertical lists, Row for horizontal strips, Grid for 2D card walls. For cross-container drag (drag a card from one column to another) hand-roll DndContext at the page level — Sortable v1 covers single-list reorder; Sortable.Group for cross-container is a planned follow-up. Reach for raw `@dnd-kit/core` if you need custom collision detection, drag overlays with arbitrary chrome, or non-list use cases (kanban swimlanes, draggable canvas nodes).
+composes_with: [Stack (vertical lists), Row (horizontal strips), Grid (2D card walls), Card (typical item content), Button (as Sortable.Handle asChild)]
+aliases: [sortable, reorder, drag and drop, dnd, draggable list, sortable list, kanban, drag to reorder, drag-drop, dragdroplist, drag handle, react native draggable flatlist]
+---
+
+```jsx
+const [items, setItems] = React.useState([
+  { id: "a", title: "First" },
+  { id: "b", title: "Second" },
+  { id: "c", title: "Third" },
+]);
+
+<Sortable values={items.map(i => i.id)} onReorder={(ids) => {
+  setItems(ids.map(id => items.find(i => i.id === id)!));
+}}>
+  <Stack gap="sm">
+    {items.map((item) => (
+      <Sortable.Item key={item.id} value={item.id}>
+        <Card>
+          <CardContent className="p-3">{item.title}</CardContent>
+        </Card>
+      </Sortable.Item>
+    ))}
+  </Stack>
+</Sortable>
+```
+
+```jsx
+// With a drag handle — only the grip activates drag; the rest of the
+// row stays clickable for child Buttons / links.
+<Sortable values={ids} onReorder={setIds} strategy="vertical">
+  <Stack gap="sm">
+    {items.map((item) => (
+      <Sortable.Item key={item.id} value={item.id}>
+        <Card>
+          <Row gap="sm" align="center" className="p-3">
+            <Sortable.Handle asChild>
+              <Button variant="ghost" size="icon">
+                <GripVertical className="h-4 w-4" />
+              </Button>
+            </Sortable.Handle>
+            <span className="flex-1">{item.title}</span>
+            <Button size="sm">Edit</Button>
+          </Row>
+        </Card>
+      </Sortable.Item>
+    ))}
+  </Stack>
+</Sortable>
+```
+
+```jsx
+// Horizontal tab strip — strategy="horizontal" + Row instead of Stack.
+<Sortable values={tabIds} onReorder={setTabIds} strategy="horizontal">
+  <Row gap="xs">
+    {tabs.map((tab) => (
+      <Sortable.Item key={tab.id} value={tab.id}>
+        <Badge>{tab.label}</Badge>
+      </Sortable.Item>
+    ))}
+  </Row>
+</Sortable>
+```
+
+```jsx
+// 2D card grid — strategy="grid".
+<Sortable values={photoIds} onReorder={setPhotoIds} strategy="grid">
+  <Grid cols="3" gap="md">
+    {photos.map((p) => (
+      <Sortable.Item key={p.id} value={p.id}>
+        <MediaSurface aspect="square" alt={p.alt} />
+      </Sortable.Item>
+    ))}
+  </Grid>
+</Sortable>
+```
+
+### Anti-patterns
+
+DO NOT add a `sortable` prop to Stack / Row / Grid — those primitives stay pure. Wrap them in `<Sortable>` to mark a collection sortable. Mixing layout and reorder concerns into one component balloons each primitive's contract for a feature 95% of stacks don't use, and loses you cross-layout consistency (one Sortable wrapping a Grid works exactly like one wrapping a Stack).
+
+DO NOT use `key` as the sortable identity. `<Sortable.Item value={item.id}>` is the source of truth — `key={item.id}` is also fine for React's reconciler but `value` is what dnd-kit reads. They usually match; if they don't, drag-end will operate on the wrong row.
+
+DO NOT try to mutate children directly to reorder. Sortable's data model is `state → children`. Reorder fires `onReorder(newValues)`; you update state; React re-renders children in the new order. Trying to read children's keys + reorder them imperatively fights React.
+
+DO NOT wrap clickable items (Card with onClick, Button-bearing rows) without thinking about drag-vs-click conflict. The PointerSensor has a 4px activation distance so single clicks pass through, but if the row's primary affordance is "click to open detail," consider a `<Sortable.Handle>` so the user clicks the body for detail and drags only the grip.
+
+DO NOT use Sortable for cross-container drag in v1. A single `<Sortable>` is one DndContext; the kanban "drag from To Do to Done" case needs one DndContext above multiple SortableContexts. Until `<Sortable.Group>` lands, that pattern needs hand-rolled `@dnd-kit/core` at the page level. Single-list, single-grid, single-strip reorder all work.

package/components/ui/stack.md

@@ -0,0 +1,50 @@
+---
+name: Stack
+import: "@gradeui/ui"
+role: layout
+props:
+  - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "md") — vertical gap between children
+  - align?: "start" | "center" | "end" | "stretch" (default "stretch") — cross-axis (horizontal) alignment of children
+  - justify?: "start" | "center" | "end" | "between" | "around" | "evenly" (default "start") — main-axis (vertical) distribution. Reach for this on absolute-positioned overlays (`justify="end"` pins children to the bottom) and split footers (`justify="between"`).
+  - asChild?: boolean (default false) — render as the child element via Slot, so `<Stack asChild><section>…</section></Stack>` stamps Stack's classes onto the `<section>` rather than nesting a wrapper div
+  - className?: string
+  - children: React.ReactNode
+when_to_use: Default top-level layout inside the main slot when composing two or more stacked regions (hero + content + footer, auth card + subtext, etc.). Prefer Stack over hand-rolled `flex flex-col gap-*` so the vertical rhythm is editable through the settings panel.
+composes_with: [Section, Row, Split, Hero, any content component]
+aliases: [stack, vstack, vertical, column, vertical layout, v-stack, vertical stack, lazyvstack]
+---
+
+```jsx
+<Stack gap="lg">
+  <Hero>…</Hero>
+  <Section>…</Section>
+  <Section>…</Section>
+</Stack>
+```
+
+```jsx
+// Narrow centred column for auth / marketing copy.
+<Stack gap="md" align="center" className="max-w-md mx-auto">
+  <CardTitle>Sign in</CardTitle>
+  <Input placeholder="Email" />
+  <Input placeholder="Password" type="password" />
+  <Button className="w-full">Continue</Button>
+</Stack>
+```
+
+```jsx
+// Hero overlay pinned to the bottom — use `justify="end"`, NOT
+// `className="flex flex-col justify-end"`. Stack is already a flex
+// column, so `flex flex-col` in className is dead weight.
+<Stack justify="end" gap="md" className="absolute inset-0 p-10 max-w-2xl">
+  <Badge>Featured</Badge>
+  <h1 className="text-5xl font-semibold">Severance</h1>
+  <Button>Play</Button>
+</Stack>
+```
+
+### Anti-patterns
+
+DO NOT add `flex flex-col` to Stack's className — Stack already applies `flex flex-col` as its base. Same for Row + `flex flex-row`. These are the literal definitions of the primitives.
+
+DO NOT reach for `className="justify-end"` (or `justify-between`, etc.) when the new `justify` prop covers it. Inline-Tailwind layout escapes are how scaffolds slowly drift away from the design system — keep them in props so the settings panel can mutate them.

package/components/ui/switch.md

@@ -0,0 +1,20 @@
+---
+name: Switch
+import: "@gradeui/ui"
+props:
+  - checked?: boolean
+  - onCheckedChange?: (checked: boolean) => void
+  - defaultChecked?: boolean
+  - disabled?: boolean
+  - id?: string
+when_to_use: Instant on/off setting ("Enable notifications", "Dark mode"). Commits on toggle — no submit button needed. For selecting-from-a-list use Checkbox.
+composes_with: [Label (via htmlFor), Card (settings rows)]
+aliases: [toggle, switch, on/off switch, ios toggle, toggle switch, switch control, react native switch]
+---
+
+```jsx
+<div className="flex items-center justify-between">
+  <Label htmlFor="notifications">Email notifications</Label>
+  <Switch id="notifications" />
+</div>
+```

package/components/ui/table.md

@@ -0,0 +1,28 @@
+---
+name: Table
+import: "@gradeui/ui"
+subcomponents: [TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption]
+props:
+  - Each subcomponent accepts native table HTML attrs
+  - No variants — styling follows the active theme tokens
+when_to_use: Structured tabular data — rows × columns with alignment requirements. NOT a layout grid — for that use div+Tailwind grid utilities. Keep to <100 rows; larger datasets need virtualisation (not in DS).
+composes_with: [Card (wrap the table), Badge (inside TableCell for status), Checkbox (row selection), Button (row actions)]
+aliases: [table, table view, data table, datatable, grid view, data grid, rows and columns]
+---
+
+```jsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead className="text-right">Amount</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>Invoice #001</TableCell>
+      <TableCell className="text-right">$250</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```

package/components/ui/tabs.md

@@ -0,0 +1,56 @@
+---
+name: Tabs
+import: "@gradeui/ui"
+subcomponents: [TabsList, TabsTrigger, TabsContent]
+sizes: [sm, md, lg]
+variants: [pill, underlined]
+props:
+  - Tabs: defaultValue?, value?, onValueChange?, orientation?
+  - TabsList: size? (sm | md | lg, default md) — t-shirt scale aligned with Button/ToggleGroup heights; cascades to every TabsTrigger via context so set it once on the list
+  - TabsList: variant? (pill | underlined, default pill) — `pill` is the shadcn chip-on-muted look; `underlined` is the minimal text + bottom-border treatment (formerly the separate SimpleTabs component, collapsed into Tabs in May 2026). Cascades to triggers.
+  - TabsTrigger: value: string — matches a TabsContent value; tooltip?: string — when set, wraps the trigger in the design-system Tooltip and auto-applies aria-label (useful for icon-only triggers); requires a TooltipProvider somewhere above the tabs
+  - TabsContent: value: string — matches a TabsTrigger value
+when_to_use: A small set of peer views within one surface (2–5 tabs). For primary nav use Side Menu/routing. For filters use a filter control, not tabs. Pick `variant="pill"` for app chrome (settings panels, in-card tab strips). Pick `variant="underlined"` for marketing/docs pages and browser-tab-style treatments.
+composes_with: [Card (tabs inside a card body), Dialog, TooltipProvider (required for tooltip prop)]
+aliases: [tabs, tab strip, tab bar, tab view, tabbed interface, pageviewcontroller, react native tab view, underlined tabs, page tabs, segment switcher, simple tabs]
+---
+
+```jsx
+<Tabs defaultValue="details">
+  <TabsList>
+    <TabsTrigger value="details">Details</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="details">…</TabsContent>
+  <TabsContent value="activity">…</TabsContent>
+</Tabs>
+```
+
+```jsx
+// Icon-only triggers — `tooltip` adds the design-system Tooltip + aria-label.
+<TooltipProvider>
+  <Tabs defaultValue="preview">
+    <TabsList size="sm">
+      <TabsTrigger value="preview" tooltip="Preview"><Eye /></TabsTrigger>
+      <TabsTrigger value="code" tooltip="Code"><Code /></TabsTrigger>
+    </TabsList>
+    <TabsContent value="preview">…</TabsContent>
+    <TabsContent value="code">…</TabsContent>
+  </Tabs>
+</TooltipProvider>
+```
+
+```jsx
+// Underlined variant — replaces the old SimpleTabs component. Use
+// `variant="underlined"` on the TabsList and it cascades to triggers.
+<Tabs defaultValue="profile">
+  <TabsList variant="underlined">
+    <TabsTrigger value="profile">Profile</TabsTrigger>
+    <TabsTrigger value="team">Team</TabsTrigger>
+    <TabsTrigger value="billing">Billing</TabsTrigger>
+  </TabsList>
+  <TabsContent value="profile">…</TabsContent>
+  <TabsContent value="team">…</TabsContent>
+  <TabsContent value="billing">…</TabsContent>
+</Tabs>
+```

package/components/ui/textarea.md

@@ -0,0 +1,14 @@
+---
+name: Textarea
+import: "@gradeui/ui"
+props:
+  - All native textarea HTML attrs (rows, value, onChange, placeholder, disabled)
+when_to_use: Multi-line text entry (descriptions, messages, comments). Pair with a Label. Single-line input → use Input instead.
+composes_with: [Label, Form, Card (in CardContent)]
+aliases: [text area, multiline, comment box, message field, text editor, multi-line text, multiline input, multiline text field, comments box, multiline textinput]
+---
+
+```jsx
+<Label htmlFor="bio">Bio</Label>
+<Textarea id="bio" rows={4} placeholder="Tell us about yourself." />
+```