Circuit owner's guide
Everything from the download to your own palette, read from the files this theme ships.
- 1.1.0
- version
- 7
- pages
- 51
- components
- 71 × 2 modes
- tokens
- 4
- workflows
unzip circuit-1.1.0.zip
cd circuit-1.1.0
bun install
bun devThe download is a complete Next.js project, not a folder of snippets. It carries 7 routes, the token file, 51 components and the agent kit.
See the priceInstall
Three ways in: the zip, the shadcn registry, or your agent over MCP.
The artifact is versioned and immutable, so the file you get is circuit-1.1.0.zip. Unzip it, run the four commands above, and the site is on localhost:3000.
The link arrives with your license, and stays valid for every future version.
Every theme is a registry item the real shadcn CLI installs. Files land under src/tailthemes/circuit/, mirroring the tree below.
Circuit is paid, so the request has to carry your license key. Put it in TAILTHEMES_LICENSE_KEY in your .env.local, then add this to components.json. The CLI expands the variable and sends the key as a header, so it never enters a URL.
{
"registries": {
"@tailthemes": {
"url": "https://tailthemes.com/r/{name}.json",
"headers": {
"Authorization": "Bearer ${TAILTHEMES_LICENSE_KEY}"
}
}
}
}bunx shadcn add @tailthemes/circuitAn all-access key works on every slug. A single-theme key works on the theme it was bought for.
A registry item is JSON, so image assets cannot travel with it. Themes that import images need the zip as well.
Point any MCP client at https://tailthemes.com/api/mcp and your agent can read the manifest, both token tables and AGENTS.md before it touches a file.
the four toolsWhat unzips
One directory, laid out the way you would lay it out yourself.
every file
Three of these do the work: src/theme.css holds every design decision, AGENTS.md is the contract your agent reads first, and .claude/skills/ holds the 4 workflows it can run.
Screenshots are not in the download. They are generated by the publish pipeline and live on the listing, not in your project.
Using it
Every page is a plain component, and the tokens are scoped to one class.
- /Fourteen classes a week. Ten lines each.8 sections
- /scheduleThis week's sheets6 sections
- /programsWhat we coach6 sections
- /classTuesday 06:00 · Platform Room6 sections
- /coachesCoaching staff5 sections
- /membershipMembership6 sections
- /componentsThe parts, unassembled27 sections
Tokens are declared on .tt-circuit as well as :root, so an install cannot repaint components you already have. Wrap the page in <div className="tt-circuit"> and everything inside picks them up.
Dark mode is a dark class on <html>. There is no second stylesheet and no dark: utility in the components.
The HTML edition
The same site again, with no framework under it.
Everything under html/ is a second, independently authored edition of the theme. html/dist/ is 7 compiled routes with local fonts and vanilla JavaScript — copy it to any static host and it is live, with no build step and no Node on the server. html/src/ is the Nunjucks source those routes compile from.
bun run build:html recompiles html/dist/ after you change the source or the tokens. bun run preview:html serves the compiled edition locally. Both ship in the download's package.json, backed by the two files in scripts/.
One token file drives both editions, so a rebrand made in src/theme.css reaches the HTML edition the next time you run the build — dist/ carries compiled CSS and never updates by itself.
The two editions are kept in step by the publish gate: every route in the manifest must have a compiled counterpart before a version ships, so the 7 pages you saw above exist in both.
Making it yours
Tokens are the API: change the values, never the names.
- Edit the values. All 71 tokens live in src/theme.css, in a light block and a dark one. Nothing in src/components/ carries a colour.
- Watch it land. Open /components. The styleguide reads every swatch, type step and radius live, so you see what the change did to the whole system at once.
- Re-check contrast. Run the check-quality workflow. The palette ships verified to WCAG AA in both modes and a rebrand should keep it there.
- .claude/skills/add-page
Circuit ships seven routes: /, /schedule, /programs, /class, /coaches, /membership, /components. Adding one is composition, not a framework change.
- .claude/skills/add-section
A section is one file in src/components/, self-contained (no imports from another section — shared behaviour lives in src/components/ui/), composing primitives and reading the fixture directly.
- .claude/skills/check-quality
Run these in order. Each one catches a different class of defect; skipping ahead to the last one hides where a failure actually started.
- .claude/skills/rebrand
Circuit is designed so a rebrand touches two files: src/theme.css (every colour, size, radius and face) and src/fixtures/ashgrove.ts (the gym's name, rooms, coaches, tiers and weekly schedule). No component sets a colour, a size, or a schedule number by hand.
Those summaries are the files' own opening lines. They are written against this repo, so where one names themes/circuit/ your copy has the project root instead.
For your agent
The theme brought its own rules, so nothing has to be reverse-engineered.
AGENTS.md is 332 lines of invariants, the file map, the type and spacing scale, and what never to touch. It opens like this.
# Circuit — the rules
The contract any agent works under inside `themes/circuit/`. It never
contradicts `themes/CONTRACT.md`; where it looks like it might, the CONTRACT
wins and this file is the bug.
| | |
|---|---|
| **Fiction** | Ashgrove Barbell Club, a strength-and-conditioning gym in a converted 1930s tram depot on the Bristol-to-Bath railway path, Fishponds, Bristol. Domain: **fitness / gym**. |
| **Positioning** | For the independent gym or boutique studio owner, or the freelancer/agency building their site, who has already seen a decorative weekly-calendar screenshot on every competitor's site — unlike the stock gym template, which sells "book a class" as a widget, Circuit sells the class itself: the roll sheet fills the way the coaches actually run it, line by line, until the lines are gone. |
| **Register** | Flat, specific, unsold. A class listing states day, time, coach, room and capacity, and stops. No "join our fitness family." |
| **Motion personality** | **Near-still, two exceptions, both reader-driven.** No entrance animation anywhere, no timers, no loops. (1) `/class`'s cutoff-rule redraw on a live countdown to the session's start time (`.circuit-cutoff-line`). (2) The home hero's eight-frame lift sequence, indexed by scroll position over the document's first 45vh (`.circuit-lift`, `ui/lift-sequence.tsx`) — added on the owner's instruction, 2026-09-07. Neither runs on its own: the second one's pause control is the scroll bar. Under `prefers-reduced-motion` both render at their resolved state, and the hero's is frame 1, a finished photograph. Focus is instant. |
| **Signature** | **The roll sheet** — see below. |
| **Sanctioned deviation** | **One off-ladder value**: the ruled-line pitch inside `.sheet-line` rows — see below. |
| **Imagery** | Three coach portraits, one equipment detail, three programme plates, one wide floor plate, and the hero's eight-frame lift burst — all generated by us. See § Imagery. |
## The signature — the roll sheet
> Every class is a fixed number of ruled lines, set by the room's own hard
> integer capacity, filled top to bottom in booking order. A dashed rule
> crosses the sheet at the session's own start time — names above it carry an
> arrival stamp and a checkmark, names below it carry only the stamp. A class
> is full when the lines are gone.
`rollFor(session)` in `src/fixtures/ashgrove.ts` is the only way to read a
session's roll sheet, and it **throws at build time** on three conditions:
1. An oversold session — more bookings than the room's hard capacity.
2. A booking whose membership tier cannot access the session's room (grafted
from the design-debate's Position proposal — `roomAccess` is checked
mechanically, never asserted in copy).
3. A coach or a room double-booked anywhere in the whole weekly fixture.
It runs at three escalating renderings, in information kind rather than size
(`ops/design/outline-circuit-2026-09-06.md` §5b): **the count** (`/`, hero
scale — "7/10" plus a compact tick row, no names), **the strip**
(`/schedule` — the tick row alone, scanned across a week), and **the full
sheet** (`/class` — every line, named, timestamped, the cutoff rule drawn).The kit is plain markdown, so the work continues on your machine and your own account. Nothing calls back here.