@gradeui/ui 1.1.0 → 1.3.0

package/components/ui/background-fill.md

@@ -0,0 +1,109 @@
+---
+name: BackgroundFill
+import: "@gradeui/ui"
+props:
+  - type: "none" | "solid" | "gradient" | "image" | "video" | "shader" — which paint to render (required)
+  - color?: string — solid fill; a token name (`primary`, `card`, `muted`, `accent`, `secondary`, `destructive`, `background`, `transparent`) or any CSS colour
+  - gradient?: { from?; via?; to?; angle? } — gradient stops (token names or CSS colours) + angle in degrees (default 135)
+  - src?: string — image or video URL
+  - fit?: "cover" | "contain" | "fill" | "none" — object-fit for image/video (default "cover")
+  - position?: string — CSS object/background position (default "center")
+  - repeat?: boolean — tile the image (background-repeat) instead of a single <img>
+  - tileSize?: string — CSS background-size when repeating (e.g. "120px")
+  - preset?: string — shader preset id (see ThreeScene)
+  - fragmentShader?: string — custom GLSL (takes precedence over preset)
+  - palette?: Partial<{ primary; secondary; accent; background }> — shader palette overrides; wrap tokens as `oklch(var(--token))`
+  - postPreset?: string | PostPreset — shader post-FX
+  - opacity?: number — layer opacity 0–1
+  - blendMode?: CSS mix-blend-mode — blend against the frame behind it
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" — match the frame's radius so the paint clips cleanly
+when_to_use: The background *paint* of a frame — a generative shader, image, video, gradient, repeating texture, or solid token rendered as a layer BEHIND the frame's content. Use it as the first child of a `relative` frame; it paints an `absolute inset-0`, `z-0`, `pointer-events-none` layer, so content carrying `relative z-10` sits on top. This is the canonical way to give any container a rich background — never drop a full-bleed `<ThreeScene>` or `<img>` as a free-standing sibling. For a sized, in-flow media element (a hero card, a thumbnail), use ThreeScene / MediaSurface / VideoPlayer directly instead.
+composes_with: [AppShell, Card, Stack, Row, Grid (any relative container), ThreeScene (shader fill), MediaSurface]
+aliases: [background, fill, frame fill, backdrop, surface fill, background image, background video, background gradient, background shader, texture, paint]
+notes: |
+  ## The fill model
+
+  A background is a PROPERTY of a frame, not a node you select — exactly
+  like a fill in Figma / Paper. Select the frame; its Fill controls drive
+  this layer. BackgroundFill is the render boundary that makes that true.
+
+  ### Required frame setup
+
+  The parent frame must be `relative` (so the `absolute inset-0` layer
+  anchors to it) and ideally `overflow-hidden` (so the paint clips to the
+  frame's corners). Content that should sit ABOVE the fill needs its own
+  stacking context — wrap it `relative z-10`:
+
+    ```jsx
+    <Card className="relative overflow-hidden">
+      <BackgroundFill type="shader" preset="mesh" opacity={0.3} />
+      <div className="relative z-10">…content…</div>
+    </Card>
+    ```
+
+  ### Why a layer (and why pointer-events-none)
+
+  A solid colour does not strictly need a layer — it could be the frame's
+  own `background`. Every other paint (image, video, gradient, shader,
+  tiled texture) needs real pixels, so it renders as an absolutely-
+  positioned layer. The layer is `z-0` + `pointer-events-none` so it sits
+  behind content and never intercepts clicks. It carries
+  `data-gds-part="frame-fill"` + `aria-hidden` so Studio treats it as
+  chrome (the frame is the selectable unit) and assistive tech skips it.
+
+  ### Type cheat-sheet
+
+    - solid    — `color` (token or CSS colour). Cheapest.
+    - gradient — `gradient={{ from, via?, to, angle }}`. Tokens get wrapped in oklch() automatically.
+    - image    — `src` + `fit` / `position`; set `repeat` (+ `tileSize`) for a tiled texture.
+    - video    — `src` (autoplays muted + looped + inline).
+    - shader   — `preset` OR `fragmentShader`, + `palette` / `postPreset`. Delegates to ThreeScene.
+
+  `opacity` + `blendMode` apply to every type — the same two controls as
+  the inspector's Blending section, so a loud shader/image can be dialled
+  back to a subtle wash behind text.
+---
+
+```jsx
+// Shader background behind a hero, dialled back so text stays readable.
+<section className="relative overflow-hidden rounded-xl">
+  <BackgroundFill
+    type="shader"
+    preset="mesh"
+    palette={{
+      primary: "oklch(var(--primary))",
+      secondary: "oklch(var(--accent))",
+      accent: "oklch(var(--primary))",
+      background: "oklch(var(--foreground))",
+    }}
+    opacity={0.35}
+  />
+  <div className="relative z-10 p-12">
+    <h1 className="text-4xl font-bold">Build at the speed of thought</h1>
+  </div>
+</section>
+```
+
+```jsx
+// Gradient wash on a card.
+<Card className="relative overflow-hidden">
+  <BackgroundFill type="gradient" gradient={{ from: "primary", to: "accent", angle: 120 }} opacity={0.18} />
+  <CardContent className="relative z-10">…</CardContent>
+</Card>
+```
+
+```jsx
+// Image background, cover-fit, with a blend mode.
+<div className="relative h-64 overflow-hidden rounded-lg">
+  <BackgroundFill type="image" src="/hero.jpg" fit="cover" blendMode="multiply" />
+  <div className="relative z-10 p-6 text-white">Featured</div>
+</div>
+```
+
+```jsx
+// Tiled texture.
+<div className="relative overflow-hidden">
+  <BackgroundFill type="image" src="/noise.png" repeat tileSize="160px" opacity={0.08} />
+  <div className="relative z-10">…</div>
+</div>
+```

package/components/ui/checkbox-card.md

@@ -0,0 +1,43 @@
+---
+name: CheckboxCard
+import: "@gradeui/ui"
+props:
+  - checked? / defaultChecked? / onCheckedChange? — standard checkbox state
+  - label?: ReactNode — title line
+  - description?: ReactNode — secondary line
+  - aside?: ReactNode — slot before the indicator (a Badge, price, hint)
+  - hideIndicator?: boolean — hide the check; selection shown by the card border + background
+  - indicatorPosition?: "leading" | "trailing" — default trailing
+  - children?: ReactNode — arbitrary static content instead of label/description
+when_to_use: Multi-select where each option is a whole selectable card (add-ons, feature toggles, opt-ins). The whole card is the control, so focus and the checked state live on the card surface. Standalone (not in a group). Static content only — never nest an interactive control inside. For a plain checkbox + label row use Field instead.
+composes_with: [Badge (in aside), MediaSurface (custom children), Stack / Grid (laying out several)]
+aliases: [checkbox card, selectable card, multi-select card, add-on card, feature card, opt-in card]
+---
+
+```jsx
+<div className="grid gap-3">
+  <CheckboxCard label="Priority support" description="24/7 response within an hour" defaultChecked />
+  <CheckboxCard label="Extended warranty" description="3 years parts and labour" />
+</div>
+```
+
+Indicator on the leading edge, with a Badge in the `aside` slot:
+
+```jsx
+<CheckboxCard
+  indicatorPosition="leading"
+  label="Priority support"
+  description="24/7 response within an hour"
+  aside={<Badge variant="info-soft">Popular</Badge>}
+  defaultChecked
+/>
+```
+
+No visible tick (selection reads from the card border + background), in a two-up grid:
+
+```jsx
+<div className="grid grid-cols-2 gap-3">
+  <CheckboxCard hideIndicator label="Email" description="Weekly digest" defaultChecked />
+  <CheckboxCard hideIndicator label="SMS" description="Critical alerts only" />
+</div>
+```

package/components/ui/checkbox.md

@@ -7,8 +7,8 @@ props:
   - 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)]
