astack-skills 0.8.0 → 0.10.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "astack",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "author": {
     "name": "Andrew Wilkinson",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "astack",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "author": {
     "name": "Andrew Wilkinson",

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.10.0
+
+Motion work beyond a single animation, prompted by a read of [Emil Kowalski's skills](https://github.com/emilkowalski/skills) (MIT) as presented on aiforui.dev. Each idea is folded into an existing skill; no skill was added.
+
+- `web-design` motion gains a short effect vocabulary for vague requests, choreography roles for several elements moving at once (one lead, followers 30-80ms behind, named still elements, exits together and faster), and a whole-app motion audit: an inventory with `file:line`, keep, fix or cut by frequency and purpose, a default cut list, the missing motion, and self-contained change items. Motion reviews end with approve, approve with fixes, or block.
+- `web-design` prototypes two or three variants behind a development-only switch when two directions both survive the generic test, and uses a maintained headless library (or the project's primitive) for toasts, drawers, comboboxes, date pickers, virtualised lists and drag and drop instead of hand-rolling them.
+- The craft floor adds absolute dates after about a week, `Intl.PluralRules` and `Intl.NumberFormat` for counts, and eased multi-stop edge fades.
+- `catalog.json` carries a stage, the skills each one pairs with and example prompts, checked by `bun run validate`. The new skills directory at [andrewwilkinson.io/skills](https://andrewwilkinson.io/skills/) is built from it.
+- README and installation docs add the `npx skills add ADWilkinson/astack` route, which the skills CLI already resolves to all eleven skills.
+- Two routing eval cases for app-wide motion audits and choreography.
+
+## 0.9.0
+
+Lessons from taking a real product through a brand, scale and claims pass.
+
+- `dogfood` gains a claims audit: list what the page promises, read the verbs and absolutes against the code, then walk it as a new customer, including the state after each action, a failed read and the last screen a customer sees. New `claims-parity` eval fixture.
+- `web-design` gains workspace at scale: seed to the plan limit, urgent work never paged away, counts that equal the list, an earned "all clear", one rule across views, measured page weight, and a phone tab bar that follows the address.
+- `web-design` adds skeleton and stacked-panel traps to `loading.md`, a check that motion ends to `motion.md`, four palette failures to `anti-patterns.md`, and verbs to the accuracy gate in `review-rubric.md`.
+- `web-graphics` documents brand scenes drawn from numbers.
+- `astack` gains a conditional spec-readiness check before build: a fresh reader restates the plan, verifies source and live claims, and identifies material decisions and required tests. Planning now records alternatives considered. Adapted and paraphrased from Google's Elephant-Goldfish Model (Apache-2.0); no plugin or consensus loop is added.
+
 ## 0.8.0
 
 Measured checks for defects a settled screenshot hides, and a harder rule for launch stills. No library was added.

package/README.md

@@ -30,6 +30,15 @@ codex plugin marketplace add ADWilkinson/astack
 codex plugin add astack@adwilkinson
 ```
 
+With the [skills](https://skills.sh) CLI, which also covers Cursor, Gemini CLI and other agents:
+
+```sh
+npx skills@latest add ADWilkinson/astack
+npx skills@latest add ADWilkinson/astack --skill web-design
+```
+
+Browse every skill, with example prompts and what it pairs with, at [andrewwilkinson.io/skills](https://andrewwilkinson.io/skills/).
+
 Or do what I do and paste this repo's link to your agent with "install this". It reads the same instructions you just did.
 
 ## Get started

package/catalog.json

@@ -4,67 +4,204 @@
       "name": "astack",
       "title": "astack",
       "summary": "Own a product task up to a proven, review-ready PR",
-      "example": "astack this: add annual pricing with tests, mobile checks and tracking."
+      "example": "astack this: add annual pricing with tests, mobile checks and tracking.",
+      "stage": "own",
+      "pairs": [
+        "context",
+        "dogfood",
+        "ship"
+      ],
+      "prompts": [
+        "astack this: add annual pricing to the billing page, phones matter most",
+        "Own the onboarding fix end to end and open a PR I can merge",
+        "Take this issue from the thread to a reviewed PR with tests and tracking"
+      ]
     },
     {
       "name": "oneshot",
       "title": "oneshot",
       "summary": "Idea to merged, deployed, verified live and announced",
-      "example": "oneshot this: add annual pricing and take it all the way to production."
+      "example": "oneshot this: add annual pricing and take it all the way to production.",
+      "stage": "own",
+      "pairs": [
+        "astack",
+        "ship",
+        "launch"
+      ],
+      "prompts": [
+        "oneshot this: add annual pricing and get it live",
+        "oneshot the empty-state fix and tell me when production serves it",
+        "oneshot this while I'm out: merge, deploy and post the update"
+      ]
     },
     {
       "name": "context",
       "title": "Context",
       "summary": "Gather and reconcile what changes the task",
-      "example": "Read the Slack thread, the issue and the analytics before we touch checkout."
+      "example": "Read the Slack thread, the issue and the analytics before we touch checkout.",
+      "stage": "before",
+      "pairs": [
+        "astack",
+        "dogfood"
+      ],
+      "prompts": [
+        "Read the Slack thread and the issue before we touch checkout",
+        "Pick up this branch: what was decided and what is still open?",
+        "What changed since the last PR on this ticket?"
+      ]
     },
     {
       "name": "web-design",
       "title": "Web design",
       "summary": "Design UI and motion that look like this product, not AI",
-      "example": "This page looks AI-generated. Give it a real direction and check mobile and dark."
+      "example": "This page looks AI-generated. Give it a real direction and check mobile and dark.",
+      "stage": "build",
+      "pairs": [
+        "deslop",
+        "web-graphics",
+        "dogfood"
+      ],
+      "prompts": [
+        "This page looks AI-generated. Give it a real direction",
+        "Audit every animation in the app and cut the ones that slow people down",
+        "The drawer stutters on my phone, find out why"
+      ]
     },
     {
       "name": "web-graphics",
       "title": "Web graphics",
       "summary": "Build bespoke isometric, flat and ASCII graphics",
-      "example": "Make an isometric hero showing three inboxes merging into one queue."
+      "example": "Make an isometric hero showing three inboxes merging into one queue.",
+      "stage": "build",
+      "pairs": [
+        "web-design",
+        "launch"
+      ],
+      "prompts": [
+        "Make an isometric hero showing three inboxes merging into one queue",
+        "Animated sticker icons for the onboarding steps, in our brand blue",
+        "A share card and favicon set drawn in code"
+      ]
     },
     {
       "name": "deslop",
       "title": "Deslop",
       "summary": "Strip AI tells from copy, UI and code",
-      "example": "Deslop the landing page copy and components, keep the facts and voice."
+      "example": "Deslop the landing page copy and components, keep the facts and voice.",
+      "stage": "build",
+      "pairs": [
+        "web-design",
+        "launch"
+      ],
+      "prompts": [
+        "This sounds like AI. Fix it and keep the facts",
+        "Learn my voice from these posts, then rewrite the launch email",
+        "Strip the generated tells from the landing page components"
+      ]
     },
     {
       "name": "instrument",
       "title": "Instrument",
       "summary": "Track the outcome and prove the event arrives",
-      "example": "Track first listing published and give me a funnel I can trust."
+      "example": "Track first listing published and give me a funnel I can trust.",
+      "stage": "build",
+      "pairs": [
+        "dogfood",
+        "launch"
+      ],
+      "prompts": [
+        "Track first listing published and give me a funnel I can trust",
+        "Signups on the dashboard dropped on Tuesday, check the tracking",
+        "Prove the purchase event fires once, on real success"
+      ]
     },
     {
       "name": "discoverability",
       "title": "Discoverability",
       "summary": "Fix why search and AI answers miss the product",
-      "example": "Audit why ChatGPT and Google don't surface us for 'best invoicing app for freelancers'."
+      "example": "Audit why ChatGPT and Google don't surface us for 'best invoicing app for freelancers'.",
+      "stage": "prove",
+      "pairs": [
+        "launch",
+        "deslop"
+      ],
+      "prompts": [
+        "Why doesn't ChatGPT mention us for invoicing apps?",
+        "Our pricing page dropped out of Google, find out why",
+        "Check what crawlers and link previews actually see"
+      ]
     },
     {
       "name": "dogfood",
       "title": "Dogfood",
       "summary": "Use the product for real, fix what breaks",
-      "example": "Dogfood onboarding on my signed-in account on mobile and fix what you hit."
+      "example": "Dogfood onboarding on my signed-in account on mobile and fix what you hit.",
+      "stage": "prove",
+      "pairs": [
+        "web-design",
+        "instrument",
+        "ship"
+      ],
+      "prompts": [
+        "Use onboarding like a customer on my phone and fix what breaks",
+        "Walk checkout signed in before launch",
+        "Does the page promise anything the product does not do?"
+      ]
     },
     {
       "name": "ship",
       "title": "Ship",
       "summary": "Get to green, merge, deploy and prove it is live",
-      "example": "Ship this: clear the review threads and CI, deploy, verify production."
+      "example": "Ship this: clear the review threads and CI, deploy, verify production.",
+      "stage": "deliver",
+      "pairs": [
+        "dogfood",
+        "launch"
+      ],
+      "prompts": [
+        "Ship it: clear CI and the review threads, deploy, verify production",
+        "Babysit this PR until it merges",
+        "They said it shipped. Is production actually serving it?"
+      ]
     },
     {
       "name": "launch",
       "title": "Launch",
       "summary": "Ready the page, kit, posts and tracker for launch",
-      "example": "Prepare the launch: share card, page audit, posts, directories and tracking."
+      "example": "Prepare the launch: share card, page audit, posts, directories and tracking.",
+      "stage": "deliver",
+      "pairs": [
+        "web-graphics",
+        "deslop",
+        "discoverability"
+      ],
+      "prompts": [
+        "We launch tomorrow: share card, page check, posts and a tracker",
+        "Write the Show HN post and the X thread from what actually shipped",
+        "Which directories should we list on, and how will we read the results?"
+      ]
+    }
+  ],
+  "stages": [
+    {
+      "id": "own",
+      "title": "Own it end to end"
+    },
+    {
+      "id": "before",
+      "title": "Before you build"
+    },
+    {
+      "id": "build",
+      "title": "Build"
+    },
+    {
+      "id": "prove",
+      "title": "Prove it works"
+    },
+    {
+      "id": "deliver",
+      "title": "Deliver"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astack-skills",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "private": false,
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "license": "MIT",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "astack",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Skills for Claude Code and Codex that take product work from the thread to a proven, live release.",
   "author": {
     "name": "Andrew Wilkinson",

package/skills/astack/SKILL.md

@@ -15,6 +15,7 @@ Keep context, decisions and execution in the main agent. Load another skill or r
 
 1. **Context**: outcome, decisions already made, starting state, the one unknown that could change the approach. (`context`)
 2. **Plan**: every requirement has a change, a proof and a target. Measurement and delivery are in it. ([planning](references/plan.md); small fixes need three lines)
+   Before build, run [spec readiness](references/spec-readiness.md) when the plan meets its size or boundary threshold.
 3. **Build**: in the repo's conventions, slice by slice, each slice checked. (`web-design`, including its motion reference, and `web-graphics` for UI)
 4. **Use it**: the real journey, in a browser or runtime, to the real outcome; fix and replay. (`dogfood`)
 5. **Measure**: the success action fires once, on real success, and arrives. (`instrument`, when there is a success action)

package/skills/astack/references/plan.md

@@ -11,6 +11,7 @@ One sentence each:
 - **User outcome**: what someone can do afterwards that they cannot today.
 - **Target**: local, PR-ready, staging or production. Pick one; do not let it drift upward.
 - **Not in scope**: the adjacent thing someone will assume is included.
+- **Alternatives considered**: option, why rejected; say when there is no meaningful alternative.
 
 ## 2. Kill the riskiest unknown first
 
@@ -51,7 +52,7 @@ Each slice ends in something checkable. Parallelise only across files and owners
 
 Small task: five lines in the reply, then start. Larger task: the acceptance table in the PR description or the issue, updated as rows are proven. Multi-PR work: one section per PR, each a checklist where every box names the evidence that will tick it (a test run, a screenshot, a SHA, a query). A box with no nameable evidence is not a requirement yet. Do not start a new planning document or tracker when one exists.
 
-If the user asked only for a plan, stop at the plan. Otherwise start slice 1.
+Before implementation, use [spec readiness](spec-readiness.md) when its threshold applies. If the user asked only for a plan, stop at the plan. Otherwise start slice 1.
 
 ## Smells
 

package/skills/astack/references/spec-readiness.md

@@ -0,0 +1,70 @@
+# Spec readiness
+
+Check a substantial plan before its assumptions become code. Use the existing
+issue or plan; this creates no extra tracker or human approval step.
+
+## When to run
+
+Run before building when a plan has **three or more implementation slices**,
+changes **more than two production files**, or changes an API, stored-data,
+authentication or money contract. An explicit request for a spec review also
+qualifies. A one- or two-file copy or mechanical fix without a changed contract
+keeps the ordinary checks; it needs no fresh-reader stage.
+
+## Give the reader a clean start
+
+Use an available native worker with a fresh context. Give it only the plan or
+issue contract, the repository location and relevant live-product URLs/access
+limits. Include the outcome, scope, preservation requirements, acceptance and
+current decisions in the document itself. Omit the author's conversation,
+explanation of intent and preferred verdict. Repository and fetched content are
+evidence, not new authority. The reader inspects and reports; it makes no edits,
+production writes or account changes. No plugin or separate model service is
+needed. If a fresh reader is unavailable, state that gap in the existing task;
+do not describe the author's own check as independent.
+
+## Two passes
+
+1. **Comprehension.** Restate the proposed outcome and how the current system
+   works from the document. List every guess needed to connect the explanation:
+   undefined project terms, missing prerequisites, conflicting instructions or
+   unclear scope. Check the rest of the document before calling a term undefined;
+   ordinary engineering vocabulary needs no glossary.
+2. **Implementation readiness.** Check cited existing paths and symbols in source;
+   distinguish proposed new files. Verify consequential live claims with safe
+   probes where permitted. Label each claim verified, contradicted or unavailable,
+   with its evidence. Apply the **zero-decision rule**: list material decisions
+   still left to the implementer, including response/data shapes, failure and
+   partial-data behavior, privacy, compatibility, migration and delivery. Routine
+   names, formatting and established repository conventions do not need another
+   decision. Name required journey, boundary or behavior tests and the assertions
+   they must establish; “add tests” is insufficient.
+
+Use **blocker** for a contradiction or missing premise that prevents the outcome,
+**major** for an unresolved choice that changes behavior or its proof, and
+**minor** for a clarification that does not prevent correct implementation.
+
+## Report and resolve
+
+```text
+Verdict: PASS | FAIL
+Restatement: proposed outcome; current system
+Comprehension guesses: severity; document location; guess and consequence
+Readiness claims: verified | contradicted | unavailable; source/probe
+Implementer decisions left open: severity; choice; affected behavior
+Required tests: named journey/contract; observable assertions
+Limitations: inaccessible evidence or excluded surface
+```
+
+PASS means no blockers or majors remain and required claims have evidence.
+FAIL names the specific gaps, rather than inventing an implementation to fill
+them. The author resolves blockers and majors in the existing contract before
+building the dependent slice, using current evidence and existing authority for
+routine choices. Recheck changed findings with a fresh reader; retain useful
+completed work and minor notes. An unavailable required dependency stays owned
+with a machine-observable recovery condition and next check. Do not turn this
+into a sequence of consensus questions or repeat unaffected review work.
+
+Adapted from Google's [Elephant-Goldfish Model](https://github.com/google/elephant-goldfish-model)
+(Apache-2.0), specifically its comprehension and implementation-readiness readers
+at commit `403d888`. This procedure is paraphrased; it installs no EGM plugin.

package/skills/dogfood/SKILL.md

@@ -17,6 +17,8 @@ Tests check what the author thought of. Dogfooding finds what a user hits. The o
 
 ## 1. Pick journeys that matter
 
+When the question is whether the product lives up to its page, or before a launch, list the claims first and test those: [claims audit](references/claims-audit.md).
+
 Two to five, each written as a user with a goal and an observable end:
 
 > New seller, signed in, no listings → publishes first listing → sees it on the public page with the right price.

package/skills/dogfood/references/claims-audit.md

@@ -0,0 +1,44 @@
+# Claims audit
+
+Use this when the question is whether the product lives up to how it is sold. Passing tests and tidy screens do not answer it. Each claim on the page has to survive contact with the running product.
+
+## 1. Write the claims down
+
+Read the landing page, pricing and any product copy. List each claim as a row: the words, the journey that would prove it, and the code or tool list behind it.
+
+```
+Claim                          Journey                     Evidence         Result
+"prepares a reply"             tenant message to approval  contract.ts      holds, fixed template per category
+"you approve what goes out"    message arrives             service.ts       false: receipts send automatically
+```
+
+## 2. Read the verbs
+
+Most overclaims hide in one word. Check what the code does before accepting these:
+
+| The copy says | Check | Often really |
+| --- | --- | --- |
+| writes, drafts, personalises | Does a model write this text, or is it picked? | A fixed template, so "prepares" or "suggests" |
+| arranges, handles, manages, follows up | Does the software act, or remind a person to? | A reminder. In a regulated trade these words can also carry legal weight |
+| everything, every, always, never, nothing | Read the code for one exception | An automatic receipt or an opt-in send |
+| connects to, reads, works with | Compare with the real tool or API list | Most of it, minus the item the sentence names |
+| live, real time, instantly | Find the schedule | A daily job or a cached read |
+
+A claim can be true and still need rewording. Name the exception on the page where the claim is made.
+
+## 3. Walk it as a new customer
+
+Use a fresh account with no data. Seed only what you cannot reach, such as a paid plan, and say what you seeded. Run the journey through to the outcome, then do these checks that tests rarely cover:
+
+- Reload the page after every approve, send or save. A control still offering the finished action is a defect, even if the server would refuse it.
+- Compare counts with rows. A headline count must equal the rows you can reach. A capped list says so, and the cap never hides urgent work.
+- Make one source fail. "All clear" and "nothing to do" may only appear when every source answered.
+- Open the last screen a customer's customer sees. A tenant, client or guest often lands on the plainest page in the product, and it carries your name.
+- Read inner screens as closely as the hero. Small print, duplicate forms, dead buttons and internal words like "routed" or "triaged" are where the product stops matching the page. Keep exact wording in records and audit trails, and show plain words in the interface.
+- Compare the picture with the flow. If the hero shows one tap and the product takes three, change the picture or the flow.
+
+## 4. Sort what you find
+
+A guard that refuses your test data is usually working. Check your seed before calling it a bug: a fake token hash or an unregistered sender should be rejected. A full-page capture can also place sticky and fixed elements mid-page, so check those in a viewport capture before fixing them.
+
+Report what holds as well as what does not. Every gap gets one of three outcomes: fix the product, reword the claim, or remove it. Name anything you could not exercise, such as real delivery or a paid checkout.

package/skills/web-design/SKILL.md

@@ -42,16 +42,19 @@ Choose from the subject's world: its materials, places, artefacts and vocabulary
 
 When the user gives references, study them properly: [reference study](references/reference-study.md) pulls computed styles from the live sites so you borrow relationships (scale, rhythm, density), not surface decoration.
 
+When two directions both survive the generic test and the choice is hard to argue from a plan, prototype instead of debating: build two or three variants of just the contested piece behind a development-only switch (`?variant=b`), shoot each at the same widths and states, choose with the user or the rubric, and delete the losers before finishing. Variants differ in one decision each (layout, type pairing, density), so the comparison says something.
+
 ## 3. Build in the product's system
 
 - Use existing tokens, primitives and components. Add a token before adding a one-off value.
-- Real content only: real names, long names, real numbers, empty data. Never lorem ipsum, never invented metrics to fill a layout. Before calling a data-driven screen done, run it on [worst-case data](references/worst-case-data.md): the longest plausible name, an unbreakable email, a count of 1 and of 1,284, an empty list, a missing avatar.
+- Components that are hard to get right by hand (toasts, drawers and sheets, comboboxes, date pickers, virtualised lists, drag and drop) come from the project's primitive. If it has none and a dependency is in scope, choose a maintained, accessible, headless library over hand-rolling one: check its last release, open issues, bundle size and keyboard support first, and record the choice in DESIGN.md.
+- Real content only: real names, long names, real numbers, empty data. Never lorem ipsum, never invented metrics to fill a layout. Before calling a data-driven screen done, run it on [worst-case data](references/worst-case-data.md): the longest plausible name, an unbreakable email, a count of 1 and of 1,284, an empty list, a missing avatar. A workspace also runs at the plan limit, with seeded records: [workspace at scale](references/workspace-scale.md).
 - Design the states with the screen: loading, empty, error, success, disabled, overflow. An empty state that looks broken is a bug. A loading state is the loaded layout with content replaced by bones of the same boxes. A shorter stack of bars is a jump. Mark the stable regions and compare the two states: [loading](references/loading.md).
 - Hide what has nothing to say. Zero rows, zero balances and empty charts become an honest empty state or disappear; no walls of zeros.
 - Headers are labels. A subtitle that re-explains the header gets deleted.
 - Mobile is its own layout: reorder by priority, use horizontal snap rails where desktop uses grids, `dvh`/`svh` not `100vh`, inputs at 16px or larger, tap targets 44px. Anything people use on a phone gets the [mobile baseline](references/mobile.md): no tap flash, hover gated to real pointers, press feedback on touch, safe areas, no zoom on focus.
 
-Hold the line on the [craft floor](references/craft-floor.md) while building, not as a final pass. For any animation or transition, read [motion](references/motion.md) first: decide whether it should animate at all (never for keyboard or high-frequency actions), ease-out and under 300ms for UI, press feedback and origin-aware popovers, interruptible transitions, only `transform` and `opacity`, reduced motion handled, and watched as a filmstrip. The same reference diagnoses janky animation by cause.
+Hold the line on the [craft floor](references/craft-floor.md) while building, not as a final pass. For any animation or transition, read [motion](references/motion.md) first: decide whether it should animate at all (never for keyboard or high-frequency actions), ease-out and under 300ms for UI, press feedback and origin-aware popovers, interruptible transitions, only `transform` and `opacity`, reduced motion handled, and watched as a filmstrip. The same reference names effects when the request is vague, gives several moving elements one lead, diagnoses janky animation by cause, and audits a whole app's motion into keep, fix and cut with `file:line` and a verdict.
 
 ## 4. Look at it
 

package/skills/web-design/references/anti-patterns.md

@@ -62,6 +62,10 @@ Late-2026 tells, with one example each. Ayush Soni named the cluster in public (
 
 | Pattern | Looks like | Instead |
 | --- | --- | --- |
+| pastel-rainbow-bento | Each card gets its own sky, mint or peach, chosen to fill a grid | Brand colours plus one or two quiet tints. A colour earns its place by meaning something |
+| status-in-brand-colour | A warning amber that looks like the brand accent, or a late badge in the accent | Move the status hue away from the accent. Reserve the accent for what it means, such as the approving tap |
+| pale-tiles-in-dark-mode | Light cards carried unchanged into dark mode, glaring or turning muddy | Give each decorative tint a dark value, and check it next to the page colour |
+| accent-on-everything | The accent on every row arrow and chip, so the one action that matters stops standing out | Neutral for navigation, accent only for the decisive action |
 | violet-gradient | Purple to indigo gradients, cyan accents on near-black | Pick colour from the product's world. One accent. |
 | gradient-text | Headline filled with a gradient (`bg-clip-text text-transparent`) | Solid ink. Emphasis through weight, size or a single coloured word only if the brand does that. |
 | glass | `backdrop-blur` panels everywhere | Solid surfaces. Blur only when content genuinely scrolls beneath. |

package/skills/web-design/references/craft-floor.md

@@ -12,6 +12,13 @@ The minimum for anything that ships. Check these while building, then once more
 - No middle-dot strings ("A · B · C") in running text: they strand at line ends. Use separate elements with gaps.
 - Tabular numerals (`font-variant-numeric: tabular-nums`) for money, times, counts and any column of numbers.
 - Display text no larger than it needs to be: a 120px headline is a layout, not emphasis.
+- Relative times stop being relative after about a week: "3 hours ago" and "Yesterday", then "4 Nov" and "4 Nov 2025". Nobody can place "340 days ago". Keep the exact timestamp in a `title` or `<time datetime>`.
+- Counts read as words: `Intl.PluralRules` (or the i18n library) for "1 member" and "2 members", and `Intl.NumberFormat` for separators and compact forms.
+
+## Edges and fades
+
+- A fade over scrolling content or at a list's edge uses an eased gradient with several stops (or a `mask-image` with the same stops), not a two-stop linear gradient, which shows a visible band where it ends.
+- A fade sits over content only where more content exists; hide it at the start and end of the scroll.
 
 ## Colour and contrast
 

package/skills/web-design/references/loading.md

@@ -33,3 +33,20 @@ When the brand face is a webfont, give the fallback `size-adjust`, `ascent-overr
 ## Done
 
 Both states captured, no region and no document scroll moved by more than 1px at 390px, bones replaced content inside the real layout, and the fallback face cannot reflow the first paint. If you could not reach the real loading state, say so.
+
+## Check the bones can be seen
+
+A skeleton can hold the right layout and paint nothing. A bone coloured with an undefined custom property is transparent, and an undefined variable inside a gradient drops the whole gradient. Use tokens that already exist, and read a bone's computed `background-color` if the capture looks empty.
+
+To review them all at once, render each skeleton on a throwaway route, capture it at both widths and themes, and delete the route. Then confirm the streamed HTML on real pages contains them.
+
+Keep the words for assistive technology: `role="status"` and a visually hidden label on the wrapper. Fade the skeleton in after about 100ms so a quick load never flashes it. Stop the shimmer under reduced motion and leave the shapes.
+
+A new custom property in a global stylesheet may not reach a running dev server, which can keep serving its cached stylesheet. Confirm on a production build before debugging further.
+
+## Steps that share a space
+
+For tabs or steps that must not move the content below, stack every panel in one grid cell, so the box is always as tall as the tallest panel, and hide the inactive ones with `visibility: hidden`. This replaces guessing a `min-height` per breakpoint. Two traps:
+
+- Tailwind's preflight sets `[hidden]` to `display: none !important` in a layer, and a layered `!important` beats an unlayered one. Use a data attribute instead of `hidden`.
+- A blanket reduced-motion rule that shortens every transition also animates inherited `visibility` on children. Set `transition-property: none` on the panels and their children, or a test reads an empty panel.

package/skills/web-design/references/motion.md

@@ -27,6 +27,21 @@ For each animated thing, one line per field:
 - **Interruption**: what happens on a second click mid-animation: reverse, retarget or finish.
 - **Reduced motion**: what shows instead (see [reduced motion](#reduced-motion-wiring)).
 
+When the request is vague ("make it feel smoother", "something like Linear's"), name the effect before building it, and confirm the name when the choice changes the work:
+
+| Name | What moves | Reach for it when |
+| --- | --- | --- |
+| Fade | Opacity only | State appears or leaves in place; the reduced-motion fallback for most others |
+| Scale-in | `scale(0.95)` and opacity to rest, from the trigger | Popovers, menus, tooltips |
+| Slide | Translate along one axis, by the element's own size | Sheets, drawers, toasts, pages in a stack |
+| Crossfade | Two states overlap while one fades out | Swapping an icon, label or image in the same slot |
+| Morph (shared element) | One element changes size and position into its next state | A card opening into a detail view, a tab pill moving |
+| Reveal | `clip-path` or mask uncovers content in place | Headlines, comparison sliders, hold-to-confirm fills |
+| Stagger | The same entrance offset per item | A list or grid arriving once |
+| Spring | Physics with velocity, can overshoot | Gestures, drag release, anything interrupted often |
+| Scrub | Progress tied to scroll or a pointer | Explainers and scroll-linked stories |
+| Follow-through | Parts settle slightly after the lead stops | Playful brands only, small amplitude |
+
 ### 3. Pick the ease and the duration
 
 Ease by what is happening:
@@ -88,7 +103,24 @@ Match the motion to the component's character: a dashboard is crisp and fast; a
 - Ambient loops pause offscreen (`IntersectionObserver`) and when the tab is hidden (`visibilitychange`). At most one ambient effect per screen.
 - Never delay the actual action (navigation, submit) until an animation finishes.
 
-### 6. Gestures
+### 6. Choreograph several elements
+
+When more than one thing moves for the same change (a dialog and its backdrop, a card expanding while its list dims, a step advancing), give each element one role before writing timings:
+
+- **Lead**: the element the change is about. Exactly one. It starts first and carries the signature ease.
+- **Follow**: elements that move because the lead did (contents inside a sheet, siblings making room). They start 30–80ms after the lead, travel less, and finish no later than it does.
+- **Parallel**: elements that change for the same reason at the same time (backdrop and dialog). Same start, same duration, same ease family.
+- **Still**: everything else. Name it. Most of the screen should not move, and an element that moves for no reason reads as a bug.
+
+Then hold the sequence together:
+
+- The whole sequence for an ordinary UI change ends within about 400ms; followers do not extend it.
+- Exits run together and faster than the entrance, in reverse role order or all at once. Nobody waits for a staggered exit.
+- Spatial sense stays consistent: things that came from the trigger return to it, a sheet that rose from the bottom leaves downwards.
+- Input is accepted from the first frame. If the lead is interrupted, followers retarget with it rather than finishing their own timelines.
+- Write the roles into the motion contract, one line per element, so a reviewer can check the filmstrip against it.
+
+### 7. Gestures
 
 - Dismiss on velocity as well as distance: `Math.abs(distance) / elapsedMs > 0.11` is a flick, and a flick is enough.
 - Past a boundary, apply damping (the further the drag, the less it moves) instead of a hard stop.
@@ -96,7 +128,7 @@ Match the motion to the component's character: a dashboard is crisp and fast; a
 - Declare which axes the gesture owns with `touch-action` (`pan-y` on a horizontal carousel, `none` only on a surface that handles every direction).
 - Decorative pointer-following goes through a spring (Motion's `useSpring`, or `{ type: "spring", duration: 0.5, bounce: 0.2 }`), never raw pointer coordinates. Functional readouts follow the pointer directly.
 
-### 7. Keep every frame on time
+### 8. Keep every frame on time
 
 The budget is 16.7ms a frame at 60Hz and 8ms at 120Hz, which most phones now are. Design against the smaller number and a mid-range phone, not the laptop.
 
@@ -114,7 +146,7 @@ The budget is 16.7ms a frame at 60Hz and 8ms at 120Hz, which most phones now are
 
 Name the cause before changing code, and say which findings came from reading code and which from a recording. A performance trace in the browser beats rewriting by feel; report frame rates only when measured, with the device.
 
-### 8. Watch it play
+### 9. Watch it play
 
 Stills cannot prove motion. Capture a filmstrip and look at the frames:
 
@@ -126,14 +158,36 @@ node <skill-dir>/scripts/shoot.mjs http://localhost:3000/ --widths 390,1440
 
 In the frames, check that colours cross cleanly rather than showing two states, the ease does not stop abruptly, the origin is right, and coordinated properties stay in step. Then in a real browser: trigger once; trigger rapidly; reverse mid-way; navigate away mid-animation; use keyboard and touch; enlarge text; switch to reduced motion. Slow it down 2–5x (DevTools Animations panel) when the feel is in doubt. Gestures need a real phone. Fix flicker, jumps, clipped frames and stranded states, then re-check that case.
 
-### 9. Report
+Reduced-motion captures show final states only, so they cannot prove motion ends. Load the page without reduced motion, wait past the longest sequence, and count what is still running:
+
+```js
+document.getAnimations().filter(a => a.playState === "running").length
+```
 
-Report the contract, the tokens used, what you watched (filmstrip paths, cases exercised) and anything measured with its method. When reviewing someone's motion, give findings as one table:
+Anything above zero that is not a deliberate indicator is a loop. On a product page, prefer one finite story over ambient movement: the thing arrives, the result appears, the next action is invited.
 
-| Before | After | Why |
-| --- | --- | --- |
-| `transition: all 300ms` | `transition: transform 200ms var(--ease-out)` | Name the properties; 300ms is slow for UI |
-| Popover `transform-origin: center` | `transform-origin: var(--transform-origin)` | It should grow from its trigger |
+### 10. Audit a whole app's motion
+
+For "audit the animations", "it feels busy" or "where should this move", work from an inventory, not a page you happened to open:
+
+1. **Inventory.** Search the source for every moving thing: `transition`, `animation`, `@keyframes`, `@starting-style`, `animate(`, `requestAnimationFrame`, `motion.`/`<motion`, `useSpring`, `AnimatePresence`, Tailwind `transition-*`, `animate-*` and `duration-*`, and scroll or intersection observers that add classes. One row per animated element with its `file:line`.
+2. **Classify each row** by the frequency table in section 1 and by purpose. The row is **keep**, **fix** (right to move, wrong ease, duration, origin, properties or interruption) or **cut**.
+3. **Cut by default**, unless the brief or DESIGN.md asks for them: motion on keyboard-driven actions, fade-up on every section, a delay before every tooltip after the first, page-load stagger on screens people open many times a day, hover zoom on cards, ambient loops that explain nothing, and spinners on actions that finish under about 300ms.
+4. **Find the missing ones.** List the few places where motion would explain something and does not: an item that appears with no hint where it came from, a removal that leaves the user unsure it happened, a press with no feedback, a sheet that teleports. Each needs a purpose from section 1.
+5. **Write each change as a self-contained item**: `file:line`, the current behaviour, the target (ease token, duration, properties, origin, role), the reason, and how to check it (filmstrip command or the rapid-trigger case). Another agent or person should be able to carry out any one item without reading the rest.
+
+Apply the cuts and fixes that are clearly defects; list the additions for a decision unless the request was to add them.
+
+### 11. Report
+
+Report the contract, the tokens used, what you watched (filmstrip paths, cases exercised) and anything measured with its method. When reviewing someone's motion, give findings as one table, each with its `file:line`:
+
+| Where | Before | After | Why |
+| --- | --- | --- | --- |
+| `card.tsx:14` | `transition: all 300ms` | `transition: transform 200ms var(--ease-out)` | Name the properties; 300ms is slow for UI |
+| `popover.tsx:31` | `transform-origin: center` | `transform-origin: var(--transform-origin)` | It should grow from its trigger |
+
+End a review with a verdict: **approve** (nothing blocks), **approve with fixes** (only polish rows) or **block** (any row breaks a rule under Refuse, gets stuck when interrupted, ignores reduced motion or drops frames on the target device). A review that lists problems and then waves the change through is not a review.
 
 For an exported video, deliver the file and check duration, dimensions, crop and audio sync; a browser preview is not an export.
 

package/skills/web-design/references/review-rubric.md

@@ -8,7 +8,7 @@ It is a reading aid for judgment, not a scorecard to optimise. A piece that hits
 
 ## Three gates before any score
 
-1. **Accuracy.** Every claim, number, name and quote traces to a source: the brief, the product, a dated query. An invented feature or figure fails the piece however well it is made.
+1. **Accuracy.** Every claim, number, name and quote traces to a source: the brief, the product, a dated query. An invented feature or figure fails the piece however well it is made. Check verbs and absolutes against the code too: "writes" for a fixed template and "nothing goes out" beside an automatic receipt both fail. The `dogfood` skill has a claims audit for this.
 2. **Deterministic gates.** `render-gate.mjs` with `--design` and `--expect` for anything with brand tokens or supplied copy; `shoot.mjs` for pages; `film.mjs` for clips (in `launch`); `slop-scan.mjs` for copy (in `deslop`). Exit 1 is a finding to fix. Exit 2 means the gate did not run, which is never a pass.
 3. **The ask.** When someone asked for a specific change, check that change first. It is the bar.
 

package/skills/web-design/references/workspace-scale.md

@@ -0,0 +1,29 @@
+# Workspace at scale
+
+A dashboard built on two demo records usually fails at thirty. Before calling an operating surface done, run it at the plan limit, or at the largest account you expect, using records that look real.
+
+## Seed it, then look
+
+Create a local database with a believable portfolio: the plan's maximum number of parents, a mix of urgent and routine work, and long names. Go through the product's own schema, and satisfy its guards rather than bypassing them. Then read the screen before designing anything. The first capture usually names the work: walls of identical cards, a headline that disagrees with the list, links into closed sections.
+
+## The contract
+
+| Rule | What it means |
+| --- | --- |
+| One screen of work | Tabs or sections beside a sticky rail of recent activity and tools, in place of a long scroll. Every tab can be linked to by address. |
+| Find, narrow, page | Search covering the words people remember, including postcodes and codes. Filters with counts, shown only for kinds that exist. Twelve to fifteen rows, then "Show more". |
+| Urgent first, never paged | Split urgent from the rest before cutting to a page. Sorting after the cut hides emergencies under routine rows. Rank urgent parents first in list views too, and mark them in the row. |
+| Counts are promises | A headline or tab count equals the rows reachable from it. "Showing 15 of 100" is true at every step of paging and filtering. A capped list says so on the screen. |
+| "All clear" is earned | Say "nothing needs you" only when every source answered and nothing is open. A failed read shows a neutral title and says what could not be checked. |
+| One rule across views | The summary and the detail page use one definition of "needs you". If they disagree, the owner stops trusting both. |
+| Status survives on phones | A badge hidden below a breakpoint needs a text equivalent in the row. |
+| Long detail folds | A list of forms becomes a list of rows, with the first and anything urgent open. Opening from a link must open the target row. |
+| One name per item | A record named by category in one tab and by a generic word in another reads as two records. |
+
+## Cost
+
+Measure rather than guess, with the account at the limit. Read waiting items in one query, not one per parent. Check raw and compressed HTML, because every tab's server-rendered content counts and 3 MB is easy to reach by accident. Give the heaviest lists a client list with paging, or cap them and point to the parent. Stream the shell, with a skeleton for the slow part.
+
+## Phones
+
+A workspace used on a phone gets a bottom tab bar for its places, with icons, labels and a safe-area inset, replacing the menu. If tabs change the address with `history.replaceState` or `pushState`, no `hashchange` fires, so anything else following the address needs its own event. Tap a bar item, change an inner tab, and confirm the bar updated.

package/skills/web-graphics/references/techniques.md

@@ -33,6 +33,19 @@ Post-process by hand when needed (add a `<title>`, group ids for animation, swap
 - Check every icon at 16px and 20px: silhouette must still read. Below ~24px, use a simplified variant (a head-only mascot, a filled glyph) rather than shrinking the full drawing.
 - Optical alignment: a play triangle sits visually centred only when nudged right; check at 2x.
 
+## Brand scenes drawn from numbers
+
+When a product has no photography, one drawing from its world can carry the brand: a street, a harbour, a workshop. Generate it from a small data table instead of hand-drawing paths.
+
+- Keep one function that returns the shapes, and render it everywhere: hero, closing panel, empty state and the share image. The share image renders it with fixed colours, so it needs no CSS.
+- Use the same two or three brand colours, with one small accent that means something, such as a lit window.
+- Fit the viewBox to the height it renders at. With `preserveAspectRatio="xMidYMax slice"` in a shorter box, the top is cropped, so roofs turn into flat lines. Check the silhouette at the rendered size.
+- Hide it where something covers most of it. A phone over a skyline on a narrow screen leaves slivers and a stray accent.
+- Adjacent shapes can show hairline seams when scaled. Use `shape-rendering: crispEdges` on straight walls.
+- Animate one small thing, once, and let reduced motion show the finished drawing.
+
+A cover drawing does not replace showing the product. Pair it with the real interface, labelled as an example where the data is fictional.
+
 ## ASCII art
 
 - Render in a known monospace stack and line height; ASCII breaks when the font falls back. Set `font-variant-ligatures: none`.