The Claude toolkit spoke-kit v1.12.0
Everything Claude knows and enforces when you work in a spoke, in one inventory. It ships as the spoke-kit plugin from this repo's marketplace — install once, and updates arrive whenever the hub is pushed.
Commands — the verbs you type
| Command | What it does |
|---|---|
/design-qa | Run a design-quality pass on this spoke's current work — on demand, any time (not just before a commit). Plain-language output: the person running this may not code. |
/new-prototype | Build a new prototype screen (or flow) in this Ecology spoke, composed from the esa-* legos. This command is written for EVERYONE — including teammates who don't code. |
/request-lego | File a request on the ecology hub for a missing or insufficient lego (component, pattern, or theming token hook). This is the right move whenever something you need doesn't exist — spokes never edit the hub directly. |
/ship | Publish this spoke's prototypes to its public GitHub Pages site. Written for non-coders: narrate each step in one plain line, and never skip the sync steps — two people deploying without syncing deletes each other's work (the dep… |
/spoke-init | Scaffold a new ESA Ecology design-system spoke — a small Astro app that re-skins the @esa/ecology hub via a [data-theme] block and documents it — from the hub's packages/spoke-template/. |
Skills — the knowledge Claude loads
| Skill | What it covers |
|---|---|
accessibility | The judgment layer of accessibility for ESA Ecology hub and spokes — load before building, styling, or reviewing ANY UI, and during /design-qa and /ship. Covers what the check-a11y PreToolUse hook CANNOT prove statically: keyboar… |
component-first | MANDATORY before building ANY UI in this @esa/ecology spoke — components, forms, dialogs, drawers, dropzones, file uploads, buttons, cards, badges, pills, chips, empty states, tooltips, AND page layout/composition (layouts.css pr… |
design-principles | The canonical aesthetic and interaction rules for ESA Ecology prototypes — load before styling, reviewing, or building ANY UI in a hub or spoke repo, and during /design-qa and /ship reviews. Covers banned visual patterns (colored… |
spoke-init | Reference detail for scaffolding a new ESA Ecology design-system spoke (an Astro brand re-skin of @esa/ecology). Use with the /spoke-init command. |
spoke-precommit-review | Pre-commit / pre-PR review for ESA ecology hub-and-spoke design-system projects (e.g. cb-fish-design, an Astro brand spoke of @esa/ecology). |
Hooks — the guardrails that run automatically
| Hook | Fires on | What it enforces |
|---|---|---|
check-manifest | PreToolUse: Write|Edit|MultiEdit | Manifest Gate (PreToolUse: Write|Edit|MultiEdit) — the FRONT-of-process teeth. A composed page must DECLARE its manifest BEFORE it is written: a header comment enumerating every section and resolving each to a COMPONENT — an esa-… |
check-component-first | PreToolUse: Write|Edit|MultiEdit | Component-First Guard (PreToolUse: Write|Edit|MultiEdit) — Node port of the original bash hook so it runs identically on macOS and Windows (no jq). BLOCKS bespoke UI primitives in an @esa/ecology spoke: exit 2 + reason on stderr… |
guard-hub-writes | PreToolUse: Write|Edit|MultiEdit | Hub-Write Guard (PreToolUse: Write|Edit|MultiEdit). In a SPOKE session, blocks writes that land inside the ecology HUB checkout — including through the node_modules/@esa/ecology symlink (targets are realpath'd before classificati… |
check-a11y | PreToolUse: Write|Edit|MultiEdit | Accessibility Gate (PreToolUse: Write|Edit|MultiEdit) — the deterministic half of the Ecology a11y posture: hooks enforce PRACTICES without being prescriptive about PATTERNS. This gate blocks only the accessibility failures that… |
check-hub-state | SessionStart: * | Hub-State Heads-Up (SessionStart). In a SPOKE session, inspects the sibling ecology HUB checkout that the spoke's file: symlinks serve from. |
Both guardrails have escape hatches that assert a human decision in the written content: bcn-lego-checked: <reason> (you walked the component lookup order and nothing fit) and hub-edit-approved: <reason> (a hub edit was explicitly approved in conversation). Use them honestly — they are claims, not magic words.
Hub scripts
| Script | What it does |
|---|---|
scripts/create-spoke.mjs | create-spoke.mjs — deterministic scaffold for a new Ecology spoke. The mechanical half of /spoke-init. |
scripts/doctor.mjs | doctor.mjs — environment check for the Ecology hub-and-spoke system. Run from a SPOKE (npm run doctor) or from the hub. |
Spokes expose the doctor as npm run doctor — the first thing to run when anything seems broken.
And the parts themselves
64 esa-* components, browsable with live specimens in the component library. The catalog on disk is always the source of truth: ls node_modules/@esa/ecology/src/components/ from any spoke.