qualia-framework 4.4.0 → 4.5.0

package/bin/state.js

@@ -1267,6 +1267,186 @@ function cmdBackfillLifetime(opts) {
   });
 }
 
+// ─── Backfill Milestones from JOURNEY.md ─────────────────
+// Reconstructs the milestones[] array + lifetime counters from the
+// "Milestone arc" table in .planning/JOURNEY.md. Required when a project
+// pre-dates v4 milestone bookkeeping (or had its tracking.json reset)
+// but JOURNEY.md captures the historical arc. Idempotent — only adds
+// missing milestones or overwrites entries flagged backfilled:true.
+//
+// JOURNEY.md table format expected:
+//   | # | Milestone | Status | Phases | Closed |
+//   | 1 | Name      | CLOSED | 1–13   | YYYY-MM-DD |
+//   | 5 | Name      | OPEN   | rolling| —      |
+//
+// Phase counting handles ranges (`1–13` → 13), comma lists (`14, 15, 16.1–16.6` → 8),
+// and "rolling" / "—" / "-" → 0.
+function cmdBackfillMilestones(opts) {
+  const t = readTracking();
+  if (!t) return output(fail("NO_PROJECT", "No .planning/ found."));
+  ensureLifetime(t);
+
+  const journeyPath = path.join(PLANNING, "JOURNEY.md");
+  if (!fs.existsSync(journeyPath)) {
+    return output(fail("NO_JOURNEY", "JOURNEY.md not found. Cannot backfill without milestone history source."));
+  }
+
+  const content = fs.readFileSync(journeyPath, "utf8");
+
+  // Parse the milestone arc table. Each row must have 5 columns:
+  // num | name | status | phases | closed
+  const rows = [];
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    const m = line.match(
+      /^\|\s*(\d+)\s*\|\s*([^|]+?)\s*\|\s*(CLOSED|OPEN|CURRENT)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|/i
+    );
+    if (m) {
+      rows.push({
+        num: parseInt(m[1], 10),
+        name: m[2].trim(),
+        status: m[3].trim().toUpperCase(),
+        phasesStr: m[4].trim(),
+        closedStr: m[5].trim(),
+      });
+    }
+  }
+
+  if (rows.length === 0) {
+    return output(
+      fail(
+        "NO_MILESTONE_TABLE",
+        "No milestone arc table found in JOURNEY.md. Expected `| # | Milestone | Status | Phases | Closed |` header followed by rows."
+      )
+    );
+  }
+
+  // Count phases from a phasesStr.
+  // "1–13" → 13. "14, 15, 16.1–16.6" → 8. "19–25" → 7. "rolling" / "—" / "-" → 0.
+  const countPhases = (s) => {
+    if (!s) return 0;
+    const lower = s.toLowerCase();
+    if (lower === "—" || lower === "-" || lower === "rolling" || lower === "n/a") return 0;
+    let count = 0;
+    for (const seg of s.split(",")) {
+      const trimmed = seg.trim();
+      if (!trimmed || trimmed === "—" || trimmed === "-") continue;
+      // Match X–Y or X-Y where X/Y can be "13" or "16.6"
+      const range = trimmed.match(/^(\d+(?:\.\d+)?)\s*[–-]\s*(\d+(?:\.\d+)?)$/);
+      if (range) {
+        const startStr = range[1];
+        const endStr = range[2];
+        // Sub-phase range like "16.1–16.6" → count by sub-index difference + 1
+        if (startStr.includes(".") && endStr.includes(".")) {
+          const startSub = parseInt(startStr.split(".")[1], 10);
+          const endSub = parseInt(endStr.split(".")[1], 10);
+          count += Math.max(0, endSub - startSub + 1);
+        } else {
+          const start = parseInt(startStr, 10);
+          const end = parseInt(endStr, 10);
+          count += Math.max(0, end - start + 1);
+        }
+      } else {
+        // Single phase like "14" or "17.1"
+        count += 1;
+      }
+    }
+    return count;
+  };
+
+  const closed = rows.filter((r) => r.status === "CLOSED").sort((a, b) => a.num - b.num);
+  const openRow = rows.find((r) => r.status === "OPEN" || r.status === "CURRENT");
+
+  t.milestones = Array.isArray(t.milestones) ? t.milestones : [];
+  let added = 0;
+  let updated = 0;
+  let totalClosedPhases = 0;
+  const closedSummaries = [];
+
+  for (const row of closed) {
+    const phaseCount = countPhases(row.phasesStr);
+    totalClosedPhases += phaseCount;
+
+    const dateMatch = row.closedStr.match(/\d{4}-\d{2}-\d{2}/);
+    const closedAt = dateMatch ? `${dateMatch[0]}T00:00:00.000Z` : "";
+
+    const summary = {
+      num: row.num,
+      name: row.name,
+      total_phases: phaseCount,
+      phases_completed: phaseCount,
+      tasks_completed: 0, // unknown for historical backfill
+      shipped_url: "",
+      closed_at: closedAt,
+      backfilled: true,
+    };
+    closedSummaries.push({ num: row.num, name: row.name, phases: phaseCount });
+
+    const existing = t.milestones.findIndex((mm) => mm && mm.num === row.num);
+    if (existing >= 0) {
+      // Don't override entries that came from real /qualia-milestone close
+      // (they have richer data). Only overwrite previously-backfilled entries.
+      if (t.milestones[existing].backfilled) {
+        t.milestones[existing] = summary;
+        updated++;
+      }
+    } else {
+      t.milestones.push(summary);
+      added++;
+    }
+  }
+
+  // Stable order by milestone number.
+  t.milestones.sort((a, b) => (a.num || 0) - (b.num || 0));
+
+  const lastClosed = closed.length > 0 ? closed[closed.length - 1].num : 0;
+
+  // Math.max — never reduce lifetime counters. Preserves real /qualia-milestone
+  // history if a project was partly closed properly and partly backfilled.
+  t.lifetime.milestones_completed = Math.max(
+    t.lifetime.milestones_completed || 0,
+    closed.length
+  );
+  t.lifetime.last_closed_milestone = Math.max(
+    t.lifetime.last_closed_milestone || 0,
+    lastClosed
+  );
+  t.lifetime.total_phases = Math.max(
+    t.lifetime.total_phases || 0,
+    totalClosedPhases
+  );
+
+  // Set current milestone — prefer the OPEN row; otherwise next-after-last-closed.
+  if (openRow) {
+    t.milestone = openRow.num;
+    t.milestone_name = openRow.name;
+  } else if (lastClosed > 0) {
+    t.milestone = lastClosed + 1;
+    t.milestone_name = readNextMilestoneNameFromJourney(t.milestone);
+  }
+
+  t.last_updated = new Date().toISOString();
+  writeTracking(t);
+
+  _trace("backfill-milestones", "allow", {
+    added,
+    updated,
+    closed_count: closed.length,
+    total_phases: totalClosedPhases,
+    lifetime: t.lifetime,
+  });
+
+  output({
+    ok: true,
+    action: "backfill-milestones",
+    added,
+    updated,
+    closed: closedSummaries,
+    open_milestone: openRow ? { num: openRow.num, name: openRow.name } : null,
+    lifetime: t.lifetime,
+  });
+}
+
 // ─── Next Report ID ──────────────────────────────────────
 // Increments report_seq and returns the next QS-REPORT-NN id. Per-project
 // counter (lives in tracking.json). /qualia-report calls this to tag each
