Skip to content

ADR-0010: Design system used only through tokens and components

  • Status: Accepted
  • Date: 2026-11-12

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?

  • 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.
  1. Tokens, theme and components in one package, packages/ui, with lint rules that forbid appearance in the apps.
  2. A ready-made component library with its own styling. Common market alternative, listed for comparison.
  3. Free use of Tailwind utilities in each app. Rejected: fixed colours, fixed fonts and arbitrary Tailwind values are forbidden in app code.

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-style rejects hex colours, colour functions, named colours, fixed fonts, arbitrary Tailwind values and inline styles that set colour, font or size.
  • ochema/no-css-declarations allows 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.

  • Good, because a new look is a change of tokens and theme, 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.
  • packages/ui/src/tokens, packages/ui/src/theme, packages/ui/src/components and packages/ui/css.
  • packages/config/eslint-plugin-ochema.js and packages/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.