← All build notes Design systems

Why every product gets its own design system

Ten products, ten design systems. We set up the tokens and components before the first screen, so agent-written code has rules to follow.

ArcLayer teamBuild notesNov 2, 20263 min read

Each of the ten products ArcLayer has designed, built and shipped, across web, iOS and the browser, has its own design system: the tokens and components every screen uses. SourceBD, a supplier sourcing tool, does not look like Kindlo, a wellbeing app with a paper friend called Oru, and it should not.

Set it up before the first screen

We build with AI agents, and an agent writes whatever the codebase lets it write. If colours, spacing and type sizes live as one-off values in each file, the agent copies them and varies them a little, and after a week no two screens quite match. A design system set up first gives the agent a short list of allowed values and named components to reuse.

Start with tokens

Tokens are the smallest design decisions: colour, type size, spacing, radius and motion timing. In a web product they sit in one file as CSS custom properties. The values in this example are illustrative:

css
:root {
  /* colour */
  --ink: #101213;
  --paper: #f9fafa;
  --accent: #D72638;

  /* spacing in 4 px steps */
  --space-1: 4px;
  --space-2: 8px;
  --space-4: 16px;
  --space-8: 32px;

  /* type and shape */
  --text-body: 16px/1.5 system-ui, sans-serif;
  --radius: 6px;
}

Components then use tokens and nothing else. A button reads var(--accent) and var(--space-4) and never holds a hex value of its own.

Put the rules where the agent reads them

An agent follows the instructions it can see when it acts. Keep the design system rules in the repository, next to the code, in plain language: which tokens exist, which components to reuse, and what to do when a screen needs something the system does not have. An agent such as Claude Code can read that file before it starts a task.

When a screen needs something new

The agent should not invent a value to get a screen finished. A new token or component is a design decision, so a person makes it, adds it to the system and writes down why in the decision log.

If a value is missing from the design system, it stays out of the product until a person adds it.

Why one system per product

A shared house style would be quicker to set up, and it would make ten different products look like one. Slipora is used at a till with a receipt in one hand. Scoreva is opened during a match to check the score. Those products have different users and different moments of use, and each interface should come from its own.

Build it
with
clarity.

Tell us what you are building and where it stands today. We will reply with questions and a first plan. Write to [email protected].

  • RezanCo-founder
  • RanaCo-founder