@nqlib/nqui 0.5.6 → 0.6.1

package/docs/nqui-skills/SKILL.md

@@ -9,17 +9,74 @@ SSOT: `packages/nqui/docs/nqui-skills/`
 
 Installed into `.cursor/nqui-skills/` via `npx @nqlib/nqui init-skills`.
 
+> **Token discipline:** Before loading multiple files, read **[READ_BUDGET.md](./READ_BUDGET.md)** — it routes any task to 1–3 files. The skills folder is ~5000 lines; don't bulk-read.
+
+---
+
+## Agent Build Protocol
+
+When asked to **build a new view, page, or feature**, follow this order:
+
+1. **Load design context** — Check `.impeccable.md` in project root. If missing, run `/impeccable teach` before any design work.
+2. **Understand the user's job** — One outcome, one primary action. What moves to a secondary surface? (See `nqui-composition/SKILL.md` checklist.)
+3. **Pick a layout pattern** — Read `COMPOSITION.md` (named patterns: app shell, settings, dashboard, wizard, master-detail). Match the pattern to the job.
+4. **Look up combos** — Read `RECIPES.md` for the specific situations you need (status pill, bulk actions, filter toolbar, the three states, etc.). Don't reinvent.
+5. **Select components** — Use `HUMAN_GUIDE.md` (task → doc) and `COMPONENTS_INDEX.md` decision tables. Load one `nqui-<name>.md` per component.
+6. **Apply the design system** — Load `nqui-design-system/SKILL.md` for sizing, spacing, and scroll contracts.
+7. **Cover all states** — Walk `STATES.md` for every interactive surface. Empty, loading, error are mandatory.
+8. **Write the copy properly** — Apply `WRITING.md` rules to every button, label, error, empty state, and toast. No "Submit", no "An error occurred", no exclamation marks.
+9. **Add motion only with intent** — If you animate anything, consult `MOTION.md` for timing/easing/choreography. Default to no motion unless it serves comprehension.
+10. **Build, then verify** — Run the pre-ship checklist in `COMPOSITION.md`. Run `/audit` on complex views.
+
+**Never skip step 1.** Generic output comes from missing design context, not missing components.
+**Never skip step 4** for product UI. The recipes encode lessons learned — bypassing them produces busy, AI-flavored work.
+**Never skip steps 7-9.** Missing states, lazy copy, and noisy motion are the three things that make AI-built UI feel AI-built.
+
+## The 30-second Linear designer test (mandatory before declaring done)
+
+Before saying "this is complete," do this thought experiment:
+
+> *If I showed this view to a senior designer at Linear, Vercel, or Things 3 — someone who builds product UI all day — what would they change in the first 30 seconds?*
+
+The honest answer is almost always one or more of these:
+
+1. **Hierarchy is weak** — too many same-weight elements competing
+2. **Empty/loading/error states are missing** or generic
+3. **Copy is lazy** — "Submit", "An error occurred", "Are you sure?"
+4. **Toolbar floats** instead of sitting in a `bg-muted/30` container
+5. **Multiple primary buttons** competing for attention
+6. **Spacing is monotonous** — same padding everywhere, no rhythm
+7. **Cards wrap everything** including things that don't need a card
+8. **No keyboard navigation** — buttons but no focus styles, no shortcuts
+9. **Decorative shadows / gradients** on flat elements that don't need depth
+10. **Motion is missing or busy** — either no transitions at all, or too many
+
+If you can name 2+ items from that list, the view isn't done. Fix them BEFORE asking the user. The point is to ship work that doesn't trigger any of these — not to ask the user "is this OK?" when you already know it isn't.
+
 ---
 
 ## nqui Component Library
 
 | Skill                           | When to use                                                        |
 | ------------------------------- | ------------------------------------------------------------------ |
