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-primary) 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.

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 64 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.