Two axes
Light and dark mode belong to the person. The accent preset belongs to the instance, and an administrator picks it under Settings → System Theme. The two never depend on each other, so a component does not branch on the accent. The default presetcollabase is Lime. The accent is the interactive colour in light and dark: primary actions, selection, active rows and the focus ring. Inter is the only typeface.
Tokens
Pick a fill by naming the surface underneath it. A sunken fill on a panel reads clearly, the same fill on the page surface nearly disappears.
Roles
A role is one class for a bundle of tokens. Names carry the prefixui-, text roles are type-*.
Combine a role with an override through
cn(role, override). The later class wins, so an override replaces the height, radius or font of a role cleanly.
Row with an override
Change a token or add a role
1
Edit the stylesheet
Change the value in
tokens.css, or add a @utility to roles.css. A role reads tokens only and never holds a raw value that a token could hold.2
Update the rule
Describe the change in
.claude/rules/design-system.md in the same pull request. A role needs two places that use it; a single use stays a class string.3
Regenerate the token package
Run
npm run generate:collakit-tokens. See Collakit token package.research/final.html fixes the declared values, and a parity test compares the running app with it. A value that differs is changed in the code, never in the test.
Next steps
Building blocks
The shared components to reuse before you write a new one.
Icon layer
Import icons under semantic names.