Case study · Phantom · The design system behind At Odd Hours
Phantom: one design system, five brands, two platforms, and a gate that proves each build matches.
Phantom is the system behind what I make at At Odd Hours: two Android apps, a shop site and the studio's own site, each with its own brand on the same components. One contract per component sits above the code, and the checks fail when a build drifts from it.

- Design Tokens
- DTCG
- Component Contracts
- Base UI
- Jetpack Compose
- Multi-brand
- Theming Axes
- Accessibility
- Storybook
- MCP / AI tooling
- Android
- Nx Monorepo
The problem you’re reading about
I make things after hours under one name, At Odd Hours. Right now that is two Android apps, a small shop with a web site, and the studio's own site with its first game on it. Each one wants its own look. None of them wants its own button.
Before Phantom, every product made the same decisions again: spacing, type, color, how a field shows an error, what a disabled button does with focus. Each copy was a little different, and the differences were not choices. They were drift.
Component libraries do not solve this on their own. A library shows you components. It does not say what a component promises: which props it has, which states it can be in, which tokens each part reads, what a screen reader is told. Without that promise written down, there is no way to check that the Android build matches the web build, or that a brand change left the rules alone. And an AI assistant asked to build a screen with the system has nothing to read except the code it is about to copy from.
Approach
Phantom puts a contract above the code. A contract is one JSON file per component that names its props, events and states, its anatomy part by part with the tokens each part reads, and its accessibility rules: the element, the role, the keyboard behavior, the minimum hit area. It names no library. It says what a button is, not how React or Compose makes one.
The contract schema descends from Southleft's open-source ds-contracts-poc, which is MIT licensed. Phantom adds platforms, the theming axes, tokens that change per prop value and per state, and a fuller accessibility block.
Underneath the contracts is one token source in the W3C design token format, in four tiers: raw values, semantic roles, recipes, and component hooks. Nine axes change what a role resolves to: brand, platform, color scheme, contrast, appearance, shape, density, text size and motion. On the web, eight of them are a data attribute you can put on any element, so a card can be dark and compact inside a light, comfortable page. Platform is fixed by the build.
Above the contracts are the implementations and the gates. The web library is built on Base UI for behavior and accessibility, with Phantom supplying the look as a skin. The Android library is Jetpack Compose with no Material. An adapter map names the library for each platform, so the contracts never have to. Each implementation has a gate: a plain script with numbered codes that fails when the code reads a token the contract does not list, skips one it does, uses a raw value, or misses a prop. The same contracts and tokens are served to any LLM through an MCP server, so an assistant reads the real system instead of guessing.
What I rejected
- Generating the code from the contract. A generator still has to be proven right, and the proof is the same gate either way. Writing the implementations by hand and checking them keeps the contract honest about what it promises, and keeps each platform idiomatic.
- Material 3 on Android. It would have brought its own tokens, its own shapes and its own idea of a button, and the gate would have spent its life excusing them.
- One copied theme per brand. Five copies of the tokens would drift the moment one got a fix. A brand in Phantom is a single file that points the primary palette at a hue ramp, plus a preset.
- Figma as the source of truth. Figma gets the tokens as variables, built from the same source, and the Figma components are checked by eye against the contract for now. The contract stays above both.
Build
8 phases. Each one is a discrete deliverable that ships before the next starts — token foundation first, then the system makes everything above it possible.
- 01
One token source, four tiers
Every token lives in one folder of W3C-format JSON. Raw values are allowed in the first tier only. Every token above it is a reference, pointing down or across the tiers and never up. Semantic roles say what a value is for, recipes are the few values that move with the axes, and component hooks are the values one component is allowed to differ on. Ten structure tests enforce the ladder: known tiers, no raw values above tier one, no cycles, every token typed.
Evidence · 1,167 tokens: 239 raw values, 136 semantic roles, 9 recipes, 783 component hooks across 43 component files.
Phantom, from one source to two platforms
Select any stage to trace what reaches it and what it reaches.
Thirteen stages. The contracts are fed by nothing: they sit above the code and feed the gates. The dashed
RandCedges are the gates reporting back to the React and Compose libraries, andcheck_contractis the same gate served to an assistant through the MCP server. - 02
Nine axes that compose on any subtree
An axis is a folder of override files, one per value, and each file may only override base tokens, only with references. When two axes touch the same token, only one of them may bind it to a raw value; the other remaps it to a role. That one rule is what lets more contrast work under either color scheme without a third file for the pair. On the web each axis is an attribute, data-ph-brand, data-ph-density and so on, and the build writes combined blocks for the pairs that share tokens, so the override still reaches the component tier when a dark card sits inside a light page. Two tests prove the nesting works in both orders.
Evidence · Axes: brand (5 values), platform (2), color-scheme (2), contrast (2), appearance (3), shape (3), density (3), text-size (3), motion (3). Eight presets name an axis tuple, including easy-read: large text, more contrast, reduced motion, comfortable density, in one switch.

