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.
- In
project.yaml, add the colour underbrand:›theme:, for exampleteam.gold: "#FFB81C". - In a scene, write
$team.goldwherever a colour goes. - 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'scolor, and the colour params of effects. - A scene can give a token a second name in its own
theme:, for exampleprimary: $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'sprimary: $team.gold→ the brand'steam.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.
- Put the font file in the project's
fonts/folder. - In
project.yaml, add it underbrand:›fonts:, for exampleknockout-heavy: fonts/Knockout-HTF.otf. - Select a text layer. In Properties, click ↻ beside the font list. This loads the new family.
- Pick the family in the font list. In YAML, write
font: knockout-heavyin the text layer.
- The file must be inside
fonts/, and end in.otf,.ttf,.woffor.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 toproject.yamlfor 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.otfbecomesknockout-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:
- Select the text layer.
- In the font list, pick the file of that weight or style, for example
inter-bold. In YAML, writefont: inter-bold. - 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):
- Drag the font file (for example
Inter-SemiBold.otf) into the Starlight window. Starlight copies it tofonts/and adds it tobrand.fonts. - Did you copy the file into
fonts/with Finder (Explorer on Windows)? Then click ↻ beside the font list. - The key is the file name in lower case, with dashes for spaces:
Inter-SemiBold.otfbecomesinter-semibold. - Pick
inter-semiboldin 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(fromGraphik-RegularItalic.otf) andminionpro-itwork. Capital letters do not matter:Inter-Regularfinds the same files asinter-regular. - If Starlight cannot read a font file, it looks for the key names instead:
inter-italic,inter-boldandinter-bold-italicforinter-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_fontsreads each font file and shows its real weight and style, the files infonts/that have no key, and the texts that ask for a weight or style that is not there.