Skip to main contentSkip to design system navigation

TOKENS

Colour, type, spacing and border tokens live in app/css/theme.css. 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 elements

The 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 background

tertiary · 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#161b16

status · 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 dot

Other 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/font/local variables.

TokenUtilitySize
Token--text-xsUtilitytext-xsSize13px at every width
Token--text-smUtilitytext-smSize14px
Token--text-bodyUtilitytext-bodySize14px, reading text (git log, card copy); 13px stays for labels
Token--text-baseUtilitytext-baseSize16px
Token--text-lgUtilitytext-lgSize18px
Token--text-xlUtilitytext-xlSize20px
Token--text-2xlUtilitytext-2xlSize24px
Token--text-3xlUtilitytext-3xlSize32px
Token--text-4xlUtilitytext-4xlSize36px
Token--text-5xlUtilitytext-5xlSize48px
Token--text-7xlUtilitytext-7xlSize64px

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

TokenUtility stepSize
Token--spacing-1Utility step1Size4px
Token--spacing-2Utility step2Size8px
Token--spacing-3Utility step3Size12px
Token--spacing-4Utility step4Size16px
Token--spacing-6Utility step6Size24px
Token--spacing-8Utility step8Size32px
Token--spacing-12Utility step12Size48px
Token--spacing-16Utility step16Size64px
Token--spacing-targetUtility steptargetSize44px general control target
Token--spacing-target-compactUtility steptarget-compactSize28px compact control target
Token--spacing-target-pointerUtility steptarget-pointerSize36px row height of the section menu from 1024px with a fine pointer
Token--space-gutterUtility steppx-[var(--space-gutter)]Sizeclamp(16px, 4vw, 24px) page gutter
Token--space-page-topUtility stepn/aSize32px below 768, 48px from 768
Token--space-sectionUtility stepmb-[var(--space-section)]Size32px below 768, 48px from 768
Token--phiUtility stepn/aSize1.618, the golden ratio behind the phi spacing scale and the contact and guitar column splits
Token--phi-space-1Utility stepn/aSize8px, the base step of the phi scale
Token--phi-space-2Utility stepn/aSizeabout 13px, one phi step above the base
Token--phi-space-3Utility stepn/aSizeabout 21px, two phi steps above the base
Token--phi-space-4Utility stepn/aSizeabout 34px, three phi steps above the base
Token--phi-invUtility stepn/aSize0.618, one divided by phi
Token--phi-rootUtility stepn/aSize1.272, the square root of phi
Token--phi-text-1Utility stepn/aSize--text-xs times --phi-root: about 15px below 768px, 16.5px from 768px
Token--phi-pair-columnsUtility stepgrid-template-columnsSizeminmax(0, 1.618fr) minmax(0, 1fr), major column first
Token--phi-pair-columns-minor-firstUtility stepgrid-template-columnsSizethe same split with the minor column first
Token--phi-pair-flex-minorUtility stepflexSize0 0 calc((1 - var(--phi-inv)) * 100%), the minor share of a flex row
Token--text-section-titleUtility steptext-[length:var(--text-section-title)]Sizesection h2: 16px below 768, 18px from 768
Token--measure-pageUtility stepsafe-zoneSize1200px, the safe zone shared by the header, every page and the footer
Token--measure-readUtility stepn/aSize72ch, 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

TokenUtilityValue
Token--tracking-tightUtilitytracking-tightValue-0.03em, the dock labels below 360px
Token--tracking-2xsUtilitytracking-2xsValue0.02em
Token--tracking-xsUtilitytracking-xsValue0.04em
Token--tracking-smUtilitytracking-smValue0.05em
Token--tracking-mdUtilitytracking-mdValue0.06em
Token--tracking-lgUtilitytracking-lgValue0.08em
Token--tracking-xlUtilitytracking-xlValue0.1em
Token--tracking-2xlUtilitytracking-2xlValue0.12em
Token--tracking-3xlUtilitytracking-3xlValue0.14em
Token--tracking-4xlUtilitytracking-4xlValue0.16em
Token--tracking-5xlUtilitytracking-5xlValue0.18em

Stylesheets write letter-spacing: var(--tracking-xl); 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.

