Components and variants

Buttons, cards, links, forms, tabs and the other catalogue components take their look from the design system, not from the page. A page node only says which variant it draws (Filled or Outlined, for a button); the variant's colours, spacing, type and corners live here, per size, state and breakpoint. Change a variant once and every button that draws it changes.

Before you start #

• You need the Super admin role, or a Content editor a Super admin has given Edit on Components (to change cells) and Variants (to add, hide or delete variants). By default a Content editor can only view components and choose variants on the page.
• Tokens come first. A component cell points at a token (a colour role, a space step, a type style), never at a raw value. If the value you want does not exist yet, add it as a token in Colours, space and themes.

How a component is laid out #

A component's look is a grid of cells. Each cell is one combination of:

• Variant: a named look, such as Filled, Outlined and Inverse for a button.
• Size: Small, Medium, Large, for components that have sizes. All sizes (base) holds what does not change by size.
• State: default, hover, focus, pressed, disabled and others, depending on the component.
• Part: a named piece of the component, such as its label, icon or border.
• Breakpoint: Mobile, Tablet, Desktop.

A cell you leave empty inherits: a size from All sizes (base), a state from the default state, a breakpoint from Mobile upward.

Style a component #

1. In the site's sidebar, open Design System, then Components. Components are grouped (Actions, Forms, Navigation, Content and so on); a card shows Customised when the site has changed it.
2. Choose Open {component} on a card, for example Open Button. You see the variants by size in rows and the states in columns, drawn under the theme and viewport chosen in the top bar.
3. Choose a cell in the grid. The Cell inspector opens with its Variant, State, Size and Breakpoint. A click on a variant's row header or a state's column header opens it with Apply to set to Variant across all states or State across all variants.
4. Under Apply to, choose how far the change reaches: This cell, Variant across all states or State across all variants.
5. Change a property, for example Background, Content colour, Padding or Radius, by picking a token. A row that shows Not set, Inherited from default state or Inherited from another cell has no value of its own here.
6. For values that differ by screen width, open Responsive values and set them for Tablet and Desktop.
7. Your changes collect under Staged changes. Remove one with Remove change, drop them all with Discard, or keep them with Save changes.

Compare with blueprint shows the blueprint's row beside the site's, so you can see what you changed.

Add a variant #

1. Open the component and go to Variants.
2. Choose Add variant.
3. Enter a Key (lower-case letters, digits and hyphens, starting with a letter, for example ghost), a Label people will read in the editor, and Start from: the variant to copy.
4. Choose Create. Then style the new variant's cells as above.

In the same table you can Rename a variant, Hide it (nobody can pick it in the editor any more; elements that already use it keep it and still draw it) or Show it again, and Delete it. Used by counts the elements on draft pages and the cells of other components that use it. Delete stays off while that count is not 0, and for the variants the site's blueprint ships.

Pick a variant on the page #

1. In the editor, select a component node (a button, a card).
2. In the inspector, choose its Variant, and its Size if it has sizes. Default draws the component's default variant.

Turn local styles into a variant #

Sometimes you style one button on a page by hand until it looks right. Make that look a variant, so the next button can use it.

1. In the editor, select the node. In the Layers panel it shows Detached (its own styles override its linked style).
2. In the inspector, open Component styles. It names the component and variant the node draws.
3. Under the promote form, enter a Variant name and a Variant key.
4. Choose Promote to variant. The site gets the new variant, the node switches to it, and the styles you moved are removed from the node. Other local styles stay on the node.

You need Edit on both Components and Variants to see the promote form.

What you see #

• Overview lists Detached instances: component nodes with local styles. A page's Findings show each one as Detached from system · {count} declarations, with Re-attach: remove local styles.
• Activity records "changed the look of a component variant", "added a component variant" and "turned a style on {target} into a component variant".
• Specimen draws every variant, size and state of a component on one sheet.

Pitfalls #

• A cell takes a semantic or foundation token (a colour role, a space step), not a palette step and not a typed value. That is on purpose: if a cell pointed at blue.500, a theme could not change it.
• Contrast is checked here too. A cell change that puts a text/background pair below AA is refused, as for tokens.
• Another variant is already called "{label}". Choose another name. Labels are unique per component.
• Not in this design system: some catalogue components have no blueprint styles on this site. They are listed apart and cannot be styled until the blueprint has them.
• Component styles and the promote form are in English only in the admin today, also when the admin is in Italian.
• Changes reach the public site when you publish.

Related #

• Colours, space and themes
• Typography and fonts
• Layers and canvas
• Site components