qualia-framework 4.3.0 → 4.5.0

package/hooks/pre-compact.js

@@ -37,6 +37,23 @@ function readCompactConfig() {
   }
 }
 
+function git(args, opts = {}) {
+  return spawnSync("git", args, {
+    encoding: "utf8",
+    timeout: 3000,
+    shell: process.platform === "win32",
+    ...opts,
+  });
+}
+
+function stateHasPendingChanges() {
+  const diff = git(["diff", "--name-only", "--", STATE_FILE]);
+  if ((diff.stdout || "").split(/\r?\n/).includes(STATE_FILE)) return true;
+
+  const untracked = git(["ls-files", "--others", "--exclude-standard", "--", STATE_FILE]);
+  return (untracked.stdout || "").split(/\r?\n/).includes(STATE_FILE);
+}
+
 let _commitStatus = null;
 let _commitReason = "no-state-file";
 let _commitFlags = null;
@@ -45,17 +62,9 @@ try {
   if (fs.existsSync(STATE_FILE)) {
     console.log("QUALIA: Saving state before compaction...");
     _commitReason = "state-clean";
-    // Check if STATE.md has uncommitted changes
-    const diff = spawnSync("git", ["diff", "--name-only", STATE_FILE], {
-      encoding: "utf8",
-      timeout: 3000,
-      shell: process.platform === "win32",
-    });
-    if ((diff.stdout || "").includes("STATE.md")) {
-      const addRes = spawnSync("git", ["add", STATE_FILE], {
-        timeout: 3000,
-        shell: process.platform === "win32",
-      });
+    // Check if STATE.md has tracked or untracked changes.
+    if (stateHasPendingChanges()) {
+      const addRes = git(["add", STATE_FILE]);
       const cfg = readCompactConfig();
       const commitArgs = ["commit"];
       if (!cfg.respect_user_hooks) commitArgs.push("--no-verify");
@@ -76,6 +85,8 @@ try {
       _commitReason = addRes.status === 0 && commitRes.status === 0
         ? "committed"
         : "commit-failed";
+    } else {
+      _commitReason = "state-clean";
     }
   }
 } catch {

package/hooks/pre-deploy-gate.js

@@ -31,7 +31,8 @@ function _trace(hookName, result, extra) {
 
 function runGate(label, cmd, args, { required = true } = {}) {
   const r = spawnSync(cmd, args, {
-    stdio: "ignore",
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf8",
     timeout: 180000,
     shell: process.platform === "win32",
   });
@@ -41,7 +42,20 @@ function runGate(label, cmd, args, { required = true } = {}) {
   }
   if (required) {
     console.error(`BLOCKED: ${label} errors. Fix before deploying.`);
-    _trace("pre-deploy-gate", "block", { gate: label });
+    const output = `${r.stdout || ""}${r.stderr || ""}`.trim();
+    if (output) {
+      const lines = output.split(/\r?\n/).filter(Boolean).slice(-20);
+      console.error(`Last ${lines.length} output line${lines.length === 1 ? "" : "s"}:`);
+      for (const line of lines) console.error(`  ${line}`);
+    } else if (r.error) {
+      console.error(`  ${r.error.message}`);
+    }
+    _trace("pre-deploy-gate", "block", {
+      gate: label,
+      status: r.status,
+      signal: r.signal || undefined,
+      error: r.error ? r.error.message : undefined,
+    });
     process.exit(2);
   }
   return false;

package/hooks/pre-push.js

@@ -102,6 +102,15 @@ function commitStamp() {
   return { committed: true, sha: lastCommit, ts: now };
 }
 
+function shouldBlock(result) {
+  const hardSkips = new Set([
+    "tracking-unreadable",
+    "git-add-failed",
+    "git-commit-failed",
+  ]);
+  return result && hardSkips.has(result.skipped);
+}
+
 function _trace(result, extra) {
   try {
     const traceDir = path.join(HOME, ".claude", ".qualia-traces");
@@ -120,10 +129,21 @@ function _trace(result, extra) {
 
 try {
   const result = commitStamp();
+  if (shouldBlock(result)) {
+    const detail = result.error ? ` ${String(result.error).slice(0, 500)}` : "";
+    const msg = `BLOCKED: tracking.json sync failed (${result.skipped}). Fix before pushing.${detail}`;
+    console.error(msg);
+    console.log(msg);
+    _trace("block", result);
+    process.exit(2);
+  }
   _trace("allow", result);
 } catch (err) {
-  // Never block a push — log and exit clean.
-  _trace("allow", { error: err.message });
+  const msg = `BLOCKED: tracking.json sync failed (${err.message}). Fix before pushing.`;
+  console.error(msg);
+  console.log(msg);
+  _trace("block", { error: err.message });
+  process.exit(2);
 }
 
 process.exit(0);

package/hooks/stop-session-log.js

@@ -103,7 +103,7 @@ try {
   const tracking = readJson(path.join(repoRoot, ".planning", "tracking.json"));
   if (tracking) {
     const p = tracking.phase || 0;
-    const pt = tracking.phase_total || 0;
+    const pt = tracking.total_phases || tracking.phase_total || 0;
     if (pt > 0) phase = `${p}/${pt}`;
     const td = tracking.tasks_done || 0;
     const tt = tracking.tasks_total || 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"
@@ -23,7 +23,13 @@
   },
   "homepage": "https://github.com/Qualiasolutions/qualia-framework#readme",
   "scripts": {
-    "test": "node --test tests/runner.js"
+    "test": "npm run test:shell",
+    "test:state": "bash tests/state.test.sh",
+    "test:hooks": "bash tests/hooks.test.sh",
+    "test:bin": "bash tests/bin.test.sh",
+    "test:lib": "bash tests/lib.test.sh",
+    "test:statusline": "bash tests/statusline.test.sh",
+    "test:shell": "bash tests/statusline.test.sh && bash tests/state.test.sh && bash tests/hooks.test.sh && bash tests/bin.test.sh && bash tests/lib.test.sh"
   },
   "files": [
     "bin/",

package/rules/design-brand.md

@@ -0,0 +1,110 @@
+# Design — Brand register
+
+**When this register applies:** marketing pages, landing pages, campaign sites, portfolios, brand microsites, anything where the design IS the product.
+
+**The bar:** distinctiveness. Memorable beats safe. If a visitor can't remember what your site looked like an hour later, you failed.
+
+This register inherits all of `design-laws.md`. The rules below add what changes when distinctiveness, not familiarity, is the goal.
+
+## The brand brief (what the agent commits to first)
+
+Before any code, the agent writes a 4-line brief and waits for user confirmation:
+
+```
+Aesthetic direction:  [editorial · brutalist · luxury · maximalist · retro-futuristic · organic · terminal-native · sci-fi · pastoral · industrial · ...]
+Color strategy:       [Restrained · Committed · Full palette · Drenched]
+Scene sentence:       [single concrete sentence — who, where, ambient light, mood]
+Differentiation:      [what someone will remember 24 hours later]
+```
+
+This is mandatory. Skipping it produces generic output that ignores the brand.
+
+## Reflex-reject aesthetic lanes
+
+The currently-saturated AI-design families. Reject by default unless the user explicitly asks for one and you confirmed they understand it's a saturated lane.
+
+| Lane | Tells | Reject because |
+|---|---|---|
+| **Generic SaaS-cream** | Off-white bg, soft shadows, rounded cards, slate text, one-color accent | Notion clone aesthetic. Every AI tool builds this first |
+| **Vercel-terminal-native** | Dark + monospace + green/blue accents + grain | The 2024-2025 v0 aesthetic. Saturated |
+| **Crypto-neon** | Pure black + electric accent + glow + grid | Web3 cliché |
+| **Healthcare-clinical** | White + teal + rounded sans + soft icons | Every health app |
+| **Fintech-navy-gold** | Navy + gold accent + serif headings | Every bank, every wealth tool |
+| **Sleek-corporate** | Inter + blue + gradient mesh + isometric illustrations | Every B2B SaaS landing 2020-2024 |
+
+If the project lands in one of these by default, the slop test failed at second-order. Rework.
+
+## Brand register — additional laws
+
+### Typography
+
+- Pick a **distinctive display face**. Editorial serifs (Fraunces, Reckless, Ogg, Editorial New, Mazius). Geometric grotesques (Migra, Söhne, Gambarino). Variable display fonts (Authentic Sans, Departure Mono).
+- Pair the display with a **refined body**. JetBrains Mono, Geist, Inter Display (NOT Inter), Söhne, Untitled Sans, Mona Sans, Switzer.
+- **Banned display fonts:** Inter, Roboto, Arial, system-ui, Space Grotesk, Montserrat, Poppins, Lato, Open Sans. These are the AI defaults — and the worst signal of "designer didn't choose this."
+- **Variable fonts encouraged.** A single variable font with axis-driven weight/optical-size is more interesting than three static cuts.
+
+### Color
+
+- Brand register defaults to **Committed** color strategy. One saturated color carries identity.
+- **Drenched** is a strong choice for hero sections. Don't be afraid.
+- Accent should be **sharp** — not a desaturated pastel-of-the-brand. The accent is the loudest element on the page.
+
+### Layout
+
+- **Asymmetry > symmetry.** Real design has tension. Centered-everything is the AI default.
+- **Diagonal flow, overlap, grid-breaking elements** when they serve the design.
+- **Scale contrast.** Hero text at clamp(4rem, 9vw, 8rem) next to body at 1rem creates drama. Hero at 2.5rem next to body at 1rem is timid.
+- **Negative space is content.** Generous whitespace > dense layouts for marketing.
+
+### Motion
+
+- One **signature motion** that gives the site personality:
+  - Parallax scroll-triggered reveal
+  - Magnetic buttons
+  - Cursor-following element
+  - Letter-by-letter text reveal on hero
+  - Scroll-driven scrubbed scene
+  - Morphing shapes between sections
+- Subtle elsewhere. Restraint everywhere except the signature.
+- Use the Web Animations API or Framer Motion for orchestrated sequences. CSS keyframes for one-offs.
+
+### Backgrounds and visual details
+
+This is where Brand earns its register. Allowed and encouraged:
+
+- Gradient meshes (CSS or SVG)
+- Noise textures (subtle, 2-5% opacity)
+- Geometric patterns (SVG, not images)
+- Layered transparencies
+- Dramatic shadows (with brand-tinted color, not gray)
+- Decorative borders (sparingly)
+- Custom cursors (page-specific, not site-wide)
+- Grain overlays on images
+- Scroll-progress indicators (interesting ones, not generic top bars)
+
+Don't use all of these on one page. Pick 1-2 that serve the brief.
+
+## Brand-specific anti-patterns
+
+In addition to `design-laws.md` absolute bans:
+
+- **Hero pattern: text-center + gradient bg + 2 CTAs + screenshot below.** The single most overused brand pattern of 2020-2025.
+- **Three-column feature grid in section 2.** The default AI brand layout.
+- **"Trusted by" logo strip in faded gray.** Lazy social proof. If the logos matter, design with them. If they don't, omit.
+- **Parallax scroll on every section.** Heavy-handed. Use it for the signature, nowhere else.
+- **Animated dots / pulsing orbs / blinking status indicators.** Decorative noise.
+- **Generic "Get Started" / "Learn More" CTA pair.** Always specify the action.
+- **Stock photography of diverse smiling people in offices.** Use illustration, abstract imagery, product screenshots, or no imagery at all.
+
+## Brand register success criteria
+
+If you can answer YES to all of these, the brand register passed:
+
+- [ ] A designer would call this **distinctive** — not "polished" but **specific**
+- [ ] The aesthetic direction is identifiable in 3 seconds
+- [ ] The color strategy is one of the four (and reads that way)
+- [ ] The scene sentence and the page agree
+- [ ] One signature motion, executed well
+- [ ] No reflex-reject lane (first or second order)
+- [ ] All anti-references avoided
+- [ ] Implementation matches vision (effort proportional to ambition)

package/rules/design-laws.md

@@ -0,0 +1,144 @@
+# Design Laws
+
+The non-negotiable rules every Qualia frontend honors. Both registers (Brand and Product) inherit from this file. Skip nothing.
+
+These laws exist because AI-generated UI has identifiable defaults — Inter font, purple gradients, identical card grids, gray-on-gray, modal-as-first-thought — and shipping the defaults is shipping AI slop. Each rule below has a specific failure mode it prevents.
+
+## 1. Color: OKLCH only
+
+Use the OKLCH color space for every color in the codebase. RGB / hex / HSL are translated values, not source values.
+
+```css
+/* yes */
+--bg:     oklch(0.16 0.012 220);
+--accent: oklch(0.78 0.14 196);
+
+/* no */
+--bg:     #1a1d22;
+--accent: #00ced1;
+```
+
+**Why:** OKLCH is perceptually uniform. Equal lightness numbers look equally light to the eye, regardless of hue. Hex doesn't give you that — `#777777` and `#7777ff` are nominally equal lightness but the blue reads darker.
+
+**Reduce chroma at the extremes.** As lightness approaches 0 or 100, high chroma reads garish. Cap chroma at 0.04 below L=0.20 and above L=0.92.
+
+**Never use `#000` or `#fff`.** Tint every neutral toward the brand hue with chroma 0.005–0.01. Pure black/white reads as untuned and generic — the dead giveaway of "designer didn't pick this color, the framework did."
+
+```css
+/* tinted neutrals */
+--text:  oklch(0.94 0.006 220);   /* 220 is the brand hue */
+--bg:    oklch(0.16 0.012 220);
+--muted: oklch(0.62 0.010 220);
+```
+
+## 2. Color strategy: pick one, commit to it
+
+Before picking colors, pick a strategy. Four steps on a commitment axis:
+
+| Strategy | Rule | When |
+|---|---|---|
+| **Restrained** | Tinted neutrals + one accent at ≤10% surface coverage | Product default; brand minimalism |
+| **Committed** | One saturated color carries 30–60% of the surface | Brand default for identity-driven pages |
+| **Full palette** | 3–4 named roles, each used deliberately | Brand campaigns; product data viz |
+| **Drenched** | The surface IS the color | Brand heroes; campaign pages |
+
+The "≤10% accent" rule is **Restrained only**. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
+
+## 3. Theme: write a scene sentence
+
+Dark vs light is never a default. Not dark "because tools look cool dark." Not light "to be safe." Before choosing, write **one sentence of physical scene**: who uses this, where, under what ambient light, in what mood.
+
+| Vague (no answer) | Concrete (forces an answer) |
+|---|---|
+| "Observability dashboard" | "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" |
+| "Customer support tool" | "Agent at a coffee-lit desk juggling 4 chats while a coworker asks a question" |
+| "Marketing site" | "Founder showing the page to an investor on an iPad in a sunlit lobby" |
+
+Run the sentence, not the category. If the sentence doesn't force an answer, add detail until it does.
+
+## 4. Typography
+
+- Body line length capped at 65–75ch
+- Hierarchy through scale + weight contrast (≥1.25 ratio between adjacent steps)
+- Avoid flat scales — if h1 is 32px and h2 is 28px, the hierarchy is invisible
+- Letter-spacing as a semantic signal:
+  - Display headlines: tight (-0.02em to -0.04em)
+  - Body: neutral (0)
+  - Labels and badges: open (+0.04em to +0.08em)
+  - Category tags: wide (+0.08em to +0.14em)
+
+## 5. Layout
+
+- **Vary spacing for rhythm.** Same padding everywhere is monotony. Tight within groups, generous between sections.
+- **Cards are the lazy answer.** Use them only when they're truly the best affordance. Nested cards are always wrong.
+- **Container depth max 2.** Card → content. Not card → panel → pill → content.
+- **Don't wrap everything in a container.** Most things don't need one.
+- **Full-width with fluid padding.** No hardcoded `max-width: 1200px` or `max-w-7xl`. Use `clamp(1rem, 5vw, 4rem)` for horizontal padding.
+
+## 6. Motion
+
+- Don't animate CSS layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`). Animate `transform` and `opacity`.
+- Ease out with exponential curves: `cubic-bezier(0.22, 1, 0.36, 1)` (out-quart) or `cubic-bezier(0.16, 1, 0.3, 1)` (out-expo). No bounce. No elastic.
+- One signature motion per page > scattered micro-interactions
+- Always respect `prefers-reduced-motion: reduce`
+
+## 7. Copy
+
+- Every word earns its place
+- No restated headings
+- No intros that repeat the title
+- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
+- CTAs name the action. "Download invoice" not "Get Started". "Continue setup" not "Learn More".
+
+## 8. Absolute bans (match-and-refuse)
+
+If you're about to write any of these, rewrite the element with different structure. No exceptions.
+
+| Banned pattern | Why | Rewrite with |
+|---|---|---|
+| **Side-stripe borders** — `border-left: 4px` colored as accent on cards / list items / callouts | Decorative noise, never semantic | Full borders, background tints, leading numbers/icons, or nothing |
+| **Gradient text** — `background-clip: text` with a gradient | Decorative, never meaningful | Single solid color. Emphasis via weight or size |
+| **Glassmorphism by default** — blur + glass cards used everywhere | Trendy slop from 2023-2024 | Rare and purposeful, or nothing |
+| **Hero-metric template** — big number, small label, three supporting stats, gradient accent | SaaS cliché | Vary layout per metric. Don't grid them |
+| **Identical card grids** — same-sized cards with icon + heading + text repeated 3+ times | The default AI hero pattern | Vary card sizes, layouts, content shapes |
+| **Modal as first thought** — every action goes through a modal | Lazy interaction design | Inline expansion, progressive disclosure, dedicated route |
+
+## 9. The AI slop test (run at two altitudes)
+
+If someone could look at this interface and say "AI made that" without doubt, it failed.
+
+**First-order check.** If someone could guess the theme + palette from the category alone, the first reflex won:
+- Observability → dark blue
+- Healthcare → white + teal
+- Finance → navy + gold
+- Crypto → neon on black
+
+If yes, rework the scene sentence and color strategy until the answer isn't obvious from the domain.
+
+**Second-order check.** If someone could guess the aesthetic family from category-plus-anti-references, the trap one tier deeper won:
+- AI workflow tool that's not SaaS-cream → editorial-typographic
+- Fintech that's not navy-and-gold → terminal-native dark mode
+- Health app that's not white-and-teal → soft-pastel
+
+The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The Brand register's reflex-reject aesthetic lanes catch the currently-saturated families.
+
+## 10. Single-icon-family rule
+
+Pick one icon family per project and enforce it. Lucide OR Heroicons OR Phosphor OR Radix Icons. Never mixed. Mixing icon families is the visual equivalent of mixing fonts.
+
+## 11. Anti-references are mandatory
+
+Every PRODUCT.md must list 3–5 sites the project should NOT look like. Anti-references are more useful than positive references because they pin down what the design is reacting against.
+
+```
+Anti-references:
+- generic SaaS-cream (Notion clones)
+- terminal-nostalgia (vercel/v0 dark)
+- corporate-navy fintech (most banks)
+```
+
+## 12. The implementation must match the vision
+
+Maximalist designs need elaborate code. Minimalist designs need restraint, precision, and careful attention to spacing and typography. The failure mode is mismatch: elaborate animation on a "clean minimal" claim, or flat execution of an ambitious concept.
+
+If you wrote 200 lines of CSS to render a "minimal" landing page, the page is not minimal. If your "bold and maximalist" page uses 4 colors and `text-center`, it's not bold.

package/rules/design-product.md

@@ -0,0 +1,110 @@
+# Design — Product register
+
+**When this register applies:** app UI, admin consoles, dashboards, internal tools, settings pages, anything where the design SERVES the product.
+
+**The bar:** earned familiarity. Fluent users of Linear, Figma, Notion, Stripe, Raycast should trust the interface on first glance. Distinctiveness is allowed but never at the cost of usability.
+
+This register inherits all of `design-laws.md`. The rules below add what changes when familiarity, not distinctiveness, is the goal.
+
+## The product brief (what the agent commits to first)
+
+Before any code, the agent writes a 4-line brief and waits for user confirmation:
+
+```
+Reference apps:       [Linear · Stripe · Notion · Figma · Raycast · Vercel · Plaid Dashboard · Pylon · ...]
+Color strategy:       [Restrained — almost always]
+Scene sentence:       [physical scene — focus on context of use, not aesthetic mood]
+Density:              [comfortable · standard · compact · ultra-compact]
+```
+
+Reference apps anchor the visual language. Pick 2-3 that share the user mental model and the density.
+
+## Density target
+
+Product UIs have to choose density. State it explicitly.
+
+| Density | Examples | Use when |
+|---|---|---|
+| **Comfortable** | Notion, Linear (default), Mailchimp | Knowledge work, low-frequency |
+| **Standard** | Stripe Dashboard, Vercel | Mainstream SaaS |
+| **Compact** | Linear (compact mode), Figma left rail | Power users, workflow tools |
+| **Ultra-compact** | Bloomberg Terminal, Trader UIs | Information-dense, professional users |
+
+Higher density = smaller font sizes (down to 12px), tighter padding, more rows per viewport. Don't pretend the app is comfortable when it's compact, or vice versa. Match the user's actual workflow.
+
+## Product register — additional laws
+
+### Typography
+
+- **One typeface family is fine** for product. Variable fonts shine here (Inter Display, Geist, Switzer, Mona Sans, Söhne, Untitled Sans).
+- Banned (per laws): Inter (regular cut), Roboto, Arial, system-ui, Space Grotesk
+- Body: 13-15px depending on density (comfortable=15, standard=14, compact=13, ultra-compact=12)
+- Hierarchy through weight (400 body, 500 labels, 600 headings) more than size
+- Tabular numerals for any numeric data: `font-feature-settings: "tnum" 1`
+- Truncate long strings with ellipsis + tooltip — never let layout collapse on a long username
+
+### Color
+
+- **Restrained is the default.** Tinted neutrals + one accent.
+- **Semantic colors required:** success (green) / warning (amber) / error (red) / info (blue). Always paired with non-color signal (icon, label, pattern).
+- Status indicators must work for color-blind users. Run the design through a deuteranopia simulator.
+- Background depth: 3 surface levels max (`bg`, `surface`, `elevated`). Subtle differences (oklch L delta of 0.03-0.05).
+
+### Layout
+
+- **Density first, aesthetics second.** A beautiful UI a user can't navigate quickly is a failed product UI.
+- **Predictable layout.** Sidebar left, main center, optional right rail. Don't reinvent navigation patterns.
+- **Sticky headers** for long-scroll views (tables, lists)
+- **Keyboard-first.** Every action accessible via keyboard. Power users will memorize shortcuts; expose them.
+- **Fitts's Law.** Frequently-used controls go to screen edges. Action buttons in tight clusters.
+
+### Components
+
+| Pattern | Product register rule |
+|---|---|
+| **Buttons** | 3 variants max: primary / secondary / ghost. Destructive variant where needed. No "outline + filled + ghost + soft + subtle" proliferation. |
+| **Inputs** | Always have visible labels (not placeholder-only). Validation inline, on blur. Error messages specific and actionable. |
+| **Tables** | Tabular numerals. Right-align numbers. Sort indicators on hover, persistent on active. Sticky headers. |
+| **Empty states** | Always include: icon, single sentence of context, primary action |
+| **Loading** | Skeleton (not spinner) for known-shape content. Spinner only for unknown duration. |
+| **Empty data** | Never "No results." Always "No invoices yet — try [action]." |
+| **Toasts** | Auto-dismiss at 5s minimum. Always dismissible. Errors don't auto-dismiss. |
+| **Modals** | Last resort (per laws). When unavoidable: trap focus, ESC to close, restore focus on close. |
+
+### Motion
+
+- Restrained. Product UI motion exists to communicate state changes, not to delight.
+- Hover transitions: 100-150ms ease-out
+- Panel slides: 200ms ease-out
+- Page transitions: 0ms (yes, zero) for navigation between similar views. Motion when it would disorient should be skipped.
+- Skeleton shimmer: 1500ms loop, subtle
+- No bounce. No elastic. No overshoot.
+
+### States (every interactive element)
+
+- Default
+- Hover (within 100ms)
+- Focus (visible ring, 2px+ offset, contrasting color)
+- Active/pressed (subtle scale or color shift)
+- Disabled (opacity 0.5, `cursor: not-allowed`, `aria-disabled="true"`)
+- Loading (per-element spinner or skeleton)
+- Error (inline message + `aria-describedby`)
+
+Every state on every interactive element. No exceptions.
+
+## Product register success criteria
+
+If you can answer YES to all of these, the product register passed:
+
+- [ ] A user fluent in the reference apps would feel oriented in 5 seconds
+- [ ] Density is consistent across the app (one chosen value, applied)
+- [ ] Keyboard navigation reaches every action
+- [ ] Empty / loading / error states present on every async surface
+- [ ] Color is never the sole information signal
+- [ ] Tabular numerals on numeric columns
+- [ ] No reinvented navigation pattern
+- [ ] Implementation matches vision (precision and restraint, not flourish)
+
+## When in doubt
+
+Ask: "Would Linear ship this?" If the answer is no, rework. Linear is not the only standard, but it is the highest commonly-cited bar for product design in 2025-2026 — fluency, restraint, density, motion all dialed in. Most product work will land within ±10% of Linear's bar; be honest about which side.