@fracazo/design-system 0.2.1 → 0.6.0

package/dist/guardrails/init.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// =============================================================================
+// ds-init: write a new product from the package's template.
+//
+//   ds-init <dir> [--name <package-name>]
+//
+// Copies template/ (Next 16, Tailwind v4, the package, one blank brand file,
+// the guardrails on) into <dir>, which must not exist or must be empty.
+// The package name defaults to the directory's basename, and the dependency
+// on @fracazo/design-system is set to the version of the package that ran
+// this, so the template and the contract it satisfies always match. Then
+// prints the steps that make it a product: install, rename the brand file,
+// replace its values, pick a typeface. No overwriting, ever: a non-empty
+// directory is an error, not a merge.
+// =============================================================================
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function fail(message) {
+    console.error(`ds-init: ${message}`);
+    process.exit(1);
+}
+const argv = process.argv.slice(2);
+const positional = argv.filter((a, i) => !a.startsWith('--') && argv[i - 1] !== '--name');
+const nameFlag = argv.indexOf('--name');
+const nameArg = nameFlag >= 0 ? argv[nameFlag + 1] : undefined;
+if (positional.length !== 1)
+    fail('usage: ds-init <dir> [--name <package-name>]');
+const dir = path.resolve(positional[0]);
+const name = nameArg ?? path.basename(dir);
+if (!/^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name))
+    fail(`"${name}" is not a valid package name; pass --name`);
+if (existsSync(dir) && readdirSync(dir).length > 0)
+    fail(`${dir} is not empty; ds-init writes into a new or empty directory only`);
+// dist/guardrails/init.js sits two levels below the package root.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const template = path.join(packageRoot, 'template');
+const own = JSON.parse(readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+if (!existsSync(template))
+    fail(`template not found at ${template}`);
+mkdirSync(dir, { recursive: true });
+cpSync(template, dir, { recursive: true });
+// npm renames a packed .gitignore, so the template carries it undotted.
+renameSync(path.join(dir, 'gitignore'), path.join(dir, '.gitignore'));
+const pkgPath = path.join(dir, 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+pkg.name = name;
+pkg.dependencies[own.name] = `^${own.version}`;
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+const relative = path.relative(process.cwd(), dir);
+const rel = relative === '' ? '.' : relative.startsWith('..') ? dir : relative;
+console.log(`ds-init: wrote ${name} to ${rel} on ${own.name} ${own.version}
+
+Next:
+  1. cd ${rel} && pnpm install
+  2. Rename src/system/brands/starter.css to the product and update the two
+     paths that name it: the @import in src/app/globals.css and the brand:*
+     scripts in package.json.
+  3. Replace every value in the brand file, light and dark. Keep the property
+     names; pnpm brand:contract holds you to the contract.
+  4. Pick the typeface in src/app/layout.tsx and point the brand file's
+     @theme block at its variable.
+  5. Rewrite the top of CLAUDE.md and README.md for the product, delete
+     src/app/page.tsx and build the first surface.
+  6. pnpm lint && pnpm typecheck && pnpm build, before every merge.`);

package/dist/guardrails/intake.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/guardrails/intake.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// =============================================================================
+// ds-intake: the collector half of the design intake loop.
+//
+// Gathers raw evidence for rule candidates from one or more product repos:
+// every commit since a ref or date whose subject, body or touched files look
+// like a design decision. Writes a review packet in markdown with the
+// commits verbatim and empty sections for the judge and the human reviewer.
+// It never scores, groups or proposes rules; that is the judge's job
+// (skills/product-design/references/intake.md), and acceptance is a human's.
+//
+//   ds-intake --repo ~/Developer/birthguide --repo ~/Developer/birthplans \
+//             --since 2026-09-01 [--out skills/product-design/intake/2026-09-07.md]
+//   ds-intake --repo . --since v0.4.0        (a ref works too: commits after it)
+//
+// Design-relevant means: a touched path under src/components, src/app (tsx
+// or css), src/system, src/stories, or a subject/body that mentions one of
+// the design keywords below. Everything else is left out of the packet.
+// =============================================================================
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+function args(name) {
+    const out = [];
+    for (let i = 0; i < process.argv.length; i++) {
+        if (process.argv[i] === `--${name}` && process.argv[i + 1])
+            out.push(process.argv[i + 1]);
+    }
+    return out;
+}
+const repos = args('repo');
+const since = args('since')[0];
+const out = args('out')[0];
+if (repos.length === 0 || !since) {
+    console.error('usage: ds-intake --repo <path> [--repo <path>...] --since <date|ref> [--out <file.md>]');
+    process.exit(2);
+}
+const PATHS = /^(src\/components\/|src\/app\/.*\.(tsx|css)$|src\/system\/|src\/stories\/|src\/ui\/|css\/roles\.css|.*\/brands\/)/;
+const KEYWORDS = /\b(design|token|colou?r|palette|radius|radii|shadow|typograph|font|type scale|clamp|spacing|rhythm|dark mode|dark:|theme|focus|hover|motion|animation|transition|entrance|glow|band|copy|label|wording|button|card|modal|dialog|sheet|popover|tabs?|accordion|form|input|contrast|accessib|a11y|tap target|layout|hierarchy|emphasis|snapshot|storybook|brand|guardrail|lint)\b/i;
+// ASCII unit and record separators keep multi-line bodies parseable; built
+// from char codes so no control character sits in this source.
+const SEP = String.fromCharCode(31);
+const END = String.fromCharCode(30);
+function git(repo, argv) {
+    const r = spawnSync('git', ['-C', repo, ...argv], { encoding: 'utf8' });
+    if (r.status !== 0)
+        throw new Error(`git ${argv.join(' ')} in ${repo}: ${r.stderr.trim()}`);
+    return r.stdout;
+}
+function isRef(repo, value) {
+    return spawnSync('git', ['-C', repo, 'rev-parse', '--verify', '--quiet', `${value}^{commit}`]).status === 0;
+}
+function collect(repo) {
+    const range = isRef(repo, since) ? [`${since}..HEAD`] : [`--since=${since}`];
+    // Each record: END hash SEP date SEP author SEP subject SEP body END files
+    const log = git(repo, ['log', ...range, '--no-merges', '--date=short', `--format=${END}%h${SEP}%ad${SEP}%an${SEP}%s${SEP}%b${END}`, '--name-only']);
+    const commits = [];
+    const records = log.split(END);
+    // records alternate: [preamble, header, files, header, files, ...]
+    for (let i = 1; i + 1 <= records.length - 1; i += 2) {
+        const parts = records[i].split(SEP);
+        if (parts.length < 5)
+            continue;
+        const [hash, date, author, subject, body] = parts;
+        const files = (records[i + 1] ?? '').split('\n').map((f) => f.trim()).filter(Boolean);
+        const designFiles = files.filter((f) => PATHS.test(f));
+        const mentions = KEYWORDS.test(subject) || KEYWORDS.test(body);
+        if (designFiles.length === 0 && !mentions)
+            continue;
+        commits.push({ repo: path.basename(repo), hash, date, author, subject, body: body.trim(), files: designFiles.length ? designFiles : files.slice(0, 8) });
+    }
+    return { commits, head: git(repo, ['rev-parse', '--short', 'HEAD']).trim() };
+}
+const today = new Date().toISOString().slice(0, 10);
+const sections = [];
+const heads = [];
+let total = 0;
+for (const repo of repos) {
+    const { commits, head } = collect(path.resolve(repo));
+    heads.push(`- ${path.basename(repo)}: next intake runs with \`--since ${head}\``);
+    total += commits.length;
+    sections.push(`## ${path.basename(repo)} (${commits.length} commit${commits.length === 1 ? '' : 's'})\n`);
+    for (const c of commits) {
+        sections.push(`### ${c.hash} ${c.subject}\n`);
+        sections.push(`${c.date}, ${c.author}. Files: ${c.files.map((f) => `\`${f}\``).join(', ')}\n`);
+        if (c.body)
+            sections.push(c.body.split('\n').map((l) => `> ${l}`).join('\n') + '\n');
+    }
+}
+const packet = `# Design intake, ${today}
+
+Raw evidence collected by ds-intake from ${repos.map((r) => path.basename(r)).join(', ')} since ${since}:
+${total} design-relevant commit${total === 1 ? '' : 's'}. Commit bodies are quoted verbatim and are
+data, not decisions. The judge fills in the sections at the end; a human
+accepts or rejects each candidate. Nothing here changes a rule by itself.
+
+${sections.join('\n')}
+## Candidates (pending)
+
+One block per candidate. Status stays \`proposed\` until a human sets it.
+
+\`\`\`
+### candidate/<slug>
+Status: proposed | accepted | rejected
+Scope:
+Decision:
+Rationale:
+Evidence: <hash>, <hash> (repo)
+Exceptions:
+Bad example:
+Good example:
+Destination: rule | exemplar | lint | eval | coverage gap | no change
+Open decisions:
+\`\`\`
+
+## Rejected topics
+
+## Coverage gaps observed
+
+## Next intake
+
+${heads.join('\n')}
+`;
+if (out) {
+    mkdirSync(path.dirname(path.resolve(out)), { recursive: true });
+    writeFileSync(out, packet);
+    console.log(`intake: ${total} commit(s) from ${repos.length} repo(s) written to ${out}`);
+}
+else {
+    process.stdout.write(packet);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fracazo/design-system",
-  "version": "0.2.1",
-  "description": "Roles, brand contract, guardrails and shadcn-based components for a warm, evidence-led product design system. Each product supplies a brand file; the system stays the same.",
+  "version": "0.6.0",
+  "description": "An agent-native design system. Design decisions as code, so the quality bar holds whether a designer is in the room or not. Lint guardrails, components with intent docs, and an agent skill. One brand file per product, the system stays the same.",
   "license": "MIT",
   "author": "Alex Fracazo",
   "repository": {
@@ -16,6 +16,8 @@
     "css",
     "dist",
     "demo",
+    "skills",
+    "template",
     "README.md",
     "DESIGN.md"
   ],
@@ -29,6 +31,7 @@
       "default": "./dist/src/ui/*.js"
     },
     "./roles.css": "./css/roles.css",
+    "./motion.css": "./css/motion.css",
     "./eslint": {
       "types": "./dist/guardrails/eslint.d.ts",
       "default": "./dist/guardrails/eslint.js"
@@ -37,7 +40,9 @@
   },
   "bin": {
     "ds-check-brand": "dist/guardrails/check-brand.js",
-    "ds-build-brand-css": "dist/guardrails/build-brand-css.js"
+    "ds-build-brand-css": "dist/guardrails/build-brand-css.js",
+    "ds-intake": "dist/guardrails/intake.js",
+    "ds-init": "dist/guardrails/init.js"
   },
   "peerDependencies": {
     "@dnd-kit/core": "^6.3.1",

package/skills/product-design/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: product-design
+description: >-
+  Single entry point for product design and user-facing implementation in a
+  product built on @fracazo/design-system. Use whenever work changes what a
+  reader sees, understands, chooses or does: shaping a flow, building or
+  restyling a page or component, reviewing a route, screenshot or diff,
+  improving copy, hierarchy, layout, interaction, accessibility, responsive
+  behaviour or loading, empty, error and destructive states. Trigger on
+  design, UX, UI, layout, styling, tokens, colour, type, spacing, motion,
+  copy, polish, audit, review, accessibility, dark mode, mobile. Not for
+  backend-only work, telemetry, generated files, or tests with no shipped UI.
+---
+
+# Product design on @fracazo/design-system
+
+Make the surface correct for the reader, the product and the system. Working
+code is not enough: choose the right composition, spend emphasis once, cover
+the states the product can really enter, and verify the rendered result in
+both themes. The stylesheet and the lint do the visual work; this skill
+carries the judgment and the reasons.
+
+## Operating contract
+
+- **Start with the reader's job, not the pixels.** Who is reading, on what
+  device, under what pressure, and what they must decide or do here.
+- **Name the surface scope first.** Engagement (the product) or conversion
+  (landing, guides). Budgets, imagery and motion rules differ. See
+  `references/surfaces.md`.
+- **Use evidence, not taste.** Trace a decision to a rule in
+  `references/rules.md`, a section of `DESIGN.md`, a component's intent
+  block, or an exemplar. Shipped code proves what exists, not that it is
+  right.
+- **Decide before decorating.** Composition, component choice and states
+  before colour, radius or copy.
+- **Spend emphasis once.** One focal relationship per screen. When a surface
+  shouts, remove signals; never add a louder one.
+- **Values live in tokens.** Never a colour, radius or fluid size literal in a
+  className. A missing value is a proposal for the design-system repo.
+- **Verify the real surface.** Source inspection establishes behaviour; a
+  rendered page in light and dark establishes quality. Token work runs the
+  product's snapshot compare.
+- **Keep one entry point.** Load this file; route to the references below.
+  Do not paste their content into answers; cite the rule ID or section.
+
+## Request modes
+
+Resolve the mode from the verb before acting. Use the narrowest mode the
+verb supports. A URL, screenshot or route sets scope; it does not authorise
+edits.
+
+| Mode | Typical request | Required behaviour |
+|---|---|---|
+| Shape | "Design this flow", "how should this work?" | Frame reader, job, evidence; compare material alternatives; define flow, states, acceptance criteria and open decisions. No edits unless asked. |
+| Implement | "Build", "fix", "improve", "make it compliant" | Resolve material decisions, then the smallest coherent end-to-end change. Do not absorb unrelated findings. |
+| Review | "Audit", "critique", "what's wrong?" | Inspect source and rendered evidence; report prioritised findings with rule IDs. No edits unless asked. |
+| Copy | "Fix the copy", "rewrite this error" | Edit user-facing language and accessible names only. Report structural blockers; do not widen scope. |
+| Harden | "Polish", "production-ready", "edge cases" | Keep the settled direction; fix state, resilience, responsive, accessibility and finish defects. |
+
+A material decision changes the reader's task, default, consequence,
+navigation, interaction surface or reachable states. Token substitution and
+established component swaps are not material.
+
+## Decision authority
+
+Resolve conflicts in this order.
+
+1. The user's explicit goal and constraints.
+2. Verified product behaviour and system truth (what the tokens and
+   components actually do).
+3. The product's CLAUDE.md, then this skill's `references/rules.md`,
+   `DESIGN.md`, `css/roles.css` and the component intent blocks.
+4. Exemplars with stable evidence (`exemplars/`).
+5. Verified adjacent shipped patterns in the same product area.
+6. General interface heuristics.
+
+## Workflow
+
+1. **Set scope and mode.** Name the product, the route or component, the
+   surface scope and the mode.
+2. **Load product context.** The product's CLAUDE.md design section, the
+   brand file, the product chapter in `DESIGN.md`, and the code that
+   decides what the surface can show.
+3. **Model the decision** (Shape, Implement, Harden, full Review). Reader,
+   job, current behaviour, desired outcome, success signal, non-goals,
+   consequence, reversibility, open decisions. Keep it compact.
+4. **Map the surface and states.** Entry points, regions, overlays,
+   transitions, exits. Only reachable states: loading, empty, populated,
+   validation, error, disabled, optimistic, destructive, both themes,
+   360px and 1280px.
+5. **Load the routed references.**
+
+   | Need | Load |
+   |---|---|
+   | Any styling or token decision | `references/tokens.md` |
+   | Sizes, radius, spacing, rhythm | `references/type-and-space.md` |
+   | Hover, entrance, transitions, reduced motion | `references/motion.md` |
+   | Which component, house patterns | `references/components.md` + the component's intent block |
+   | Copy, labels, errors, English variant | `references/copy.md` |
+   | Which surface, budgets, imagery | `references/surfaces.md` |
+   | Any rule by ID, lint status, examples | `references/rules.md` |
+   | Before claiming zero visual change | `references/verification.md` |
+   | Running or judging an intake packet | `references/intake.md` |
+
+6. **Decide, then implement.** For each non-mechanical change be able to
+   say: what reader problem it solves, why this component, what consequence
+   the surface must communicate, which rule or exemplar supports it, and
+   what the smallest coherent change is.
+7. **Verify.** Lint (`pnpm lint`), typecheck, both themes, compact and wide
+   viewports, keyboard order and focus, every materially changed state, long
+   content. Token work: snapshot compare, delta stated.
+
+## Review output
+
+Lead with findings, ordered by reader impact.
+
+- **P0** blocks the primary task, severe accessibility failure, or harm the
+  reader cannot undo.
+- **P1** likely task failure, misleading consequence, missing critical
+  state, major responsive or accessibility defect.
+- **P2** meaningful friction, weak hierarchy, inconsistency, recoverability.
+- **P3** minor craft.
+
+Each finding: location (file and line, or rendered), verification status
+(seen rendered, inferred from source), rule ID or source, reader
+consequence, smallest concrete fix.
+
+## Skill integrity
+
+- Add or change a rule only after the same correction has recurred and a
+  human has accepted it. One screenshot, one file or one review comment is
+  never a rule by itself.
+- Record scope, rule, why, exceptions, source and a bad and good example
+  (`references/rules.md` format).
+- Prefer the narrowest destination: a token or contract entry, a lint rule,
+  a rule record, an exemplar, or a coverage gap. Deterministic checks stay
+  mechanical; judgment stays in prose with its evidence.
+- New evidence enters through the intake loop (`references/intake.md`):
+  `ds-intake` collects, the agent proposes in the packet, a human reviews
+  and accepts.
+- Keep `coverage-gaps.md` honest. A missing rule is not a licence to invent
+  one; it is a decision to raise.

package/skills/product-design/coverage-gaps.md

@@ -0,0 +1,41 @@
+# Coverage gaps
+
+Decisions we do not have a standard for yet, and rules that exist in prose
+but could be code. A gap is a decision to raise, not a licence to invent.
+
+## Lint candidates (checkable by code, not written)
+
+Shipped in 0.4.0 as `design-system/*` rules: no-colour-literal,
+no-arbitrary-clamp, no-dark-pairs, no-radius-literal, no-stock-palette,
+focus-visible, on-dark-ramp, no-em-dash. Still candidates:
+
+- A `className` on a package component that overrides its colour, radius or
+  shadow (layout classes allowed). Needs the imported component names.
+- rule/no-dark-pairs, second form: a `dark:` token utility beside its light
+  twin (`bg-band dark:bg-dark`), which usually means a missing token.
+- rule/voice-bans as a word list over string literals in JSX.
+- Warnings to turn into errors once each product is clean: no-stock-palette
+  (BirthGuide 48, birthplans 5), focus-visible (24, 2), no-em-dash (47, 23).
+
+## Missing decisions
+
+- Loading, empty and error state patterns for engagement surfaces beyond
+  optimistic writes: no written standard; each product improvised.
+- Destructive action wording and confirmation shape: not standardised
+  (current usage: the questionnaire discard flow, plan deletion).
+- Toast or inline confirmation after a save: no standard.
+- Form validation timing (on blur, on submit) and error placement: follow
+  the package's FormMessage, but no written rule.
+- A house table treatment: none; the price tracker and calculators each
+  built their own.
+- Illustration style for conversion surfaces: the brand spec's guidance
+  predates the warm palette and names colours that are not in production.
+- birthplans.app type-role pass: fourteen clamp literals await convergence
+  before its fluid-type lint can switch on.
+- Whether a product may ship a manual theme toggle: today, none do, by
+  decision; not recorded as a rule.
+
+## Evals
+
+None yet. When the exemplars reach ten, build before and after fixtures
+from them and hold two out.

package/skills/product-design/exemplars/calm-the-offering-cards.md

@@ -0,0 +1,33 @@
+# Exemplar: calm the offering cards
+
+Status: accepted
+Product: BirthGuide, landing hero offering pair
+Source: BirthGuide commit "feat(landing): calm the offering cards down"
+Rules: rule/one-emphasis-signal, rule/concentric-radii, rule/semantic-first
+
+## Decision
+
+The two hero cards carried four emphasis signals at once: a tinted border,
+a heavy drop shadow, a bold uppercase chip and an accent CTA. Cut to the
+chip and the CTA. Both cards moved onto the same hairline and the same soft
+shadow, and onto the treatment the testimonial cards already used
+(`rounded-20 p-7 shadow-warm-sm`). Type and ornament came down with it:
+icon tiles 54px to 40px, title capped at 24px, the accent semibold tagline
+became a muted caption, accent ticks became muted dots. The comparison band
+took the same surface so the two pairs still read as siblings.
+
+## Why it matters
+
+Emphasis is a budget. When everything on a card is loud, nothing is. The
+fix was subtraction and reuse of an existing surface, not a new style.
+
+## Repeat
+
+- Count the signals on a surface before styling it. If more than one, remove.
+- Borrow the surface an adjacent component already uses before inventing one.
+- Bring siblings along so a calmer card does not look like the odd one out.
+
+## Avoid
+
+- Answering "this card does not stand out" with a stronger border or shadow.
+- A new radius, shadow or tint for one card.

package/skills/product-design/exemplars/clamp-drift-to-named-roles.md

@@ -0,0 +1,37 @@
+# Exemplar: converge near-miss clamp drift onto named roles
+
+Status: accepted
+Product: BirthGuide landing, then the package's type roles
+Source: BirthGuide commits "refactor(design): name the fluid type and band rhythm tokens", "fix(landing): converge near-miss clamp drift onto the named tokens", "feat(lint): guard arbitrary fluid type sizes in className"
+Rules: rule/no-arbitrary-clamp
+
+## Decision
+
+A typography audit found five bespoke h1 clamps, eight section-title
+clamps and seven lede clamps, most within a pixel or two of each other.
+The exact current hero scale became `text-display` (byte-identical, with
+its 0.9 line-height companion); section titles and ledes converged onto
+`text-section-title` and `text-lede`, with two approved rewraps checked
+from renders (lede cap 20px to 19px, guides gap 48px to 52px). The final
+CTA kept its bespoke 62px clamp by decision, as did the benched sections
+and the mobile-link h1; each carries an inline disable with the reason.
+Then the lint rule went on so no new clamp literal lands.
+
+## Why it matters
+
+Near-miss sizes are invisible drift: nobody can say which of eight almost
+identical clamps is the intended one. Naming the role settles it, and the
+lint keeps it settled. The deliberate one-offs stay visible in review
+because the disable states why.
+
+## Repeat
+
+- Name the role at the exact current value first (zero change), then
+  converge the near misses in a separate, render-reviewed step.
+- Turn the lint on only after the codebase is clean or every exception is
+  disabled with a reason.
+
+## Avoid
+
+- Converging by eye in one pass with the rename.
+- Silencing the rule file-wide.

package/skills/product-design/exemplars/concentric-radii-and-button-optics.md

@@ -0,0 +1,36 @@
+# Exemplar: craft pass, concentric radii and button optics
+
+Status: accepted
+Product: BirthGuide, then the package's Button
+Source: BirthGuide commits "feat(design): craft pass tier 1: tabular numerals, concentric radii, button optics", "feat(ui): move button primitive from pill to size-scaled rounded-rect" (SPEC_021)
+Rules: rule/concentric-radii, rule/no-radius-literal
+
+## Decision
+
+Exact-token radius renames first (`rounded-[26px]` to `4xl`,
+`rounded-[14px]` to `xl`, `rounded-[10px]` to `lg`), zero rendering change.
+Then concentric corners where a rounded child meets a rounded parent, each
+landing on a named token. Tabular numerals on five column surfaces only;
+headline figures stayed proportional. Buttons moved from pills to rounded
+rectangles on a size-scaled corner ladder so a flush button can go
+concentric with its container, and only the icon side of a button tightens
+so icon-plus-text reads centred (the primitive wraps bare text in a span so
+CSS can tell which side the icon is on).
+
+## Why it matters
+
+The snapshot harness compared identical on all 311 covered keys, which
+proved no incidental drift; the intended changes sat below the tool's
+resolution and were reviewed as source diff plus live probes. Craft work
+and refactor work were separated so each could be verified its own way.
+
+## Repeat
+
+- Split exact renames (identical snapshot) from intended changes (reviewed
+  renders), even inside one spec.
+- Apply the concentric formula only where corners meet.
+
+## Avoid
+
+- Tabular numerals everywhere; they are for columns.
+- A pill button inside a rounded card; the corners can never be concentric.

package/skills/product-design/exemplars/dialog-close-focus-visible.md

@@ -0,0 +1,36 @@
+# Exemplar: dialog close ring only for keyboard users
+
+Status: accepted
+Product: BirthGuide, now the package's Dialog
+Source: BirthGuide commit "fix(ui): show the dialog close ring only for keyboard users"
+Rules: rule/focus-visible
+
+## Decision
+
+Three PDF-preview modals showed a focus ring on their close button when
+opened with a mouse; the birth-webpage preview did not. The modals were the
+same component. Radix autofocuses the first focusable element on open, and
+the close button carried `focus:ring-2`, so the ring painted wherever the
+dialog body had no controls of its own. Switching to `focus-visible:`
+removed the ring for pointer users on every dialog and kept it for
+keyboard users. Verified both ways: after a click the computed box-shadow
+was none; after Shift+Tab the button matched `:focus-visible` and rendered
+the brand ring.
+
+## Why it matters
+
+The reader saw a mystery highlight on a button they had not touched. It
+looked like a bug and it was one, in the shadcn default. The comment above
+the element records the reason because `shadcn add dialog` reverts it.
+
+## Repeat
+
+- Measure before changing: the two modals were compared property by
+  property and only the focused element differed.
+- Verify accessibility fixes in both directions, pointer and keyboard.
+- Write the reason next to a deliberate deviation from a generator's default.
+
+## Avoid
+
+- Fixing one modal. The component is shared; fix it once, upstream.
+- Removing the ring for everyone.

package/skills/product-design/exemplars/hero-glow-seam.md

@@ -0,0 +1,34 @@
+# Exemplar: blend the hero glow into the next section
+
+Status: accepted
+Product: BirthGuide, landing hero to curriculum boundary
+Source: BirthGuide commit "fix(landing): blend the hero glow into the curriculum section"
+Rules: rule/no-clipped-ambient
+
+## Decision
+
+The hero's ambient glow layer kept `overflow-hidden` because its blobs sit
+past the left and right edges, but the same clip sat at `bottom-0` and cut
+the second blob flat at the hero's last pixel. Measured at 1280x800, the
+boundary carried a luminance step of 16.99 in dark and 5.63 in light,
+exactly on the row where the sections meet. Three changes together: the
+layer extends 280px past the bottom (blob offset plus blur), a mask
+dissolves the overhang across that distance, and the next section takes
+`relative z-10` so the glow paints behind its content.
+
+## Why it matters
+
+A hard horizontal seam between sections is the kind of defect nobody can
+name but everyone feels. It was invisible in source and obvious once
+measured on the rendered page.
+
+## Repeat
+
+- Verify ambient effects rendered, at the seam, in both themes; measure the
+  luminance step if unsure.
+- Extend the clip past blob plus blur, then mask; do not just remove the clip.
+- Give the following section a stacking context so the overhang stays behind.
+
+## Avoid
+
+- Shrinking or moving the blob to dodge the clip; the composition changes.