@ericrisco/rsc 1.1.0 → 1.1.1

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.0",
+  "version": "1.1.1",
   "counts": {
     "skills": 278
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/doctor.js

@@ -8,6 +8,7 @@ import { listBackups } from './lib/backups.js';
 import { SDD_GATE_TEXT } from '../targets/hook-once.mjs';
 import { isEnabled, checkSello, readSello, countFindings, readEffectiveConfig, validateRiskConfig } from '../targets/sello.mjs';
 import { designIdentity } from './lib/design-identity.js';
+import { startingPointSummary } from './lib/starting-point.js';
 import { countGaps } from './lib/capabilities.js';
 
 // The sello's health, surfaced where the user already looks (spec: non-blocking
@@ -62,6 +63,10 @@ export function doctor({ target, home, cwd }) {
     // stops without one; until lib/design-identity.js nothing checked it (P2). Reported here,
     // never nagged about and never blocking: a missing identity is low risk (P7).
     designIdentity: designIdentity(root),
+    // The other half of the same question: an identity is what this project settled on, a starting
+    // point is what it has to settle FROM. Three skills promise to propose one and none could look;
+    // this is the look. One field, not a section — a report grows for every user who runs it (P5).
+    designStartingPoint: startingPointSummary(root),
     // An inert gate must never read as an armed one (the same rule the sello follows):
     // the gitmoji guard has a per-project kill switch, so say which state it is in.
     gitmojiGuard: existsSync(join(root, '.rsc', '.no-gitmoji')) ? 'opted-out' : 'armed',

package/scripts/lib/starting-point.js

@@ -0,0 +1,314 @@
+// 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/SKILL.md

@@ -35,6 +35,8 @@ Follow the harness 02-DOCS convention (brand study = wiki articles under `02-DOC
 
 The completeness checklist spans visual identity (OKLCH color system, type pairing & scale, logo, imagery/illustration mood, density, radius/shadow/motion personality), reference/inspiration sites the user loves, layout preferences, dark-mode stance, accessibility & performance constraints, and brand voice/positioning (so copy and design agree). Full checklist + exact question script → `references/brand-grounding.md`.
 
+**When a dimension has no answer** — the non-technical default, and the reason this gate used to be impassable: do not invent one and do not wave the STOP through. `references/starting-point.md` is how a starting point gets proposed instead: what the project already owns is checked first, the value comes from a reference you opened and measured, and it is written marked `propuesto` — which does **not** count as complete until the user confirms it.
+
 The order is: **brand grounding → trend research → build.**
 
 ## Pick a direction first
@@ -66,7 +68,7 @@ Then map the project type to composition, density, and motion budget. Density an
 Trends churn quarterly and your built-in aesthetic prior is the median of every AI template ever scraped. Never prescribe from stale memory; counter it with a loop:
 
 1. Define 2–3 reference archetypes from the DIRECTION BRIEF (e.g. "Linear-grade dev tool, dark, type-led").
-2. WebSearch award galleries and tier-1 product sites: `awwwards.com`, `godly.website`, `land-book.com`, `mobbin.com`, Refactoring UI, and the tier-1 sites (Linear, Stripe, Vercel, Cursor, Resend).
+2. Browse the dated registry in `references/inspiration-sources.md` — whole pages to beat, SaaS and conversion surfaces, real product flows (Mobbin, Page Flows), single patterns, and the design systems that are specification rather than inspiration — plus the tier-1 sites (Linear, Stripe, Vercel, Cursor, Resend). Every entry there carries a verification date; `godly.website` now redirects to `recent.design`, which is exactly why the list is dated and not inline.
 3. WebFetch 3–5 exemplars, prompting each for type, color, layout, motion, and copy voice — concrete details, not adjectives.
 4. Extract a pattern table from what they share and where they differ.
 5. Synthesize a one-paragraph DESIGN DIRECTION with citations (which URL contributed what).

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

@@ -96,7 +96,7 @@ Ask **one batch at a time**. Send the batch, wait for the answer, persist what y
     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 (from the research-first protocol / `trends-2026.md`) they can confirm, rather than silently defaulting to your generic prior.
+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
 

package/skills/design/references/design-systems.md

@@ -39,3 +39,11 @@ Everything in `../SKILL.md` that is not styling: the brand gate, the accessibili
 the Core Web Vitals budget, the 5-second value-prop test, and the tell registry in
 `../scripts/verify.sh`. An official design system settles which components you use. It does
 not settle whether the page says anything.
+
+## Where to browse for component ideas
+
+When a surface needs an idea rather than a primitive, `../../pick-ui-library/references/component-galleries.md`
+names where to go — Aceternity for marketing effects, 21st.dev for breadth, React Bits for tunable
+animation — and what each is good for. Take the technique and rebuild it in this project's tokens;
+check the brand study for what it refuses first, because a component that contradicts a stated ban
+makes the page look less designed, not more.

package/skills/design/references/inspiration-sources.md

@@ -0,0 +1,96 @@
+# Reference — where to go looking for a bar
+
+> Last verified: **2026-08-24**. Every URL below was requested on that date and answered.
+> Four sites block automated requests (403/429) but are alive in a browser — marked *(bot-blocked)*.
+> A source with no date does not exist. Re-check before quoting one as current.
+
+**Go and look.** Your built-in aesthetic prior is the median of every template ever scraped, so the
+fastest way past it is to open real work and name what it does. This file is where to open.
+
+Two rules that make the browsing worth anything:
+
+- **Come back with a specific page, not a gallery.** `../../design-loop/SKILL.md` needs a bar you can
+  open — one URL, one screenshot. "Something like Awwwards" is not a bar; a named site from it is.
+- **Extract principles, not pixels.** "Headline is 8× the body, one accent at 3% coverage" travels to
+  your project. Cloning a competitor's exact grid is theatre, and `research-method.md` says so.
+
+## A whole page to beat
+
+The default bucket. Use it when the goal is a site or landing and you need something to converge on.
+
+| Source | Go here for |
+|---|---|
+| [Awwwards](https://www.awwwards.com) | The award tier. Ambitious, often over-built — take the craft, leave the load time. |
+| [Recent](https://recent.design) | Formerly **Godly**; `godly.website` now 301s here. Curated modern web, strong signal-to-noise. |
+| [SiteInspire](https://www.siteinspire.com) *(bot-blocked)* | Long-running, filterable by style, type and subject. Calmer taste than Awwwards. |
+| [Land-book](https://land-book.com) *(bot-blocked)* | Landing pages at volume, filterable by industry and style. |
+| [Httpster](https://httpster.net) | Opinionated and current, less polished-agency than the rest. |
+| [Minimal Gallery](https://minimal.gallery) | When the brief is restraint and you need proof it can still sell. |
+| [Curated Design](https://curated.design) | Aggregated across galleries — a fast first sweep. |
+| [Nicely Done](https://nicelydone.club) | Real product sites and app UI rather than portfolios. |
+| [Lapa Ninja](https://lapa.ninja) *(bot-blocked)* | Large landing archive, free, categorised. |
+| [One Page Love](https://onepagelove.com) | Single-page sites specifically — the constraint is the point. |
+
+## SaaS and conversion surfaces
+
+| Source | Go here for |
+|---|---|
+| [SaaS Landing Page](https://saaslandingpage.com) | Real SaaS landings, browsable **by section** (hero, pricing, testimonials, footer) — the most useful axis when you are building one section at a time. |
+| [Landingfolio](https://www.landingfolio.com) | Landings and page sections, heavy on conversion patterns. |
+
+## Real product, real flows — not portfolios
+
+The most under-used bucket. Portfolio galleries show the hero; these show what happens after the click.
+
+| Source | Go here for |
+|---|---|
+| [Mobbin](https://mobbin.com) | Screens and full flows from shipped apps, mobile and web. The reference for "how does a real onboarding actually go". |
+| [Page Flows](https://pageflows.com) | Recorded user flows end to end — signup, checkout, cancellation. Video, so you see the motion too. |
+| [Screensdesign](https://screensdesign.com) | Mobile app screens with an emphasis on what is currently shipping. |
+| [Refero](https://refero.design) | UI/UX inspiration organised for browsing by pattern. |
+
+## One section, one pattern
+
+Use when the piece is small and named: `design-loop` splits a goal into three or four pieces, and
+these are for when a piece is "the footer" or "the empty state".
+
+| Source | Go here for |
+|---|---|
+| [Footer.design](https://www.footer.design) | Footers only. Narrow on purpose, and the narrowness is why it is good. |
+| [Collect UI](https://collectui.com) | Daily-UI-style collections by component and pattern. |
+| [UI Garage](https://uigarage.net) | Patterns tagged by element and by industry. |
+| [UI Movement](https://uimovement.com) | Motion and interaction specifically — pair with the frequency gate in `../../animate/SKILL.md` before copying anything. |
+| [Dark.design](https://dark.design) · [Dark Mode Design](https://darkmodedesign.com) | Dark interfaces done properly, which is a different problem from inverting a light one. |
+| [Scrnshts](https://scrnshts.club) | App Store screenshot design — a real discipline of its own. |
+
+## Design systems as the canonical answer
+
+Not inspiration: **specification**. When the question is "what is the correct behaviour for this
+component", these outrank any gallery.
+
+| Source | Go here for |
+|---|---|
+| [Material 3](https://m3.material.io) | Google's system. Exhaustive on states, motion and tokens. |
+| [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) | The reference for platform behaviour and for what *not* to invent on Apple platforms. |
+| [Shopify Polaris](https://polaris.shopify.com) | Dense, commerce-grade product UI with unusually good content guidance. |
+| [IBM Carbon](https://carbondesignsystem.com) | Enterprise density and data-heavy patterns. |
+| [GitHub Primer](https://primer.style) | Developer-tool UI, which is the closest analogue for most rsc projects. |
+| [The Component Gallery](https://component.gallery) *(bot-blocked)* | The same component compared **across** design systems — the fastest way to see the range of correct answers. |
+| [Adele](https://adele.uxpin.com) | Index of public design systems and their pattern libraries. |
+| [Designsystems.com](https://www.designsystems.com) | Essays on building and maintaining a system, not a system itself. |
+
+## Niche, but the right answer when it fits
+
+| Source | Go here for |
+|---|---|
+| [Interface In Game](https://interfaceingame.com) | Game UI. Useful well beyond games for diegetic and high-density HUD ideas. |
+| [Mobile.design](https://mobile.design) | Mobile-first patterns collected on their own terms. |
+
+## Housekeeping
+
+- **[Bestfolios](https://www.bestfolios.com) returned 502 on 2026-08-24** and is excluded until it
+  comes back. Do not cite it.
+- **Component ideas**, as opposed to whole pages, live in
+  `../../pick-ui-library/references/component-galleries.md` — Aceternity, 21st.dev, React Bits.
+- **Identity outranks all of this.** Check `02-DOCS/wiki/brand/` for what the project refuses before
+  bringing an idea back. A gallery cannot know what your brand vetoed.

package/skills/design/references/research-method.md

@@ -145,3 +145,10 @@ When the direction changes mid-project (new competitor, pivot), re-run the loop
 - `visual-system.md` — turn the filled direction into tokens.
 - `../../nextjs/SKILL.md` — implement the chosen direction on the App Router stack.
 - *frontend-design-direction* — product-domain direction judgment (external reference, not a repo skill).
+
+## Where to look
+
+`inspiration-sources.md` is the dated registry of where to browse: whole pages to beat, SaaS and
+conversion surfaces, real product flows (Mobbin, Page Flows — the bucket most people skip), single
+patterns like footers and empty states, and the design systems that are specification rather than
+inspiration. Extract principles, not pixels, and come back with a named page rather than a gallery.

package/skills/design/references/starting-point.md

@@ -0,0 +1,75 @@
+# Reference — proposing a starting point
+
+Three places promise to propose one: `../../design-loop/SKILL.md` phase 1 when the user says *skip*,
+the closing line of `brand-grounding.md` when a visual dimension has no direction, and
+`../../design-dna/SKILL.md`'s REUSE mode. This file is what they propose *from*. Without it the
+fallback is your own prior, which is the AI-template median — the thing the whole area exists to escape.
+
+## 0. What the project already owns wins
+
+**Look before you offer.** Run it; do not reason about it:
+
+```bash
+npx @ericrisco/rsc doctor --json   # read `designStartingPoint`
+```
+
+| State | What it means | What you do |
+| --- | --- | --- |
+| `owned` | An identity article or at least one legible style record exists | Propose **that**, by name, first. Offer nothing external until the user rejects it. More than one record → all of them are candidates, ordered as reported. Never pick one silently. |
+| `none` | Looked in both scopes, found nothing | Go to §1. |
+| `inconclusive` | Something could not be read | Say what, and ask for another route to it. **Do not propose past a blind spot** — a proposal made without looking is the defect this file exists to remove. |
+
+If the owned identity **contradicts** what the user is now asking for, name the conflicting rule and let
+them decide which wins. Same rule the loop's preflight already applies to a bar from outside.
+
+A record that `doctor` reports with a pair below its contrast floor is not offered as a starting point.
+
+## 1. What are you building → which bar
+
+At most **three** candidates. Each one gets a name, one line on why it fits *this* product, and one line
+on when it would be the wrong choice. Then **wait**. No answer → take the most demanding one and say so.
+
+Sources are in `inspiration-sources.md`; the tier-1 set and the dated-looking list are in
+`trends-2026.md`. **Only propose what you can actually open** — that registry marks several sources as
+bot-blocked, and a bar that cannot be fetched dies in the loop's preflight.
+
+| Building | Candidate bars | Wrong choice when |
+| --- | --- | --- |
+| SaaS marketing | Stripe · [SaaS Landing Page](https://saaslandingpage.com) browsed by section · Linear | The product is a daily tool, not a purchase decision — a marketing skin on a workhorse |
+| Dev tool | Linear · Vercel · Resend · [Primer](https://primer.style) | The audience is not technical: dev-tool restraint reads as unfinished to them |
+| Dashboard / internal tool | [Carbon](https://carbondesignsystem.com) · [Polaris](https://polaris.shopify.com) · [Mobbin](https://mobbin.com) flows | It is a landing page with a chart on it — density is not the job |
+| Portfolio / editorial | [Awwwards](https://www.awwwards.com) · [Recent](https://recent.design) · [One Page Love](https://onepagelove.com) | Anything with a conversion target: award craft routinely costs LCP and the 5s test |
+| E-commerce | [Minimal Gallery](https://minimal.gallery) for restraint · [Nicely Done](https://nicelydone.club) for real product surfaces | The catalogue is huge and the real problem is search and filtering, not the hero |
+| Docs | [Stripe docs](https://docs.stripe.com) · [Material 3](https://m3.material.io) on states | Reading is not the job — it is a reference table, so density beats calm |
+
+Nothing here fits what they are building? **Say so and interview.** Do not stretch the nearest row: a bar
+chosen because it was closest is the vague bar that makes the loop approve everything on round one.
+
+## 2. A proposal is not an answer
+
+1. **Open the reference.** No value is proposed from a page you did not fetch. Blocked → say so, pick
+   another. Never substitute a description from memory.
+2. **Measure it** — the loop's teardown already does this and writes 5 to 7 mechanisms. Those measured
+   values *are* the researched default this file was missing. They are not invented, and they come from
+   a page that already ships.
+3. **Check colour before writing it.** Any text pairing must measure **≥ 4.5:1** (≥ 3:1 for large text
+   and UI). Below that, it is **not proposed** — not proposed-with-a-warning.
+4. **Write it marked `propuesto`, naming the reference it came from.** Never as a confirmed value.
+5. A dimension that is proposed and not yet confirmed **does not count as complete** against
+   `brand-grounding.md`'s checklist. The hard STOP stays up for it. Otherwise the prefill becomes the
+   way to cross the gate with nobody having confirmed anything.
+6. Only what the user confirms becomes the project's identity.
+
+## 3. The base is the floor, not the concept
+
+A starting point gets you a defensible floor in one exchange. It does **not** satisfy the ONE signature
+element (`signature-and-craft.md` §2), and it never will: every project that picked the same bar would
+converge on the same page. If the only thing making this surface distinctive is the bar it started from,
+there is no concept yet.
+
+## See Also
+
+- `inspiration-sources.md` — the source registry, dated, with the bot-blocked entries marked.
+- `trends-2026.md` — the tier-1 set, and what currently reads as a template.
+- `brand-grounding.md` — the checklist this fills in, and the STOP it does not lift.
+- `signature-and-craft.md` — the part a starting point cannot give you.

package/skills/design-dna/SKILL.md

@@ -25,6 +25,10 @@ Nobody wrote down **why** the winner was beautiful. Next time you ask for "the s
 
 If a `dna.json` already exists for the style named, you are in REUSE. Never re-derive a style that has a record.
 
+To find out which records exist — in either scope, without guessing at paths — run
+`npx @ericrisco/rsc doctor --json` and read `designStartingPoint`. A record it reports as `unreadable`
+is **not** a record you can reuse: say what is missing, do not use half of one.
+
 ## Hard rules (these are the skill)
 
 1. **A specification that cannot fail is not a specification.** If every rule you wrote is one a bad output could still satisfy, you wrote a mood board.

package/skills/design-loop/SKILL.md

@@ -34,7 +34,15 @@ website", "good SaaS design"), push once for the specific page or file: a critic
 reference invents the comparison and approves everything on round one.
 
 On *skip*, propose three candidate bars, one line each on why, and wait. No answer → take the
-hardest one and say so.
+hardest one and say so. **Where they come from:** `../design/references/starting-point.md` — run its
+step 0 first, because a bar the project already owns outranks anything you would pick from outside,
+and proposing from memory is how this promise used to resolve to the AI-template median.
+
+**Where to go looking.** For a whole page to beat, and for the flows and single patterns behind it:
+`../design/references/inspiration-sources.md`. For a component idea rather than a whole reference:
+`../pick-ui-library/references/component-galleries.md`. Browse for the technique, never to clone a
+competitor's exact grid — and come back with **a specific page you can open**, because a gallery
+is not a bar.
 
 ## Phase 2 — Preflight
 

package/skills/pick-ui-library/SKILL.md

@@ -27,6 +27,7 @@ A lookup skill. When invoked with a task ("I need toasts", "what should I use fo
 2. **Check what's already installed.** Look at `package.json` first. If the project already uses a listed library, use it. If it uses a competitor (e.g. react-window instead of Virtuoso), flag the recommendation but don't churn the dependency without being asked.
 3. **Recommend one library**, state what it's for in one sentence, and install/wire it up if that's part of the request. Don't present a menu of options when the list has a clear answer.
 4. If the task isn't covered by the list, say so explicitly and recommend from your own knowledge — but be clear you've left the curated list.
+5. **Need an idea rather than a library?** Go and look: `references/component-galleries.md` names where to browse for component ideas (Aceternity for marketing effects, 21st.dev for breadth, React Bits for tunable animation) and what each is good for. Take the technique, build it in the project's own tokens.
 
 ## The list
 

package/skills/pick-ui-library/references/component-galleries.md

@@ -0,0 +1,59 @@
+# Reference — where to go looking for component ideas
+
+> Last verified: **2026-08-24** — all three returned HTTP 200 on that date.
+
+**Go and look.** When you need a component idea and your own prior is the median of every AI template
+ever scraped, these are the places to browse instead of inventing from memory. Open them, see what
+exists, come back with something specific.
+
+## Where to go, and for what
+
+### [Aceternity UI](https://ui.aceternity.com/components) — effects for a surface that must stop the scroll
+
+Go here for **motion and atmosphere on a marketing surface**, not for primitives. What's there:
+
+- **Backgrounds:** Aurora, Beams, Vortex, Sparkles, gradient fields
+- **Cards:** 3D tilt, hover reveal, card stack, spotlight
+- **Text:** typewriter, flip, encrypted/scramble, generate-in, canvas text
+- **Scroll:** sticky scroll, container scroll, hero parallax
+- **Navigation:** floating navbar, floating dock, sidebar, notch, tabs
+- **Buttons:** magnetic, moving border, hover gradient
+- **Data as spectacle:** globe, timeline, world map, before/after compare
+- **Whole sections:** hero, pricing, testimonials, CTA, feature blocks
+
+Best used when you can name the feeling you want and need to see how someone already built it.
+
+### [21st.dev](https://21st.dev/community/components) — breadth, ranked by what people actually use
+
+A community registry rather than a curated library, so it's the widest net of the three. Marketing
+blocks *and* real UI — buttons, cards, forms, modals, inputs, tables — plus Shaders and ASCII art.
+Sortable by popular and newest, with view counts.
+
+Go here when you don't know what you're looking for yet and want to see the range. Read the code of
+anything you like: community means unvetted, and popularity is not review.
+
+### [React Bits](https://reactbits.dev/get-started/index) — animated interactions, deeply customizable
+
+~46k stars. Animations, 3D, CSS effects, built to be tuned rather than dropped in.
+
+Go here when Aceternity's version of an effect is close but you need to control it.
+
+## Two things to carry with you
+
+**Ideas travel; code stays there.** Take the technique, the ratio, the interaction — then build it in
+the project's own tokens. Never vendor a gallery's source into this catalog: rsc ships publicly (P9),
+and React Bits' licence (MIT + Commons Clause) forbids redistributing its components outright. In the
+user's own project, installing any of the three is fine.
+
+**Identity outranks the gallery.** Check `02-DOCS/wiki/brand/` for what this project refuses before
+pulling an idea. A lot of what these galleries do best — aurora and gradient-mesh backgrounds,
+glassmorphism, neon, blobs, decorative 3D — is also on the AI-tell list in
+`../../design/references/ai-tells.md`, and some brand studies veto it by name. And run the frequency gate
+from `../../animate/SKILL.md`: a spotlight card earns its place on a hero someone sees once, and never on
+a table they open forty times a day.
+
+## Not a substitute for the primitives
+
+A dialog still comes from `base-ui`, a toast from Sonner, a command palette from cmdk. Focus trapping,
+dismissal and accessibility are solved; an animated card does not replace a solved primitive. Use
+`SKILL.md`'s list for the task, and this file for the look.