@@ -1342,6 +1522,9 @@ try {
     case "backfill-lifetime":
       cmdBackfillLifetime(opts);
       break;
+    case "backfill-milestones":
+      cmdBackfillMilestones(opts);
+      break;
     case "next-report-id":
       cmdNextReportId(opts);
       break;
@@ -1349,7 +1532,7 @@ try {
       output(
         fail(
           "UNKNOWN_COMMAND",
-          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|next-report-id> [--options]`
+          `Usage: state.js <check|transition|init|fix|validate-plan|close-milestone|backfill-lifetime|backfill-milestones|next-report-id> [--options]`
         )
       );
   }

package/docs/erp-contract.md

@@ -200,6 +200,11 @@ Authorization: Bearer <api-key>
   external callers. Internal idempotent UPSERT on `(project_id,
   client_report_id)` retries is the one exception (see "Idempotent UPSERT
   on retry" above).
+- The ERP resolves each report to a canonical internal project when possible.
+  Repository URL is the strongest signal, followed by repo/project slug, then
+  configured aliases, then the human report project name. This keeps legacy
+  repo/report names like `USD-Academy` or `USD-ACVADEMY` correctly linked to
+  ERP project names like `Underdog-Sales-Academy`.
 - **`dry_run` retention (v4.0.4+):** The ERP deletes rows where
   `dry_run = true AND submitted_at < now() - 7 days` via a daily cron at
   03:00 UTC. Production report views (list, project tree, email digests)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "description": "Claude Code workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

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.