Themes
A theme sets a website’s colours, fonts and shapes. Widgets and layouts read these through design tokens, so changing the theme needs no component changes.
Structure
- index.scss
Each folder with an index.scss compiles to public/assets/theme/<name>/main.css. npm run generate:style does this, and so does every build.
The template includes default, visor-modern and its colour variants: crimson, emerald, graphite, teal, terracotta and violet.
Create a theme
The create-theme skill does this for you, from your design’s CSS or from scratch. A theme is always a new folder.
Create the file
// app/styles/my-brand/index.scss
@use "../../../styles/design-system/api" as vds; // Must be the first line
@import "./../visor-modern/index.scss";
:root {
@include vds.theme((
primary: #0a618b,
secondary: #20b1bb,
ink: #18181b,
text: #0a142f,
canvas: #ffffff,
subtle: #f3f4f6,
border: #d9d9d9,
radius: 20px,
));
}Compile it
npm run generate:stylegenerate:style also recompiles the template’s own themes. Don’t commit those changes: run git checkout -- public/assets/theme/<that-theme>.
Preview it
In Developer mode, your theme appears in Theme Configuration with a Local badge, ready to preview.
Merge and activate it
Merge it. After the preview rebuilds, anyone at the site can activate it in Theme Configuration. visor_theme_activate and visor_preview_wait can do this too. Only built themes can be activated.
Deploy
The live website shows the theme from its next Deploy.
Design tokens
The Visor Design System is available on every site.
| Item | Details |
|---|---|
| Tokens | CSS variables named --vds-<group>-<name>. Use the semantic ones. |
| Source | styles/design-system/tokens/*.tokens.json, compiled by npm run tokens:build. |
| Components | @/components/design-system: Container, Section, Stack, Grid, Heading, Text, Button, Card, Badge, Alert, Icon and more. |
| Helpers | vds.media-up() and vds.focus-ring for your SCSS. |
| Colour bands | .vds-scope-inverse and .vds-scope-brand. |
See it all at http://localhost:3000/preview/design-system, or read docs/DESIGN_SYSTEM.md in the repository. npm run design-system:export packages it for Claude Design.
Rules for your styles
- No hex colours or fixed font sizes in widgets and layouts. Use tokens.
- Put widget styles in
styles/site/widgets/<name>.scss, with BEM names. - Never style
.vds-*classes globally. - Don’t import styles in
app/layout.tsx.
How a website picks its theme
The theme is stored on the frontend. app/layout.tsx links that theme’s main.css. If the file isn’t in the build, it falls back to default and logs a warning.
| Situation | Theme used |
|---|---|
| A deployed frontend | Its own theme. VISOR_FRONTEND_ID tells it which frontend it is. |
| Your local dev server | The theme of the site’s active frontend, whichever frontend’s code you have. |
So each frontend of a site can look different, and switching one never restyles another.
In npm run dev, SCSS is imported for hot reload, except for visor-modern* themes, which need npm run generate:style.