StepMin widthMax width (below)Usage
Step--viewport-narrowMin width360pxMax width (below)359.98pxUsagenarrowest phones
Step--viewport-phoneMin width480pxMax width (below)479.98pxUsagewide phones
Step--viewport-mdMin width768pxMax width (below)767.98pxUsagephone to tablet; matches MOBILE_BREAKPOINT_PX
Step--viewport-splitMin width900pxMax width (below)899.98pxUsagetwo-column splits
Step--viewport-lgMin width1024pxMax width (below)1023.98pxUsagetablet to desktop; the dock hides
Step--viewport-xlMin width1280pxMax width (below)1279.98pxUsagewide 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

TokenValueUsage
Token--border-widthValue1pxUsageBorders and dividers
Token--radius-noneValue0UsageSharp controls
Token--radius-controlValue2pxUsageMaximum control radius

Keyboard focus uses :focus-visible 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/css/base.css applies it to links, buttons, inputs, selects, summaries and tabbable elements, so a component does not restate it. pnpm lint:css-tokens fails a focus rule that writes its own width, color or offset, or that paints the ring on plain :focus.

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[data-motion="reduce"], and every reduction is keyed to that attribute in app/css/animations.css, crt.css, components-*.css and component logic. Check the affected animation rather than assuming one global rule disables all motion.

Module headers (components/responsive/Module) reveal text in character steps as they enter the viewport, driven by scroll position (animation-timeline: view() in components-scroll-type.css). 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 :root block of app/css/theme.css:

TokenValueUsage
Token--type-reveal-char-durationValue28msUsagetime per revealed character
Token--type-reveal-max-durationValue1.4sUsagecap on one element's reveal
Token--type-reveal-caret-widthValue0.6chUsagecaret width
Token--type-reveal-caret-heightValue1.05emUsagecaret height
Token--type-reveal-caret-blinkValue1.05sUsageone blink cycle
Token--type-reveal-caret-blinksValue3Usageblink cycles after the reveal
UtilityValueUsage
Utilityduration-[80ms]Value80msUsagemicro transitions (hover, press)
Utilityduration-100Value100msUsagefast UI feedback
Utilityduration-200Value200msUsagestandard transitions
Utilityease-outValueSharedUsageeasing used by Button and Field

Layers

Every z-index is a step of the --z-* scale in app/css/theme.css; a stylesheet writes z-index: var(--z-drawer) and markup writes z-(--z-topbar). pnpm lint:css-tokens fails a literal. Layers stack in this order:

Layerz-indexUsage
Layerrainz-index--z-rain (0)Usagethe Matrix rain canvas
LayerCRT layersz-index--z-crt-vignette (1) to --z-crt-beam (5)Usagevignette, scanlines, mask, noise, flicker, scan beam
Layerlocalz-index--z-local (1), --z-local-above (2)Usagestacking inside one component
Layercontentz-index--z-content (10), --z-content-raised (11)Usage.page-main, page content above the CRT overlay
Layertitle barz-index--z-title-bar (109)Usagethe phone title bar
Layerheader chromez-index--z-topbar (110)Usagethe desktop topbar and the phone status bar
Layerto topz-index--z-to-top (115)Usagethe scroll-to-top button
Layeroffline noticez-index--z-offline (118)Usagethe no-signal bar; the drawer and its scrim cover it
Layerdockz-index--z-dock (120)Usagebottom navigation dock
Layerscrimz-index--z-scrim (125)Usagethe drawer scrim behind the open menu
Layerposition linez-index--z-position-line (126)Usagethe side scroll-progress line below 1024px
Layerprogress linez-index--z-progress-line (127)Usagethe page-load bar on /links
Layerdrawerz-index--z-drawer (130)Usagethe section menu drawer
Layersystem failurez-index--z-sysfail (9998)Usagethe SYSTEM FAILURE plate
Layerskip linkz-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.

PrefixOwnerExamples
Prefix--eq-*Ownerthe EQ curve and spectrum (EqSpectrumStrip)Examplesplot and axis heights, bar gaps, curve stroke, level steps
Prefix--guitar-*Ownerthe guitar moduleExamplescolumn template, photo filters and ratio, arrow size
Prefix--mixer-*Ownerthe DAW mixerExampleschip width, chain rows, transport gap
Prefix--links-thumb-*Ownerthe /links cover frame (Cover frame)Examplescontrast, brightness, tint, reveal duration
Prefix--receipt-*Ownerthe project receipts listExamplesmetric, value and company column widths
Prefix--breakpoint-guitarOwnerthe guitar moduleExamplesthe one component-owned layout width (700px)