+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. For a label + description row, wrap in Field. When each option should be a whole selectable card (label + description, selected state on the card surface), use CheckboxCard.
+composes_with: [Label (via htmlFor), Field (label + description row), CheckboxCard (whole-card selectable option), Card, Form rows, Table (for row selection)]
 aliases: [checkbox, tickbox, tick box, check, multi-select item]
 ---
 

package/components/ui/code.md

@@ -18,8 +18,9 @@ props:
   - filename?: string — optional label rendered in the header chrome
   - wrap?: boolean — wrap long lines instead of horizontal scroll
   - bare?: boolean — drop chrome (border, header, padding) — for inline use
+  - size? (xs | sm | md) — type-scale preset. `xs` (12px) for dense changelog cards / inline blocks; `sm` (14px, default) for marketing heroes and docs; `md` (16px) for focal-point displays.
   - height? (auto | number | string) — container sizing. `auto` (default) grows with content. Number = pixels (`300` → `300px`). String passes through as CSS (`"20rem"`, `"50vh"`).
-  - maxLines?: number — cap the visible line count at exactly N line-heights. Wins over `height`. Use for terminal windows, code-tour cards, and surfaces that need a stable vertical rhythm regardless of snippet length.
+  - maxLines?: number — cap the visible line count at exactly N line-heights. Wins over `height`. Inherits the current size's line-height automatically.
 when_to_use: Read-only code surface for marketing heroes, docs, changelog entries, AI-output displays. Use `diff` for the "diff hero" pattern (before/after side-by-side or stacked). Use `reveal="lines"` with `trigger="inView"` for scroll-driven marketing pages. Use `reveal="typewriter"` for AI-output / chat-style displays. Use `bare` for inline code inside prose. NOT a code editor — for editable code, reach for an external editor primitive (CodeMirror / Monaco).
 composes_with: [SectionBlock, Card, Tabs (for multi-file examples), Carousel (slide-to-slide code progression)]
 aliases: [code block, code, code snippet, code surface, syntax highlighted code, diff hero, diff view, diff block, changelog code, before after code, scroll-triggered code, typewriter code]

