Lumina owner's guide
Everything from the download to your own palette, read from the files this theme ships.
- 1.0.0
- version
- 8
- pages
- 33
- components
- 124 × 2 modes
- tokens
- 4
- workflows
unzip lumina-1.0.0.zip
cd lumina-1.0.0
bun install
bun devThe download is a complete Next.js project, not a folder of snippets. It carries 8 routes, the token file, 33 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 lumina-1.0.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/lumina/, mirroring the tree below.
Lumina 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/luminaAn 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.
- /Lumina Edu — language school7 sections
- /skillsProfessional skills academy7 sections
- /tutoringTutoring centre7 sections
- /teamsCorporate training7 sections
- /programsEvery program — the full matchboard4 sections
- /programOne program — the decision page7 sections
- /instructorsThe instructors — the ruled directory3 sections
- /componentsThe parts — the drawn style guide18 sections
Tokens are declared on .tt-lumina as well as :root, so an install cannot repaint components you already have. Wrap the page in <div className="tt-lumina"> 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 8 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 8 pages you saw above exist in both.
Making it yours
Tokens are the API: change the values, never the names.
- Edit the values. All 124 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
A route is one file in src/app/ that composes sections and does nothing else.
- .claude/skills/add-section
A section is one file in src/components/. It imports primitives from src/components/ui/, data and derivations from src/fixtures/lumina.ts, and nothing else.
- .claude/skills/check-quality
Run these in order. Each catches a different class of defect, and skipping to the last one hides where a failure started.
- .claude/skills/rebrand
A rebrand touches three files and no component:
Those summaries are the files' own opening lines. They are written against this repo, so where one names themes/lumina/ 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 654 lines of invariants, the file map, the type and spacing scale, and what never to touch. It opens like this.
# AGENTS.md — Lumina
Rules for any agent (or human) editing this theme. They are not style
suggestions; the publish gate and the extension skills in `.claude/skills/`
assume them.
The direction is `ops/design/lumina-2026-09-19.md` — Phase 0 is the frame,
Phase 1 the token record and every contrast number in this file.
## The four declarations
| | |
|---|---|
| **Signature** | **The sentence Matchboard.** The page's H1 *is* the form: *"I want to learn **[Spanish]** at **[beginner]** level, **[in person]**, starting in **[January]**."* Four of its words are real controls, each with a 10px mono field label above it and a 4px Signal underline beneath, and the departure board and week grid below are the answer to whatever the sentence currently says. It recurs on `/`, `/skills`, `/tutoring`, `/teams` and `/programs` — **five different sentences**, not one component with the nouns swapped. It does not transplant: it needs a catalog whose every row is described by the same four facts, so that a sentence can be a query and a table can be its answer. The departure board is the *second* device and deliberately not the signature — it is the answer half, and more portable than it is distinctive. |
| **Sanctioned deviation** | **Opener variety (P-7) is broken on purpose across the four vertical landings.** `/`, `/skills`, `/tutoring` and `/teams` all open with the sentence hero, because that is the product: one matchboard carrying a language school, a cohort academy, a parent booking for a year-10 and a training manager buying twelve seats. The rule is honoured on every interior route — `/programs` opens with the full matchboard and its filter rows, `/program` with the ink decision band, `/instructors` with the ruled monogram grid, `/components` with the token sheet. **Exactly one deviation of this kind — do not add a second.** |
| **Register** | **Plain and decisive** (`/content-pass`). Short declaratives; the sentence carries the idea and nothing repeats it. Second person for the reader. No urgency, no seat counts, no accreditation, no testimonials — a school that has to say it is good is a school that cannot show a timetable. |
| **Motion personality** | **Two animations in the whole system, and the style guide says so as a rule rather than an inventory.** `lumina-rise` (the hero arriving once on load, the facts strip 250ms behind it) and `lumina-drift` (the greeting ribbon behind the language hero, 48s linear, `aria-hidden`). Nothing else on the page ever moves. Hover and press feedback is 120ms colour; a disclosure opens in 150ms. Both animations stop under `prefers-reduced-motion`. |The kit is plain markdown, so the work continues on your machine and your own account. Nothing calls back here.