@ericrisco/rsc 3.1.3 → 3.3.0

package/skills/design-dna/templates/SKILL.md.tmpl

@@ -1,42 +0,0 @@
----
-name: __SLUG__
-description: "Use when building anything in the __NAME__ style: __ONE_LINE__ Fires on '__SLUG__', 'in the __NAME__ style', 'another one like <reference>', 'same look as before'. Captured from __MEDIUM__; drives any format. NOT inventing a new direction (that is `design`), NOT re-deriving this style (its record already exists in dna.json)."
-tags: [style, design-dna, __SLUG__]
-recommends: [design-dna, nextjs, marketing]
-origin: design-dna
----
-
-# __NAME__
-
-*__ONE_LINE__*
-
-Captured __CAPTURED__ from __MEDIUM__. Reference kept in `reference/`. Worked proof in `example/`.
-
-## How to use this
-
-1. Load **`PROMPT.md` only**, and attach `reference/__REF__`. Never paste `dna.json` into a prompt: it is the record, not the payload, and its size is exactly what breaks compliance.
-2. Pick an archetype by name before writing a line. Structure first, or piece 8 will not sit beside piece 1 as a set.
-3. Build. Web build goes to `../nextjs/SKILL.md`, words to `../marketing/SKILL.md`; the identity stays here.
-4. Run the self-check. Name every test and its result:
-
-       python3 scripts/check.py <output files or a rendered PNG>
-
-   Non-zero exit means do not ship. Answer the MANUAL tests out loud.
-
-## What this style is, in one screen
-
-__SUMMARY__
-
-## Do not
-
-__BANS__
-
-## Known drift risks
-
-__CONFIDENCE__
-
-These are the values that were inferred rather than measured. If output starts feeling off, re-measure these first.
-
-## Maintenance
-
-Re-capture only when the reference itself changes. To extend the style, edit `dna.json`, then recompile `PROMPT.md` under the 2KB cap: adding a signature means deleting one. Method and rationale: `../design-dna/SKILL.md`.

package/skills/design-dna/templates/check.py.tmpl