package/components/ui/composer.md

@@ -0,0 +1,226 @@
+---
+name: Composer
+import: "@gradeui/ui"
+props:
+  - placeholder?: string
+  - initialText?: string — plain text content to seed on mount
+  - initialJson?: string — Lexical state JSON (from a previous onSubmit round-trip)
+  - formats?: ComposerFormat[] | false — available formats (defaults to bold/italic/underline/strikethrough/code/h1/h2/blockquote/ul/ol); pass false for plain text only
+  - toolbar?: boolean | "top" — show the formatting toolbar above the editor; default false
+  - triggers?: ComposerTriggerConfig[] — mention/slash configs, eg. `[{ char: "@", items: people }, { char: "/", items: commands }]`
+  - attachments?: boolean | ComposerAttachmentConfig — enable image paste + paperclip when true/object; default off
+  - onSubmit?: (content: ComposerContent, attachments?: ComposerAttachment[]) => void
+  - isLoading?: boolean — disables editor, swaps default Send for Stop
+  - onStop?: () => void
+  - maxLength?: number
+  - autoFocus?: boolean
+  - submitOnEnter?: boolean — default true (Shift-Enter still inserts newline)
+  - leftActions?: ReactNode — override the default paperclip
+  - rightActions?: ReactNode — override the default Send/Stop
+  - hideSend?: boolean — hide the default Send without replacing it
+  - steps?: ComposerStep[] — scripted demo sequence
+  - trigger?: DemoTrigger — "mount" | "inView" | "manual"; default "mount"
+  - play?: boolean — for trigger="manual"
+  - speed?: DemoSpeed — "slow" | "normal" | "fast"; default "normal"
+  - loop?: boolean
+  - loopDelay?: number — ms between loop iterations, default 2000
+  - readOnly?: boolean — disables editing AND focusability; programmatic playback still works; use for marketing demos so the script doesn't steal focus
+  - bare?: boolean — strip the card chrome
+  - className?: string
+when_to_use: |
+  THE PRIMITIVE for any text composition surface — Slack / Discord /
+  Teams chat input, AI chat / copilot prompt box, comment thread input,
+  GitHub / Linear / Jira comment box, Reddit / Twitter reply box,
+  Notion / Linear document body, email composer, post body, anywhere
+  a user types text and submits.
+
+  CONCRETE TEST — if you find yourself writing a `<textarea>` (or
+  `<Input>` styled tall) with a row of `<Bold>` / `<Italic>` /
+  `<Paperclip>` / `<Send>` buttons below or beside it, STOP. That is
+  `<Composer>`. Use it.
+
+  Common shapes:
+    Chat input with formatting + attachments + send
+      → <Composer formats={["bold","italic","code"]} toolbar attachments />
+    AI prompt box with paperclip + send
+      → <AIChatComposer />  (preset wrapping Composer)
+    Comment / reply input
+      → <ComposerReply triggers={[{char:"@", items: people}]} />
+    Document body editor
+      → <Composer toolbar formats={[...]} bare />
+
+  Built on Lexical for rich text, mentions, slash commands. The
+  `attachments` prop wires image paste + paperclip + chip preview row
+  with object URL lifecycle handled internally — don't roll that
+  plumbing yourself. The `triggers` prop wires @mentions and /slash
+  commands with a typeahead popover. The `formats` array picks which
+  toolbar buttons render when `toolbar` is on.
+
+  Shares the lib/demo step vocabulary with <Code> so scripted
+  typing/format/mention demos animate in the same rhythm as your
+  terminal demos.
+composes_with: [AIChatComposer (preset wrapping this with paperclip + send + attachments), ComposerReply (preset for comment threads), AIChat (uses AIChatComposer internally), Card (host above for reply boxes), Avatar (in leftActions slot for "your" avatar next to the input)]
+aliases: [
+  composer, message input, message bar, rich text editor, rich text input,
+  mention input, slash input, text editor, prompt input, comment composer,
+  comment input, reply input, reply box,
+  chat input, chat box, chat input bar, chat composer, chat field,
+  slack input, slack composer, slack message box, discord input,
+  discord composer, teams chat input, message composer, post composer,
+  textarea with toolbar, formatting input, formatted text input,
+  message field, send message input, write a message, compose message
+]
+---
+
+```jsx
+// Plain text chat-style composer
+<Composer
+  placeholder="Ask anything…"
+  onSubmit={(content) => send(content.text)}
+  formats={false}
+/>
+
+// Comment composer with mentions
+<Composer
+  placeholder="Add a comment…"
+  triggers={[{ char: "@", items: teamMembers }]}
+  onSubmit={(content) => postComment(content.text, content.mentions)}
+  submitOnEnter={false}
+  formats={["bold", "italic", "code"]}
+  toolbar
+/>
+
+// AI chat composer with attachments, mentions AND slash commands
+<Composer
+  placeholder="Describe a UI, or paste a screenshot…"
+  triggers={[
+    { char: "@", items: docs },
+    { char: "/", items: commands, stripTrigger: true },
+  ]}
+  attachments
+  onSubmit={(content, atts) => {
+    sendToAssistant(content.text, content.mentions, atts?.map(a => a.file));
+  }}
+  isLoading={isStreaming}
+  onStop={stop}
+/>
+
+// Marketing demo — scripted playback
+<Composer
+  placeholder="Type a message…"
+  triggers={[{ char: "@", items: [{ id: "1", value: "alice" }] }]}
+  steps={[
+    { type: "type", text: "Hey " },
+    { type: "mention", trigger: "@", value: "alice", query: "ali" },
+    { type: "type", text: ", check out " },
+    { type: "select", text: "check out" },
+    { type: "format", format: "italic" },
+    { type: "wait", ms: 800 },
+    { type: "submit" },
+  ]}
+  trigger="inView"
+  speed="normal"
+  loop
+/>
+```
+
+## Demo step vocabulary
+
+Shares `type` / `wait` / `clear` with `<Code>` (driven by the same `useScriptedDemo` hook). Adds Composer-specific verbs:
+
+- `{ type: "mention", trigger, value, query? }` — insert a mention/slash token. Pass `query` to show the typeahead in flight, then resolve to `value`.
+- `{ type: "format", format }` — apply a format to the current selection.
+- `{ type: "select", text }` — select a substring (precondition for `format`).
+- `{ type: "newline" }` — insert a paragraph break.
+- `{ type: "submit" }` — fire `onSubmit`.
+
+## Imperative handle
+
+```tsx
+const ref = useRef<ComposerHandle>(null);
+ref.current?.focus();
+ref.current?.clear();
+ref.current?.insert("…");
+ref.current?.restart();       // replay scripted steps from the start
+ref.current?.restart(3000);   // replay after a 3s delay
+ref.current?.getContent();    // { text, json, mentions }
+ref.current?.getEditor();     // underlying Lexical editor (escape hatch)
+```
+
+## Themes
+
+All colours read from CSS variables (`--gds-composer-*` palette in `globals.css`). The mention pills, toolbar buttons, attachment chips, and editor surface all rebrand with the active gradeui theme without component changes.
+
+## Anti-patterns
+
+```jsx
+// ❌ Rolling a chat / Slack / Discord input as <textarea> + manual
+//    toolbar buttons + Send button. This is the EXACT shape Composer
+//    exists to consolidate — caught in the wild on a "Slack clone"
+//    generation where the model assembled this inline.
+//    Loses: attachment intake + object URL lifecycle, mention popover,
+//    slash commands, action-row slots, the Lexical state graph for
+//    rich content round-trip, the scripted-demo step machine.
+<div className="border rounded-xl bg-card">
+  <textarea
+    placeholder="Message #general"
+    value={inputText}
+    onChange={(e) => setInputText(e.target.value)}
+    onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) handleSend(); }}
+    rows={3}
+    className="w-full bg-transparent p-3 resize-none focus:outline-none"
+  />
+  <Row justify="between" align="center" className="px-3 py-2 border-t">
+    <Row gap="xs">
+      <Button size="icon" variant="ghost"><Bold /></Button>
+      <Button size="icon" variant="ghost"><Italic /></Button>
+      <Button size="icon" variant="ghost"><List /></Button>
+      <Button size="icon" variant="ghost"><Smile /></Button>
+      <Button size="icon" variant="ghost"><Paperclip /></Button>
+    </Row>
+    <Button onClick={handleSend}>Send</Button>
+  </Row>
+</div>
+
+// ✅ The Grade way. Same shape, every affordance free.
+<Composer
+  placeholder="Message #general"
+  formats={["bold", "italic", "code", "ul"]}
+  toolbar
+  attachments
+  triggers={[{ char: "@", items: teamMembers }]}
+  onSubmit={(content, atts) => handleSend(content.text, atts)}
+/>
+```
+
+```jsx
+// ❌ Reaching for <Input> (single-line) for a multi-line chat / reply
+//    surface. Input is for one-line text fields. Use Composer for any
+//    surface where the user might type more than one line — chat,
+//    comments, post bodies.
+<Input
+  placeholder="Reply to thread…"
+  value={reply}
+  onChange={(e) => setReply(e.target.value)}
+/>
+<Button onClick={postReply}>Reply</Button>
+
+// ✅ ComposerReply preset has the right defaults for a reply box.
+<ComposerReply
+  placeholder="Reply to thread…"
+  triggers={[{ char: "@", items: people }]}
+  onSubmit={(content) => postReply(content.text)}
+/>
+```
+
+```jsx
+// ❌ Importing TipTap, Lexical, Slate, or any other editor framework
+//    directly into a scaffold. Composer already wraps Lexical and
+//    handles all the plumbing.
+import { useEditor, EditorContent } from "@tiptap/react";
+const editor = useEditor({ extensions: [StarterKit, ...] });
+<EditorContent editor={editor} />
+
+// ✅ Use Composer. Same capability, integrated with the design system.
+<Composer toolbar formats={["bold", "italic", "h1", "h2", "blockquote", "ul", "ol"]} />
+```

