@vegastack/design 0.1.0 → 0.2.0

package/skills/vegastack-consume/references/registry-integrity.md

@@ -0,0 +1,132 @@
+# Registry integrity — what the three steps actually guarantee
+
+The fail-closed add flow in the `vegastack-consume` skill is three commands. This explains what each
+one proves, what it deliberately does not prove, and how to configure it.
+
+## Contents
+
+- [Why three steps and not one](#why-three-steps-and-not-one)
+- [Step 1 — pre-write verification](#step-1--pre-write-verification)
+- [Step 2 — copy-in](#step-2--copy-in)
+- [Step 3 — post-write verification](#step-3--post-write-verification)
+- [The guarantee, stated precisely](#the-guarantee-stated-precisely)
+- [Limits](#limits)
+- [Configuration](#configuration)
+- [Staying up to date](#staying-up-to-date)
+
+## Why three steps and not one
+
+`shadcn add` **re-fetches** the item from the registry. A registry that changed between your
+preflight and the copy-in would slip through a single-step check — a time-of-check/time-of-use
+(TOCTOU) gap.
+
+Step 1 saves the exact verified bytes. Step 3 proves the files on disk match **those saved bytes**,
+not a fresh fetch. That is what closes the gap.
+
+## Step 1 — pre-write verification
+
+```bash
+npx --package=@vegastack/design vegastack-design verify --save "$ITEM" button
+```
+
+Full mode (the default) checks the Sigstore signature via `cosign` **and** the canonical item hash.
+The signature is the real trust boundary: it requires the deployed signed manifest and asserts the
+exact pinned GitHub-OIDC release identity, not merely a valid signature from anyone.
+
+```bash
+npx --package=@vegastack/design vegastack-design verify --hash-only --save "$ITEM" button
+```
+
+Hash-only mode skips `cosign`. Use it for local development, where `cosign` is unavailable, or before
+the signed manifest is deployed. **It does not prove provenance** — it only proves the item is
+internally consistent.
+
+Either mode aborts on mismatch and writes the verified item JSON to `--save`. If `--save` is omitted,
+it creates a private unique temp directory and prints the path; reuse that path in step 3.
+
+Retain the verified digest in the parent shell **before** `shadcn` or any dependency code runs:
+
+```bash
+EXPECTED="$(node -e 'process.stdout.write(JSON.parse(require("node:fs").readFileSync(process.argv[1],"utf8")).meta.integrity)' "$ITEM")"
+```
+
+Step 3 uses this independently retained value to detect replacement of the saved item itself, not
+just drift in the copied files.
+
+## Step 2 — copy-in
+
+```bash
+pnpm dlx shadcn@latest add @vegastack/button
+```
+
+The registry item content carries a provenance header (`// @vegastack <name>@<ver> sha256-…`), but
+the current shadcn CLI **strips leading comments on copy-in**. That is expected and is never a
+finding by itself — update tracking is header-optional.
+
+## Step 3 — post-write verification
+
+```bash
+npx --package=@vegastack/design vegastack-design verify \
+  --post-write --item "$ITEM" --expected-integrity "$EXPECTED" --target-dir .
+```
+
+Offline, no network. `--target-dir` is your project root, where shadcn wrote the files.
+
+It first recomputes the saved item's hash against the independently retained digest, then compares
+the bytes on disk against the item's `content` for every file. Exits 1 with a per-file diff on any
+mismatch.
+
+## The guarantee, stated precisely
+
+shadcn's contiguous start-of-file comment/whitespace prologue removal is accepted **only** for the
+file types it actually transforms. After that:
+
+- every non-import line must match byte-for-byte;
+- an `import` (or `export … from`) line may differ **only** in its module specifier, and **only** when
+  that difference exactly matches the registry-source-alias → consumer-alias rewrite declared by your
+  `components.json` (resolved using standard TypeScript/JavaScript `paths`).
+
+Anything else exits 1: an injected or removed line, an altered non-import line, an import repointed to
+a non-alias specifier, altered import bindings, or a missing file. No executable code can change
+without being caught.
+
+## Limits
+
+It proves byte-faithfulness _modulo_ the exact transformed-code leading-comment removal and the
+configured alias rewrite. It does **not** evaluate arbitrary build-tool alias plugins, package import
+maps, or extended config files.
+
+## Configuration
+
+`--help` lists every flag and environment variable: `VEGASTACK_REGISTRY`,
+`VEGASTACK_TRUSTED_REGISTRY_ORIGIN`, the `CF_ACCESS_*` service-token headers, and `VEGASTACK_SIGNER_*`.
+
+Credentialed requests must use the exact trusted HTTPS origin (production is the default) and
+redirects are rejected. A custom credentialed registry must set its trust anchor in
+operator-controlled process or CI configuration — **never** in a checkout-local dotenv file.
+
+If `@vegastack/design` is a devDependency, wire `verify:registry` (pre-write) and
+`verify:registry:post` (post-write) scripts instead of invoking `npx` each time.
+
+## Staying up to date
+
+Copy-in means no automatic updates — you re-pull when you want them.
+
+```bash
+npx --package=@vegastack/design vegastack-design check-updates                  # ⬆ update · ≈ drift · ✓ up to date · ? not in registry
+npx --package=@vegastack/design vegastack-design check-updates --fail-on-update # CI drift gate (exit 1 on update or drift)
+```
+
+A provenance header is used as a fast path when present. For normal headerless shadcn copies, the
+tool maps the exact registry target by filename and compares the complete installed item after the
+real leading-comment and configured-alias transforms.
+
+`≈ drift` means the file differs from the registry item — either an upstream update or your own local
+edits. It refuses to attach credentials to any origin other than `VEGASTACK_TRUSTED_REGISTRY_ORIGIN`
+(default `https://design.vegastack.com`) and never follows registry redirects.
+
+Per stale component: `shadcn add @vegastack/<name> --diff` to review, then `--overwrite` to apply,
+then re-run the post-write verification above.
+
+Status is computed by hash, so a component correctly reads `up to date` when the registry's global
+version bumped but that component's content did not change.

package/skills/vegastack-design-audit/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: vegastack-design-audit
+description: Read-only audit of an application that consumes the VegaStack design system — finds hardcoded colours and sizes, off-system utility classes, raw HTML where a component exists, accessibility gaps, provider/setup mistakes, and component copies that have drifted from the registry. Reports file:line findings with severity; never edits. Use when asked to audit a project for design-system alignment, check token compliance, or find stale VegaStack components.
+---
+
+# Consumer design audit (read-only)
+
+**Reports findings; never edits.** Output is a grouped `file:line · rule · fix · severity` list.
+
+This audits an application that consumes VegaStack. Scope it to your own UI source — **exclude
+`components/ui/`**, which holds copied-in VegaStack components you do not own. Drift there is a
+separate check (§5), not a styling finding.
+
+## 1. Drift and setup first
+
+These are mechanical and catch the highest-value problems:
+
+```bash
+npx --package=@vegastack/design vegastack-design check-updates
+```
+
+`⬆ update` means the registry has a newer version. `≈ drift` means the installed file differs from
+the registry item — either an upstream change or a local edit to a file you do not own. Both are
+findings; a local edit to a copied-in component is a **high** finding, because the next
+`--overwrite` silently destroys it. The fix is to move the customisation into your own wrapper
+component or a token override.
+
+Then verify setup, since these failures look like component bugs:
+
+- Is `@vegastack/design/theme.css` (or `preset.css`) imported before your own CSS?
+- Does the app root have `isolation: isolate` — either via `base.css` or `className="isolate"`?
+  Without it, portaled popups render under page chrome.
+- Is `<VegaStackProvider>` mounted once at the app root, with `suppressHydrationWarning` on `<html>`?
+- Are there two providers, or a provider mounted below a route boundary? Both cause theme and toast
+  bugs that present as random.
+
+## 2. Hardcoded visual values
+
+Every visual value must resolve through a semantic token.
+
+**The searches below produce candidates, not findings.** Open every hit before reporting it. A `#`
+match inside a comment, a URL fragment, a CSS id selector, or a string that documents some library's
+default is not a hardcoded colour. A `[…]` arbitrary value is legitimate when it holds a
+`var(--token)`, a `calc()` containing one, a layout primitive (`fr`, `%`, `auto`, `min-content`), or
+a CSS keyword. Reporting a comment as an error costs the owner more trust than the finding is worth.
+
+```bash
+rg -n '#[0-9a-fA-F]{3,8}\b' --glob '!components/ui/**' --glob '*.{ts,tsx,css}'
+rg -n '\b(bg|text|border|fill|stroke|ring)-(slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}' --glob '!components/ui/**'
+rg -n '\[[0-9]+(px|rem|em)\]' --glob '!components/ui/**'
+rg -n 'style=\{\{' --glob '!components/ui/**'
+```
+
+- **hardcoded colour** — a hex literal used as a style value. Use a semantic token. **error**
+- **raw palette** — a Tailwind palette class. Use `bg-primary`, `text-muted-foreground`,
+  `border-border`, or a status family. **error**
+- **hardcoded dimension** — an arbitrary px/rem value. Use the size, spacing, or radius scale.
+  **error**
+- **inline style** — allowed only when every key is a `--*` custom property. Any direct visual
+  property is a finding. **error**
+
+## 3. Off-system utilities
+
+```bash
+rg -n '\b(rounded-xl|rounded-2xl|rounded-3xl|text-4xl|text-5xl|text-6xl|font-bold|font-semibold|transition-all|transition-colors|z-[0-9]+|opacity-[0-9]+|tracking-[a-z]+|shadow-[a-z]+|blur-[a-z]+)\b' --glob '!components/ui/**'
+```
+
+- `rounded-xl` and larger do not exist — the scale caps at `rounded-lg`. **error**
+- `text-4xl` and larger are off-scale — use `text-display-sm/md/lg/xl`. **error**
+- `font-bold`/`font-semibold` — the weight ladder is 400/500, owned by the type roles. **error**
+- `transition-all` / `transition-colors` — colour changes are immediate; enumerate the causal
+  opacity, transform, or geometry properties. **error**
+- a raw `z-N` — two bands only: `z-(--z-raised)`, `z-(--z-overlay)`. **error**
+- a raw `opacity-NN` — use an `--opacity-*` role (`opacity-0`/`opacity-100` are exempt). **warning**
+- raw `tracking-*`, `shadow-*`, `blur-*` — owned by the type and effect roles. **warning**
+- a raw `/NN` colour-alpha step — use an `--alpha-*` role. Alpha and opacity are different roles and
+  are not interchangeable. **warning**
+- `uppercase` on non-mono type, or above 14px. Uppercase is mono-exclusive. **warning**
+
+Every `transition*` utility must pair a `duration-*` **and** an `ease-*` token in the same class
+string, or it silently inherits a default curve. **warning**
+
+## 4. Component substitution and accessibility
+
+- **Raw HTML where a component exists** — a native `<button>`, `<input>`, `<select>`, `<textarea>`,
+  or a hand-rolled dialog, dropdown, tooltip, or tab set. Use the VegaStack component; it carries the
+  states, keyboard model, and ARIA. **warning**
+- **A second icon library**, or a hand-written inline `<svg>` used as an icon. Only `lucide-react`
+  and `Icon`/`BrandIcon` from `@vegastack/design/icons` are sanctioned. **error**
+- **`outline-none` with no replacement focus affordance** anywhere in the file. **error**
+- **Icon-only controls with no accessible name** — a button with no visible text needs `aria-label`
+  or `aria-labelledby`. Prefer `IconButton`, which requires it at the type level. **error**
+- **Missing states** — a surface that fetches data needs loading, empty, and error states, not just
+  the success path. **warning**
+- **Truncation** — `truncate`/`line-clamp-*` on the same element as `flex`/`inline-flex` silently
+  does nothing, because `flex` wins the display conflict. Put `min-w-0` on the flex container and
+  `truncate` on an inner span. **warning**
+- **Touch targets** below 24×24 — expand with an invisible hit area
+  (`relative` + `before:absolute before:-inset-N`), not a larger visual control. **warning**
+
+## 5. Local edits to copied-in components
+
+```bash
+rg -n '@vegastack' components/ui/ -l
+```
+
+A copied-in component is yours to keep but not to edit — the next `--overwrite` overwrites it. Any
+diff reported by `check-updates` as `≈ drift` on a file you did not intend to change is a **high**
+finding. Route customisation through a token override, a wrapper component, or a `className` prop.
+
+A missing `// @vegastack …` provenance header is **normal** and never a finding on its own: the
+shadcn CLI strips leading comments during copy-in.
+
+## 6. Output
+
+Group by file. Each finding: `file:line` · rule · suggested fix · severity.
+
+- **error** — a hardcoded visual value, an accessibility violation, or an edited copied-in component.
+- **warning** — raw HTML where a component exists, a missing state, an off-system utility with a
+  working fallback.
+- **info** — a component with an available update worth a deliberate `--diff` review.
+
+Never auto-fix. Report, and let the owner decide.

package/skills/vegastack-design-system/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: vegastack-design-system
+description: Build product UI with the VegaStack design system — which component to pick, the semantic token vocabulary, composition patterns for forms and overlays, and the do/don't rules that keep code on-system. Use before generating or editing any UI code in a project that consumes @vegastack/design.
+---
+
+# VegaStack design system
+
+Base UI + Tailwind v4 + OKLCH semantic tokens. Components are copy-in via a private shadcn registry;
+the runtime and token layer are public npm.
+
+Load this before writing UI code. For first-time project setup (installing packages, wiring the
+provider, configuring registry access), use the `vegastack-consume` skill instead.
+
+## Pick a component
+
+[references/components.md](references/components.md) is the complete roster, grouped by family, with
+each component's one-line purpose. Read it when choosing between components.
+
+You can also query the live registry, which carries `meta.whenToUse` / `meta.whenNotToUse` on every
+item to disambiguate close calls (primary vs. ghost vs. destructive):
+
+```bash
+pnpm dlx shadcn@latest list @vegastack
+```
+
+Rules that decide most component questions:
+
+- **Compose `app-shell`** for a sidebar + header + main layout — never hand-roll the landmark trio.
+- **`segmented`** for 2–5 exclusive options inline; **`tabs`** when the choice switches page regions.
+- **`alert` variant=strip** for in-content notices and plan/trial rows; **`announcement-banner`** only
+  for the full-width inverse strip at the very top of the page.
+- **`code-block`** for static syntax-highlighted source; **`terminal`** for command sessions.
+- **`navigation-menu`** is top-level site navigation with panels, not a menu inside a page.
+- **Marketing components** (`marketing-surface`, `section-header`, `figure-frame`, `terminal`,
+  `logo-row`, `testimonial`, `staggered-text-reveal`, `particle-field`, `pricing-section`, and
+  Button's `cta` variant) are scoped to `.vs-marketing` and must never appear in product UI.
+
+## Tokens
+
+Semantic CSS custom properties from `@vegastack/design-tokens/theme.css` (OKLCH, `:root` + `.dark`).
+Always use the utility, never a raw value.
+
+| Role     | Utilities                                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------ |
+| Surface  | `bg-background` `bg-card` `bg-popover` `bg-muted` `bg-accent` `bg-sidebar-*`                     |
+| Text     | `text-foreground` `text-muted-foreground` `text-{primary,accent,popover}-foreground`             |
+| Status   | `bg-{destructive,success,warning,info}` + `-subtle` / `-hover` / `-text` / `-foreground`         |
+| Border   | `border-border` `border-input` — there are no rings; focus is the native outline                 |
+| Radius   | `rounded-{xs,sm,md,lg}` — `lg` is the cap, `xl` does not exist                                   |
+| Type     | `text-{xs…3xl}` · `text-h1…h4` · `text-label` · `text-mono-label` · `text-display-{sm,md,lg,xl}` |
+| Font     | `font-sans` `font-mono` `font-serif`                                                             |
+| Motion   | `duration-{fast,base,slow}` paired with `ease-{standard,emphasized,exit,spring}`                 |
+| Entrance | `motion-pop-in` `motion-enter-up` `motion-shake`                                                 |
+
+Alpha and opacity are **different roles**: colour compositing takes an `--alpha-*` token
+(`bg-foreground/(--alpha-ink-tint)`), whole-element opacity takes an `--opacity-*` token
+(`opacity-(--opacity-dim)`). A raw `/20` or `opacity-50` is wrong in both cases.
+
+`--brand` is a marker-role accent only — never a functional state colour.
+
+**Overriding tokens:** redefine one runtime variable in your global CSS and every component repaints
+in both themes:
+
+```css
+:root {
+  --primary: oklch(0.55 0.2 264);
+}
+```
+
+Never override a `--color-*` variable — that is the build-inlined Tailwind bridge, not the runtime
+contract.
+
+## Composition patterns
+
+- **Forms** — Base UI `Field` + react-hook-form `Controller` + Zod 4 (`z.email()`). `Field.Control`
+  emits `onValueChange`, not a DOM `onChange` event.
+- **Overlays** — enter/exit is driven by `data-starting-style`/`data-ending-style` on the popup root,
+  inside a portal + positioner. Theme, toast, tooltip, and direction providers all come from
+  `<VegaStackProvider>`; your app root needs `isolation: isolate` or portaled popups can render under
+  page chrome.
+- **Compound parts import flat** — `import { DialogTrigger, DialogContent }`. Sub-property access
+  (`<Dialog.Trigger>`) only works inside a `'use client'` file, because across the RSC boundary the
+  compound is a client-reference proxy and the sub-property is `undefined`.
+- **Polymorphism** uses Base UI's `render` prop, never Radix's `asChild`.
+
+## Do / Don't
+
+**Do**
+
+- Use a semantic token for every visual value.
+- Use `render` for polymorphism and `cn()` from `@vegastack/design` for class merging.
+- Use `Icon`/`BrandIcon` from `@vegastack/design/icons`, or `lucide-react` directly for internal
+  chrome.
+- Implement every applicable state: default, hover, focus, loading, empty, error, success, disabled.
+- Put `truncate` on an inner span, with `min-w-0` on the flex container.
+
+**Don't**
+
+- Hardcode a hex, a px value, or a raw Tailwind palette class (`bg-neutral-900`, `text-red-500`).
+- Use `font-bold`/`font-semibold` — the weight ladder is 400/500, owned by the type roles.
+- Use `rounded-xl`, `text-4xl` or larger, a raw `z-N`, or `transition-all`/`transition-colors`.
+- Set `outline-none` without providing another focus affordance.
+- Pull in a second icon library or hand-write an inline `<svg>` as an icon.
+- Put `uppercase` on non-mono type, or on anything above 14px.
+
+## Reference
+
+Full component documentation, live previews, prop tables, and accessibility notes:
+<https://design.vegastack.com/docs/components>. Machine-readable summaries for agents are at
+`/llms.txt` and `/llms-full.txt` on the same host.

package/skills/vegastack-design-system/references/components.md

@@ -0,0 +1,151 @@
+# Component roster
+
+<!-- GENERATED — do not hand-edit. Regenerated from the design system's component contract,
+     which is the authority for membership and counts. -->
+
+**96 components**, plus 439 animated-icon items, 2 hooks (`use-animation-replay`, `use-mobile`), and 1 starter block (`dashboard-01`) — 538 registry items in total.
+
+Install any of them with `shadcn add @vegastack/<name>`. Animated icons install as
+`@vegastack/icon-<name>`; the bare name is reserved for components, so `icon-button` is the
+component and never an icon.
+
+## Actions
+
+- **`button`** — Trigger an action. 15 variants × 8 sizes, with loading + Base UI Button semantics.
+- **`copy-button`** — Copy a value to the clipboard with transient check feedback — a ghost icon button that swaps Copy → Check and fires onCopied.
+- **`icon-button`** — A square, icon-only action button — a thin Button wrapper that requires an accessible label.
+- **`segmented`** — Segmented control — a single-select, always-one-selected view/mode switcher on a muted track with a raised active chip.
+- **`split-button`** — A primary action joined to a dropdown of related secondary actions — one default click, plus a chevron menu.
+- **`toggle`** — A two-state button that can be pressed on or off — bold/italic, mute, pin.
+- **`toggle-group`** — Joined toggle buttons sharing one selection — single or multiple, variants/sizes, horizontal/vertical, full keyboard navigation.
+
+## Form
+
+- **`auto-save-input`** — An input that debounces edits and persists them via an async onSave, with an inline idle/saving/saved/error status.
+- **`checkbox`** — A binary (or tri-state) toggle — checked, unchecked, indeterminate, disabled, built on Base UI Checkbox.
+- **`color-picker`** — A swatch-triggered popover presenting a grid of preset colors — pick one, fire onValueChange, mark the selection.
+- **`combobox`** — A filterable, keyboard-navigable listbox behind a text input — type-to-filter, grouped items, async status, and a multi-select chip mode.
+- **`country-select`** — A searchable country combobox returning the ISO 3166-1 alpha-2 code, with flag + name. Built on Combobox.
+- **`date-picker`** — Pick a single date or a date range from a calendar popover — token-styled, keyboard-navigable, with optional quick presets.
+- **`emoji-picker`** — A popover with a searchable, category-grouped grid of emoji that returns the selected character via onSelect (curated set, not full Unicode).
+- **`field`** — A form-field wrapper — label, inline label action, description, and error/success message, built on Base UI Field.
+- **`field-inline`** — Click-to-edit text — displays a value, swaps to a focused input on click, commits on Enter or blur, cancels on Escape.
+- **`input`** — A styled Base UI input — all input types, Field state data attributes, error and disabled states, focus-visible ring, and optional prefix/suffix addons.
+- **`label`** — A styled native label for form controls — htmlFor association, disabled dimming, optional required indicator.
+- **`otp-input`** — A multi-slot one-time-passcode input — keyboard navigation, paste distribution, masking, disabled, built on Base UI OTP Field.
+- **`password-input`** — A password field with a show/hide eye toggle and an optional live requirements checklist.
+- **`radio-group`** — A set of mutually-exclusive options — single selection, arrow-key navigation, disabled, built on Base UI Radio Group.
+- **`region-select`** — A searchable combobox of states/provinces for a country, with a free-text fallback for countries with no subdivisions.
+- **`select`** — A dropdown for choosing one option — trigger with value and chevron, grouped scrollable popup, full keyboard navigation, animated enter/exit.
+- **`slider`** — Pick a number or a [from, to] range from a continuous track — keyboard accessible, with optional steps. Built on Base UI Slider.
+- **`switch`** — An on/off toggle for instant, self-saving binary settings — built on Base UI Switch.
+- **`textarea`** — A styled native textarea for multi-line text — error/disabled states, a focus-visible ring, and an optional auto-grow mode.
+
+## Display
+
+- **`code-block`** — A code panel with a language header and copy affordance — the shared code surface for chat transcripts, docs, and examples.
+- **`onboarding-checklist`** — A getting-started card — segmented progress + step rows, collapsible to a progress pill.
+- **`stat`** — A labelled value block — muted label over a value, honest faint empty state, optional delta line. Two scales.
+- **`tag-group`** — Hue-tinted label chips on the 10-hue tag palette, with +N overflow collapsing and removable tags.
+
+## Data display
+
+- **`accordion`** — A stack of collapsible sections — single or multiple open, animated height, a rotating chevron, full keyboard support.
+- **`animated-number`** — A number display that tweens from its previous value to a new one on every change — Intl.NumberFormat-aware (currency/percent/compact), instant under reduced motion, the dashboard stat-card counter.
+- **`avatar`** — A circular user/entity image with an initials fallback, five sizes, and an overlapping AvatarGroup stack.
+- **`badge`** — A compact status or label chip. 3 variants × semantic colors × 4 sizes, with dot, loading, and icon support.
+- **`card`** — A borders-only content surface — no shadows, with composable header, content, and footer parts.
+- **`chart`** — A themed Recharts wrapper — token-only series colors (--chart-1…--chart-8), a bordered tooltip/legend, and Recharts' own built-in keyboard + screen-reader layer.
+- **`collapsible`** — A single toggleable open/close region with an animated height, built on Base UI Collapsible.
+- **`empty`** — A zero-data placeholder — icon, title, description, actions, with intent tints and an optional dashed border.
+- **`item`** — A compact anatomy row for list/feed content — media, title, description, actions, groupable with dividers.
+- **`kbd`** — A styled keyboard-key indicator — OS-aware modifier glyphs, a keys array, and small sizes.
+- **`markdown-view`** — Render a markdown string to safe, token-styled HTML — headings, lists, code, blockquotes, links, GFM tables — XSS-safe, no raw HTML.
+- **`relative-time`** — Render a date as a human-relative string ("2 hours ago", "yesterday") with native Intl.RelativeTimeFormat — self-updating, with an absolute-date tooltip.
+- **`status-icon`** — A small status indicator icon — todo, in progress, blocked, done — each mapping to a lucide icon and semantic color.
+- **`table`** — Styled semantic table primitives — a scrollable container plus header, body, footer, row, head, cell, caption.
+- **`truncated-text`** — Truncate text to one line or N lines with an ellipsis, revealing the full text in a tooltip only when it overflows.
+
+## Data
+
+- **`data-list`** — A generic, typed data table — configurable columns, row selection, sortable headers, plus loading and empty states.
+- **`filter-bar`** — A row of removable filter chips, an "Add filter" dropdown, and an optional search input — for list and table filter toolbars.
+- **`property-list`** — Record-facts rows: an icon+label column beside a value column, as an accessible definition list.
+
+## Overlay
+
+- **`alert-dialog`** — A modal confirmation dialog with four semantic intents — non-dismissable, forcing a deliberate Cancel/confirm choice.
+- **`context-menu`** — A menu of actions revealed by right-click (or long-press) — items, submenus, separators, labels, shortcuts, checkbox/radio.
+- **`dialog`** — A modal overlay — five sizes, a header/footer layout, focus trapping, and animated enter/exit.
+- **`dropdown-menu`** — A menu of actions triggered by a button — items, submenus, separators, labels, shortcuts, and checkbox/radio selections.
+- **`hover-card`** — A rich preview panel that opens on hover or focus — interactive content, four directions, forgiving delays.
+- **`popover`** — A click-triggered floating panel for arbitrary content — positioning, an optional arrow, and built-in dismiss.
+- **`sheet`** — A dialog that slides in from a screen edge — four sides, header/footer layout, focus trapping, animated slide.
+- **`tooltip`** — A floating label on hover or focus — smart shared delay, rich content, optional keyboard hints, collision-aware positioning.
+
+## Navigation
+
+- **`breadcrumb`** — A hierarchical navigation trail — links, separators, the current page, and ellipsis collapse for long paths.
+- **`command`** — A searchable command palette — filtered, grouped items with keyboard navigation, optionally inside a ⌘K dialog.
+- **`navigation-menu`** — Site-nav mega-dropdown on the Base UI NavigationMenu primitive — chip triggers, one shared sliding panel, grid links.
+- **`page-header`** — The standardized header at the top of a page — back button, breadcrumb trail, title, description, actions, secondary menu, and a favorite star.
+- **`pagination`** — Page navigation — previous/next, numbered page links, an ellipsis for long ranges, and the active page.
+- **`sidebar`** — A collapsible app navigation rail — header/content/footer, labelled groups, menu items with active state, and an expand/collapse trigger.
+- **`tabs`** — Layered content sections — line or pill variants, optional icons and count badges, horizontal or vertical, full keyboard navigation.
+
+## Feedback
+
+- **`alert`** — A status banner — five semantic variants, an optional icon, and an optional dismiss button.
+- **`progress`** — A determinate horizontal progress bar for measurable, ongoing tasks — built on Base UI Progress.
+- **`progress-indicator`** — A compact circular pie-fill progress indicator (0–100%) — a server-safe SVG glyph in circle or squircle shapes.
+- **`provider`** — The single app-root wrapper — theme (next-themes), Sonner toasts, tooltip coordination, and text direction in one mount-once component.
+- **`skeleton`** — A token-driven loading placeholder — line, circle, rect, card shapes, configurable count, reduced-motion-aware pulse.
+- **`sonner`** — Brief, non-blocking notifications — a token-styled Sonner toaster with success/error/warning/info variants that follows the theme.
+- **`spinner`** — An indeterminate loading indicator — a spinning icon inheriting currentColor, four sizes, role=status by default.
+
+## Layout
+
+- **`app-shell`** — The shared dashboard layout — a skip-linked sidebar + header + scrollable main region, composing Sidebar/SidebarTrigger into one reusable, hash-tracked shell.
+- **`resizable`** — Draggable, keyboard-resizable split panes — horizontal or vertical, nestable, with an optional collapsible panel. Built on react-resizable-panels.
+- **`scroll-area`** — A scroll container with custom, auto-hiding scrollbars — dual-axis, token-styled, built on Base UI ScrollArea.
+- **`separator`** — A thin rule dividing content — horizontal or vertical, decorative by default, built on Base UI.
+- **`settings-row`** — A borders-only settings layout — titled sections, bordered cards, and label-plus-control rows.
+
+## Media
+
+- **`image`** — A presentational framed image with aspect-ratio, rounding, a loading skeleton, and an error fallback.
+- **`notification-bell`** — A bell icon button with an unread-count badge overlay. Presentational — the app supplies the count.
+
+## Rich text
+
+- **`text-edit`** — A Tiptap-based rich-text editor with a compact, token-styled toolbar (bold, italic, strike, heading, lists, blockquote, code) — controlled HTML in, HTML out. Collaboration deferred.
+
+## Chat
+
+- **`tool-call-chip`** — An agent-activity chip — tool action label + muted result meta, optionally rendered as a button.
+
+## Communication
+
+- **`attachment`** — A file chip / thumbnail card for chat and message-compose surfaces - media slot, name + meta, uploading/error/complete states, remove/download actions.
+- **`bubble`** — A chat speech bubble - 7 token-driven variants (incl. brand-tinted), start/end alignment, interactive content, and a floating reactions chip.
+- **`marker`** — An inline conversation marker - status lines, system notes, and labelled dividers. 3 variants, Base UI render-polymorphic.
+- **`message`** — Layout primitives for a conversation row - avatar anchoring, content column, header/footer slots, start/end alignment. Server-safe.
+- **`message-scroller`** — A virtualised, auto-scrolling conversation viewport - pins to the latest message, preserves position on prepend, tracks the anchor, and a floating scroll-to-end button.
+
+## Marketing
+
+- **`announcement-banner`** — A dismissible one-line announcement — the full-width inverse page-top band (in-content notices use Alert variant=strip).
+- **`comparison-matrix`** — A plan-feature matrix with accessible ✓/− availability cells and a highlighted plan column.
+- **`figure-frame`** — A sharp-cornered media frame with an optional mono FIG-annotation caption.
+- **`logo-row`** — A muted logo/wordmark strip — alpha-dimmed at rest, restoring on hover for linked items.
+- **`marketing-surface`** — Opts a subtree into the brand's dark warm ground, independent of the page's .dark class.
+- **`particle-field`** — A deterministic, very-low-alpha canvas field of drifting phosphor dots — hero atmosphere only.
+- **`pricing-section`** — Marketing plan cards — mono price display, check feature lists, highlighted-plan treatment.
+- **`ruled-band`** — A hairline-bounded editorial strip with mono-label ends — the changelog/serial-number furniture.
+- **`section-header`** — A marketing section lead-in — mono uppercase eyebrow, display-scale title, optional description.
+- **`terminal`** — A dark mono command block with a phosphor prompt glyph and a composed copy button.
+- **`testimonial`** — A pull-quote — a serif-italic quote over a mono uppercase attribution line.
+
+## Marketing motion
+
+- **`staggered-text-reveal`** — Display text whose words rise in on mount, staggered one motion-enter-up step apart — CSS-only.