@@ -1,143 +0,0 @@
-#!/usr/bin/env python3
-"""Auto tests for the __NAME__ style. Exits non-zero on any failure.
-
-    python3 scripts/check.py <output.html|output.css|output.png> [more files...]
-
-Reads dna.json and runs every test marked "auto": true that carries a "probe".
-Tests without a probe are reported as MANUAL and never silently pass.
-A probe handed no artefact it can read is reported as SKIP with its reason -
-never as PASS or FAIL.
-
-Probe kinds
------------
-regex_absent        {"kind":"regex_absent","pattern":"..."}                 fails if the pattern appears
-regex_count         {"kind":"regex_count","pattern":"...","exactly":1}      or "min"/"max"
-distinct_css        {"kind":"distinct_css","property":"font-size","max":3}  distinct declared values
-css_ratio           {"kind":"css_ratio","property":"font-size","min":6.0}   largest / smallest declared
-min_unit            {"kind":"min_unit","property":"font-size","min_px":28}  smallest declared value
-color_coverage      {"kind":"color_coverage","hex":"#ff4d00","max_pct":8,
-                     "tolerance":24}                                        needs an image file + Pillow
-"""
-import json, os, re, sys
-
-HERE = os.path.dirname(os.path.abspath(__file__))
-DNA_PATH = os.path.join(HERE, "..", "dna.json")
-if not os.path.isfile(DNA_PATH):
-    sys.exit("no dna.json beside this script, so there is nothing to check against.\n"
-             "This style skill was scaffolded and never finished. Fix:\n"
-             "  write dna.json, then validate it with\n"
-             "  python3 ../design-dna/scripts/emit.py <slug> --validate")
-DNA = json.load(open(DNA_PATH))
-
-TEXT_EXT = {".html", ".htm", ".css", ".scss", ".jsx", ".tsx", ".svg", ".md", ".js", ".ts"}
-IMG_EXT = {".png", ".jpg", ".jpeg", ".webp"}
-
-
-def load(paths):
-    text, images = "", []
-    for p in paths:
-        ext = os.path.splitext(p)[1].lower()
-        if ext in IMG_EXT:
-            images.append(p)
-        elif ext in TEXT_EXT or os.path.isfile(p):
-            text += "\n" + open(p, encoding="utf-8", errors="replace").read()
-    return text, images
-
-
-def css_values(text, prop):
-    out = []
-    for raw in re.findall(rf"{re.escape(prop)}\s*:\s*([^;}}\"']+)", text, re.I):
-        m = re.match(r"\s*(-?[\d.]+)\s*(px|rem|em|pt|%)?", raw)
-        if not m:
-            continue
-        n = float(m.group(1))
-        unit = (m.group(2) or "px").lower()
-        out.append(n * 16 if unit in ("rem", "em") else n)
-    return out
-
-
-def coverage(path, hex_target, tol):
-    try:
-        from PIL import Image
-    except ImportError:
-        return None, "Pillow not installed (pip install pillow)"
-    tr, tg, tb = (int(hex_target.lstrip("#")[i:i + 2], 16) for i in (0, 2, 4))
-    im = Image.open(path).convert("RGB")
-    im.thumbnail((400, 400))
-    px = list(im.get_flattened_data()) if hasattr(im, "get_flattened_data") else list(im.getdata())
-    hit = sum(1 for r, g, b in px if abs(r - tr) <= tol and abs(g - tg) <= tol and abs(b - tb) <= tol)
-    return 100.0 * hit / max(1, len(px)), None
-
-
-# Probes that read declared values. Handed no text they must SKIP: a regex over an empty
-# string is not a check, and calling it PASS or FAIL is the gate lying in one direction
-# or the other.
-TEXT_PROBES = ("regex_absent", "regex_count", "distinct_css", "css_ratio", "min_unit")
-
-
-def run(test, text, images):
-    pr = test.get("probe")
-    if not pr:
-        return "MANUAL", "no probe declared"
-    k = pr.get("kind")
-    if k in TEXT_PROBES and not text.strip():
-        return "SKIP", "no text artefact passed; this probe reads declarations, not pixels"
-    if k == "regex_absent":
-        hits = re.findall(pr["pattern"], text, re.I)
-        return ("FAIL" if hits else "PASS"), f"{len(hits)} match(es)"
-    if k == "regex_count":
-        n = len(re.findall(pr["pattern"], text, re.I))
-        ok = (n == pr["exactly"]) if "exactly" in pr else (pr.get("min", 0) <= n <= pr.get("max", 10 ** 9))
-        return ("PASS" if ok else "FAIL"), f"found {n}"
-    if k == "distinct_css":
-        vals = sorted(set(css_values(text, pr["property"])))
-        return ("PASS" if len(vals) <= pr["max"] else "FAIL"), f"{len(vals)} distinct: {vals}"
-    if k == "css_ratio":
-        vals = [v for v in css_values(text, pr["property"]) if v > 0]
-        if not vals:
-            return "SKIP", f"no {pr['property']} declarations found"
-        r = max(vals) / min(vals)
-        return ("PASS" if r >= pr["min"] else "FAIL"), f"ratio {r:.2f}:1"
-    if k == "min_unit":
-        vals = [v for v in css_values(text, pr["property"]) if v > 0]
-        if not vals:
-            return "SKIP", f"no {pr['property']} declarations found"
-        return ("PASS" if min(vals) >= pr["min_px"] else "FAIL"), f"smallest {min(vals)}px"
-    if k == "color_coverage":
-        if not images:
-            return "SKIP", "no image passed; render the output to PNG to check coverage"
-        pct, err = coverage(images[0], pr["hex"], pr.get("tolerance", 24))
-        if err:
-            return "SKIP", err
-        lo, hi = pr.get("min_pct", 0), pr.get("max_pct", 100)
-        return ("PASS" if lo <= pct <= hi else "FAIL"), f"{pct:.1f}% of canvas"
-    return "SKIP", f"unknown probe kind {k!r}"
-
-
-def main():
-    if len(sys.argv) < 2:
-        print(__doc__)
-        return 2
-    text, images = load(sys.argv[1:])
-    failed = manual = 0
-    print(f"design-dna check: {DNA['meta']['name']}\n")
-    for t in DNA.get("tests", []):
-        if not t.get("auto"):
-            status, detail = "MANUAL", "human judgement"
-        else:
-            status, detail = run(t, text, images)
-        failed += status == "FAIL"
-        manual += status == "MANUAL"
-        print(f"  [{status:6}] {t['id']:28} {t['check']}")
-        if detail:
-            print(f"            {detail}")
-        if status == "FAIL":
-            print(f"            fail looks like: {t['fail_looks_like']}")
-    print(f"\n{failed} failed, {manual} need human judgement.")
-    if manual:
-        print("Answer the MANUAL tests out loud before you call this done.")
-    return 1 if failed else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/design-loop/SKILL.md