package/components/ui/dropdown-menu.md

@@ -7,7 +7,9 @@ props:
   - DropdownMenuTrigger: asChild?: boolean — usually wraps a Button
   - DropdownMenuContent: align? "start" | "center" | "end"; side? "top" | "right" | "bottom" | "left"; sideOffset? number
   - DropdownMenuContent: surface? (solid | translucent | glass | glass-strong) — what the menu surface is *made of*. `solid` (default) is `bg-popover`. `translucent` matches Apple HIG / iOS menu sheets. `glass` for menus floating over rich canvases.
+  - DropdownMenuContent: size? "default" | "sm" | "xs" — menu density; cascades to every item (Item, Checkbox, Radio, SubTrigger, Label) via context so a compact trigger gets a compact menu. Use "xs" in dense tool panels.
   - DropdownMenuSubContent: surface? (solid | translucent | glass | glass-strong) — same axis applied to nested submenu surfaces
+  - DropdownMenuSubContent: size? "default" | "sm" | "xs" — match the parent content's size down the tree
   - 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

package/components/ui/field.md

@@ -0,0 +1,26 @@
+---
+name: Field
+import: "@gradeui/ui"
+props:
+  - layout?: "option" | "setting" — option (default): control leads, text beside it; setting: text leads, control pinned trailing
+  - children: one bare control (Checkbox / RadioGroupItem / Switch) + Field.Label + Field.Description? + Field.Trailing? — order does not matter
+when_to_use: Pair a bare control with a label and optional description in a row, with id + aria-describedby wired automatically. Use layout="setting" for the classic settings row (label on the left, Switch on the right). For a selectable CARD where the whole surface is the control, use RadioCard / CheckboxCard / SwitchCard instead.
+composes_with: [Checkbox, RadioGroup, RadioGroupItem, Switch, Badge (inside Field.Trailing)]
+aliases: [field, form field, control row, label and description, two line checkbox, option row, setting row, toggle row]
+---
+
+```jsx
+<Field>
+  <Checkbox value="terms" />
+  <Field.Label>Accept terms</Field.Label>
+  <Field.Description>You agree to the privacy policy.</Field.Description>
+</Field>
+```
+
+```jsx
+<Field layout="setting">
+  <Field.Label>Email notifications</Field.Label>
+  <Field.Description>Weekly digest of activity.</Field.Description>
+  <Switch defaultChecked />
+</Field>
+```

