Themes
Pick a theme on this site, watch both kits change live, then commit it to your project with one code.
Every page of this site has a theme bar at the bottom. Pick a preset or a brand colour and the whole site changes, along with every live phone and browser frame in it: those are the real kits, re-themed as you pick. The theme studio has every control, next to a phone and a browser, with undo, and a shuffle that rolls new values for everything you haven't locked (lock the colour, shuffle the type).
Nothing you pick here touches a project until you use the theme: the bar and the studio hand you a short
code (pk1-…, or pk2-… once you change the typeset) that reproduces the theme exactly, and one command writes it into tokens/tokens.json.
What a theme sets
| Options | |
|---|---|
| Brand colour | Any colour. The swatches are Tailwind's ramps; any other colour generates an 11-step ramp in OKLCH around it. |
| Neutral | Zinc, neutral, slate, stone, gray, or a grey tinted with the brand hue |
| Radius | None to 2xl, and whether the native kit's buttons and chips are pills or follow the radius (web buttons always follow it) |
| Type | A heading, a body and a mono font from a curated list of Google Fonts |
| Typeset | Body text size (14–18px; every text size scales with it), leading (line height), and for long-form text, flow (space between paragraphs) and measure (the longest line) |
| Icons | Lucide's stroke: thin, regular or bold |
| Depth | Flat, soft, raised or hard (offset) shadows on cards, sheets and menus |
| Density | Compact, comfortable or spacious: control heights and padding in the native kit, the whole spacing scale on the web |
| Border | Hairline, regular or heavy outlines |
Status colours (success, warning, destructive, info) stay as they are.
Contrast is never your problem
A brand colour can look right and still fail as text: amber links, yellow buttons, a blue that's fine on white
and too dark on the dark theme. The generator checks every pairing the kits render, in both themes (the same
gate as tokens:build, plus tones on muted surfaces), and moves anything that fails: same hue, the smallest
lightness change that passes WCAG AA. The bar shows how many colours it adjusted; open it to see each one,
before and after. A theme from the picker can never fail the build.
Use a theme
Use theme gives you four ways to take it with you:
-
Ask your coding agent. Copy the prompt; the kits'
apply-themeskill applies the code, runs the checks and tells you what it adjusted. -
In the Protokit repo, from the root, so the native kit, the web kit and this site stay one brand:
npm run theme:apply -- pk1-XXXXXXXXXXXX -
In a kit you copied out, from the app folder:
npx kit-tokens theme apply pk1-XXXXXXXXXXXX -
Share a link (
/themes/?t=<code>) to show someone the theme, or download tokens.json and drop it in.
apply only rewrites what a theme owns: the brand and neutral ramps, the semantic colours, radius, fonts,
shadows, borders, icon stroke, control sizes and the typeset. Spacing, the base type scale, motion and your
descriptions stay.
It records the theme in tokens.json, so kit-tokens theme show (and each kit's Foundations page) can say
which theme is applied, and whether anyone has edited its tokens by hand since. apply won't overwrite hand
edits without --force.
npx kit-tokens theme presets # the presets and their codes
npx kit-tokens theme show # the applied theme
npx kit-tokens theme apply calm --dry-runCodes
A code is the whole recipe, packed into twelve characters with a checksum, so a typo is caught rather than
quietly giving you a different theme. The same code produces the same theme in every version of
@itshendri/kit-tokens that reads it; a generator change that would alter a theme comes with a new code
version.