Colours, space and themes

Each site has its own design system: the colours, type, space and shape every page draws from. You change a value once, as a token, and every page and component that uses it follows. This page covers colours, space and shape, and themes; type has its own page.

Before you start #

• You need the Super admin role, or a Content editor a Super admin has opened the area to. By default a Content editor can edit the palette and only view the rest. A Content author does not see the Design System at all.
• The site was created from a blueprint. Its design system starts as the blueprint's values; what you change is stored as the site's overrides, and you can always go back.
• If the site still follows its blueprint, the Overview offers Set up the brand first. Brand setup derives a whole palette, roles, type and space from a few choices. Start there for a new site, then fine-tune here.

Find your way around #

1. In the site's sidebar, open Design System. The pages are Overview, Brand setup, Colours, Typography, Space & shape, Surfaces, Components, Themes and Specimen.
2. The bar at the top of each page sets what you look at: Theme (which theme the samples show), the viewport (Desktop, Tablet, Mobile), and Changed from blueprint, which hides every token you have not changed.
3. Overview shows Health (errors and warnings, such as Contrast below AA or Unused tokens), Changed from blueprint (every override, with the blueprint value beside the site's), Detached instances and Role permissions.

Change a colour role #

Text, surfaces, borders and the accent are roles: each role points at a step of a palette ramp, or holds its own colour. Change roles rather than raw colours, and every component that uses the role follows.

1. Open Colours. At the top, Roles shows what text, surfaces, borders and the accent look like in each theme.
2. Scroll to Semantic roles. Each row shows what the role points at and Used by (how many components and pages use it).
3. Choose Edit on the role.
4. Pick a Palette step, or Own colour and enter a value. The row says which theme and set you are writing to (Edits {theme}, in the set {set}.).
5. Wait for the check. Every pair passes AA. Ready to save. means you can save; Some pairs would fall below AA. Pick another colour to save. means you cannot.
6. Choose Save.

Change a palette step #

1. On Colours, find Palette ramps. Steps with a solid outline are the site's own; dashed steps are derived from them and change when you change their source.
2. Choose a step and enter its hex in Hex of {step}.
3. Choose Save.

Change any token in the drawer #

Every token table (on Colours, Space & shape and Typography) opens the same drawer.

1. Choose a token's name in a table. The Design token drawer opens with the token's Name, Set, Resolves to and the Blueprint value.
2. Choose Value to type a value, or Token to point at another token (filter the list with Filter tokens). A pointer is better than a copy: it follows the token it points at.
3. Read Preview before saving. No warnings. means the change is clean.
4. Choose Save. Undo in the top bar reverses the last save.
5. To drop your override, choose Reset to blueprint in the drawer.

To add a token, choose Add token above a table, name it in lower-case words joined by - with segments separated by . (for example space.section.hero), and save.

Change space and shape #

1. Open Space & shape. Spacing, Measures, Radii, Borders, Shadows, Durations, Easings, Opacity, Grid, Breakpoints, Layers, Icon sizes and Icon strokes each have a table.
2. Open a token in the drawer and change it as above. A length has Previous step of the scale and Next step of the scale buttons, so you can move along the scale instead of typing.
3. Save.

To make a whole group of spacing tighter or looser at once, give the group a scale factor instead of changing every step. Choose Add token above Spacing, name it scale inside the group (for example space.section-y.scale), and give it a number: 0.75 makes every section spacing 25 % tighter, 1.2 20 % looser. space.scale scales all spacing. Every length of the group is multiplied, also where it is an alias of the base scale, and the table shows the factor as × 0.75 beside the scaled lengths. Set it back to 1, or delete it, to undo.

Add and apply a theme #

A theme switches a set of token values: a dark theme, a sub-brand, a section style.

1. Open Themes. Each card shows a theme and Where it applies: the whole site wherever no other theme does (the default), The whole site, for visitors who prefer a light or dark scheme, One page (by its address, for example /shop), or The sections that pick it.
2. To make a new one, open Advanced, then choose New theme in the theme matrix. Give it a Key and a Label, choose Start from and Sets it activates, then Create theme.
3. A new theme starts as a Draft: it shows in the previews and never publishes. Look at it with Preview in editor, then clear its draft flag in the matrix to let it publish.
4. To use a theme on one section, select the section in the editor, open Styles, and pick it under Section theme.

Decide who may edit #

Only a Super admin can change this.

1. Open Overview and scroll to Role permissions.
2. For each Area (Palette, Semantic colours, Font families, Components, Variants, Themes and so on), set the level for Editor and Client: No access, View, Edit, and on some areas a level in between (Choose variants, Switch default, Export, Editable areas only).

What you see #

• A changed token shows Changed in its table, and appears under Changed from blueprint on the Overview.
• A role you may only view shows View only.
• Every save shows in Activity as, for example, "changed a design-system token".

Pitfalls #

• Not saved: someone else saved first. Another person saved the design system after you opened it. It was read again; make your change once more.
• Not saved: your role may not edit this area. Ask the Super admin to open the area to your role in Role permissions.
• Reset to the blueprint (under More actions in the top bar) resets every override in the page's scope: on Colours, every colour token. Undo reverts it, but check the count in the confirmation first.
• The default theme cannot be a draft, and a draft theme cannot be the default.
• Design-system changes reach the public site only when you publish.

Related #

• Components and variants
• Typography and fonts
• Your first site (brand setup)
• Publish and versions