Skip to Content

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:style

generate: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.

ItemDetails
TokensCSS variables named --vds-<group>-<name>. Use the semantic ones.
Sourcestyles/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.
Helpersvds.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.

SituationTheme used
A deployed frontendIts own theme. VISOR_FRONTEND_ID tells it which frontend it is.
Your local dev serverThe 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.

Last updated on