How the system works

Hub and spokes

A spoke is its own repo, cloned next to the hub. It consumes the hub's npm packages through file:../ecology links — so a spoke is always on the hub's latest, and a git pull in the hub updates every spoke on the machine. Patterns that prove broadly useful get promoted up into the hub; spokes never grow private forks of system pieces.

Tokens: why styling changes are one-liners

Three tiers. Primitives are raw values (--color-teal-9, --spacing-400) — they never move. Semantic tokens express intent (--color-background-brand) and reference primitives. Component tokens are each component's public theming surface (--form-border-color, --sidenav-bg).

A spoke re-brands by overriding the semantic and component layers inside one [data-theme="slug"] block in its theme file — component internals are never touched. The working rule: a styling change in a spoke is a token re-point until proven otherwise. If no token hook exists for what you need, that's a gap to file (/request-lego), not a license to hand-style.

You don't write that block by hand. The theme maker takes a brand colour, a neutral temperature and a corner language, and derives the rest — two twelve-step ramps, the full neutral chain, light and dark, and the eight foreground colours that decide whether the contrast gate passes. It hands back a small recipe file; /spoke-init takes that recipe and the theme is done before the spoke exists.

Two kinds of component

Presentational pieces ship as .astro templates (badge, card, empty state). Interactive pieces ship as Lit Web Components (.ts) — framework-agnostic custom elements that work in any stack, which is what makes the system's output portable to whatever a dev team builds in. Browse all 66 in the component library.

Two distribution channels — runtime and intelligence

The hub distributes two different things, through two channels:

• Runtime (npm packages): @esa/tokens, @esa/ecology (the components), @esa/docs (this documentation shell), @esa/handoff (the dev-handoff exporter + inspector). Spokes depend on these via file: links.
• Intelligence (the spoke-kit Claude plugin): the skills, guardrail hooks, and workflow commands Claude uses when you work in a spoke. Distributed from this repo as a Claude Code plugin marketplace — every spoke's settings enable it, updates flow with a git push. See the Claude toolkit for the live inventory.

This split is the reason nothing drifts: code travels as packages, knowledge travels as a plugin, and both have exactly one source of truth — this repo.

The prototyping workflow

Day to day, you drive Claude with four verbs (full descriptions on the toolkit page):

1. /new-prototype — Claude interviews you in plain language, then composes the screen from the component library.
2. Iterate conversationally — "make the filters a sidebar", "this feels cramped".
3. /design-qa — an on-demand quality pass: design rules, token discipline, build checks.
4. /ship — syncs with teammates, builds, and publishes to the spoke's public site.

Guardrails run automatically: Claude is blocked from hand-rolling UI primitives a component already provides, and blocked from editing the hub out of a spoke session (/request-lego files the gap instead).

What this is for

Three jobs, all served by the same system: business-development demos (a credible product vision on a public URL — see Biochar Atlas), client alignment (working prototypes to react to, instead of static decks — see CB Fish), and dev handoff (every prototype compiles to clean HTML/CSS, and the handoff tooling exports de-scoped bundles with a token contract a dev team — or their AI — can re-implement on any stack).

The spokes today

Starting a new spoke takes one command — /spoke-init in the hub repo scaffolds it from the template, theme skeleton and guardrails included.