Skip to Content
Starlight

Brand kit & tokens

The brand kit holds the project's colours and fonts. A token is a named colour, like $team.gold. Change it once, and every layer that uses it changes.

The brand kit is the brand: block of project.yaml. It has two parts: theme: for colours and fonts: for font files.

Use a token

Define a colour once in project.yaml, then use its name everywhere.

  1. In project.yaml, add the colour under brand: › theme:, for example team.gold: "#FFB81C".
  2. In a scene, write $team.gold wherever a colour goes.
  3. Or, in Properties, click a colour's swatch. Then click the token under brand tokens (Pick a colour). The layer then stores the $token, not the hex value.
brand:                         # in project.yaml
  theme:
    team.gold: "#FFB81C"
    accent:    $team.gold        # a token can point to another token

theme:                         # in a scene file
  primary: $team.gold            # a second name for a brand token
  flash:   "#FFFFFF"              # a colour for this scene only
  • Tokens work only in colour keys: fill, stroke, a gradient stop's color, and the colour params of effects.
  • A scene can give a token a second name in its own theme:, for example primary: $team.gold. Then the scene's layers use $primary, and a new look needs one changed line.
  • A scene's theme: can also hold a hex colour of its own. If a scene name and a brand token are the same, the scene's colour wins.
  • Write brand colours as hex values in quotes. Only tokens that end in a hex colour show under brand tokens. The scene's names come first, then the brand's.
  • Typing a hex code under custom hex puts a fixed colour in place of the token.
  • Animated colours (the colour keyframes of a gradient stop, of a shape's fill or stroke, or of a text's fill) can use tokens too. A token keyframe keeps the token's name, so it follows the brand kit. When you animate a colour that uses a token, the first keyframe keeps that token.

How a token finds its colour

Starlight looks in the scene's theme first, then in the project's brand.theme. It follows each $ name until it finds a real colour.

  • Example: fill: $primary → the scene's primary: $team.gold → the brand's team.gold: "#FFB81C".
  • Brand keys can use dots (team.gold) or nesting (team: { gold: … }). Both work. If a file has both spellings, the dotted key wins.
  • A token that names nothing is an error (unresolved token $x). So is a chain that comes back to itself (token cycle at $x). The error names the field (Read an error message).
  • Starlight also refuses a scene change from Claude that has such a token.
  • To fix it, define the token, or use a "#hex" colour.

Brand fonts

brand.fonts gives each font file a family name. A text layer uses that name.

  1. Put the font file in the project's fonts/ folder.
  2. In project.yaml, add it under brand: › fonts:, for example knockout-heavy: fonts/Knockout-HTF.otf.
  3. Select a text layer. In Properties, click ↻ beside the font list. This loads the new family.
  4. Pick the family in the font list. In YAML, write font: knockout-heavy in the text layer.
  • The file must be inside fonts/, and end in .otf, .ttf, .woff or .woff2. Write its path from the project folder. A file in another folder does not load.
  • Reload Project from Disk does not load a family that you added by hand. Click ↻, or restart Starlight.
  • If the font file is missing, the text uses a heavy, narrow system font. The scene still works.
  • ↻ also finds new files in fonts/ and adds them to project.yaml for you. It saves this as a version.
  • It names each new family after its file name, in lower case, with dashes for spaces. Knockout Heavy.otf becomes knockout-heavy. If that name is taken, it adds -2.
  • ↻ looks only at files directly in fonts/, not in subfolders. Dropping a font file on the window does the same as ↻ (Fonts and the fallback chain).

Weights and styles of a font

A font family, for example Inter, comes as one file for each weight and style: Inter-Regular.otf, Inter-Italic.otf, Inter-Bold.otf. In Starlight each file is its own brand font, with its own name in brand.fonts. This name is the key.

brand:
  fonts:
    inter-regular: fonts/Inter-Regular.otf
    inter-italic: fonts/Inter-Italic.otf
    inter-bold: fonts/Inter-Bold.otf
    inter-bolditalic: fonts/Inter-BoldItalic.otf

Make a text bold or italic:

  1. Select the text layer.
  2. In the font list, pick the file of that weight or style, for example inter-bold. In YAML, write font: inter-bold.
  3. Leave weight empty. A font file has only one weight. With a weight of 600 or more, Starlight makes the letters thicker itself (a fake bold), even with the Bold file. A weight under 600 changes nothing.

Add a weight or a style that is not there yet (for example SemiBold):

  1. Drag the font file (for example Inter-SemiBold.otf) into the Starlight window. Starlight copies it to fonts/ and adds it to brand.fonts.
  2. Did you copy the file into fonts/ with Finder (Explorer on Windows)? Then click ↻ beside the font list.
  3. The key is the file name in lower case, with dashes for spaces: Inter-SemiBold.otf becomes inter-semibold.
  4. Pick inter-semibold in the font list.

Italic and bold words inside one text (the text's markup setting): *word* is italic, **word** is bold and ***word*** is bold italic. Each style uses its own file. Starlight reads the font files and picks a file of the same family:

  • italic: the italic file nearest to the text's weight. For a Medium text, this is Medium Italic.
  • bold: the Bold file (700). If there is no Bold, the next heavier file. Bold is never lighter than the text.
  • bold italic: the italic file of that bold weight.
  • The key names do not matter. graphik-regularitalic (from Graphik-RegularItalic.otf) and minionpro-it work. Capital letters do not matter: Inter-Regular finds the same files as inter-regular.
  • If Starlight cannot read a font file, it looks for the key names instead: inter-italic, inter-bold and inter-bold-italic for inter-regular.

When a file is not there:

  • No file for a key: the text uses the fallback fonts (Fonts and the fallback chain).
  • No file for a markup style: those words are upright, or at the normal weight. The properties panel says which file to add. Starlight never makes a fake slant.
  • A variable font has all weights in one file. Starlight uses only one weight from it. To use more weights, use one file for each weight.
  • Claude can check all of this: the MCP tool list_fonts reads each font file and shows its real weight and style, the files in fonts/ that have no key, and the texts that ask for a weight or style that is not there.

On this page