Repository navigation
ADR 0001
github-actions[bot] edited this page Nov 21, 2026
·
1 revision
Status: accepted · Built: planned · Date: 2026-11-18
Decision only; tokens are built in the foundation PR.
Spotstrap should serve eight projects: two static Astro sites, spotcraft (SvelteKit and Astro), lifts and bars (TanStack Start and Expo), sokobanko (Nuxt), tagtape (Electron and Astro) and vinskiano (TanStack Start). They use two token vocabularies today:
- shadcn's names (
background,foreground,primary,muted,border,ring…): spotcraft, sokobanko, tagtape, vinskiano. - Home-grown names (
bg,surface,raised,line,text,muted,accent,accent-ink,fail): the two websites, lifts and bars. Bars can't adopt React Native Reusables because of the mismatch.
Values are hex in some projects and oklch in others. Dark mode follows the system everywhere
except sokobanko, which has a toggle and a .dark class. Brand colors are also repeated
outside CSS: theme-color meta tags, favicons, manifests, icon scripts and a Pixi palette.
-
Names are shadcn's:
background,foreground,card,popover,primary,secondary,muted,accent,destructive(each with-foregroundwhere shadcn has one),border,input,ring,chart-1…chart-5and thesidebar-*set. Spotstrap adds:-
surfaceandraised, the two levels abovebackground; - font roles
--font-sans,--font-display,--font-mono; - the size and type tokens of ADR 0003.
-
-
Values are oklch and static. No
calc(),var()chains orcolor-mix()in theme values, so Uniwind (React Native) parses the same file. -
Dark mode follows the system by default (
prefers-color-scheme). Projects with a toggle opt in to a.darkclass variant instead; the theme values are the same. -
A brand theme sets values only: accent hue and values, the neutral hue,
--radius, the fonts, and whether shadows are on. It never adds or renames tokens. Spotstrap ships a neutral theme and a preset for each project's current look. -
Tokens are also exported as JSON (
spotstrap/tokens.json), resolved per theme and mode, for meta tags, favicons, manifests and canvas code.
- shadcn components in React, Svelte and Vue, and React Native Reusables, work without renaming anything.
- The two websites, lifts and bars rename their tokens when they adopt spotstrap
(
bg→background,text→foreground,accent→primary,fail→destructive,line→border). - Hex values convert to oklch once, in the brand presets.
- A theme can't invent tokens, so components can rely on every token existing.
Published from docs/. Edit the files there; changes here are overwritten.