package/components/ui/fill-picker.md

@@ -0,0 +1,36 @@
+---
+name: FillPicker
+import: "@gradeui/ui"
+props:
+  - value: FillValue — current paint ({ type, color?, gradient?, src?, fit?, repeat?, tileSize?, preset?, palette?, postPreset?, opacity? }) (required)
+  - onChange: (value: FillValue) => void — called on any change (required)
+when_to_use: Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. A fill-type icon row (solid · gradient · image · pattern · video · shader) switches the panel below; a global opacity sits at the foot. Emits a FillValue that maps 1:1 onto BackgroundFill props. This is a Studio/inspector chrome control — pair it with BackgroundFill, which renders the chosen paint. Not for app content.
+composes_with: [BackgroundFill (renders the FillValue), Popover (host it in a popover), ShaderPresetPicker (the shader tab), the inspector Fill section]
+aliases: [fill picker, paint picker, background picker, fill chooser, fill popover]
+notes: |
+  Grade is token-led, so the solid + gradient tabs lead with theme-token
+  swatches (`primary`, `accent`, `secondary`, `muted`, `card`,
+  `background`, `destructive`, `transparent`) rather than a freeform HSV
+  square. The "pattern" tab is sugar for an image fill with `repeat` on.
+
+  The `FillValue` is the shared data shape: store it on a frame and feed
+  it straight to `<BackgroundFill {...value} />`. Solid colour can be a
+  className (`bg-<token>`) instead of a layer; every other type renders
+  as a `<BackgroundFill>` child of the frame.
+---
+
+```jsx
+const [fill, setFill] = useState({ type: "shader", preset: "mesh", opacity: 0.35 });
+
+<Popover>
+  <PopoverTrigger asChild><button>Fill</button></PopoverTrigger>
+  <PopoverContent className="w-[320px] p-3">
+    <FillPicker value={fill} onChange={setFill} />
+  </PopoverContent>
+</Popover>
+
+<div className="relative overflow-hidden">
+  <BackgroundFill {...fill} />
+  <div className="relative z-10">…content…</div>
+</div>
+```

