@ericrisco/rsc 3.1.4 → 3.3.1

package/scripts/lib/starting-point.js

@@ -1,314 +0,0 @@
-// What does this project already own to start from, and does its colour hold up?
-//
-// The design area declares three times that it will propose a starting point when the user has
-// none — `design-loop` phase 1 on `skip`, the closing line of `design`'s brand grounding, and
-// `design-dna`'s REUSE mode — and none of the three had anything behind it. An unbacked promise to
-// propose falls back to the model's prior, which is the AI-template median the area exists to
-// escape. Spec: 02-DOCS/wiki/sdd/specs/design-starting-point.md
-//
-// This file is the half that can be an algorithm (P1): listing what is installed, and refusing to
-// propose a colour that fails contrast. The half that needs judgement — which reference is the right
-// bar for what you are building — is prose, in design/references/starting-point.md.
-//
-// Read-only, always. `02-DOCS` is untracked and has no undo (P9), and a discovery pass has no
-// business writing anywhere.
-import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
-import { designIdentity, BRAND_DIR } from './design-identity.js';
-
-// WCAG 2.2 AA. Body text, and the relaxed floor for large text and UI components.
-export const TEXT_MIN = 4.5;
-export const UI_MIN = 3.0;
-
-// Which palette roles are held to which floor. `design-dna`'s schema fixes the role vocabulary
-// (ground, ink, accent, secondary, hairline); anything outside it is skipped rather than guessed at,
-// because inventing a threshold for an unknown role is how a gate starts approving things.
-const TEXT_ROLES = new Set(['ink', 'secondary']);
-const UI_ROLES = new Set(['accent']);
-const GROUND_ROLE = 'ground';
-
-// A record is only reusable if it carries the fields a style is actually rebuilt from. Half a record
-// cannot be reused, so it is reported as unreadable instead of offered as a candidate.
-const REQUIRED = ['palette'];
-const DIMENSIONS = ['palette', 'type', 'space', 'surface', 'motion', 'signatures', 'voice'];
-
-/** Where `design-dna` emits, and where rsc installs, in both scopes. */
-export function defaultRoots({ home = homedir(), cwd = process.cwd() } = {}) {
-  const roots = [];
-  for (const base of home === cwd ? [cwd] : [cwd, home]) {
-    roots.push(join(base, '.claude', 'skills'));
-    roots.push(join(base, '.rsc', 'skills'));
-  }
-  return roots;
-}
-
-function parseHex(hex) {
-  if (typeof hex !== 'string') return null;
-  const m = /^#([0-9a-fA-F]{6})$/.exec(hex.trim());
-  if (!m) return null;
-  const n = parseInt(m[1], 16);
-  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
-}
-
-// WCAG relative luminance. The sRGB transfer function, not a shortcut: an approximation here is a
-// wrong ratio everywhere downstream, and it would pass a test written against this file's own output.
-function luminance([r, g, b]) {
-  const lin = [r, g, b].map((c) => {
-    const s = c / 255;
-    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
-  });
-  return 0.2126 * lin[0] + 0.7152 * lin[1] + 0.0722 * lin[2];
-}
-
-/**
- * WCAG 2.x contrast ratio between two colours, 1.0 … 21.0. Symmetric.
- * @param {string} a sRGB hex, `#rrggbb`
- * @param {string} b sRGB hex, `#rrggbb`
- */
-export function contrastRatio(a, b) {
-  const ca = parseHex(a);
-  const cb = parseHex(b);
-  if (!ca || !cb) throw new TypeError(`not an sRGB hex colour: ${!ca ? a : b}`);
-  const la = luminance(ca);
-  const lb = luminance(cb);
-  const [hi, lo] = la >= lb ? [la, lb] : [lb, la];
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-/**
- * Does this palette's text hold up against its own ground?
- *
- * Runs before a measured colour is written as a proposed dimension: a value that fails is not
- * proposed at all, rather than proposed and flagged. Three outcomes are kept apart on purpose —
- * measured-and-passing, measured-and-failing, and **not measured**. Collapsing the third into the
- * first is the vacuous pass this area has already paid for twice.
- *
- * @param {Array<{role: string, hex: string, name?: string}>} colors — `palette.colors` from a dna.json
- * @returns {{ok: boolean, pairs: Array<object>, failures: Array<object>, skipped: Array<object>,
- *            unparsed: string[], reason: string}}
- */
-export function checkPairings(colors) {
-  const list = Array.isArray(colors) ? colors : [];
-  const pairs = [];
-  const skipped = [];
-  const unparsed = [];
-
-  const ground = list.find((c) => c && c.role === GROUND_ROLE);
-  const groundHex = ground ? parseHex(ground.hex) : null;
-  if (!ground) {
-    return { ok: false, pairs, failures: [], skipped, unparsed, reason: 'no ground role in the palette — nothing to measure against' };
-  }
-  if (!groundHex) {
-    unparsed.push(String(ground.hex));
-    return { ok: false, pairs, failures: [], skipped, unparsed, reason: `ground colour is not an sRGB hex: ${ground.hex}` };
-  }
-
-  for (const c of list) {
-    if (!c || c.role === GROUND_ROLE) continue;
-    const isText = TEXT_ROLES.has(c.role);
-    const isUi = UI_ROLES.has(c.role);
-    if (!isText && !isUi) {
-      // A hairline is not text. Saying so is not the same as saying it passed.
-      skipped.push({ role: c.role, name: c.name, reason: 'role carries no text, so no text floor applies' });
-      continue;
-    }
-    if (!parseHex(c.hex)) {
-      unparsed.push(String(c.hex));
-      continue;
-    }
-    const min = isText ? TEXT_MIN : UI_MIN;
-    const ratio = Math.round(contrastRatio(c.hex, ground.hex) * 100) / 100;
-    pairs.push({ role: c.role, name: c.name, fg: c.hex, bg: ground.hex, ratio, min, ok: ratio >= min });
-  }
-
-  const failures = pairs.filter((p) => !p.ok);
-  // Not measuring anything is not a pass. An empty failure list only means green when at least one
-  // pair was actually evaluated and nothing was left unparsed.
-  const ok = failures.length === 0 && unparsed.length === 0 && pairs.length > 0;
-  const reason = unparsed.length
-    ? `${unparsed.length} colour(s) could not be parsed, so they were not measured`
-    : pairs.length === 0
-      ? 'no text or UI role to measure against the ground'
-      : failures.length
-        ? `${failures.length} pair(s) below their floor`
-        : `${pairs.length} pair(s) measured, all above their floor`;
-  return { ok, pairs, failures, skipped, unparsed, reason };
-}
-
-function readRecord(dir, slug) {
-  const file = join(dir, 'dna.json');
-  let raw;
-  try {
-    raw = readFileSync(file, 'utf8');
-  } catch (e) {
-    return { error: `cannot read dna.json: ${e.code || e.message}` };
-  }
-  let dna;
-  try {
-    dna = JSON.parse(raw);
-  } catch (e) {
-    return { error: `dna.json is not valid JSON: ${e.message}` };
-  }
-  const missing = REQUIRED.filter((k) => !dna || !dna[k]);
-  if (missing.length) return { error: `record is missing ${missing.join(', ')} — half a record cannot be reused` };
-
-  return {
-    record: {
-      slug: (dna.meta && dna.meta.slug) || slug,
-      name: (dna.meta && dna.meta.name) || slug,
-      path: file,
-      covers: DIMENSIONS.filter((d) => dna[d]),
-      palette: (dna.palette && dna.palette.colors) || [],
-    },
-  };
-}
-
-// What the harness's own identity articles mention. A record the project actually used outranks one
-// that merely happens to be installed — but the others stay on the list, because choosing for the
-// user is exactly what the spec forbids.
-function citedSlugs(harnessRoot) {
-  const dir = join(harnessRoot, BRAND_DIR);
-  let text = '';
-  try {
-    for (const f of readdirSync(dir)) {
-      if (!f.endsWith('.md')) continue;
-      try { text += readFileSync(join(dir, f), 'utf8').toLowerCase(); } catch { /* one unreadable article is not the answer */ }
-    }
-  } catch { /* no identity here; designIdentity reports that half */ }
-  return text;
-}
-
-/**
- * What this project already owns to start a design from.
- *
- * @param {string[]} roots — skill directories to scan. Defaults to both scopes, both layouts.
- * @param {string} harnessRoot — where `02-DOCS/` lives, for the identity half and the ordering.
- * @returns {{state: 'owned'|'none'|'inconclusive', identity: object, records: object[],
- *            unreadable: Array<{path: string, reason: string}>, reason: string, fix?: string}}
- *   `owned`        — an identity or at least one legible record exists.
- *   `none`         — looked everywhere, found nothing. Carries the way out (P6).
- *   `inconclusive` — something could not be read. Never reported as `none`, never as green.
- */
-export function ownedStartingPoints(roots = defaultRoots(), harnessRoot = process.cwd()) {
-  const identity = designIdentity(harnessRoot);
-  const records = [];
-  const unreadable = [];
-  let blind = 0;
-
-  for (const root of roots) {
-    // existsSync follows symlinks, so a dangling one answers false and would be filed as "nothing
-    // installed here". That is unreadability, not absence — the exact conflation designIdentity was
-    // fixed for. lstat sees the link itself and tells them apart.
-    if (!existsSync(root)) {
-      let dangling = false;
-      try { dangling = lstatSync(root).isSymbolicLink(); } catch { /* genuinely absent */ }
-      if (dangling) {
-        blind += 1;
-        unreadable.push({ path: root, reason: 'skills root is a symlink that does not resolve' });
-      }
-      continue;
-    }
-    let entries;
-    try {
-      if (!statSync(root).isDirectory()) {
-        blind += 1;
-        unreadable.push({ path: root, reason: 'skills root exists but is not a directory' });
-        continue;
-      }
-      entries = readdirSync(root, { withFileTypes: true });
-    } catch (e) {
-      blind += 1;
-      unreadable.push({ path: root, reason: `cannot read skills root: ${e.code || e.message}` });
-      continue;
-    }
-    for (const entry of entries) {
-      // Dirents, not statSync: a symlinked entry could otherwise report on a directory outside the
-      // root we were asked to scan.
-      if (!entry.isDirectory()) continue;
-      const dir = join(root, entry.name);
-      if (!existsSync(join(dir, 'dna.json'))) continue;
-      const { record, error } = readRecord(dir, entry.name);
-      if (error) { unreadable.push({ path: join(dir, 'dna.json'), reason: error }); continue; }
-      if (!records.some((r) => r.slug === record.slug)) records.push(record);
-    }
-  }
-
-  const cited = citedSlugs(harnessRoot);
-  records.sort((a, b) => {
-    const ac = cited.includes(a.slug.toLowerCase()) ? 0 : 1;
-    const bc = cited.includes(b.slug.toLowerCase()) ? 0 : 1;
-    return ac - bc || a.slug.localeCompare(b.slug);
-  });
-
-  if (records.length || identity.state === 'present') {
-    return {
-      state: 'owned',
-      identity,
-      records,
-      unreadable,
-      reason: [
-        identity.state === 'present' ? `identity present (${identity.articles.length} article(s))` : 'no harness identity',
-        `${records.length} style record(s)`,
-        unreadable.length ? `${unreadable.length} unreadable` : null,
-      ].filter(Boolean).join(', '),
-    };
-  }
-
-  // Something was there and we could not use it. Saying "nothing to propose" would be a finding we
-  // did not earn, and saying nothing at all would hide it.
-  if (unreadable.length || blind || identity.state === 'inconclusive') {
-    return {
-      state: 'inconclusive',
-      identity,
-      records,
-      unreadable,
-      reason: unreadable.length
-        ? `could not read ${unreadable.length} candidate(s): ${unreadable[0].reason}`
-        : `identity could not be read: ${identity.reason}`,
-      fix: 'name what could not be read, and ask for another route to it — never propose past a blind spot',
-    };
-  }
-
-  return {
-    state: 'none',
-    identity,
-    records: [],
-    unreadable,
-    reason: 'no harness identity and no style record installed in any scope',
-    fix: 'propose at most three openable references as candidate bars (design/references/starting-point.md), then run `design-loop`',
-  };
-}
-
-/**
- * The compact projection `doctor` reports: one object, not a section (P5 — every byte of a report is
- * paid by every user who runs it). Contrast is folded in per record because a record whose own
- * palette fails is not a starting point anyone should be offered.
- *
- * @returns {{state: string, records: string[], contrast: string, unreadable: number, reason: string}}
- */
-export function startingPointSummary(root = process.cwd(), roots = defaultRoots({ cwd: root })) {
-  const r = ownedStartingPoints(roots, root);
-  let failing = 0;
-  let unmeasured = 0;
-  for (const rec of r.records) {
-    const c = checkPairings(rec.palette);
-    if (c.failures.length) failing += 1;
-    else if (!c.ok) unmeasured += 1;
-  }
-  const contrast = r.records.length === 0
-    ? 'no record to measure'
-    : failing
-      ? `${failing} record(s) with a pair below its floor`
-      : unmeasured
-        ? `${unmeasured} record(s) could not be measured`
-        : 'all records above their floors';
-  return {
-    state: r.state,
-    records: r.records.map((x) => x.slug),
-    contrast,
-    unreadable: r.unreadable.length,
-    reason: r.reason,
-    ...(r.fix ? { fix: r.fix } : {}),
-  };
-}

package/skills/design/evals/README.md

@@ -1,53 +0,0 @@
-# Eval harness — `design` skill
-
-This is an **agent-run** eval, not a shell script. The cases in `cases.yaml` are fed to a
-Claude Code agent and graded by inspection. There is no `pytest` to run; the "harness" is the
-procedure below plus a human (or a judge agent) checking outputs against the rubrics.
-
-## What's under test
-
-1. **Triggering** — does the `design` skill activate on the right prompts and stay quiet on
-   near-misses that belong to a sibling (`marketing`, `nextjs`, `flutter`) or to nothing in-repo?
-2. **Capability** — when it does fire, does the guidance measurably beat an unguided answer?
-
-## A. Triggering accuracy
-
-For each prompt in `should_trigger` and `should_not_trigger`:
-
-1. Start a fresh agent session with **only the `design` skill discoverable** (its `SKILL.md`
-   description in the system prompt / skill index). Do not pre-load sibling skills.
-2. Paste the prompt verbatim as the user's first message.
-3. Observe whether the agent **invokes/loads the `design` skill** (announces it, reads
-   `SKILL.md`, or applies its protocol) before answering.
-4. Run **3–5 independent trials per prompt** (fresh session each) to average out sampling noise.
-
-Scoring per prompt:
-- `should_trigger` → PASS if the skill fires in the **majority** of trials.
-- `should_not_trigger` → PASS if the skill **does not** fire in the majority of trials. Bonus:
-  the agent routes to the `route_to` target (or correctly declines when `route_to: none`).
-
-**Pass bar:** >= 90% trigger accuracy across all prompts (true-positives + true-negatives over
-total). Any `should_not_trigger` that fires in a majority of trials is a hard fail to fix in the
-`SKILL.md` description/When-NOT section, even if the aggregate clears 90%.
-
-## B. Capability uplift (with vs without)
-
-For each `capability` scenario:
-
-1. **Without:** fresh session, skill NOT available, give the scenario prompt. Save the answer.
-2. **With:** fresh session, `design` skill available and applied, same prompt. Save the answer.
-3. Grade both against the scenario's `must_include` points — one point per item, mark
-   covered / not covered. Use a second agent as judge or grade by hand.
-4. Compute coverage = covered / total `must_include`, for each condition.
-
-**Pass bar:** WITH the skill covers **>= 80%** of `must_include`; WITHOUT it covers materially
-less (target a >= 30-point absolute gap). If the gap is small, the skill isn't earning its place —
-fix the skill, not the rubric. The brand-grounding STOP and the research-first/CWV/WCAG points are
-the high-signal items most likely to be missing without the skill; weight attention there.
-
-## Notes / honesty
-
-- Triggering is inherently stochastic; that's why we average trials and report a percentage, not a
-  binary. Re-run if results straddle the bar.
-- Keep grading faithful to `SKILL.md` — if a case drifts from the actual description, fix the case.
-- These files document intent and a repeatable procedure; they are **not** wired into CI.

package/skills/design/references/ai-tells.md

@@ -1,75 +0,0 @@
-# AI tells — the ones only a reader can catch
-
-The mechanical tells are **not here**. `scripts/verify.sh` carries a registry of them and
-flags them with file and line, so re-teaching them as prose would be paying twice for the
-same rule. This file holds only what a `grep` cannot decide: presences you have to *look* at
-the page to see.
-
-Part of this corpus is adapted from [Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill)
-(MIT), whose lists came out of real production tests. The split into checkable-vs-judged, the
-thresholds, and the wording are ours.
-
-Every item below is a **default**, overridable by a brief that explicitly asks for it. What
-makes them tells is that they show up *unasked*, as the model's idea of "looking designed".
-
-## Fabricated substance
-
-- **A product UI built out of divs.** A fake task list, fake terminal or fake dashboard
-  assembled from styled rectangles is the single most reliable signature of generated work.
-  Use a real screenshot, a real component, a generated image, or show nothing.
-- **Hand-rolled decorative SVG.** Abstract squiggles and blobs authored inline to fill space.
-  Icons come from a maintained set; decoration comes from a real asset or not at all.
-- **The Jane Doe cast.** "John Doe", "Sarah Chan", egg avatars, `99.99%`, `50%`, round
-  thousands, and startup-slop brand names ("Acme", "Nexus", "SmartFlow"). Real work has
-  specific, slightly awkward names and messy numbers (`47.2%`, not `50%`).
-- **Testimonials nobody said.** A quote with no attributable person, or five quotes with the
-  same cadence, reads as filler. One real quote beats three invented ones.
-
-## Decoration wearing the costume of information
-
-- **Atmospheric locale strips.** A city, a timezone, a temperature in the nav or footer. Only
-  earns its place for a genuinely distributed studio, a travel brand, or a physical venue.
-- **Status dots with no status.** A coloured dot before nav items, list rows or badges. Keep
-  it only where it reports real state, and then only once per section.
-- **Invented photo credits.** `Field study no. 12 · Ines Caetano` under a stock image.
-  Credit a real photographer or write a functional caption.
-- **Pills laid over images.** Tags floated on top of a photo. Either the image speaks alone,
-  or the caption sits below it, outside the frame.
-- **Decoration strips under the hero.** `BRAND. MOTION. SPATIAL.` in small mono caps. Only
-  legitimate when those words are real navigation or real status.
-
-## Labels that say nothing
-
-- **Poetic section labels.** "Field notes", "From the field", "On our desks", "Currently on
-  the bench". Use the functional name ("Testimonials", "Latest writing") or no label.
-- **Generic step labels.** "Stage 1 / Stage 2", "Phase 01 / 02". The step content *is* the
-  label: "Install", "Configure", "Ship".
-- **Mock-humble asides** and micro-meta sentences under a heading ("The list will stay short
-  on purpose"). Eyebrow, headline, body. Nothing else.
-- **"Quietly trusted by".** Say "Used at", "Customers include", or let the logos speak.
-
-## Composition habits
-
-- **Three identical feature cards.** The default feature row. Reach for a two-column zig-zag,
-  an asymmetric grid, or a horizontal rail instead — and do not run the same split three
-  sections in a row.
-- **The corner floater.** A giant left-aligned headline with a small explainer paragraph
-  floating in the section's top-right, aligned to nothing. Stack it, or build a real
-  two-column header.
-- **Rotated vertical text** and crosshair grid lines drawn only to look designed. Both are
-  agency-portfolio clichés unless they organise real content.
-- **A bento with empty cells.** N items means N cells, and at least two cells need real
-  visual variation — otherwise it is a white card grid with extra steps.
-
-## The second default (repetition)
-
-Obeying every rule produces correct pages that all look the same. Before fixing type and
-palette, read the project's recorded design decisions and either reuse them deliberately or
-say why you are departing. Two specific defaults to distrust: reaching for the same display
-serif again, and answering every premium-consumer brief with the beige/brass/oxblood family.
-
-## Surface treatments to distrust by default
-
-Outer glows and neon; pure `#000000` (use an off-black); oversaturated accents that refuse to
-sit with the neutrals; gradient fills on large headings; custom cursors (outdated, hostile to
-accessibility and to performance); glass on every surface rather than on floating ones.

package/skills/design/references/brand-grounding.md

@@ -1,197 +0,0 @@
-# Brand Grounding — Checklist, Question Script & Persistence (visual)
-
-The brand study is the source of truth every design decision is grounded in. This file holds the **completeness checklist** (the visual/design dimensions a brand study must cover before you paint a single pixel), the **question script** (how to interview the user, batched), and the **persistence format** (how to write it into `02-DOCS` and link it from `CLAUDE.md`). The runtime mechanism that invokes this — the hard STOP on an incomplete study — lives in `SKILL.md` under "Brand grounding (read this first)".
-
-This skill **co-owns the brand study with the `marketing` skill**. Marketing owns the *words* dimensions (positioning, audience, value prop, voice & tone, proof, offers, channels, SEO/GEO keywords — see `../../marketing/references/brand-grounding.md`). Design owns the *visual* dimensions below. They write into the **same** `02-DOCS/wiki/brand/` study and the **same** `## Brand & voice` section of root `CLAUDE.md` — never a parallel copy. If marketing already created the study, extend it with the visual articles; do not duplicate the words articles.
-
-## Where the brand study lives
-
-Following the `harness` Karpathy-wiki convention (compiled articles in `wiki/`, immutable raw inputs in `raw/`):
-
-```text
-02-DOCS/
-├── raw/brand/             ← immutable: pasted inputs (screenshots, palettes, competitor lists, mood refs)
-│   ├── inspiration-linear.png
-│   ├── existing-palette.txt
-│   └── …
-└── wiki/brand/            ← compiled brand study, one article per dimension
-    ├── index.md             ← positioning one-liner + links to every dimension article
-    ├── visual-identity.md   ← color (OKLCH), type pairing & scale, logo, radius/shadow/motion personality  [DESIGN]
-    ├── imagery.md           ← photography vs illustration mood, iconography, texture/grain  [DESIGN]
-    ├── layout.md            ← density, composition, dark-mode stance, reference/inspiration sites  [DESIGN]
-    ├── constraints.md       ← accessibility level, performance budget, existing design system/tokens  [DESIGN]
-    ├── audience.md          ← ICP, pains, desires  [MARKETING]
-    ├── value-proposition.md ← value prop, differentiation  [MARKETING]
-    ├── voice.md             ← tone, do/don't word lists, voice samples  [MARKETING]
-    ├── proof.md             ← credibility, metrics, customers  [MARKETING]
-    ├── offers.md            ← offers + primary/secondary CTA  [MARKETING]
-    ├── channels.md          ← active channels  [MARKETING]
-    └── seo.md               ← target keywords  [MARKETING]
-```
-
-Small projects may collapse the visual dimensions into one `visual-identity.md` with each dimension as a `##` heading — but every dimension below must still be present and filled.
-
-## Completeness checklist (visual dimensions)
-
-The visual side of the study is **COMPLETE** only when every dimension below is filled with real, specific content. Any empty, placeholder, or "TBD" dimension = **INCOMPLETE** = hard STOP, interview the user. (The words dimensions are checked by `marketing/references/brand-grounding.md`; design needs the voice/positioning articles present so copy and design agree, but design only *interviews* for the visual gaps.)
-
-- [ ] **V1. Color system** — brand hue(s) and neutrals expressed (or convertible) to OKLCH; a target ramp (50→900); the accent's role; the 60-30-10 intent. Capture any existing hex/brand colors so they can be converted to OKLCH tokens (OKLCH is the source of truth; sRGB hex is an approximation — see `visual-system.md`).
-- [ ] **V2. Typography** — display face + text face (and mono if code is shown), or a single superfamily with weight contrast; the modular scale ratio (e.g. 1.25); any licensed/owned fonts the brand must use. Never three+ families.
-- [ ] **V3. Logo & wordmark** — does one exist? light/dark variants, clear-space, min size, and whether a favicon/app icon is needed. If absent, note it as a gap (`[[NEEDS ASSET]]`) — never invent a logo silently.
-- [ ] **V4. Imagery & illustration mood** — photography vs 3D vs illustration vs abstract; realistic vs stylized; iconography style (line vs filled, corner radius); texture/grain/noise stance. This sets whether the hero shows a product screenshot, a render, or an editorial image.
-- [ ] **V5. Density & personality** — how the surface should *feel*: airy/editorial vs dense/utilitarian; the radius personality (sharp 0–4px vs soft 12px+); shadow personality (flat vs layered elevation); motion personality (still/quiet vs expressive). These become token values.
-- [ ] **V6. Reference / inspiration sites** — 2–5 sites the user loves and *why* (e.g. "Linear for restraint", "Stripe for gradients done right"). These anchor the research-first protocol's archetypes; without them you research blind.
-- [ ] **V7. Layout preferences** — composition leanings (centered hero vs asymmetric/bento vs editorial), max-width feel, any required sections or a sitemap, mobile-first vs desktop-first emphasis.
-- [ ] **V8. Dark-mode stance** — light-only, dark-only, or both with a token-swap; if both, which is the default. (Dark mode via semantic token swap, not per-component overrides — see `visual-system.md`.)
-- [ ] **V9. Accessibility & performance constraints** — target conformance (WCAG 2.2 AA is the floor here; AAA if mandated); Core Web Vitals budget (LCP/INP/CLS); locales/RTL; reduced-motion seriousness; any device/bandwidth constraints.
-- [ ] **V10. Existing design system / tokens** — is there a Tailwind `@theme`, a `tokens.json`, a Figma library, or component kit to extend? Reusing the system beats inventing a parallel one.
-- [ ] **V11. Voice & positioning present (cross-check)** — the marketing-owned `voice.md` and `value-proposition.md` articles exist and are filled, so copy and design agree. If absent, hand off to the `marketing` sibling skill (or interview for them too) — a premium surface with off-voice copy is not premium.
-
-## Question script (ask in batches, never all at once)
-
-Ask **one batch at a time**. Send the batch, wait for the answer, persist what you learned, then send the next batch. Skip questions a located-but-incomplete study already answers — only fill the gaps. Stop interviewing the moment every dimension is complete.
-
-### Batch 1 — references & feel
-
-```text
-1. Show me 2–5 sites or apps whose look you love — and for each, what specifically (the
-   restraint, the type, the color, the motion)? Paste links or screenshots.
-2. In three words, how should this feel? (e.g. calm/editorial, dense/technical,
-   playful/vivid, refined/luxury)
-3. Airy or dense? Should it breathe with whitespace, or pack information tightly?
-4. Light mode, dark mode, or both? If both, which is the default?
-```
-
-### Batch 2 — color & type
-
-```text
-5. Do you have brand colors already? Paste any hex/RGB values, a palette, or a brand guide —
-   I'll convert them to an OKLCH token ramp (I'll save the raw input under 02-DOCS/raw/brand/).
-6. If not: pick a brand hue direction (cool/blue, warm/orange, green, violet, near-neutral)
-   and how saturated it should read (muted vs vivid).
-7. Any required or owned fonts? If not, do you lean geometric-sans, humanist-sans, serif/
-   editorial, or mono-forward (dev tool)?
-8. How loud should the type be — understated, or oversized expressive headlines?
-```
-
-### Batch 3 — assets, imagery & layout
-
-```text
-9. Is there a logo/wordmark? Send light + dark versions if you have them. Need a favicon/app icon?
-10. What imagery direction — product screenshots, photography, 3D renders, illustration, or
-    abstract? Realistic or stylized? Any reference for the icon style?
-11. Radius/shadow/motion personality: sharp & flat, or soft & elevated? Still & quiet, or
-    expressive motion? (I'll bake these into tokens.)
-12. Any must-have sections or a required sitemap? Centered hero or asymmetric/bento?
-```
-
-### Batch 4 — constraints & system
-
-```text
-13. Accessibility target — is WCAG 2.2 AA enough, or is AAA / a specific standard mandated?
-    Any RTL/locale needs?
-14. Performance budget or device constraints I should design within? (slow networks, low-end
-    devices, a hard LCP target?)
-15. Is there an existing design system, Tailwind @theme, tokens.json, or Figma library to
-    extend rather than replace?
-```
-
-If the user can't answer a question, that dimension stays incomplete — note the gap, keep the STOP in place for that dimension, and offer to propose a researched default they can confirm, rather than silently defaulting to your generic prior. **How to actually propose one: `starting-point.md`.** It is the difference between offering something and improvising something: what the project already owns is checked first, the value comes from a reference you opened and measured, and it is written marked `propuesto`. A proposed-and-unconfirmed dimension does **not** count as complete against the checklist above — the STOP stays up until the user confirms it.
-
-## Persistence format
-
-### Visual-identity wiki article template
-
-Each `02-DOCS/wiki/brand/*.md` article follows the harness wiki format. It is an OKF v0.1 article: open it with YAML frontmatter carrying a non-empty `type:` (`brand-study`), then the H1 and body:
-
-```markdown
----
-type: brand-study
-title: Brand — Visual Identity
-description: The visual personality — OKLCH color system, type pairing & scale, and radius/shadow/motion personality.
-tags: [brand, visual-identity, design]
-timestamp: YYYY-MM-DDTHH:MM:SSZ
-topic: brand
-status: stable
----
-
-# Brand — Visual Identity
-
-> Sources: {user interview, YYYY-MM-DD}
-> Raw: [existing-palette](../../raw/brand/existing-palette.txt); [inspiration-linear](../../raw/brand/inspiration-linear.png)
-
-## Overview
-
-One paragraph: the visual personality and the ONE memorable detail.
-
-## Color (OKLCH source of truth)
-
-| Token | OKLCH | Role |
-| --- | --- | --- |
-| brand-500 | oklch(0.62 0.19 256) | primary accent (10% allocation) |
-| bg | oklch(0.99 0 0) | background (light) |
-| fg | oklch(0.21 0.01 256) | foreground |
-
-(Any sRGB hex the user gave is recorded as an approximation, not the source — see `visual-system.md`.)
-
-## Typography
-
-- Display: Geist Semibold · Text: Inter Regular · Mono: Geist Mono (code)
-- Scale ratio: 1.25 (major third), 16px base
-
-## Personality
-
-- Radius: soft (0.875rem cards) · Shadow: layered transparent elevation · Motion: quiet, entry reveals only
-
-## See Also
-
-- [Layout](layout.md)
-- [Constraints](constraints.md)
-```
-
-### Raw inputs
-
-Paste each user-provided input (palette text, competitor list, screenshots saved as files) under `02-DOCS/raw/brand/` with a one-line provenance header on text files:
-
-```markdown
-> Source: user-pasted, YYYY-MM-DD, origin: "current brand guide, page 3 palette"
-
-<the pasted values, unedited>
-```
-
-Binary inputs (screenshots, logo files) go in verbatim and are linked from the article's `> Raw:` line; never compiled or edited.
-
-### CLAUDE.md link
-
-Add (or **extend**, never duplicate) the shared `## Brand & voice` section in the root `CLAUDE.md`. Additive only — never delete existing sections. Create `CLAUDE.md` if absent. If `marketing` already created this section, append the visual links to it rather than writing a second section.
-
-```markdown
-## Brand & voice
-
-Design and marketing/landing copy are grounded in the brand study under
-`02-DOCS/wiki/brand/`. Read it before any user-facing design or copy:
-
-- [Positioning](02-DOCS/wiki/brand/index.md)
-- [Visual identity (color, type, personality)](02-DOCS/wiki/brand/visual-identity.md)
-- [Imagery & illustration](02-DOCS/wiki/brand/imagery.md)
-- [Layout & references](02-DOCS/wiki/brand/layout.md)
-- [Accessibility & performance constraints](02-DOCS/wiki/brand/constraints.md)
-- [Audience](02-DOCS/wiki/brand/audience.md)
-- [Value proposition](02-DOCS/wiki/brand/value-proposition.md)
-- [Voice & tone](02-DOCS/wiki/brand/voice.md)
-
-Raw inputs (palettes, screenshots, voice samples): `02-DOCS/raw/brand/`.
-The `design` skill owns the visual articles; `marketing` owns the words
-articles. Either stops to interview the user if its dimensions are missing.
-```
-
-Also update `02-DOCS/wiki/index.md` (add the new brand articles) and append a one-line entry to `02-DOCS/wiki/log.md` per the harness wiki protocol.
-
-## See Also
-
-- `../SKILL.md` — the runtime grounding mechanism (hard STOP) that uses this checklist.
-- `visual-system.md` — turns the captured color/type/personality into Tailwind v4 `@theme` tokens.
-- `research-method.md` — uses the reference sites (V6) as archetypes for the research loop.
-- `trends-2026.md` — researched defaults to offer when a visual dimension has no user direction.
-- `../../marketing/references/brand-grounding.md` — the co-owned words dimensions (incl. SEO/GEO) of the same study.
-- `../../harness/SKILL.md` — the canonical `02-DOCS` wiki protocol and article templates.