@ericrisco/rsc 1.0.33 → 1.1.0

package/skills/design-loop/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: design-loop
+description: "Use when something must be built well and there is a real reference it should beat: turn what makes the reference good into measured mechanisms, then run a builder and three fresh-context critics until all three pass. Fires on 'design loop', 'make it as good as <site>', 'it looks generic'. NOT keeping an already-won look (that is `design-dna`)."
+tags: [design, critique, loop, reference, quality, convergence]
+recommends: [design, design-dna, marketing, nextjs]
+origin: risco
+---
+
+# Design Loop — the front door of the design area
+
+*A reference you can open, mechanisms you can check, and three judges who did not build the thing.*
+
+This is where a design request **enters**. It owns the method: the bar, the judges, the rounds. It
+does not own the visual system — `../design/SKILL.md` does, and this skill invokes it as the builder.
+
+**Why the method and not a rubric.** A rubric scored by whoever built the piece measures *intent*,
+because the builder knows what they were going for and so they see it there. And scores drift upward
+every round: a 7 that becomes an 8 with nothing changed is how a loop declares itself finished early.
+Binary verdicts from someone who did not build it are the fix for both.
+
+Four phases. Do not skip ahead, and do not start building during 1 to 3.
+
+## Phase 1 — Interview
+
+Ask exactly these three, together, then stop and wait.
+
+1. What are you building, and how long or how big?
+2. Name something that already does this brilliantly — a site, a video, a doc, anything I can open.
+   If nothing comes to mind, say skip.
+3. Any files I should work from? Design system, brand doc, script, existing draft.
+
+**A vague bar is the number one reason this method fails.** If they name something vague ("Apple's
+website", "good SaaS design"), push once for the specific page or file: a critic with no concrete
+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.
+
+## Phase 2 — Preflight
+
+A check, not a question. Run it before any work and report in one block.
+
+- **Fetch the bar now.** Screenshot the URL or read the file. Blocked or missing → say so, ask for
+  another. Never substitute a description from memory.
+- **Confirm you can render our output**: screenshots for a site, a filmstrip for animation, a PDF
+  render for a doc.
+- **Name the generation tools the goal needs** (image, video, voice) and confirm they are connected.
+- **Confirm the input files exist**: design system, brand doc, script.
+- **Read the harness identity if it exists** — `02-DOCS/wiki/brand/`, reached from the root
+  `CLAUDE.md` `## Brand & voice` section, the same place `design`, `marketing` and
+  `presentations` read. A bar from outside cannot silently overrule the identity this project
+  already committed to: if the reference contradicts it, say which rule conflicts and let the
+  user decide which one wins. If no identity exists yet, say so — this run is what creates it.
+
+Then print what is working, what is missing, and **which critic goes blind** if something is
+missing. Never carry on quietly with a critic that cannot see — a verdict from a judge who cannot
+see the thing is worse than no verdict, because it looks like evidence.
+
+## Phase 3 — Teardown
+
+Read the reference properly and write **5 to 7 mechanisms** to `bar.md`.
+
+Mechanisms, not adjectives. "Feels premium" is useless. These are useful:
+
+- headline is 5x body size, three type sizes total
+- one accent colour, used at most twice per screen
+- motion always resolves in one direction
+- nothing animates for under 400ms
+- whitespace above the fold is at least 40% of the frame
+
+Every line must be something a critic can check by looking. Show `bar.md` to the user before
+continuing — and where a mechanism contradicts the harness identity, mark the conflict rather
+than resolving it silently in favour of the reference.
+
+## Phase 4 — Loop
+
+Split the goal into the smallest pieces that can be improved and judged on their own. You choose
+them. Keep it to three or four unless told otherwise: **every extra piece multiplies the run, and so
+does every extra round.**
+
+For each piece: fan out a builder, then three critics, each with fresh context and no knowledge of
+how the builder worked.
+
+- **Brief critic** — judges against the stated goal only. Does it do the thing? Ignore aesthetics.
+- **System critic** — judges against the project's design system only. Objective adherence.
+- **Craft critic** — judges against `bar.md` and rendered output only. Put ours next to the
+  reference blind, labels stripped, say which is better, name the single biggest gap.
+
+Write each critic's brief yourself, adapted to this goal. Do not reuse generic wording across
+different goals.
+
+### Rules
+
+- **Critics judge rendered output, never the code.** Reading the implementation makes a critic
+  evaluate intent instead of result.
+- **Binary verdicts, not scores.** Scores drift upward every round.
+- **Critics are harsh, and harshness has a floor.** A critic has explicit permission to say a piece
+  passes. A judge under standing orders to find fault will manufacture one, and then "all three must
+  pass" is a door that recedes as you approach it.
+- **All three must pass.** Any fail goes back to the builder with the single biggest gap named — one,
+  not a list.
+- **No fixed round count.** The exit is winning, or the user stopping the run, or the halt below.
+
+### The halt — how this loop is allowed to end
+
+Fresh-context critics cannot see the gap history, so nothing arbitrates across rounds. Left alone,
+two incompatible gaps ("more air" / "more density") make the builder ping-pong forever, and the only
+brake is a human watching. Keep the gap history and use it:
+
+> **The same biggest gap named twice for the same piece halts that piece.** Put the two competing
+> demands side by side and ask the user to decide. Do not spend a third round on it.
+
+This is not a nicety. A loop whose declared exit is "all three pass" and which cannot detect that it
+will never get there is a gate that cannot close.
+
+### Progress and cost
+
+Keep a live progress page: piece status, each critic's verdict, gap history, round count.
+
+There is **no reliable self-reported token cost, so do not show one.** Show round count and pieces
+instead. If the user names a ceiling, treat it as a checkpoint: pause and ask before passing it, and
+tell them plainly that the real brake is them watching and stopping the run.
+
+## When the piece wins
+
+Hand the winner to `../design-dna/SKILL.md` to codify it: measured ratios, bans and tests that can
+fail, so piece eight still sits beside piece one as a set. Winning once and not writing down why is
+how the look drifts back to generic by the fifth piece.
+
+## What breaks this
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Everything approved on round one | Vague bar | Push for the specific page or file |
+| Approvals that do not survive a second look | Builder judged its own work | Critics need fresh context |
+| Verdicts creep upward each round | Scores instead of binaries | Binary job, not a score |
+| Loop never exits | No halt on a repeated gap | Apply the halt above |
+| Loop exits with the piece still weak | Fixed round count | The exit is winning |
+| Obeys the letter, misses the point | Over-specifying | Every extra instruction is one fewer decision the model makes with its own judgment |
+
+## Hand-offs
+
+- **The visual system, brand grounding, page composition** → `../design/SKILL.md`. It is the builder
+  this loop invokes; it stays reachable directly when there is no bar to beat and no loop to run.
+- **Codifying the winner into a permanent identity** → `../design-dna/SKILL.md`.
+- **The words** → `../marketing/SKILL.md`. **The build** → `../nextjs/SKILL.md`.
+- **Motion craft, and routing among the frontend craft siblings** → `../design-eng/SKILL.md`.
+- **"Show me a few versions and I'll pick"** → `../prototype/SKILL.md`. That is selection among
+  variants; this is convergence against a bar.
+- **SDD gate.** This skill runs a method; it does not outrank the chain. If the request is a new
+  feature or a non-trivial behaviour change in a real app, `../specify/SKILL.md` runs first, then
+  `plan`, then the loop builds what was approved.

package/skills/design-loop/evals/README.md

@@ -0,0 +1,56 @@
+# Eval harness — `design-loop` skill
+
+Agent-run eval, not a shell script. The cases in `cases.yaml` are fed to a Claude Code agent and
+graded by inspection. 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 loop fire when a goal comes with a real reference to beat, and stay
+   quiet on the near-misses that belong to a sibling? The expensive confusions are `design` (visual
+   system, no bar), `prototype` (variants picked by preference, no bar) and `design-dna` (the winner
+   already exists).
+2. **Capability** — when it fires, does it hold the three phases it is easiest to skip, and does its
+   loop actually terminate?
+
+## A. Triggering accuracy
+
+Run each `should_trigger` prompt in a session with the skill installed. It must activate. Run each
+`should_not_trigger` prompt: it must stay quiet and the named `route_to` sibling must be the one that
+answers.
+
+The two cases worth watching, because they are where the boundary really is:
+
+- *"Show me three versions and I'll pick"* → `prototype`. Selection is not convergence. The user is
+  the judge and no bar exists.
+- *"Codify this into a reusable style"* → `design-dna`. Nothing left to converge; this is the
+  downstream half.
+
+## B. Capability
+
+The three scenarios are the three things this skill exists to do and the three it is cheapest to
+fake:
+
+1. **The vague bar and the blind critic.** A bar of "Apple's website" must be pushed back on once,
+   and a missing render capability must be declared as *which critic goes blind* — not absorbed
+   silently. A critic that cannot see, still voting, is the failure this phase prevents.
+2. **Termination.** The scenario hands it an oscillation: air, then density, then air again. The
+   skill must halt the piece and surface the two competing demands. **This is the case that matters
+   most**: everything else in the skill is judgement, but a loop that cannot detect it will never
+   converge is a gate that cannot close, and the constitution's P2 forbids exactly that.
+3. **Hand-off on winning.** Four more pages after a win must go through `design-dna`, not four more
+   loops. Re-deriving a style you already won is how the set stops looking like a set.
+
+## Grading
+
+A case passes when every `must_include` line is observably present in the agent's output or actions.
+Partial credit is not useful here: the mechanisms are the skill, and a run that keeps the prose but
+drops the halt has kept the part that costs nothing.
+
+## Known limits of this eval
+
+- **Scores vs binaries** and **critics judging rendered output only** are properties of a real
+  multi-round run. A single-turn eval can check that the skill *states* them; it cannot prove a
+  four-round run honoured them. Verifying that needs a live run against a real reference.
+- The halt is checked from a described history, not a real one. It tests the rule, not the
+  bookkeeping that feeds it.

package/skills/design-loop/evals/cases.yaml

@@ -0,0 +1,60 @@
+skill: design-loop
+
+should_trigger:
+  - prompt: "Build me a landing page for our analytics product that's as good as linear.app — here's the URL."
+    why: "Goal plus a named, openable reference to beat. This is the skill's core shape: a bar exists and the work must clear it."
+  - prompt: "Our homepage looks generic. Loop it against stripe.com until it actually wins."
+    why: "'Looks generic' plus a named bar plus explicit looping — three of the skill's stated triggers in one sentence."
+  - prompt: "/design-loop"
+    why: "Explicit invocation by name; the skill must run its own interview rather than asking what the user wants in free form."
+  - prompt: "I want a pitch deck that holds up next to this one — attaching their PDF."
+    why: "Non-obvious because the medium is not web. The method is medium-agnostic: a deck with an openable reference is the same loop, and the craft critic renders to PDF instead of screenshots."
+  - prompt: "Run the critic loop on the pricing page and don't stop until it beats the reference."
+    why: "Names the mechanism (critic loop) and the exit condition (beating the reference) rather than the outcome."
+  - prompt: "Quiero que esta página le gane a la de vercel. Dale vueltas hasta que gane."
+    why: "Non-English phrasing with no keyword overlap with the description; the trigger is the semantic shape — a reference to beat plus iteration until it wins."
+  - prompt: "This animation feels cheap compared to the one on their site. Can you get it to that level?"
+    why: "Non-obvious: reads like a motion request, but a named reference plus a quality gap is a bar to converge against. The loop owns convergence and hands the motion implementation to the craft siblings."
+
+should_not_trigger:
+  - prompt: "This page came out great. Codify it into a reusable style so my next five pages match it."
+    route_to: "design-dna"
+    why: "The winner already exists; nothing left to converge. Capturing an identity is the downstream half of the pipe, not the loop."
+  - prompt: "Pick a colour palette and type pairing for my product and give me the Tailwind tokens."
+    route_to: "design"
+    why: "Visual system work with no reference to beat and nothing to judge. `design` stays directly reachable exactly for this."
+  - prompt: "Show me three versions of this button and I'll pick the one I like."
+    route_to: "prototype"
+    why: "Selection among variants by human preference, not convergence against a measured bar. The user is the judge and there is no reference."
+  - prompt: "Review the motion in this diff and tell me what's off."
+    route_to: "review-animations"
+    why: "One diff, motion-specific, no reference and no build-then-judge rounds. Reviewing is not looping."
+  - prompt: "Write the hero headline and value prop for our developer-tool site."
+    route_to: "marketing"
+    why: "The words, not the bar. `voice` constrains copy in this pipe; it does not write it."
+  - prompt: "Set up the Next.js App Router routing and server actions for these pages."
+    route_to: "nextjs"
+    why: "Pure build mechanics with no design judgement involved at all."
+
+capability:
+  - scenario: "User asks: 'Make our homepage as good as Apple's website.' (Vague bar. The repo has a design system at design-system.md but no way to render output to screenshots.)"
+    must_include:
+      - "Pushes back ONCE for the specific page or file rather than accepting 'Apple's website' — names that a vague bar is the top failure mode because a critic with no concrete reference invents the comparison and approves everything on round one."
+      - "Runs preflight BEFORE any work and reports it as one block: fetches the bar, checks render capability, checks input files."
+      - "Explicitly names that the CRAFT critic goes blind because output cannot be rendered — does not quietly proceed with three critics when only two can see."
+      - "Does not start building during the interview, preflight or teardown phases."
+      - "Writes 5-7 mechanisms to bar.md as checkable measurements (ratios, coverage, percentages, absences) and shows them to the user before continuing; rejects adjectives like 'feels premium' as mechanisms."
+      - "Uses binary verdicts, never numeric scores, and states that scores drift upward every round."
+      - "Keeps critics on rendered output only, never the implementation, and gives each fresh context with no knowledge of how the builder worked."
+  - scenario: "The loop is running on a hero section. Round 2's craft critic names 'not enough breathing room above the fold' as the biggest gap. Round 3's craft critic names 'the hero feels empty, needs more density' as the biggest gap. Round 4 would name 'not enough breathing room' again."
+    must_include:
+      - "HALTS that piece instead of starting another round — detects that the same biggest gap has been named twice for the same piece."
+      - "Puts the two competing demands side by side (more air vs more density) and asks the user to decide, rather than picking one itself or averaging them."
+      - "Does not present the halt as a failure of the loop; it is the declared exit for non-convergence."
+      - "Shows round count and pieces rather than claiming a token cost, and states that no reliable self-reported token cost exists."
+      - "Keeps the gap history that made the detection possible, as part of the live progress page."
+  - scenario: "A piece has cleared all three critics and the user says 'perfect, now do the other four pages'."
+    must_include:
+      - "Hands the winner to design-dna to codify it into a permanent identity before building the remaining pieces, rather than re-running the loop from scratch four more times."
+      - "Names why: winning once without writing down the mechanisms is how the look drifts back to generic by the fifth piece."
+      - "Does not merge the won style with any other identity."

package/skills/review-animations/SKILL.md

@@ -135,3 +135,54 @@ Adapted for the rsc catalog from **[emilkowalski/skills](https://github.com/emil
 [Sonner](https://sonner.emilkowal.ski), [Vaul](https://vaul.emilkowal.ski) and
 [animations.dev](https://animations.dev). The craft bar here is his; the routing, gates and evals
 that make it an rsc skill are not. Nothing in this body is a substitute for his course.
+---
+
+# Craft reference, inherited from the umbrella
+
+*Moved here from `design-eng` (spec: `design-area-cleanup`), which routes and no longer teaches.
+This is the same material by the same author; where it overlaps a rule stated above, the above is
+the summary and this is the reasoning.*
+
+## Review Format (Required)
+
+When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:
+
+| Before | After | Why |
+| --- | --- | --- |
+| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
+| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
+| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
+| No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
+| `transform-origin: center` on popover | `transform-origin: var(--transform-origin)` | Popovers should scale from their trigger (not modals — modals stay centered) |
+
+Wrong format (never do this):
+
+```
+Before: transition: all 300ms
+After: transition: transform 200ms ease-out
+────────────────────────────
+Before: scale(0)
+After: scale(0.95)
+```
+
+Correct format: A single markdown table with | Before | After | Why | columns, one row per issue found. The "Why" column briefly explains the reasoning.
+
+## Review Checklist
+
+When reviewing UI code, check for:
+
+| Issue                                      | Fix                                                              |
+| ------------------------------------------ | ---------------------------------------------------------------- |
+| `transition: all`                          | Specify exact properties: `transition: transform 200ms ease-out` |
+| `scale(0)` entry animation                 | Start from `scale(0.95)` with `opacity: 0`                       |
+| `ease-in` on UI element                    | Switch to `ease-out` or custom curve                             |
+| `transform-origin: center` on popover      | Set to trigger location or use Base UI's `var(--transform-origin)` (modals are exempt — keep centered) |
+| Animation on keyboard action               | Remove animation entirely                                        |
+| Duration > 300ms on UI element             | Reduce to 150-250ms                                              |
+| Hover animation without media query        | Add `@media (hover: hover) and (pointer: fine)`                  |
+| Keyframes on rapidly-triggered element     | Use CSS transitions for interruptibility                         |
+| Framer Motion `x`/`y` props under load     | Use `transform: "translateX()"` for hardware acceleration        |
+| Same enter/exit transition speed           | Make exit faster than enter (e.g., enter 2s, exit 200ms)         |
+| Elements all appear at once                | Add stagger delay (30-80ms between items)                        |
+
+---