Design system and tokens

The site and the administration look consistent because they share the same components and the same tokens. This chapter says what exactly is shared, where it is changed, and how you verify a change did not break the other side.

What is shared — in numbers

	Front end (template1)	Administration (default)
Component files	58	66
Of which identical with the other branch	57	57
Its own	1 (cookie settings)	9 (dashboard, fold cards, dense table, secret field…)

A change in components/ shows up on BOTH sides

Fifty-seven files are shared. Editing a button for the sake of one admin page recolours buttons on the website too — and nobody connects the two, because the edit was made "in the administration". Deviations therefore belong in custom/, see SCSS structure.

A component belonging to a single branch is fine — a dashboard makes no sense on the website. What is wrong is editing a shared component for one side's needs.

Two levels of tokens

Level	Where	Example
Base	abstracts/_vars.scss	--color-primary, --font-primary, --border-radius
Component	next to the component itself	--card-bg, --card-radius

A component token is the component's interface: it says what can be changed from the outside without reaching inside. Its value in turn references a base token, so a change of palette travels through the whole system.

.card {
  --card-bg: var(--color-surface);   // ← a reference, not a concrete colour
  background: var(--card-bg);
}

A missing token is a signal

When a theme forces you to reach into a component, a token is almost always missing. Adding one beats duplicating the component — the second copy stops being maintained the moment the first one changes.

The design kit versus the theme

ui-demo/final-design/ holds the design iterations — the HTML the theme grew out of. It uses its own class naming.

Design-kit classes are NOT theme classes

A chunk of markup copied from the design picks up no styling in the theme. The result looks like broken rendering, so people hunt for a bug in the CSS — when the class simply does not exist in the theme. The template to copy from is the component catalogue, not the design.

Design mock-ups carry styles in the attribute

style="…" right in the markup. That does not belong in a theme — the value cannot be overridden by a token and will survive the first change of palette exactly as it was.

A new component, step by step

1. Check it does not already exist — the catalogue has 49 chapters; half of all "new" components are a variant of an existing one.
2. Write it into components/ with its own tokens, values referencing base ones.
3. Add it to ui-demo/ — otherwise nobody will find it and in six months it gets written a second time.
4. Verify both branches — a shared component has to render in the administration too.
5. Click through it — do not just build it.

A click-through shows what a build cannot

A compiled CSS file says nothing about how the component looks next to the others, what it does when the text overflows, and whether it can be operated from the keyboard. Visual comparison lives in var/ds-baseline/ — screenshots and page metrics from before and after a change.

Where to look for what

I want to	Where
see how a component should look	component catalogue
change a colour, typeface, spacing	abstracts/_vars.scss, deviations in custom/_vars-override.scss
edit one component	components/_<name>.scss — ⚠️ it lands on both branches
deviate for my theme only	custom/
verify nothing broke	var/ds-baseline/tools/