Skip to content

Design system

This page explains where the appearance of the product lives and what keeps it there. It is part of section 9 of the arc42 template. The decision is recorded in ADR-0010.

The look of the whole product must be replaceable without rewriting features. That only works when no screen carries a colour, a font or a size of its own: one fixed value in one screen is enough for a new look to miss it.

  • packages/ui is the only place where a colour, a font, a radius or a spacing value is written.
  • An app builds screens with the components of packages/ui and with layout classes. It never styles an element itself.
  • Replacing the look means changing tokens and theme, and at most the inside of the components. The names of the tokens and the public interface of the components stay.

packages/ui has three layers. Each one uses only the layer above it in this table.

Layer What it holds
Tokens Every value of the look as a CSS custom property prefixed with --ui-: 41 colours with a light and a dark value, and 65 values that do not change with the theme (type scale, weights, radii, spacing, sizes of the shell, motion). The names are semantic (--ui-color-surface, --ui-color-danger-ink), never a description of the value. In packages/ui/src/tokens/index.ts and packages/ui/css/tokens.css.
Theme The light and dark themes, the theme switch, and the bridge to Tailwind. Light is the base, and data-theme="dark" on <html> applies the dark values. The first visit follows the saved choice, then the operating system, then dark. In packages/ui/src/theme and packages/ui/css/tailwind-theme.css.
Components Buttons, fields, tables, the register pattern, the board, overlays, charts, the application shell and the mobile shell, built on Radix primitives and styled by CSS classes prefixed with ui-. Icons are re-exported from here. In packages/ui/src/components and packages/ui/css/components.

Three details make the rule hold in practice:

  • Tailwind knows only the tokens. tailwind-theme.css starts with --*: initial, which removes every default of Tailwind (palette, spacing scale, radii, shadows, fonts), and then maps each utility to a token. In an app, bg-surface, text-muted, p-4 and rounded-lg exist; bg-blue-500 does not. Each utility reads the token variable itself, so switching the theme re-themes every utility.
  • An app stylesheet has two lines. apps/web/src/index.css imports Tailwind and @ochema/ui/theme.css, and nothing else.
  • Fonts are part of the package. Inter and JetBrains Mono are served from the product’s own files (packages/ui/css/fonts.css). No page loads a font from another site.

The office system (apps/web) and the driver app (apps/driver) use the three layers. The landing site and the careers site are Astro sites that use the same tokens and Tailwind theme. This documentation site maps the tokens to the variables of its own theme in a single stylesheet, apps/docs/src/styles/theme.css.

In development, the office system shows every component with its variants at /dev/ui (apps/web/src/dev/catalog). The route is not part of a production build.

The tokens were extracted from the visual reference of the product, design/direction-d.html, and the reference stays in the repository as the source the tokens are compared with.

Guarantee Enforced by
No colour, font, size or arbitrary Tailwind value in an app. The lint rule ochema/no-hardcoded-style (packages/config/eslint-plugin-ochema.js) rejects hex colours, colour functions, named colours, fixed fonts, arbitrary values such as p-[13px], and inline styles that set colour, font or size. It is on in apps/web, apps/driver and packages/app-kit, and in the .astro files of apps/landing and apps/careers.
No appearance in an app stylesheet. The lint rule ochema/no-css-declarations allows a stylesheet of apps/web, apps/driver or packages/app-kit to import Tailwind and @ochema/ui only.
No way around the components. no-restricted-imports rejects direct imports of Radix, of the icon library, of fonts and of the Tailwind palette in the apps (packages/config/eslint-react.js).
The rules themselves work. packages/config/test/eslint-plugin-ochema.test.js runs both rules over accepted and rejected examples.
The CSS and the token list are the same thing. packages/ui/test/tokens.test.ts fails when tokens.css and src/tokens/index.ts differ, or when a colour differs from design/direction-d.html.
Text is readable in both themes. The same test computes, in each theme, the contrast of the pairs declared in contrastPairs and requires WCAG AA: 4.5 to 1 for 24 pairs of text and background, and 3 to 1 for 3 focus indicators.
The documentation follows the product. apps/docs/test/theme.test.ts fails when the documentation stylesheet has a colour, a font or a radius of its own.
  • A screen cannot improvise. When a screen needs something the components do not offer, the component or the token is added to packages/ui first. There is no one-off styling.
  • The components are maintained in-house. Radix provides the keyboard and focus behaviour of the primitives; what is built on top of them, such as the board and the register pattern, is the product’s own work, including its accessibility. See Quality requirements.
  • One look for every company. The package ships one look, in light and dark. Replacing it for the whole product is the supported case. A different look per company is not built: the careers page of a company carries its logo and its texts, not its own colours.
  • The public sites have a stylesheet of their own. apps/landing and apps/careers import the shared theme and add a few rules of their own in src/styles/global.css. The rule that forbids declarations in a stylesheet does not run there; the rule that forbids fixed values in the markup does.