Colour aliases
Name what a colour is for, such as Body or Surface, so the AI tools that build with your brand know where each colour goes. Aliases are optional.
An alias is a name for what one of your colours is for. If your palette holds a dark brown, naming it Body tells an agent that this is the colour for running text. An agent is an AI tool that builds with your brand, such as Claude Code or Cursor.
Aliases are optional. Without them your colours still reach your agents, and a component can point at a colour directly. Add an alias when you want an agent to know what a colour is for, or when you expect to change that colour later and want everything that uses it to follow.
You'll find them in your brand under Colors & fonts, in the Aliases section.
Add an alias
- Select + Add an alias.
- Choose one of the offered names, or type a name of your own.
- Pick the colour it points at.
- Select Add alias.
Sidenote offers eleven common names: Title, Body, Muted text, Surface, Raised surface, Border, Emphasis, Link, Success, Warning and Danger. Use the ones that fit your brand and leave the others.
A name you type is kept exactly as you write it, including spaces. It has to be different from your other aliases, and it can't match the path of a colour, such as color.brand.primary.
An alias's colour can't be changed from this page yet, and an alias can't be removed.
Use a suggestion
Sidenote may list suggestions above the table, each marked Suggested. They are read from your components, your colour names and the ends of your colour scales. A colour called text.muted, for example, is suggested as Muted text.
- Use adds the alias.
- Dismiss removes the suggestion, and it stays dismissed.
A suggestion only ever points at a colour you already have, and nothing is added until you select Use.
Give Emphasis several colours
Emphasis is the one alias that can hold more than one colour, for brands that use different accent colours in different places. Each colour can carry a note saying when to use it, and agents choose between the colours by reading the notes.
Read the contrast line
Once you have more than one alias, a line under an alias shows how readable it is against another of your aliases. The number is a contrast ratio. A higher number is easier to read.
| The alias is | Its line shows | Example |
|---|---|---|
| Text, such as Body or Link | The background it sits on | Sits on Surface at 11.2. |
| A background, such as Surface or Emphasis | The text it carries | Carries Body at 11.2. |
| An edge, such as Border | How it reads against the surface | Against Surface it reads 1.0, so the edge is invisible. |
Sidenote measures against two thresholds: 4.5 for body text, and 3 for large text and for edges such as borders. A number followed by "large text only" clears 3 and falls short of 4.5.
A low number never stops you saving. It tells you what the pairing measures so you can decide whether it matters for how you use those colours.
To see every combination, select Check every pair. A grid shows each colour measured against every other. Aliases that share a colour appear as one row.
Add dark values
An alias can hold a second colour for use on dark backgrounds.
- Under the table, select Add dark values. A Dark column appears.
- On each row, Sidenote suggests a dark colour from your palette and shows its contrast. Select Use to accept it.
A dark colour can't be picked freely yet. A row Sidenote has no suggestion for shows Not set. To take a dark value off again, select Clear.
Your agents are told which aliases have a dark value. If you set none, they are told that this brand has no dark values, so they don't guess by reusing your light colours on a dark background.
If none of your colours is readable on your dark surface, the cell says "Nothing you own passes here" and offers Add a colour.
If your brand already has aliases such as Inverse text and Inverse surface, Sidenote offers to turn them into dark values. Select Fold them in to accept, or Keep them as their own names.
When a colour can't be deleted
Select a colour to open it. If an alias, a component or a gradient points at that colour, Sidenote lists everything that points at it, and Delete won't remove the colour until each one has somewhere to go.
- For each item in the list, choose a replacement under Point it at…. To send them all to the same colour, use the picker at the top of the list.
- Select Delete. Each item moves to its new colour and the old colour is removed in the same step.
To leave your brand as it was, close the colour without selecting Delete.
Related
- Gradients: build a gradient from your colours and use it as an Emphasis colour.
- Scales: build a range of lighter and darker steps from one colour. Dark value suggestions come from these.
- Brand components: use an alias in a button, a card or another component.