package/components/ui/input.md

@@ -3,10 +3,13 @@ name: Input
 import: "@gradeui/ui"
 props:
   - type?: string (text | email | password | number | search | url | tel | date)
+  - size?: "default" | "sm" | "xs" — control density. `default` (h-9) for forms; `sm` (h-8) and `xs` (h-7) for dense tool panels like the inspector.
+  - startSlot?: ReactNode — adornment rendered inside the leading edge (icon, prefix, currency symbol). Non-interactive by default so clicks focus the input.
+  - endSlot?: ReactNode — adornment rendered inside the trailing edge (unit like "px", a clear button, a stepper). Same pointer rules as startSlot.
   - 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.
+when_to_use: Any single-line text entry. Always pair with a Label for accessibility. Use startSlot/endSlot for icons, prefixes and units instead of hand-positioning absolute children; use size="sm"/"xs" in dense tool panels.
 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]
+aliases: [text field, textbox, textfield, form field, text input, secure field, search field, url field, number field, textinput, text input field, react native textinput, unit input, input with icon]
 ---
 
 ```jsx
@@ -15,3 +18,25 @@ aliases: [text field, textbox, textfield, form field, text input, secure field,
   <Input id="email" type="email" placeholder="you@example.com" />
 </div>
 ```
+
+Slots — a leading icon and a trailing unit, no manual positioning:
+
+```jsx
+<Input
+  size="sm"
+  type="number"
+  placeholder="0"
+  startSlot={<Ruler className="size-4" />}
+  endSlot={<span className="text-xs text-muted-foreground">px</span>}
+/>
+```
+
+Sizes — `default` for forms, `sm` / `xs` for dense panels:
+
+```jsx
+<div className="grid gap-2">
+  <Input size="default" placeholder="Default (h-9)" />
+  <Input size="sm" placeholder="Small (h-8)" />
+  <Input size="xs" placeholder="Extra small (h-7)" />
+</div>
+```