+| **nqui-composition**            | Apple-inspired craft for composing screens (clarity / deference / depth). Read before building new views. |
+| **COMPOSITION.md**              | Named layout patterns, three-surface cap, anti-patterns, pre-ship checklist — read before building any view |
+| **RECIPES.md**                  | Component combos for common product situations (status pill, bulk actions, the three states, etc.) |
+| **STATES.md**                   | The 12-state matrix every interactive surface must cover. Mandatory checklist per view. |
+| **WRITING.md**                  | UX copy rules — buttons, errors, empty states, microcopy. The differentiator between AI-built and human-built. |
+| **MOTION.md**                   | Motion as a system — timing scale, easing vocabulary, choreography, reduced-motion. Read before animating anything. |
+| **ELEVATION.md**                | The 2+1 surface hybrid model — cap inline nesting at 2 surfaces, use spacing for the rest. Read before any layered UI. |
+| **HUMAN_GUIDE.md**              | Task → component doc routing (forms, toolbar, dashboard, overlays, states) |
+| **AGENT_PROMPT.md**             | Canonical system prompt for AI agents using nqui. Reference this in your agent setup. |
+| **EVAL.md**                     | 12-prompt eval set + grading rubric. Run before releases. |
+| **THEMING.md**                  | Brand customization without breaking the rules. |
+| **MIGRATION.md**                | Breaking changes per release. Scan before upgrading. |
 | **nqui-components**             | Implementing UI, choosing components, component props and examples |
-| **nqui-design-system**          | Design token conventions, spacing, Card + ScrollArea patterns      |
+| **nqui-design-system**          | Design token conventions, spacing, Card + ScrollArea / bounded panels (see `nqui-scroll-area.md` §0)      |
 | **nqui-shadcn**                 | Managing nqui components (adding, fixing, styling, composing UI)   |
 | **nqui-install**                | Install, setup peers, CSS init, CLI commands                       |
 | **nqui-bundle-size**            | Bundle size best practices when adding deps or creating packages   |
+| **nqui-data-tables**            | TanStack/native HTML tables + ScrollArea: bounded height, sticky header, HV scroll, IO or paging |
 | **nqui-local-published-toggle** | Switching between local and published @nqlib/nqui                  |
 
 ---

package/docs/nqui-skills/STATES.md

