TOKENS
Colour, type, spacing and border tokens live in app/.
Tailwind's @theme generates utilities from these custom properties. Swatches
read their values directly from that file.
Color
Use semantic roles for text and emphasis. The ordinal families remain available for surfaces and existing consumers; code syntax uses the green and grey ramps.
Semantic roles
--color-text#e6ffe6Body text on the page and terminal surfaces--color-text-secondary#a1b3a1Labels, captions and secondary text at full opacity--color-green#00ff41Headings, accents and interactive elementsThe page background is secondary-950. Body text uses text (the same mint
as tertiary-50); signal emphasis uses green (the same green as primary-500).
Use text-secondary for new secondary text instead of primary-300,
primary-400 or tertiary-400. Those shades remain available for existing consumers.
primary · green (the brand)
--color-primary-50#eafff0--color-primary-100#c4ffd8--color-primary-200#8ff2b2--color-primary-300#5ae07bExisting annotations; use text-secondary for new text--color-primary-400#4ade80Existing labels; use text-secondary for new text--color-primary-500#00ff41Headings, accents, interactive elements--color-primary-600#28c840--color-primary-700#1e9b32--color-primary-800#166f24--color-primary-900#0c4015--color-primary-subtle#00ff4166Borders, dividers (green 40%)--color-primary-border#00ff4133Decorative divider (green 20%, 1.5:1); never a control edge--color-primary-faint#00ff411fVery subtle background (green 12%)--color-primary-quiet#00ff411aHover background (green 10%)secondary · black (surfaces)
--color-secondary-50#e8e8e8--color-secondary-100#cfcfcf--color-secondary-200#a8a8a8--color-secondary-300#808080--color-secondary-400#5c5c5c--color-secondary-500#3d3d3d--color-secondary-600#262626--color-secondary-700#141414--color-secondary-800#0a0a0a--color-secondary-900#050505Shell / terminal backgrounds--color-secondary-950#000000Page backgroundtertiary · white (foreground)
--color-tertiary-50#e6ffe6Body text (19.8:1 contrast on black)--color-tertiary-100#dbf2db--color-tertiary-200#c4d9c4--color-tertiary-300#a9bda9--color-tertiary-400#8a9d8a--color-tertiary-500#6b7c6b--color-tertiary-600#515f51--color-tertiary-700#3a463a--color-tertiary-800#262f26--color-tertiary-900#161b16status · window chrome and alerts
Two off-ramp hues exist, and each carries a meaning no green can. They are the only colors outside the green and grey ramps.
--color-quinary-500#febc2eWindow-chrome minimize dot--color-senary-300#ff8a8aAlerts: form errors, shell errors, mixer clip LED--color-senary-500#ff5f57Window-chrome close dotOther color tokens in the same file: the --color-glow-02 to --color-glow-60 ramp (signal green at 2% to 60% alpha, for glows and washes), --color-eq-bar-top and --color-eq-bar-bottom (the EQ spectrum gradient), --color-print-ink, --color-print-paper and --color-print-rule (print sheet), and --color-crt-phosphor-red and --color-crt-phosphor-blue (the CRT sub-pixel mask). The Matrix Rain colors --color-rain-head and --color-rain-body map to primary-800 and primary-900. Components reference them through utilities or var(); no stylesheet writes a raw color.
Type Scale
The base h1 rule uses --font-display, Inter at weight 900. Body text, controls
and other base headings use --font-mono, JetBrains Mono. Consumers can override these rules. Both stacks reference
the existing next/ variables.
| Token | Utility | Size |
|---|---|---|
Token--text-xs | Utilitytext-xs | Size13px at every width |
Token--text-sm | Utilitytext-sm | Size14px |
Token--text-body | Utilitytext-body | Size14px, reading text (git log, card copy); 13px stays for labels |
Token--text-base | Utilitytext-base | Size16px |
Token--text-lg | Utilitytext-lg | Size18px |
Token--text-xl | Utilitytext-xl | Size20px |
Token--text-2xl | Utilitytext-2xl | Size24px |
Token--text-3xl | Utilitytext-3xl | Size32px |
Token--text-4xl | Utilitytext-4xl | Size36px |
Token--text-5xl | Utilitytext-5xl | Size48px |
Token--text-7xl | Utilitytext-7xl | Size64px |
--text-min is 13px at every width, phones included. --text-xs uses that floor.
Use these tokens for small text; fixed pixel utilities do not inherit the floor.
Sizes use rem units so they follow the reader's default font size.
The base h1 is 32px, rising to 36px at 1280px. h2 is 20px, rising to
24px at 768px. h3 is 18px. Consumers can select larger steps for display text.
Spacing
| Token | Utility step | Size |
|---|---|---|
Token--spacing-1 | Utility step1 | Size4px |
Token--spacing-2 | Utility step2 | Size8px |
Token--spacing-3 | Utility step3 | Size12px |
Token--spacing-4 | Utility step4 | Size16px |
Token--spacing-6 | Utility step6 | Size24px |
Token--spacing-8 | Utility step8 | Size32px |
Token--spacing-12 | Utility step12 | Size48px |
Token--spacing-16 | Utility step16 | Size64px |
Token--spacing-target | Utility steptarget | Size44px general control target |
Token--spacing-target-compact | Utility steptarget-compact | Size28px compact control target |
Token--spacing-target-pointer | Utility steptarget-pointer | Size36px row height of the section menu from 1024px with a fine pointer |
Token--space-gutter | Utility steppx-[ | Sizeclamp(16px, 4vw, 24px) page gutter |
Token--space-page-top | Utility stepn/a | Size32px below 768, 48px from 768 |
Token--space-section | Utility stepmb-[ | Size32px below 768, 48px from 768 |
Token--phi | Utility stepn/a | Size1.618, the golden ratio behind the phi spacing scale and the contact and guitar column splits |
Token--phi-space-1 | Utility stepn/a | Size8px, the base step of the phi scale |
Token--phi-space-2 | Utility stepn/a | Sizeabout 13px, one phi step above the base |
Token--phi-space-3 | Utility stepn/a | Sizeabout 21px, two phi steps above the base |
Token--phi-space-4 | Utility stepn/a | Sizeabout 34px, three phi steps above the base |
Token--phi-inv | Utility stepn/a | Size0.618, one divided by phi |
Token--phi-root | Utility stepn/a | Size1.272, the square root of phi |
Token--phi-text-1 | Utility stepn/a | Size--text-xs times --phi-root: about 15px below 768px, 16.5px from 768px |
Token--phi-pair-columns | Utility stepgrid-template-columns | Sizeminmax(0, 1., major column first |
Token--phi-pair-columns-minor-first | Utility stepgrid-template-columns | Sizethe same split with the minor column first |
Token--phi-pair-flex-minor | Utility stepflex | Size0 0 calc((1 - var(--phi-inv)) * 100%), the minor share of a flex row |
Token--text-section-title | Utility steptext-[ | Sizesection h2: 16px below 768, 18px from 768 |
Token--measure-page | Utility stepsafe-zone | Size1200px, the safe zone shared by the header, every page and the footer |
Token--measure-read | Utility stepn/a | Size72ch, the line length of text blocks |
Small and medium Buttons have a 44px minimum height. Small Buttons use 10px horizontal padding; medium and large Buttons use 14px. Large Buttons have a 52px minimum height. CopyButton has a 44px minimum width and height in every state.
Letter Spacing
| Token | Utility | Value |
|---|---|---|
Token--tracking-tight | Utilitytracking-tight | Value-0.03em, the dock labels below 360px |
Token--tracking-2xs | Utilitytracking-2xs | Value0.02em |
Token--tracking-xs | Utilitytracking-xs | Value0.04em |
Token--tracking-sm | Utilitytracking-sm | Value0.05em |
Token--tracking-md | Utilitytracking-md | Value0.06em |
Token--tracking-lg | Utilitytracking-lg | Value0.08em |
Token--tracking-xl | Utilitytracking-xl | Value0.1em |
Token--tracking-2xl | Utilitytracking-2xl | Value0.12em |
Token--tracking-3xl | Utilitytracking-3xl | Value0.14em |
Token--tracking-4xl | Utilitytracking-4xl | Value0.16em |
Token--tracking-5xl | Utilitytracking-5xl | Value0.18em |
Stylesheets write letter-spacing:; markup writes tracking-xl.
Viewports
A media query cannot read a custom property, so stylesheets write theme(--viewport-md) and Tailwind
substitutes the width at build time. Each step has a below twin 0.02px lower, so max-width ends
where the next min-width starts and no width matches both or neither.
| Step | Min width | Max width (below) | Usage |
|---|---|---|---|
Step--viewport-narrow | Min width360px | Max width (below)359.98px | Usagenarrowest phones |
Step--viewport-phone | Min width480px | Max width (below)479.98px | Usagewide phones |
Step--viewport-md | Min width768px | Max width (below)767.98px | Usagephone to tablet; matches MOBILE_ |
Step--viewport-split | Min width900px | Max width (below)899.98px | Usagetwo-column splits |
Step--viewport-lg | Min width1024px | Max width (below)1023.98px | Usagetablet to desktop; the dock hides |
Step--viewport-xl | Min width1280px | Max width (below)1279.98px | Usagewide desktop |
A few queries stay literal because they mark one component's measured ladder, not a layout step: the
content-visibility size estimates (340, 412 and 600px), the contact grid steps (512 and 640px) and
three one-off folds (389.98, 599.98 and 1199.98px).
Borders
| Token | Value | Usage |
|---|---|---|
Token--border-width | Value1px | UsageBorders and dividers |
Token--radius-none | Value0 | UsageSharp controls |
Token--radius-control | Value2px | UsageMaximum control radius |
Keyboard focus uses : and one ring: --focus-ring (a 2px solid signal outline) with
--focus-ring-offset (2px), or --focus-ring-offset-inset (-2px) for a control that sits flush against its
neighbours. app/ applies it to links, buttons, inputs, selects, summaries and tabbable
elements, so a component does not restate it. pnpm lint: fails a focus rule that writes its
own width, color or offset, or that paints the ring on plain :.
Motion
Components use Tailwind duration and easing utilities, plus named CSS animations.
The MOTION switch is the single control. A first visit starts with motion on, even
when the operating system asks for reduced motion. Switching it off sets
body[, and every reduction is keyed to that attribute in
app/, crt., components-*. and component logic. Check
the affected animation rather than assuming one global rule disables all motion.
Module headers (components/) reveal text in character steps as they enter
the viewport, driven by scroll position (animation-timeline: in
components-scroll-type.). Their caret blinks four times and then stays solid. The MOTION
switch disables this effect. Browsers without scroll-driven animation support show static headers.
Elements marked data-type-reveal (panel titles with reveal, reading-view headings, footer
lines) use a second mechanism. The TypeReveal island, mounted once by GlobalMotion in the
root layout, adds type-reveal-ready to <html> and a class to each element when it first enters
the viewport. The text then reveals one character per step, and the caret blinks and disappears.
With the MOTION switch off, or without IntersectionObserver, every element shows at once. The
timing comes from tokens in the : block of app/:
| Token | Value | Usage |
|---|---|---|
Token--type-reveal-char-duration | Value28ms | Usagetime per revealed character |
Token--type-reveal-max-duration | Value1.4s | Usagecap on one element's reveal |
Token--type-reveal-caret-width | Value0.6ch | Usagecaret width |
Token--type-reveal-caret-height | Value1.05em | Usagecaret height |
Token--type-reveal-caret-blink | Value1.05s | Usageone blink cycle |
Token--type-reveal-caret-blinks | Value3 | Usageblink cycles after the reveal |
| Utility | Value | Usage |
|---|---|---|
Utilityduration-[ | Value80ms | Usagemicro transitions (hover, press) |
Utilityduration-100 | Value100ms | Usagefast UI feedback |
Utilityduration-200 | Value200ms | Usagestandard transitions |
Utilityease-out | ValueShared | Usageeasing used by Button and Field |
Layers
Every z-index is a step of the --z-* scale in app/; a stylesheet writes
z-index: and markup writes z-(--z-topbar). pnpm lint: fails a literal.
Layers stack in this order:
| Layer | z-index | Usage |
|---|---|---|
| Layerrain | z-index--z-rain (0) | Usagethe Matrix rain canvas |
| LayerCRT layers | z-index--z-crt-vignette (1) to --z-crt-beam (5) | Usagevignette, scanlines, mask, noise, flicker, scan beam |
| Layerlocal | z-index--z-local (1), --z-local-above (2) | Usagestacking inside one component |
| Layercontent | z-index--z-content (10), --z-content-raised (11) | Usage., page content above the CRT overlay |
| Layertitle bar | z-index--z-title-bar (109) | Usagethe phone title bar |
| Layerheader chrome | z-index--z-topbar (110) | Usagethe desktop topbar and the phone status bar |
| Layerto top | z-index--z-to-top (115) | Usagethe scroll-to-top button |
| Layeroffline notice | z-index--z-offline (118) | Usagethe no-signal bar; the drawer and its scrim cover it |
| Layerdock | z-index--z-dock (120) | Usagebottom navigation dock |
| Layerscrim | z-index--z-scrim (125) | Usagethe drawer scrim behind the open menu |
| Layerposition line | z-index--z-position-line (126) | Usagethe side scroll-progress line below 1024px |
| Layerprogress line | z-index--z-progress-line (127) | Usagethe page-load bar on / |
| Layerdrawer | z-index--z-drawer (130) | Usagethe section menu drawer |
| Layersystem failure | z-index--z-sysfail (9998) | Usagethe SYSTEM FAILURE plate |
| Layerskip link | z-index--z-skip-link (9999) | Usageskip-to-content link, always on top |
Component tokens
The @theme block also holds tokens scoped to one component. They are not a shared vocabulary, so
a new component declares its own rather than reusing another's.
| Prefix | Owner | Examples |
|---|---|---|
Prefix--eq-* | Ownerthe EQ curve and spectrum (EqSpectrumStrip) | Examplesplot and axis heights, bar gaps, curve stroke, level steps |
Prefix--guitar-* | Ownerthe guitar module | Examplescolumn template, photo filters and ratio, arrow size |
Prefix--mixer-* | Ownerthe DAW mixer | Exampleschip width, chain rows, transport gap |
Prefix--links-thumb-* | Ownerthe / cover frame (Cover frame) | Examplescontrast, brightness, tint, reveal duration |
Prefix--receipt-* | Ownerthe project receipts list | Examplesmetric, value and company column widths |
Prefix--breakpoint-guitar | Ownerthe guitar module | Examplesthe one component-owned layout width (700px) |