ADR-0010: Design system used only through tokens and components
- Status: Accepted
- Date: 2026-11-12
Context and problem statement
Section titled “Context and problem statement”A requirement from the start: the whole look of the product can be replaced without rewriting features. That only works if no screen carries appearance of its own.
Where does appearance live, and how is that kept true as screens are added?
Decision drivers
Section titled “Decision drivers”- Replacing the look means changing one package.
- Light and dark themes, with text contrast at WCAG AA.
- The rule must be enforced by a tool on every change.
Considered options
Section titled “Considered options”- Tokens, theme and components in one package,
packages/ui, with lint rules that forbid appearance in the apps. - A ready-made component library with its own styling. Common market alternative, listed for comparison.
- Free use of Tailwind utilities in each app. Rejected: fixed colours, fixed fonts and arbitrary Tailwind values are forbidden in app code.
Decision outcome
Section titled “Decision outcome”Chosen option: 1.
packages/ui has three layers: tokens (colours, fonts, radii and spacing as CSS variables), theme (the current theme) and components (built on Radix primitives, styled with CSS classes prefixed ui-). The apps build screens only with those components and with Tailwind utilities generated from the tokens. Fonts are self-hosted by the package.
The rule is enforced by the ESLint plugin in packages/config/eslint-plugin-ochema.js:
ochema/no-hardcoded-stylerejects hex colours, colour functions, named colours, fixed fonts, arbitrary Tailwind values and inline styles that set colour, font or size.ochema/no-css-declarationsallows an app stylesheet to import only Tailwind and@ochema/ui.- Direct imports of Radix, of the icon library and of fonts are forbidden in the apps.
The rules apply to apps/web, apps/driver and packages/app-kit, and the style rule also to the .astro files of the landing site and the careers site. The documentation site maps the same tokens to the variables of its theme in one stylesheet, checked by a test.
Consequences
Section titled “Consequences”- Good, because a new look is a change of
tokensandtheme, and at most of the inside of the components. The public interface of the components stays. - Good, because every screen is consistent in both themes without extra work.
- Bad, because a screen that needs something new waits for a component or a token to be added to
packages/ui. There is no one-off styling. - Bad, because the components are maintained in-house, including their accessibility behaviour beyond what Radix provides.
More information
Section titled “More information”packages/ui/src/tokens,packages/ui/src/theme,packages/ui/src/componentsandpackages/ui/css.packages/config/eslint-plugin-ochema.jsandpackages/config/eslint-react.js: the rules and where they are switched on.apps/docs/src/styles/theme.css: the tokens mapped to the documentation theme.- Concept page: Design system.