@@ -0,0 +1,154 @@
+---
+name: nqui-states
+description: The complete state matrix every interactive thing must handle. Use when building any view or component to ensure you've designed for ALL states, not just the happy path. AI work overwhelmingly fails on missing states (empty, loading, error, edge). This file is the checklist.
+---
+
+# nqui States — The Complete Matrix
+
+The #1 reason AI-built UIs feel unfinished: they design the happy path and forget the other 11 states. This file is the checklist. Read it for every screen and component. Don't ship until every applicable state has an intentional design.
+
+## The 12 states every interactive surface can be in
+
+| State | When | Designed how |
+|-------|------|--------------|
+| **Idle** | Default resting state | The thing you usually think of as "the design" |
+| **Hover** | Pointer over (desktop only — degrade gracefully on touch) | Subtle background shift, never a transform |
+| **Focus** | Keyboard navigation lands here | Visible ring (`focus-visible:ring-2 ring-ring`), never `outline:none` alone |
+| **Active / Pressed** | Mouse down / tap in progress | Slight darken or inset shadow, fast (<100ms) |
+| **Selected** | User has chosen this | Persistent visual change (e.g., `bg-accent/70`), distinct from hover |
+| **Disabled** | Action unavailable | Reduced opacity (`opacity-50`) + `cursor-not-allowed` + `aria-disabled` — but explain why somewhere |
+| **Loading** | Async work in progress, no result yet | Shape-matched `Skeleton`, NOT a spinner unless duration is unknown and tiny |
+| **Empty** | Loaded successfully, no data | `Empty` component with one sentence + one action that teaches the interface |
+| **Error** | Load or action failed | Inline `Alert variant="destructive"` with cause + recovery, never just "Error" |
+| **Optimistic** | User acted, we applied locally, server hasn't confirmed | Render the new state immediately + `toast` with undo |
+| **Stale** | Cached data, may be outdated | Subtle "Updated 3 min ago" indicator + refresh affordance |
+| **Success / Transient** | Action completed, briefly confirmed | `toast.success` (auto-dismiss) — NEVER a persistent banner |
+
+## State-coverage requirements by surface type
+
+Not every surface needs all 12. Use this matrix to know what's mandatory per surface.
+
+| Surface | Required states | Common omissions to fix |
+|---------|-----------------|------------------------|
+| **Lists / tables** | idle, loading, empty, error | Empty (most missed), error |
+| **Forms** | idle, focus, validation-error, submitting, success, server-error | Submitting state, server-error vs field-error |
+| **Buttons** | idle, hover, focus, active, disabled, loading | Loading state (with spinner inside button) |
+| **Inputs** | idle, focus, filled, invalid, disabled, read-only | Read-only vs disabled distinction |
+| **Cards / items in a list** | idle, hover, focus, selected | Focus (keyboard navigation) |
+| **Toggles / switches** | off, on, focus, disabled, indeterminate | Indeterminate for "mixed" bulk states |
+| **Async data views** | loading, empty, populated, error, refreshing | Refreshing (vs full reload) |
+| **File upload** | idle, dragging-over, uploading, success-each, error-each, complete | Dragging-over, per-file error |
+| **Search** | idle, typing, debouncing, loading, results, no-results, error | Debouncing vs loading distinction |
+| **Modals / sheets** | closed, opening, open, closing, blocked-by-pending-action | Blocked-by-pending (can't close mid-save) |
+
+## The state machine — common transitions
+
+Designing each state in isolation isn't enough. Design the **transition** between them.
+
+```
+fresh page load:
+  loading (skeleton, ~300ms min to avoid flash) → populated | empty | error
+
+user adds item:
+  populated → optimistic (new item appears immediately, slightly faded)
+            → confirmed (full opacity) | error (revert + toast)
+
+user deletes item:
+  populated → optimistic (item slides out + toast w/ undo, 6s)
+            → confirmed (gone) | undone (slides back)
+
+user submits form:
+  idle → submitting (button shows spinner, form disabled)
+       → success (toast + navigate | reset) | error (inline + keep values)
+
+cached data view:
+  stale (with indicator) → user pulls to refresh → refreshing (spinner overlay, keep stale visible)
+                        → updated | error (keep stale, show error toast)
+```
+
+## Mandatory rules
+
+1. **No state may be a blank screen.** If loading is < 300ms, suppress the skeleton (use a delay). If > 300ms, show one. Never show whitespace for an indeterminate period.
+2. **Empty is a design opportunity, not a failure.** Bad: "No items." Good: "No issues yet — create your first issue to start tracking." with a CTA.
+3. **Errors must say what + what to do.** Bad: "An error occurred." Good: "Couldn't save changes — check your connection and try again." with a Retry button.
+4. **Optimistic UI requires undo.** If you apply a destructive action immediately, the toast must offer undo for ≥ 6 seconds.
+5. **Focus state is non-negotiable.** Removing the focus ring (`outline: none`) without replacing it is an accessibility violation. Use `focus-visible:ring-2 ring-ring ring-offset-2`.
+6. **Disabled needs a reason.** A disabled button with no tooltip is a dead end. Either explain why (Tooltip on hover) or hide it.
+7. **Loading should preview the shape.** `Skeleton` blocks should match the dimensions of the real content — text lines as text-height bars, images as aspect-ratio boxes.
+8. **Success is transient.** Never leave a green success banner on screen — toast and dismiss. Only errors persist until acknowledged.
+
+## State templates (copy these)
+
+### List with all three async states
+```tsx
+{loading ? (
+  <ListSkeleton count={5} />
+) : error ? (
+  <Alert variant="destructive">
+    <AlertTitle>Couldn't load items</AlertTitle>
+    <AlertDescription>{error.message}</AlertDescription>
+    <AlertAction onClick={retry}>Try again</AlertAction>
+  </Alert>
+) : items.length === 0 ? (
+  <Empty>
+    <EmptyHeader>
+      <EmptyMedia variant="icon"><InboxIcon /></EmptyMedia>
+      <EmptyTitle>{emptyTitle}</EmptyTitle>
+      <EmptyDescription>{emptyDescription}</EmptyDescription>
+    </EmptyHeader>
+    <EmptyContent><Button onClick={onCreate}>{emptyCta}</Button></EmptyContent>
+  </Empty>
+) : (
+  <ItemGroup>{items.map(...)}</ItemGroup>
+)}
+```
+
+### Button with loading state
+```tsx
+<Button disabled={isPending} onClick={submit}>
+  {isPending ? <Spinner className="size-4" /> : null}
+  {isPending ? "Saving…" : "Save"}
+</Button>
+```
+
+### Form field with validation
+```tsx
+<Field data-invalid={!!error}>
+  <FieldLabel htmlFor={id}>{label}</FieldLabel>
+  <Input id={id} aria-invalid={!!error} aria-describedby={`${id}-help`} />
+  {error ? (
+    <FieldError id={`${id}-help`}>{error}</FieldError>
+  ) : (
+    <FieldDescription id={`${id}-help`}>{helpText}</FieldDescription>
+  )}
+</Field>
+```
+
+### Optimistic delete with undo
+```tsx
+function handleDelete(id) {
+  const item = items.find(i => i.id === id)
+  optimisticRemove(id)
+  toast.success(`Deleted "${item.name}"`, {
+    action: { label: "Undo", onClick: () => optimisticRestore(item) },
+    duration: 6000,
+  })
+}
+```
+
+## The state audit (run before shipping)
+
+For every interactive surface on your view, walk through this list:
+
+- [ ] What does it look like when there's no data?
+- [ ] What does it look like while it's loading?
+- [ ] What does it look like if loading fails?
+- [ ] What does each interactive element look like on hover? on focus? when active? when disabled?
+- [ ] What happens if the user submits/clicks while a previous action is still pending?
+- [ ] What happens with very long content (long name, long description, 100 items)?
+- [ ] What happens with very short content (1 character, 1 item)?
+- [ ] Is success communicated? Is it transient (toast) or persistent (UI change)?
+- [ ] Can the user undo destructive actions?
+- [ ] Is there a focus indicator on every interactive element?
+
+If any answer is "I haven't designed for that," the view isn't done.

package/docs/nqui-skills/THEMING.md

@@ -0,0 +1,203 @@
+---
+name: nqui-theming
+description: How to customize nqui's brand color, density, radius, and dark/light tokens without breaking the design rules. Use when a consumer asks "how do I make nqui match my brand?" or when adding a custom theme.
+---
+
+# nqui Theming — Brand Customization Without Breaking the Rules
+
+nqui's defaults are opinionated. They are NOT the limit of what the kit can look like. This file is how you customize the kit while keeping the design rules (elevation, motion, hierarchy) intact.
+
+## What you can change (safely)
+
+| Token group | Where | Safe to override |
+|-------------|-------|------------------|
+| **Brand color** | `--primary-*` scale + `--primary` mapping | ✅ Full hue/chroma shift |
+| **Radius scale** | `--radius` (base) | ✅ Affects all radius tokens |
+| **Density** (control sizes) | `nqui-design-system/SKILL.md` size scale | ✅ via prop, NOT by changing token sizes |
+| **Dark/light surface lightness** | `--background`, `--muted`, `--popover` | ✅ Within the 2+1 rule constraints |
+| **Foreground softness** | `--foreground` (dark mode soft 0.92) | ✅ Per brand preference |
+| **Sidebar direction** | `--sidebar` | ⚠️ Pick one direction for both modes |
+| **Border weight** | `--border` lightness | ✅ Subtle adjustments |
+| **Chart palette** | `--chart-1` through `--chart-5` | ✅ Categorical or sequential — your call |
+
+## What you CANNOT change without breaking the philosophy
+
+| Token | Why locked |
+|-------|------------|
+| **Surface count** (2+1 inline + 1 elevated) | Adding a `--surface-c` defeats `ELEVATION.md`'s entire premise |
+| **Z-index scale** (`--z-*`) | Stacking conflicts cascade. Keep the semantic scale. |
+| **Motion principle** (default: no motion, restrained when present) | Adding default transitions to everything = busy UI |
+| **Shadow philosophy** (only on elevated surfaces) | Inline shadows turn flat surfaces into decorative noise |
+| **The decision rules** (ToggleGroup vs RadioGroup, Dialog vs AlertDialog) | These are semantic, not aesthetic. Locked. |
+
+If your brand "needs" a third surface or default shadows on cards, the brand expression should happen via **color + typography + radius**, not by relaxing the rules.
+
+---
+
+## How to override safely
+
+### Brand color (the most common ask)
+
+Override the primary scale in your app's CSS, after nqui's import:
+
+```css
+@import "@nqlib/nqui/index.css";
+
+:root {
+  /* Replace nqui's blue (hue 240) with your brand hue */
+  --primary-100: oklch(0.655 0.11 30);   /* your hue */
+  --primary-200: oklch(0.655 0.135 30);
+  --primary-300: oklch(0.655 0.155 30);
+  --primary-400: oklch(0.655 0.172 30);
+  --primary-500: oklch(0.605 0.215 30);
+  --primary-600: oklch(0.575 0.238 30);
+  --ring: var(--primary-500);
+}
+
+.dark {
+  --primary-100: oklch(0.30 0.14 30);
+  --primary-200: oklch(0.34 0.165 30);
+  --primary-300: oklch(0.385 0.185 30);
+  --primary-400: oklch(0.435 0.198 30);
+  --primary-500: oklch(0.515 0.168 30);
+  --primary-600: oklch(0.565 0.185 30);
+}
+```
+
+**Rules for picking your brand hue:**
+- One hue. Don't override into two hues alternating — that breaks the focus + selection consistency.
+- Match the L (lightness) values of nqui's defaults to keep contrast guarantees.
+- OKLCH only — don't mix HSL/RGB here.
+
+### Radius (rounder or sharper)
+
+Change the single base — the scale derives from it:
+
+```css
+:root {
+  --radius: 0.25rem;   /* sharper — closer to Stripe/GitHub */
+  /* OR */
+  --radius: 0.75rem;   /* rounder — closer to Vercel/Linear */
+}
+```
+
+`--radius-sm/md/lg/xl/2xl` automatically follow.
+
+### Density (compact vs comfortable)
+
+**Don't change the token sizes** (h-6/h-7/h-8 are the design system contract). Instead, **default to a different size globally** via your component wrappers OR pass `size="sm"` as the project convention.
+
+For an ultra-compact app: build a tiny `<UiProvider>` that defaults all interactive components to `size="sm"`. For a comfortable app, use defaults.
+
+### Surface palette (warm paper vs cool gray vs pure)
+
+```css
+:root {
+  /* Cool gray (instead of warm paper) */
+  --background: oklch(0.985 0.002 250);   /* hue 250 = cool, instead of 95 warm */
+  --muted: oklch(0.92 0.003 250);
+  --border: oklch(0.89 0.004 250);
+}
+```
+
+When you change the bg hue, **shift the semantic colors with it**:
+- success hue 135 → maybe 130 (closer to cool palette)
+- warning hue 80 → keep
+- destructive hue 25 → maybe 20
+- info hue 200 → keep or cut
+
+See `colors.css` for the full set.
+
+### Chart palette
+
+Default is **categorical** (5 distinct hues). If your product visualizes ordinal data instead (severity, intensity), override with shades of primary:
+
+```css
+:root {
+  /* Sequential (intensity gradient) — use for ordinal data */
+  --chart-1: oklch(0.85 0.10 240);   /* lightest blue */
+  --chart-2: oklch(0.75 0.14 240);
+  --chart-3: oklch(0.65 0.18 240);
+  --chart-4: oklch(0.55 0.22 240);
+  --chart-5: oklch(0.45 0.25 240);   /* deepest blue */
+}
+```
+
+Document which type your project uses so consumers don't mix them.
+
+---
+
+## Theme audit before shipping
+
+Before publishing a custom-themed nqui app:
+
+- [ ] Contrast check: `--foreground` on `--background` ≥ 4.5:1 (AA), `--muted-foreground` on `--muted` ≥ 4.5:1
+- [ ] Hover state visible: `--accent` clearly distinct from `--muted` AND `--border`
+- [ ] Focus ring visible: `--ring` clearly visible on `--background` and `--muted`
+- [ ] Primary button readable: `--primary-foreground` on `--primary` ≥ 4.5:1
+- [ ] Destructive button readable: `--destructive-foreground` on `--destructive` ≥ 4.5:1
+- [ ] Dark mode flipped: every check above passes in `.dark` too
+- [ ] Sidebar direction consistent: same relative-to-page direction in both modes
+- [ ] Chart palette appropriate: categorical for categories, sequential for intensity — not mixed
+
+Run `/audit` (or whatever your eval is) after the theme is in place.
+
+---
+
+## Common branding requests + the nqui-friendly answer
+
+| Request | Nqui-friendly answer |
+|---------|----------------------|
+| "Make it more colorful" | Use brand color in MORE places (active states, badges, accents) — don't add MORE colors |
+| "Make cards stand out more" | More space + uppercase labels. Not shadow + border + hue shift. |
+| "Make it feel premium" | Larger spacing scale, smaller font sizes, single restrained accent. NOT more flair. |
+| "Make it more playful" | Rounder radius (`--radius: 0.75rem`), warmer hue, slightly more saturated accent. NOT bouncy motion. |
+| "Make it feel like Linear / Notion / Stripe" | Pick ONE; study their actual choices (hue, density, surface use). Don't try to be all three. |
+| "Add brand gradient backgrounds" | No. nqui doesn't do decorative gradients. If you need brand expression on a marketing page, do it there, not in product UI. |
+
+---
+
+## What NOT to do when theming
+
+- ❌ Override component CSS directly (`button.nqui-button { background: red; }`). Use tokens.
+- ❌ Add new surface tokens beyond the 3 (`--surface-d` etc.)
+- ❌ Add default shadows to Card / Input / Button
+- ❌ Replace `var(--radius-*)` with hardcoded `border-radius: 12px` in component overrides
+- ❌ Add motion (transitions, animations) that wasn't there by default
+- ❌ Override the focus ring to be invisible "for design" — accessibility violation
+- ❌ Use `!important` to fight component styles — there's a better way (tokens or composition)
+
+If you're tempted to do any of the above, the kit isn't right for your use case. That's fine — fork or use a different kit. Don't bend nqui out of shape.
+
+---
+
+## Building a theme variant pack
+
+If you want a true alternative theme (e.g., "Brand A theme" / "Brand B theme"), structure as:
+
+```
+your-app/themes/
+├── brand-a.css       /* :root + .dark overrides */
+├── brand-b.css
+└── default.css       /* explicit default */
+```
+
+Load one at a time via `<link>` swap or `@import` based on environment. Don't try to ship all themes in one CSS file — token cascades get unpredictable.
+
+---
+
+## Tracking customizations
+
+Document every token your team overrides in a `THEME_OVERRIDES.md` in your project. Future engineers (and AI agents) need to know WHY a token is overridden, not just WHAT.
+
+Example:
+```md
+## THEME_OVERRIDES
+
+- `--primary-*`: hue 30 (orange) — match brand identity
+- `--radius`: 0.25rem — sharper, more "fintech" feel
+- `--background`: cool gray hue 250 — better contrast with brand orange
+- `--info`: removed (we don't use info semantically)
+```
+
+This is what makes a customized nqui maintainable.

package/docs/nqui-skills/WRITING.md

@@ -0,0 +1,205 @@
+---
+name: nqui-writing
+description: UX copywriting rules — buttons, labels, error messages, empty states, microcopy. The single largest differentiator between AI-built and human-built UI. Read when writing ANY user-facing text in a component.
+---
+
+# nqui Writing — Voice, Copy, Microcopy
+
+UX writing is design. "Project deleted" and "Got it — project deleted, undo in 6 seconds" use the same components but feel like different products. This file is the rule set. Read before writing any user-facing string.
+
+## Voice principles
+
+These are not stylistic suggestions — they're the rule set applied to every label, button, message, and toast.
+
+1. **Specific over generic.** Bad: "An error occurred." Good: "Couldn't reach the server." Bad: "Are you sure?" Good: "Delete 412 issues and 1.2 GB of attachments?"
+2. **Present tense, active voice.** Bad: "Your changes have been saved." Good: "Changes saved." Bad: "An email will be sent to you." Good: "We'll email you when it's done."
+3. **Calm, never alarmist.** Bad: "ERROR! Failed to save!" Good: "Couldn't save — check your connection." Errors are user moments — don't make them feel punished.
+4. **Address the user as "you," refer to system as "we" sparingly.** "You haven't created any issues yet." "We'll notify you when…" — but most copy needs no pronoun at all.
+5. **No exclamation marks.** Almost never. They read as either alarmist or AI-cheery. The rare exception: legitimate celebration ("Welcome back!" after a long absence — and even then, optional).
+6. **No emoji in UI chrome.** They become noise. Reserve for actual user content (chat, notes). Status icons are not emoji — they're SVGs from the icon set.
+7. **Title case for buttons and titles. Sentence case for everything else.** Buttons: "Save Changes" or "Save changes"? **Sentence case** ("Save changes") is the modern default — Apple, Linear, Stripe all use it. Only use Title Case for proper page titles ("Workspace Settings" → "Workspace settings").
+
+## Button labels
+
+**Pattern: verb + object.** Always.
+
+| ❌ Bad | ✅ Good | Why |
+|--------|---------|-----|
+| "OK" | "Got it" / "Save" / "Done" | "OK" is ambiguous about consequence |
+| "Submit" | "Send invite" / "Create issue" / "Pay $42" | "Submit" never tells you what happens |
+| "Yes" / "No" | "Delete project" / "Keep project" | Yes/No requires re-reading the question |
+| "Confirm" | "Confirm deletion" / "Confirm purchase" | Confirm what? |
+| "Continue" | "Continue to payment" / "Save and continue" | Continue to where? |
+| "Cancel" (in destructive dialog) | "Cancel" is fine here — the action is clear | Cancel of the destructive action |
+
+**Verb tense:** present imperative ("Save", "Delete", "Send"). Not past ("Saved"), not future ("Will save"), not gerund ("Saving" — that's a loading state, not a label).
+
+**Length:** 1–3 words is the target. 4 only if the verb genuinely needs an object phrase ("Move to archive").
+
+**Primary vs secondary verb pairs:**
+- "Save" / "Cancel" — not "Save" / "Discard" (discard sounds more destructive than it is)
+- "Delete" / "Keep" — destructive contrast, neutral keep
+- "Send invite" / "Cancel" — verb+object on primary, single-word on escape
+- "Publish" / "Save as draft" — both have meaning, no "Cancel" needed
+
+## Error messages
+
+**Pattern: what happened + why (if useful) + what to do.**
+
+| ❌ Bad | ✅ Good |
+|--------|---------|
+| "Error." | "Couldn't save changes." |
+| "Invalid input." | "Use a valid email address (e.g., name@company.com)." |
+| "Network error." | "Couldn't reach the server — check your connection and try again." |
+| "Permission denied." | "You don't have permission to edit this project. Ask the workspace admin to give you the editor role." |
+| "500 Internal Server Error" | "Something went wrong on our end. We're looking into it — try again in a minute." |
+
+**Rules:**
+- Never use error codes in user-facing text (log them, don't show them — unless it's a developer tool)
+- Don't blame the user even when it's their input ("Invalid email" → "Use a valid email like name@company.com")
+- Don't apologize excessively. One "Sorry" max, usually none. Solve the problem instead.
+- If the user can fix it, tell them how. If they can't, tell them what we're doing about it.
+
+## Empty states
+
+**Pattern: title (what's empty) + description (why this is normal and what to do) + CTA (the one action that fills it).**
+
+```
+❌ Bad:                    ✅ Good:
+No items.                   No issues yet
+                            Create your first issue to start tracking work.
+                            [+ New issue]
+```
+
+**Rules:**
+- Never just say "Empty" or "No data" alone — that's a state, not a message.
+- The CTA in the empty state should be the SAME action as the primary CTA above the list. Don't introduce new actions just for empty.
+- For a filtered empty state ("no issues match your search"), give an escape route — "Clear filter" — not just an apology.
+- Onboarding empty states (user's first time) can be longer and educational. Returning-user empty states (user deleted all their items) should be brief.
+
+**Filtered vs onboarding empty states:**
+```tsx
+// Onboarding empty (no items ever)
+<EmptyTitle>No issues yet</EmptyTitle>
+<EmptyDescription>Create an issue to track bugs, features, or anything else you're working on.</EmptyDescription>
+<Button>+ New issue</Button>
+
+// Filter empty (items exist, just none match)
+<EmptyTitle>No issues match "{searchTerm}"</EmptyTitle>
+<EmptyDescription>Try a different search or clear the filter.</EmptyDescription>
+<Button variant="outline" onClick={clearFilter}>Clear filter</Button>
+```
+
+## Confirmation copy (destructive actions)
+
+**Pattern: state the specific consequence, name the action button after the verb.**
+
+```
+❌ Bad:                          ✅ Good:
+Title: "Are you sure?"           Title: "Delete this project?"
+Body: "This action cannot        Body: "All 412 issues and 1.2 GB of
+       be undone."                      attachments will be removed.
+                                        This cannot be undone."
+[Cancel] [OK]                    [Cancel] [Delete]
+```
+
+**Rules:**
+- Title is a question ending in "?". Body is a statement.
+- Body must state the SPECIFIC stakes — count of items, name of thing being affected, time period. Generic "this cannot be undone" without specifics is noise.
+- Primary button repeats the verb from the title ("Delete this project?" → "Delete")
+- Escape button is always "Cancel", not "Keep" or "No"
+
+## Toasts and transient messages
+
+**Success toasts: state the result. Past tense, no exclamation.**
+
+```
+"Project archived"  ← good
+"✓ Successfully archived your project!" ← bad (icon redundant, redundant verb, exclamation)
+```
+
+**Toast with undo:**
+```
+"Issue deleted" [Undo]
+"Moved to archive" [Undo]
+"3 items archived" [Undo]
+```
+
+**Toast for async confirmation (started, not finished):**
+```
+"Generating report — we'll email you when it's ready"
+"Invitation sent to alex@company.com"
+```
+
+**Duration:**
+- Success without action: 3 seconds
+- Success with undo: 6 seconds (Gmail standard)
+- Error: until dismissed (don't auto-dismiss errors)
+- Info: 4 seconds
+
+## Labels and microcopy
+
+### Field labels
+- **Sentence case, no colon.** "Email address" not "Email:"
+- **Specific over generic.** "Work email" not "Email" (when you mean specifically work email)
+- **Match the data being collected.** "Phone number" not "Phone" if you need a number
+
+### Field descriptions (helper text)
+- One sentence, no period needed
+- Explain the consequence, not just the format
+  - Bad: "Maximum 50 characters"
+  - Good: "Shown in the sidebar and on invoices"
+
+### Placeholders
+- **Don't replace labels with placeholders.** Both serve different purposes — labels are persistent, placeholders are examples.
+- Use placeholders for format examples: "you@company.com" not "Enter your email"
+- Don't use placeholders for required-field markers — that's what asterisks (or "required") are for
+
+### Time and date formatting
+- **Relative for recent**: "2 minutes ago", "Yesterday", "Last Tuesday"
+- **Absolute for old**: "May 17, 2026" or "May 17"
+- **Show absolute on hover** for relative timestamps (use `Tooltip`)
+- **24-hour for product UIs in international contexts**; 12-hour for US-only consumer
+- Always include timezone for scheduled times: "3:00 PM PT"
+
+### Numbers and units
+- **Abbreviate large numbers**: 1,234 → 1.2k, 1,234,567 → 1.2M (in dense UIs)
+- **Use thin spaces or commas for thousands**, never bare digits: `1,234` not `1234`
+- **Always show units inline**: "12 MB", "42 issues", "3 days"
+- **Round in summary, exact in detail**: "About 1.2k issues" in a header, "1,247 issues" in a stats panel
+- **Use `tabular-nums` font feature** so numeric columns align
+
+## Anti-patterns (the AI-flavored ones)
+
+These are the copy patterns that immediately signal "AI wrote this":
+
+| ❌ Anti-pattern | ✅ Use instead |
+|----------------|---------------|
+| "Welcome to your dashboard!" | "Dashboard" (let the page name itself) |
+| "Let's get started!" | "Create a project to begin" |
+| "Awesome!" / "Great job!" | (nothing — completion is its own reward) |
+| "Effortlessly manage your..." | (cut the entire sentence) |
+| "Powered by AI" / "Smart suggestions" | (let the feature speak for itself) |
+| "Click here to..." | "Open settings" / button with verb |
+| "Please" before every instruction | (cut "please" — direct is respectful in UI) |
+| "Don't worry, your data is safe" | (don't introduce worry just to dismiss it) |
+| Emoji in every label (📊 Analytics, 🎯 Goals) | (icon SVG, no emoji) |
+| "Whoops!" / "Oops!" / "Yikes!" | "Couldn't [verb]" (neutral, specific) |
+| "Loading..." / "Please wait..." | (use Skeleton matching the shape, no text) |
+| "You have no items yet" | "No issues yet" (omit "you have") |
+| Sentences ending in "..." | (use only for in-progress states like "Saving…") |
+
+## The microcopy audit
+
+Before shipping a view, read every string aloud:
+
+- [ ] Does each button tell the user what will happen when clicked?
+- [ ] Does each error message tell the user how to fix it?
+- [ ] Does the empty state teach the interface or just apologize?
+- [ ] Is there any "Please" or "Sorry" that could be cut?
+- [ ] Is every "this/that/it" specific (named, not pronoun)?
+- [ ] Any exclamation marks? Cut them unless legitimately celebratory.
+- [ ] Any em-dashes in places where a colon or period would work? (Em-dashes are an AI signature — use them deliberately, not reflexively.)
+- [ ] Does the copy read like a tired colleague wrote it, or like a marketing person wrote it? Tired colleague is right.
+
+If anything reads as "trying too hard," cut it.