package/components/ui/label.md

@@ -3,8 +3,9 @@ name: Label
 import: "@gradeui/ui"
 props:
   - htmlFor?: string — binds to the input's id
+  - size?: "default" | "sm" | "xs" — text size, mirrors Input/Select/Textarea so a field and its label scale together. default = text-sm; xs = 11px for dense tool panels.
   - All native label HTML attrs
-when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control.
+when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control. Match `size` to the field it labels (size="xs" label over a size="xs" input).
 composes_with: [Input, Textarea, Checkbox, Switch, RadioGroup, Select]
 aliases: [label, form label, field label, caption]
 ---

package/components/ui/logo.md

@@ -0,0 +1,57 @@
+---
+name: Logo
+import: "@gradeui/ui"
+subcomponents: []
+props:
+  - sources: LogoSources (required) — artwork keyed by lockup then appearance:
+      { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }.
+      Each slot is any node (inline <svg>, <img>, component).
+  - lockup?: "square" | "horizontal" | "icon" (default "horizontal")
+  - mode?: "light" | "dark" (default "light") — the background the logo sits on
+  - mono?: boolean (default false) — use the single-colour artwork (inherits currentColor)
+  - size?: "sm" | "md" | "lg" | "xl" | number (default "md") — height; width is intrinsic
+  - label?: string — accessible name (brand name); becomes aria-label + role="img"
+  - decorative?: boolean — aria-hidden when the name is already nearby
+  - href?: string — renders the logo as a link (logo-links-home)
+  - className?: string
+when_to_use: A brand mark with built-in variations — a square mark for tight
+  spaces, a horizontal lockup for headers, monochrome for busy/inverted
+  surfaces. Reach for Logo in toolbars, sidenav headers, and footers instead
+  of dropping a bare <img>, so the lockup and on-dark/on-light treatment are
+  switchable by prop. The artwork is supplied by the consumer; Logo just picks
+  the right slot for the context.
+composes_with: [AppShell, AppShellHeader, Sidebar, SidebarHeader, Row, Stack]
+aliases: [logo, brand, brandmark, wordmark, lockup, brand logo, app logo, logotype]
+---
+
+```jsx
+// Sidenav header: square mark when collapsed, horizontal when expanded.
+// Supply your own artwork per slot; here inline SVGs stand in.
+<Logo
+  lockup="horizontal"
+  mode="dark"
+  size="md"
+  label="Acme"
+  sources={{
+    square: { light: <AcmeSquare />, dark: <AcmeSquareWhite /> },
+    horizontal: { light: <AcmeWide />, dark: <AcmeWideWhite /> },
+    icon: { mono: <AcmeGlyph /> },
+  }}
+/>
+```
+
+### Anti-patterns
+
+DO NOT drop a bare `<img src="logo.png">` in a toolbar/sidenav/footer when you
+want light/dark or square/horizontal switching — use `<Logo>` so the variant
+is a prop.
+
+DO NOT invert a colour logo with a CSS filter to fake a dark version — supply
+the brand's real `dark` artwork in the `sources` slot.
+
+DO NOT set both `label` and `decorative` — `decorative` hides the logo from
+assistive tech; `label` names it. Pick one (name it unless the brand name is
+already in the DOM right beside it).
+
+DO NOT hardcode a width — `size` sets the height and the artwork keeps its own
+aspect ratio (square/icon are 1:1, horizontal stays wide).