One attribute on one element. The dark, compact card inside a light page resolves every token it reads, down to the component tier. - 03
One build, four outputs
The build resolves the source once and writes CSS custom properties with one block per axis value, JSON, a typed TypeScript module, and Kotlin. The Kotlin file has one property per token and an enum per axis, and the Android resources include a window theme per preset, so an app launches in the right colors before Compose has drawn anything. The Compose library reads the generated Kotlin straight from the tokens package, so there is no copy to go stale. One environment variable renames every variable and attribute for a white-label build.
Evidence · tokens.css at 2,784 lines with 33 attribute blocks. PhantomTokens.kt with 1,167 properties. Eight Android window themes. A test asserts every token has a Kotlin property and every axis an enum.

One token, followed through the build. The source names a role; CSS and Kotlin each resolve it per mode, and the Android theme reads the same output so an app launches in its preset's colors. - 04
Contracts, and a gate that proves itself
Forty-four contracts, from button to data table, written by hand against a schema that names no library. The contract gate has 26 numbered codes. It checks that every token a contract reads exists in the built tokens, that no contract reads a raw value or another component's hooks, that a component hook nobody reads does not exist, that per-prop token maps only name real props and real values, that interactive parts declare keyboard behavior and a focus ring, and that the adapter map agrees with the installed library down to its version and its exported parts. The gate's own test holds 35 contracts broken on purpose, one for each way of being wrong, and fails if any code has no case that makes it fire.
Evidence · 26 codes, 35 mutation cases, one valid example contract. Runs in under a second as part of the build.

A planted error. One raw hex color in button.css, and the gate names the code, the line and the fix. The gate's own tests plant errors the same way. - 05
React on Base UI, the look as a skin
Base UI supplies behavior and accessibility: focus management, keyboard handling, the ARIA wiring. Phantom supplies the look as a skin, set by a provider and a data attribute on each component's root, so a wireframe section can sit inside a finished page. The React gate checks each component's CSS against its contract in both directions: a token the contract lists but the CSS never reads is a dropped decision, and a token the CSS reads but the contract does not list is an undocumented one. Both fail. Props are checked with the real TypeScript checker, so a prop hidden behind an extended type still counts. A raw value in CSS fails unless the line carries a written reason.
Evidence · 44 components, 152 tests, 28 of them run through axe. Three skins: default, wireframe and none, where none is raw Base UI with no CSS at all.

Every story renders under every axis and skin from the toolbar, with accessibility violations set to fail the story. - 06
Compose with no Material, and a ledger for every gap
The Android library depends on Compose foundation and UI only. Each composable reads the generated Kotlin tokens through a theme that takes a preset, the same axis tuple the web uses. The Compose gate mirrors the React one: tokens checked both ways, raw dp and sp values failing without a written reason, a parameter for every contract prop. What makes it honest is the gap ledger. A token or prop the composable does not cover yet must be listed with a reason, and the gate fails when a listed gap quietly closes or stops existing. Hover is the common one: a finger never hovers, so hover tokens are declared out of scope rather than silently skipped.
Evidence · 16 of 44 contracts built: button, card, tabs, progress, callout, input, chip, bubble, avatar, icon, badge, stat, top bar, empty state, field and nav bar. 31 recorded gaps, each with a reason.

One contract, two builds. The anatomy names the parts and the tokens; each platform renders them its own way and the gates hold both to the same list. - 07
A brand is one file and a preset
Adding a brand means adding a hue ramp to the raw values, one file that points the primary palette at it, and a preset that names the rest of the axes. Nothing else changes. The output tests then check every text and control pair for that brand in light and dark, at default and more contrast, against WCAG AA. When one brand's red failed dark mode's primary text on a weak background at 4.33 to 1, the test said so and the ramp's darkest step moved. The build also generates the brand's Kotlin preset and its Android window theme, so an app picks it up with one line.
Evidence · Five brands: the white-label default, one per Android app, one for the shop and one for the studio. Each is checked across 4 scheme and contrast combinations with 57 pairs apiece, about 228 contrast checks per brand and about 1,140 in all, on every test run.

One attribute on the web, one preset on Android. The components did not change between any of these four frames. - 08
Served to people and to assistants
Storybook documents every component with the nine axes and the skin in the toolbar and the accessibility add-on set to fail a story on any violation. The MCP server serves the same system to any LLM: it lists components, returns a contract with its adapter entry, lists and explains tokens with their reference chain and the axes that change them, explains any gate code, and runs the real contract gate on a candidate contract before anything is written. An assistant working in this repo reads the system instead of inferring it.
Evidence · 8 MCP tools and 3 resources, reading only the built output of the tokens and contracts packages. Registered in the repo so every coding agent gets it.