@@ -1,160 +0,0 @@
----
-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. **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:
-a gallery of real products. 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
-
-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** → `../motion-craft/SKILL.md`. **How the interface should be built** → `../ui-engineering/SKILL.md`.
-- **"Show me a few versions and I'll pick"** → `../variant-explorer/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

@@ -1,56 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-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: "variant-explorer"
-    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: "motion-craft"
-    why: "One diff, motion-specific, no reference and no build-then-judge rounds. The motion craft skill owns the complaint-to-cause mapping; 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/motion-craft/SKILL.md

@@ -1,125 +0,0 @@
----
-name: motion-craft
-description: "Use when an interface moves and the movement has to feel right — durations and easing, what must never animate, fixing motion that reads sluggish, cheap or janky, and reduced-motion. Web and native. NOT the visual system (that is `design`), NOT the graded critique (that is `design-loop`)."
-tags: [motion, animation, interface, craft, frontend]
-recommends: [design]
-profiles: [full]
-origin: risco
----
-
-# Motion craft — movement that reads as intent
-
-Motion is not decoration laid over an interface. It is the interface **explaining what just
-happened**: what appeared, what it came from, what is still loading, what the user just did. When
-motion feels wrong the complaint is almost never "the curve is off" — it is "this feels cheap", or
-"slow", or "I don't know what happened". Those are the symptoms this skill exists to convert into
-decisions.
-
-## The one rule
-
-**Every animation answers a question the user is already asking.** If you cannot name the question,
-delete the animation — it is costing time and attention and returning nothing.
-
-| The user is asking | The motion that answers it |
-| --- | --- |
-| "Where did this come from?" | It enters from its origin, not from nowhere |
-| "Is it working?" | Immediate feedback, under 100ms, even before the result |
-| "What did I just do?" | The changed thing moves; nothing else does |
-| "Where did it go?" | It exits toward where it can be found again |
-| nothing | **no animation** |
-
-That table is the whole method. Everything below is how to honour it without shipping something
-that janks.
-
-## Duration: the only numbers worth memorising
-
-Movement is read as *slow* long before it is read as *long*. The usable range is narrower than most
-people expect, and the mistake is almost always **too slow**, not too fast.
-
-| What moves | Range | Why |
-| --- | --- | --- |
-| State on an element already on screen (hover, toggle, press) | 100–150ms | It must feel like a response, not an event |
-| Something entering or leaving in place (menu, tooltip, toast) | 150–250ms | Long enough to be seen, short enough not to be waited for |
-| A region rearranging (list reflow, panel) | 250–350ms | Bigger travel needs more time to stay legible |
-| A full view transition | 300–400ms | The ceiling. Past 400ms it is a wait, not a transition |
-
-Two rules that come from those numbers, not from taste:
-
-- **Exits are faster than entrances**, usually by about a third. The user has already decided; making
-  them watch the decision leave is the single most common way an interface feels sluggish.
-- **Distance and duration scale together, sub-linearly.** Doubling the travel does not double the
-  time. If a value grows past 400ms because the element crosses the screen, the layout is the
-  problem, not the timing.
-
-## Easing: three curves cover almost everything
-
-- **Entering, or responding to input** — start fast, settle slow (`ease-out` family). The user's
-  attention is already there; arriving quickly and settling reads as responsive.
-- **Leaving** — start slow, accelerate away (`ease-in` family). It matches how the eye lets go.
-- **Moving between two on-screen positions** — accelerate and decelerate (`ease-in-out` family).
-
-**Linear is for one thing only: continuous, non-positional change** — a progress bar filling, a
-spinner rotating, a colour crossfade. Linear on anything that moves in space reads as mechanical,
-because nothing physical starts at full speed.
-
-Springs are worth reaching for when the motion should feel *physical* — dragging, dismissing,
-anything the user's finger or pointer is still in contact with. They are the wrong tool for
-appearing and disappearing, where a bounce reads as indecision.
-
-## What must never animate
-
-This is where most jank comes from, and it is not a matter of degree.
-
-- **Never animate layout.** Width, height, top, left, margin, padding — each frame forces the engine
-  to recompute geometry. Animate transform and opacity, which do not.
-- **Never `transition: all`.** It is the shortest path to animating layout by accident. List the
-  properties.
-- **Never animate what the user is reading.** Text that moves while being read is illegible.
-- **Never block input on an animation.** The interface accepts the next action immediately, even
-  mid-motion. An animation that must finish before the user may act has become a modal dialog.
-- **Never animate more than one thing per event.** If three things move when one changed, the user
-  cannot tell which one mattered.
-
-## Reduced motion is not an edge case
-
-A real share of people have vestibular conditions for which large movement is nauseating, and they
-have told their operating system so. Honouring it is not optional and it is not a fallback to
-nothing:
-
-- **Keep** the feedback: opacity changes, colour, instant state.
-- **Remove** the travel: no sliding across the screen, no scaling, no parallax, no auto-playing loops.
-- The interface must still say what happened — it just says it without moving.
-
-An implementation with no reduced-motion branch is unfinished, the same way an interface with no
-error state is unfinished.
-
-## Diagnosing motion that feels wrong
-
-The complaint names the symptom; this maps it to a cause.
-
-| Complaint | Usually | Fix |
-| --- | --- | --- |
-| "Sluggish" | Duration too long, or the exit matches the entrance | Cut to the range above; make exits faster |
-| "Cheap" / "amateur" | Linear easing on positional movement, or bounce on entrances | Match curve to direction |
-| "Janky" / "stutters" | Animating layout properties | Move to transform and opacity |
-| "Distracting" | More than one thing moving per event | Animate only what changed |
-| "I don't know what happened" | Motion with no origin or destination | Move it from where it came from |
-| "Nice, but I'd turn it off" | No reduced-motion branch, or motion that repeats | Honour the setting; never loop what is not loading |
-
-## Anti-patterns → STOP
-
-| If you're about to… | Reality / Fix |
-| --- | --- |
-| Add motion because the screen feels static | Static is not a defect. Motion with no question to answer is noise with a frame cost. |
-| Copy a duration from a design you liked | You copied the number without its distance and its context. Take the range, verify against the feel. |
-| Animate a list so every item cascades in | Stagger past ~4 items becomes a queue the user waits through. Cap it, or drop it. |
-| Use a spring for a menu appearing | A bounce on an entrance reads as indecision. Springs are for what the pointer is still touching. |
-| Ship motion without checking reduced-motion | It is not an edge case. Unchecked means unfinished. |
-| Reach here for the visual system | Type, colour, spacing and composition are `../design/SKILL.md`. This skill only moves what that one placed. |
-
-## See Also
-
-- `../design/SKILL.md` — the visual system this motion serves.
-- `../design-loop/SKILL.md` — the graded critique that judges a finished screen, motion included.
-- `../design-dna/SKILL.md` — turning a look, motion rules included, into a reusable identity.
-- `../accessibility/SKILL.md` — the wider ground reduced-motion sits in.

package/skills/motion-craft/evals/cases.yaml

@@ -1,38 +0,0 @@
-skill: motion-craft
-
-should_trigger:
-  - prompt: "The menu animation feels sluggish, can you make it feel snappier?"
-    why: "The canonical case: a complaint about feel, which this skill converts into a duration and an easing decision."
-  - prompt: "What duration and easing should this dropdown use?"
-    why: "Directly the numbers this skill owns, for an element entering in place."
-  - prompt: "My list animation stutters when it reflows."
-    why: "Jank is the symptom of animating layout properties, which is the one hard rule here."
-  - prompt: "Añade una animación al abrir el panel, pero que no quede cutre."
-    why: "Same ask in Spanish; the trigger is the intent, not the language."
-  - prompt: "Does this respect prefers-reduced-motion? I don't think we handled it."
-    why: "Reduced-motion is treated here as part of finishing the work, not as an edge case."
-  - prompt: "Everything on the page moves at once when I click one button."
-    why: "More than one thing moving per event is a named diagnosis in this skill."
-
-should_not_trigger:
-  - prompt: "Design a landing page for my analytics SaaS — hero, pricing, the works."
-    route_to: "design"
-    why: "Type, colour, spacing and composition are the visual system, which this skill only moves once it exists."
-  - prompt: "Review this checkout screen and tell me how good it actually is, with a grade."
-    route_to: "design-loop"
-    why: "Graded critique of a finished screen is the loop's job; this skill builds motion, it does not judge screens."
-  - prompt: "This design came out great — turn it into a style I can reuse everywhere."
-    route_to: "design-dna"
-    why: "Codifying a look into a permanent identity is capture, not motion craft."
-  - prompt: "Make the site keyboard navigable and fix the contrast failures."
-    route_to: "accessibility"
-    why: "Accessibility beyond reduced-motion is its own ground; only the motion half lives here."
-  - prompt: "Our React app re-renders too much and the profiler shows wasted renders."
-    route_to: "react"
-    why: "A rendering performance problem is framework work, even when the symptom looks like stutter."
-
-capability:
-  - prompt: "This modal slides in over 600ms with a linear curve and it feels cheap. Fix it and say why."
-    why: "Exercises the two most common defects at once — too slow, and linear on positional movement — and demands the reasoning, not just new numbers."
-  - prompt: "We animate width and height on the sidebar and it janks on mobile. What do we do instead?"
-    why: "The layout-vs-compositor rule is the load-bearing piece of technical content here."