@hegemonart/get-design-done 1.47.0 → 1.49.0

package/hooks/gdd-design-quality-check.js

@@ -0,0 +1,340 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * hooks/gdd-design-quality-check.js — advisory PostToolUse hook for the
+ * default-AI-aesthetic regex floor (Phase 49, Quick Anti-Slop Floor).
+ *
+ * The cheapest possible anti-slop pass: on every front-end file write, scan the
+ * written content for the visual tells that mark a UI as "an AI generated this"
+ * (gradient spam, the purple/violet default palette, glassmorphism stacks, the
+ * Inter default, centered-everything heroes, undraw/isometric clip art, filler
+ * CTA copy, decorative motion with no loading intent). Each match is a non
+ * blocking WARN. The catalog the rules come from lives at
+ * reference/visual-tells.md (8 named categories, 1:1 with the 8 rules here).
+ *
+ * Contract (mirrors hooks/gdd-a11y-gate.js):
+ *   - Read stdin JSON (the PostToolUse payload: {tool_name, tool_input,
+ *     tool_response, cwd, ...}).
+ *   - Only act on Write/Edit/MultiEdit tools targeting a .tsx/.vue/.svelte/.astro
+ *     file. Everything else is a bare {continue:true}.
+ *   - Scan the written content against 8 regex rules; collect matches as warnings.
+ *   - Emit one `design_quality_warn` event through scripts/lib/event-chain.cjs
+ *     (baseDir injected from cwd; the emit is best-effort and never fatal).
+ *   - Print a concise advisory to stdout and ALWAYS write {continue:true}, exit 0.
+ *     This hook is WARN-only. It never blocks a write.
+ *
+ * Dependency-free: core fs/path plus the in-repo event-chain helper. No npm deps.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** Front-end source extensions this hook scans. */
+const FRONTEND_EXT = ['.tsx', '.vue', '.svelte', '.astro'];
+
+/**
+ * The 8 v1 rules. Each `category` matches a heading in reference/visual-tells.md.
+ * `test(content)` returns an array of { line, match } hits (possibly empty).
+ * Regexes are tuned for precision (low false-positive) over recall.
+ */
+
+/** Find the 1-based line number for a character offset in `content`. */
+function lineOf(content, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < content.length; i++) {
+    if (content[i] === '\n') line += 1;
+  }
+  return line;
+}
+
+/** Collect up to `cap` global-regex matches as {line, match}. */
+function collect(content, re, cap = 5) {
+  const hits = [];
+  let m;
+  re.lastIndex = 0;
+  while ((m = re.exec(content)) !== null) {
+    hits.push({ line: lineOf(content, m.index), match: m[0] });
+    if (m.index === re.lastIndex) re.lastIndex += 1; // zero-width guard
+    if (hits.length >= cap) break;
+  }
+  return hits;
+}
+
+/** Count global-regex matches without allocating the match list. */
+function countMatches(content, re) {
+  let n = 0;
+  let m;
+  re.lastIndex = 0;
+  while ((m = re.exec(content)) !== null) {
+    n += 1;
+    if (m.index === re.lastIndex) re.lastIndex += 1;
+  }
+  return n;
+}
+
+const RULES = [
+  {
+    rule: 'gradient-spam',
+    category: 'gradient-spam',
+    // >=3 Tailwind gradient-direction utilities in one file.
+    run(content) {
+      const re = /\bbg-gradient-to-(?:r|br|tr|b|bl|l|tl|t)\b/g;
+      const count = countMatches(content, re);
+      if (count < 3) return [];
+      const hits = collect(content, re, 5);
+      // Tag the first hit with the aggregate count for the advisory.
+      if (hits.length) hits[0].match = `${hits[0].match} (x${count})`;
+      return hits;
+    },
+  },
+  {
+    rule: 'generic-cta',
+    category: 'default-AI-hero',
+    // Filler hero / CTA copy. Word-boundaried, case-insensitive.
+    run(content) {
+      const re = /\b(?:Get Started|Welcome to|Lorem ipsum|Learn More)\b/gi;
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'centered-everything-syndrome',
+    category: 'centered-everything-syndrome',
+    // mx-auto AND text-center co-occurring inside one className string.
+    run(content) {
+      // Match a quoted class string that contains both utilities, in either order.
+      const re =
+        /(["'`])(?=[^"'`]*\bmx-auto\b)(?=[^"'`]*\btext-center\b)[^"'`]*\1/g;
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'inter-everything',
+    category: 'inter-everything',
+    // font-inter utility OR a font-family: Inter declaration, when no other
+    // custom font token (font-<name>, --font-*, or a second font-family) is near.
+    run(content) {
+      const interRe = /\bfont-inter\b|font-family:\s*['"]?Inter\b/gi;
+      const interCount = countMatches(content, interRe);
+      if (interCount === 0) return [];
+      // A sibling custom-font signal suppresses the warning (a deliberate stack).
+      const siblingFont =
+        /\bfont-(?!inter\b|sans\b|serif\b|mono\b|medium\b|semibold\b|bold\b|light\b|normal\b|thin\b|black\b|extrabold\b|extralight\b)[a-z]/i.test(
+          content,
+        ) ||
+        /--font-[a-z]/i.test(content) ||
+        /font-family:\s*['"]?(?!Inter\b)[A-Za-z]/i.test(content);
+      if (siblingFont) return [];
+      return collect(content, interRe, 5);
+    },
+  },
+  {
+    rule: 'purple-violet-default',
+    category: 'purple-violet-default',
+    // The default-AI palette bg-(purple|violet)-(500|600|700) with no theme
+    // token class (bg-primary / bg-brand / bg-accent / a CSS var) nearby.
+    run(content) {
+      const re = /\bbg-(?:purple|violet)-(?:500|600|700)\b/g;
+      if (countMatches(content, re) === 0) return [];
+      const themeToken =
+        /\bbg-(?:primary|brand|accent|surface|foreground|background|muted)\b/i.test(
+          content,
+        ) || /bg-\[(?:var\(--|hsl|oklch|rgb)/i.test(content);
+      if (themeToken) return [];
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'glassmorphism-spam',
+    category: 'glassmorphism-spam',
+    // >=3 of backdrop-blur* / bg-white/(10|20|30) in one file.
+    run(content) {
+      const re = /\bbackdrop-blur(?:-\w+)?\b|\bbg-white\/(?:10|20|30)\b/g;
+      const count = countMatches(content, re);
+      if (count < 3) return [];
+      const hits = collect(content, re, 5);
+      if (hits.length) hits[0].match = `${hits[0].match} (x${count})`;
+      return hits;
+    },
+  },
+  {
+    rule: 'isometric-illustration-fallback',
+    category: 'isometric-illustration-fallback',
+    // undraw / isometric markers in an asset path or src attribute.
+    run(content) {
+      const re = /\b(?:undraw|isometric)[\w./-]*/gi;
+      return collect(content, re, 5);
+    },
+  },
+  {
+    rule: 'decorative-motion-without-intent',
+    category: 'decorative-motion-without-intent',
+    // animate-(pulse|bounce|spin) on a non-loading, non-icon element.
+    // Conservative: only flag a className that has the animate utility but no
+    // loading/skeleton/spinner/icon signal on the same class string.
+    run(content) {
+      const re =
+        /(["'`])(?=[^"'`]*\banimate-(?:pulse|bounce|spin)\b)(?![^"'`]*(?:\b(?:animate-(?:pulse|bounce|spin)\s+)?(?:loading|loader|spinner|skeleton|icon|i-)\b|sr-only))[^"'`]*\1/g;
+      return collect(content, re, 5);
+    },
+  },
+];
+
+/**
+ * Resolve the written content from a PostToolUse payload, tolerating Write
+ * (tool_input.content), Edit (new_string), and MultiEdit (edits[].new_string),
+ * and falling back to a tool_response filePath/content when present.
+ *
+ * Returns { filename, content } or null when there is nothing front-end to scan.
+ */
+function extractWrite(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const tool = payload.tool_name || payload.toolName;
+  if (tool !== 'Write' && tool !== 'Edit' && tool !== 'MultiEdit') return null;
+
+  const input = payload.tool_input || payload.toolInput || {};
+  const filename =
+    input.file_path ||
+    input.filePath ||
+    input.path ||
+    (payload.tool_response &&
+      (payload.tool_response.filePath || payload.tool_response.file_path)) ||
+    '';
+  if (!filename) return null;
+
+  const ext = path.extname(String(filename)).toLowerCase();
+  if (!FRONTEND_EXT.includes(ext)) return null;
+
+  const parts = [];
+  if (typeof input.content === 'string') parts.push(input.content);
+  if (typeof input.new_string === 'string') parts.push(input.new_string);
+  if (Array.isArray(input.edits)) {
+    for (const e of input.edits) {
+      if (e && typeof e.new_string === 'string') parts.push(e.new_string);
+    }
+  }
+  // Fall back to a post-write file content echo if the input carried none.
+  if (parts.length === 0 && payload.tool_response) {
+    const tr = payload.tool_response;
+    if (typeof tr.content === 'string') parts.push(tr.content);
+  }
+
+  const content = parts.join('\n');
+  if (!content) return null;
+  return { filename: String(filename), content };
+}
+
+/**
+ * Pure evaluator: scan `content` (with `filename` for category context) against
+ * the 8 rules. Exported for unit testing without a process.
+ *
+ * @returns {{ warnings: Array<{rule, category, line, match}>, count: number }}
+ */
+function evaluate(content, filename) {
+  const warnings = [];
+  if (typeof content !== 'string' || content.length === 0) {
+    return { warnings, count: 0 };
+  }
+  for (const r of RULES) {
+    let hits = [];
+    try {
+      hits = r.run(content) || [];
+    } catch {
+      hits = []; // a misbehaving rule must never break the advisory
+    }
+    for (const h of hits) {
+      warnings.push({
+        rule: r.rule,
+        category: r.category,
+        line: h.line,
+        match: h.match,
+      });
+    }
+  }
+  return { warnings, count: warnings.length };
+}
+
+/** Best-effort event emit through the in-repo event-chain helper. Never throws. */
+function emitEvent(cwd, filename, result) {
+  try {
+    const { appendChainEvent } = require('../scripts/lib/event-chain.cjs');
+    appendChainEvent({
+      agent: 'gdd-design-quality-check',
+      outcome: 'warn',
+      event: 'design_quality_warn',
+      file: filename,
+      warning_count: result.count,
+      categories: [...new Set(result.warnings.map((w) => w.category))],
+      warnings: result.warnings.slice(0, 20),
+      baseDir: cwd,
+    });
+  } catch {
+    /* observability is best-effort — swallow */
+  }
+}
+
+/** Build the concise stdout advisory string for a non-empty result. */
+function advisoryNote(filename, result) {
+  const cats = [...new Set(result.warnings.map((w) => w.category))];
+  const base = path.basename(filename);
+  const lines = [
+    `gdd-design-quality-check: ${result.count} visual-tell ` +
+      `warning${result.count === 1 ? '' : 's'} in ${base} ` +
+      `across ${cats.length} categor${cats.length === 1 ? 'y' : 'ies'} ` +
+      `(${cats.join(', ')}).`,
+  ];
+  for (const w of result.warnings.slice(0, 8)) {
+    lines.push(`  - [${w.rule}] line ${w.line}: ${w.match}`);
+  }
+  lines.push('  See reference/visual-tells.md for remediation patterns. (advisory, non-blocking)');
+  return lines.join('\n');
+}
+
+/**
+ * Core hook entry. Accepts a parsed payload, returns the decision object to
+ * write to stdout. Always returns { continue: true } (advisory only).
+ * Exported for unit testing without spawning a process.
+ */
+function main(payload, opts = {}) {
+  const cwd = (payload && payload.cwd) || opts.cwd || process.cwd();
+  const write = extractWrite(payload);
+  if (!write) return { continue: true };
+
+  const result = evaluate(write.content, write.filename);
+  if (result.count === 0) return { continue: true };
+
+  emitEvent(cwd, write.filename, result);
+  const note = advisoryNote(write.filename, result);
+  return { continue: true, systemMessage: note };
+}
+
+async function run(stdin = process.stdin, stdout = process.stdout) {
+  let buf = '';
+  for await (const chunk of stdin) buf += chunk;
+  let payload;
+  try {
+    payload = JSON.parse(buf || '{}');
+  } catch {
+    stdout.write(JSON.stringify({ continue: true }));
+    return;
+  }
+  const decision = main(payload);
+  if (decision.systemMessage) {
+    // Surface the advisory on stderr too so it is visible in plain hook logs.
+    try {
+      process.stderr.write(decision.systemMessage + '\n');
+    } catch {
+      /* swallow */
+    }
+  }
+  stdout.write(JSON.stringify(decision));
+}
+
+// Run as a CLI only when invoked directly; tests require() this module and call
+// evaluate()/main() against mock payloads without triggering stdin reads.
+if (require.main === module) {
+  run().catch(() => {
+    process.stdout.write(JSON.stringify({ continue: true }));
+  });
+}
+
+module.exports = { main, evaluate, extractWrite, RULES, FRONTEND_EXT };

package/hooks/hooks.json

@@ -116,6 +116,23 @@
             "command": "node --experimental-strip-types \"${CLAUDE_PLUGIN_ROOT}/hooks/context-exhaustion.ts\""
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-a11y-gate.js\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-design-quality-check.js\""
+          }
+        ]
       }
     ],
     "Stop": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.47.0",
+  "version": "1.49.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -115,7 +115,10 @@
     "agent-sdk",
     "figma",
     "extractor",
-    "design-system-sync"
+    "design-system-sync",
+    "worktree-safe",
+    "anti-slop",
+    "confidence-gate"
   ],
   "skills": [
     "SKILL.md"

package/reference/brief-quality-rubric.md

@@ -0,0 +1,98 @@
+# Brief Quality Rubric
+
+The five anti-patterns `agents/brief-auditor.md` grades `.design/BRIEF.md` against. Each entry pairs a
+definition with a good and bad example, the detection signal the auditor greps for, and a severity note.
+This rubric is advisory: a flagged brief still proceeds to explore. The point is to surface vagueness
+while the cost of fixing it is one sentence, not a redesign.
+
+A brief is the contract every later stage checks against. A vague brief produces an unverifiable cycle,
+because verify has nothing concrete to test. The auditor reads the brief once and writes findings to
+`.design/BRIEF-AUDIT.md`; the brief skill then offers `/gdd:discuss brief` when any anti-pattern fires.
+
+---
+
+## AP-1: Vague verbs without a metric
+
+**Definition:** The problem or goal uses a soft verb (improve, optimize, streamline, enhance, modernize,
+refresh) with no number, threshold, or observable change attached. The verb hides the actual target.
+
+- **Bad:** "Improve the checkout flow."
+- **Good:** "Cut checkout abandonment from 38 percent to under 25 percent on mobile."
+
+**Detection signal:** Match soft verbs (`improve`, `optimize`, `streamline`, `enhance`, `modernize`,
+`refresh`) in the Problem or Success Metrics sections, then check the same sentence for a digit, a
+percent sign, or a unit. A soft verb with no adjacent quantity is a hit.
+
+**Severity:** Major. A goal with no metric cannot be verified, so the whole cycle inherits the ambiguity.
+
+---
+
+## AP-2: Missing audience
+
+**Definition:** The brief never names who the design is for. No role, device, context, or skill level is
+stated, so every later trade-off (density, reading level, input model) is a guess.
+
+- **Bad:** "Build a dashboard for tracking orders."
+- **Good:** "Build an order dashboard for warehouse leads on a shared floor tablet, glanceable at arm's length."
+
+**Detection signal:** Read the Audience section. Flag when it is empty, a placeholder (`TBD`, `users`,
+`everyone`, `all users`), or names no role plus context. A single generic noun with no qualifier is a hit.
+
+**Severity:** Major. Audience drives density, tone, and accessibility floor; without it the design optimizes
+for no one.
+
+---
+
+## AP-3: Immeasurable success criteria
+
+**Definition:** Success is described in feelings rather than observables (looks modern, feels clean, is
+intuitive, delights users). There is no event, count, or threshold a verifier could check.
+
+- **Bad:** "Users should feel the app is fast and modern."
+- **Good:** "First contentful paint under 1.5 seconds; task completion rate above 90 percent in five tests."
+
+**Detection signal:** Scan Success Metrics for subjective adjectives (`modern`, `clean`, `intuitive`,
+`delightful`, `nice`, `beautiful`) with no paired number or pass/fail condition. Subjective-only criteria
+are a hit.
+
+**Severity:** Major. Verify cannot grade a feeling; immeasurable criteria collapse the verify gate.
+
+---
+
+## AP-4: Scope creep
+
+**Definition:** The Scope section lists more than the cycle can deliver, or mixes unrelated surfaces into
+one brief, so the in-scope line stops constraining anything.
+
+- **Bad:** "Redesign onboarding, billing, settings, the marketing site, and add dark mode."
+- **Good:** "In scope: the three-step onboarding flow. Out of scope: billing, settings, marketing site."
+
+**Detection signal:** Count distinct surfaces or top-level features named as in-scope. More than three
+unrelated surfaces in one brief, or an in-scope list with no matching out-of-scope line, is a hit.
+
+**Severity:** Minor. Wide scope is recoverable by splitting, but unsplit it inflates every later estimate.
+
+---
+
+## AP-5: Missing anti-goals
+
+**Definition:** The brief states what to build but never what to avoid. With no anti-goals, explore widens
+to fill the vacuum and the design picks up patterns the team never wanted.
+
+- **Bad:** (Scope lists features only; no "we are deliberately not doing X" line anywhere.)
+- **Good:** "Anti-goals: no new navigation paradigm, no carousel, do not touch the existing auth screens."
+
+**Detection signal:** Look for an explicit non-goal, anti-goal, or out-of-scope statement framed as a
+prohibition (`do not`, `avoid`, `no new`, `out of scope`). A brief with zero prohibition statements is a hit.
+
+**Severity:** Minor. Anti-goals prevent drift; their absence is a warning, not a blocker.
+
+---
+
+## How findings are scored
+
+The auditor reports a count of fired anti-patterns and lists each with its section and the matched text.
+It does not compute a pass/fail gate and it does not block the brief to explore transition. Major findings
+(AP-1, AP-2, AP-3) carry more weight in the summary line than Minor findings (AP-4, AP-5), so the user
+knows which gaps most threaten a verifiable cycle. When any anti-pattern fires, the brief skill surfaces a
+one-line pointer offering `/gdd:discuss brief` to refine before moving on.

package/reference/copy-quality.md

@@ -0,0 +1,135 @@
+---
+name: copy-quality
+type: heuristic
+version: 1.0.0
+phase: 48
+tags: [copy, microcopy, ux-writing, ctas, errors, empty-states, aria, alt-text, i18n, voice, pillar-1]
+last_updated: 2026-06-03
+---
+
+# Copy Quality - Microcopy Rubric
+
+This file is the rubric the Copy pillar (Pillar 1 of `agents/design-auditor.md`) scores against, and the detailed reference that `agents/copy-auditor.md` applies. The design-auditor's Pillar 1 carries the 1-4 score and a one-line finding; this file holds the per-category criteria, the failure patterns, and the i18n lens that produce that score.
+
+Voice and tone are owned by [`brand-voice.md`](./brand-voice.md): the five axes (formal/casual, serious/playful, expert/approachable, reverent/irreverent, authoritative/collaborative), the 12 archetypes, and the tone-by-context table. This file does not restate those. It checks whether the implemented strings honor the voice the product declared, and whether each microcopy surface does its specific job.
+
+Cultural and locale meaning is owned by [`rtl-cjk-cultural.md`](./rtl-cjk-cultural.md); engineering primitives for localized strings are owned by [`i18n.md`](./i18n.md). This file consumes the i18n text-expansion table as a copy-length lens (see Internationalization Lens below).
+
+## Why Copy Is a Pillar
+
+Generic or default copy is the most common quiet failure in shipped UI. A "Submit" button, a "No data" empty state, and a raw stack-trace error each pass a functional test and each fail the user. Specific, purposeful language is a craft signal: it shows the team pictured a real person reading the screen. The Copy pillar measures that gap between functional text and intentional text.
+
+## Category Rubrics
+
+Each category below lists what good looks like and the failure patterns to grep for. A category is "weak" when the failure patterns dominate; "absent" when the surface exists with no considered copy at all.
+
+### Button and CTA labels
+
+Good labels are verb-first and name the object: "Export CSV", "Add member", "Send invite", "Delete project". The user reads the label and knows the outcome before clicking. Primary actions carry the specific verb; secondary actions ("Cancel", "Back") may stay plain because they are reversible and conventional.
+
+Failure patterns: bare "Submit", "OK", "Go", "Click here", "Button", or a noun with no verb ("Form", "Settings" on an action). A primary action labeled "Save" with no object on a screen that saves several distinct things is weak, not broken.
+
+```bash
+grep -rEn ">(Submit|Click Here|OK|Go|Button|Done)<" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### Error messages
+
+Good error copy names the cause and the recovery, and never blames the user. State what happened, then what to do: "We could not save your changes. Check your connection and try again." For validation, point at the field and the fix: "Enter a date in the future." The tone matches the stakes (see the tone-by-context table in `brand-voice.md`); data-loss and payment failures are calm and serious, never playful.
+
+Failure patterns: raw codes or stack traces shown to users ("Error 500", "undefined is not a function"), blame language ("You entered an invalid value", "Your input was wrong"), and dead ends that state the failure with no next step.
+
+```bash
+grep -rEn "went wrong|Error [0-9]|invalid input|you entered|try again" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### Empty states
+
+Good empty states orient and offer the first action. They explain why the screen is empty and give one clear thing to do: "No projects yet. Create your first project to get started." A first-run empty state is an onboarding moment, not an error.
+
+Failure patterns: "No data", "Nothing here", a bare zero, or an empty container with no copy. An empty state that explains the emptiness but offers no action is weak.
+
+```bash
+grep -rEn "No data|No results|Nothing here|No items|empty" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### Loading and skeleton copy
+
+Good loading copy reassures and signals progress without nagging: "Getting your data...", "Almost there." Skeleton screens are preferred to spinner-plus-text for content that has a known shape; when text is shown, it is brief and specific to what is loading. Long operations name the step ("Uploading 3 of 12 files").
+
+Failure patterns: "Loading..." with no context on a multi-second operation, a spinner with no label on a process that can fail, or jokey loading copy on a high-stakes action.
+
+```bash
+grep -rEn "Loading|Please wait|spinner|Skeleton" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### ARIA text quality
+
+ARIA strings are copy the screen-reader user hears. They must describe purpose, not implementation. `aria-label="Close dialog"` is good; `aria-label="button"` or `aria-label="icon"` is noise. Live-region announcements (`aria-live`, `role="status"`, `role="alert"`) carry the same cause-plus-recovery standard as visible errors. Labels must not duplicate adjacent visible text in a way that makes the reader say it twice.
+
+Failure patterns: `aria-label` set to the element type, `aria-label` that restates a visible label verbatim, missing `aria-label` on icon-only controls, and silent live regions on async state changes.
+
+```bash
+grep -rEn "aria-label=\"(button|icon|link|image|click)\"" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### Alt-text quality
+
+Good alt text conveys the function or meaning of an image in context. A logo links home: `alt="Acme home"`, not `alt="logo"`. A decorative image takes empty alt (`alt=""`) so the reader skips it. An informative chart names its takeaway, not its file. Alt text never starts with "image of" or "picture of"; the reader already knows it is an image.
+
+Failure patterns: `alt="image"`, `alt="photo"`, filename alt (`alt="IMG_2043.jpg"`), missing alt on informative images, and non-empty alt on purely decorative images.
+
+```bash
+grep -rEn "alt=\"(image|photo|picture|img|logo)\"|alt=\"[^\"]*\\.(png|jpg|jpeg|svg|webp)\"" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### Form labels, helper, and validation copy
+
+Every input has a persistent visible label (placeholders are not labels). Helper text sets expectations before the user types ("Use 8 or more characters"). Validation copy is specific and arrives at the right time: inline after blur for format rules, on submit for cross-field rules. Required and optional states are stated in words, not color alone.
+
+Failure patterns: placeholder-as-label, helper text that only appears as an error after failure, generic "This field is required" with no field name when several are blank, and validation copy that says what is wrong but not how to fix it.
+
+```bash
+grep -rEn "placeholder=|required|This field|is invalid" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+```
+
+### Voice and tone alignment
+
+Read the declared voice from `.design/DESIGN-CONTEXT.md` (axis positions and archetype, if recorded) and check the implemented strings against it. A Caregiver health app with a curt, blaming error message is off-voice even if the error is technically clear. A formal finance app with "Oops!" on a failed transfer is off-voice. Use the tone-by-context table in `brand-voice.md` as the per-surface contract: error, empty state, success, onboarding, loading, destructive confirmation each have a recommended register.
+
+Failure patterns: one tone for marketing copy and a flatly different tone for in-product copy, playful language on high-stakes actions, and copy that contradicts the declared archetype.
+
+## Internationalization Lens
+
+Apply this lens to copy-heavy components (anything where text drives width: buttons, nav, tabs, chips, table headers, banners). It folds the [`i18n.md`](./i18n.md) text-expansion table into the copy score.
+
+Two probes:
+
+1. **Hardcoded user-facing strings.** Strings rendered to users should flow through the project's i18n layer, not sit as literals in JSX. A literal English string in a component is a copy defect for any product that ships, or plans to ship, more than one locale.
+
+   ```bash
+   grep -rEn ">[A-Z][a-z]+ [a-z]+.*<|aria-label=\"[A-Z][a-z]+ " src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+   ```
+
+2. **Expansion-overflow at +40%.** German expands English by about +30%, Russian by about +40% (see the expansion table in `i18n.md`). A fixed-width control sized to English is the worst case. The lens: for each copy-bearing component with a width constraint, ask whether the label survives a +40% expansion without clipping or truncating mid-word. Containers sized to `EN base x 1.4` clear the worst row of that table. Flag fixed pixel widths on text controls and single-line labels with no wrap or ellipsis strategy.
+
+   ```bash
+   grep -rEn "w-\[[0-9]+px\]|width:\s*[0-9]+px|truncate|whitespace-nowrap" src/ --include="*.tsx" --include="*.jsx" 2>/dev/null | head -10
+   ```
+
+A copy-heavy component that hardcodes strings, or that clips at +40%, drops the Copy pillar by one point and appears in the findings with the `i18n_readiness` lens tag (see `audit-scoring.md` Lens-Tags).
+
+## Scoring Guide (Copy Pillar, 1-4)
+
+This scale matches the 1-4 definitions in `agents/design-auditor.md`. The Copy pillar score is a single 1-4 value; the categories above supply the evidence.
+
+| Score | Label | Criteria |
+|-------|-------|----------|
+| 4 | Exemplary | CTAs are verb-object specific; error messages name cause and recovery without blame; empty states orient and offer a first action; ARIA and alt text describe purpose; form copy guides before and during input; voice matches the declared axes and archetype; copy-heavy components survive a +40% expansion and route strings through i18n. |
+| 3 | Solid | Most copy is intentional; one or two generic labels remain (a plain "Save" on a single-purpose form); error and empty states are present and human but plain; minor voice drift only. |
+| 2 | Present but weak | Mix of intentional and generic copy; some empty states missing; errors show raw codes or blame; ARIA or alt text restates element type; hardcoded strings or +40% overflow risk in copy-heavy components. |
+| 1 | Absent or broken | Majority generic ("Submit", "OK", "Cancel"); empty states absent or "No data"; errors are developer-facing; ARIA labels are noise; alt text is "image" or filenames; no voice considered. |
+
+## How findings feed the audit
+
+`agents/copy-auditor.md` runs these probes, scores the pillar, and writes `.design/COPY-AUDIT.md` as a supplement. `agents/design-auditor.md` folds that score and the top finding into Pillar 1 of `.design/DESIGN-AUDIT.md`. Neither file changes the separate 7-category 0-10 system in `audit-scoring.md`; the Copy pillar is a qualitative 1-4 signal, not a weighted metric.