The assistant asks the system, not its memory. check_contract runs the same gate the build runs.
How the system resists drift
A system like this does not stay right on its own. Someone types a hex value because it is faster, a token gets read that nobody wrote down, a library upgrade renames a part, a brand ships with text you cannot read. Phantom's answer is to make each of those fail a check, as early as possible, with a code that says what to do.
A raw value in component CSS or Kotlin
The raw-value scan fails on any color, length or time literal that is not a token. The escape is a written reason on that line.
Otherwise the value is right on one screen and wrong on every other brand and mode.
A token the contract never mentioned
The both-ways check: CSS reads a token the contract lacks, or the contract lists one the CSS never reads. Either fails.
Otherwise the contract describes a component that no longer exists.
A design decision nobody uses
A component hook that exists in the tokens but is read by no contract fails the contract gate.
Otherwise the token set fills with dead values that look like choices.
A library upgrade
The adapter map carries the library version and every mapped part, and both are checked against the installed package.
Otherwise a renamed part breaks a component quietly, two upgrades later.
A gap on the second platform
Compose must list every token or prop it does not cover, with a reason, and the gate fails when a listed gap closes or disappears.
Otherwise the Android build is described as complete when it is not.
A new brand
About 228 contrast checks per brand run on every test, across light, dark and more contrast.
Otherwise unreadable text ships in the one mode nobody looked at.
All three gates run in about three seconds, so they run on every build rather than on a schedule. The numbered codes mean a failure reads the same in a terminal, in a status note and in an assistant's reply, and the fix is written next to each one.
Outcomes
- 1,167 tokens from one source, built to CSS, JSON, TypeScript and Kotlin, with Android window themes per preset. 38 token tests pass on every build, including about 1,140 contrast checks.
- Nine theming axes that compose on any subtree, and eight presets that name them. A dark, compact card inside a light page is one attribute, not a second component.
- 44 contracts that name no library, and a 26-code gate proven by 35 contracts broken on purpose.
- 44 React components on Base UI with 152 tests, three skins, and a gate that checks CSS against the contract in both directions.
- 16 Compose composables with no Material dependency, a mirrored gate, and 31 recorded gaps, each with a reason.
- Five brands, each one file and a preset. Two of them run on phones today in the Android apps; two run on the web in the shop and the At Odd Hours site.
- An MCP server with 8 tools, so an assistant reads the real contracts and tokens and can run the gate on its own draft.
- What's next: Figma checked against the contracts rather than by eye, and the remaining 28 composables.
Key Decisions
6 architectural decisions, and the reasoning behind each.
Contracts read semantic roles, recipes and their own hooks, never raw values and never another component's hooks.
A shared value has to be promoted to a role before two components can use it, so the token set says what things are for. The gate enforces it, which is what keeps the rule true after the first week.
Adapters name the library. Contracts never do.
The same 44 contracts describe the React build and the Compose build. Swapping Base UI for something else is a new map, not a rewrite of the system's promises.
Axes compose through references, and only one axis may bind a token to a raw value.
Any pair of axes can nest without a file for the pair. That is why there are 16 axis files and not hundreds.
The skin is an attribute on each component's root, not an inherited one.
Nested skins work without scoping tricks, so a wireframe section can sit inside a finished page while you decide what it should be.
Component CSS is checked against the contract in both directions.
A dropped decision and an undocumented one are the two ways a contract stops being true. Catching both keeps the contract worth reading.
No Material 3 on Android, and no generated code on either platform.
Each platform stays idiomatic and the contract stays the only thing both have to agree with. The cost is honest too: 28 composables are still to build, and the ledger says which pieces of the 16 are not finished.
What this proves
A design system can keep five brands and two platforms consistent without a copy of anything. The contract is the thing above the code, the tokens are the thing under it, and the gates are what make both statements checkable instead of hopeful.
The checks are the product as much as the components are. Numbered codes, cases that prove each code fires, and a reason required for every exception are what let the system grow without anyone keeping the rules in their head. They are also what an AI assistant needs, because an assistant can run a gate but cannot remember a convention.
Building it taught me where the edges are. The CSS can put a dark block inside a light page but not yet a light block inside a dark one, so a dark-first site runs on the light scheme and marks its dark parts. The adapter map fell behind the code and said 18 components were built when all 44 were. Hover means nothing on a phone, so the Compose ledger declares it out of scope rather than pretending. Each of those is written down next to the rule it bent, which is the whole idea.