Design Tokens

Design tokens are named values that define the visual look of your sheet — colors, spacing, fonts, and other style properties. Instead of typing the same color code or spacing value in dozens of places, you define it once as a token and reference it everywhere. When you want to change your sheet's look, you update the token and every component that uses it updates automatically.

Why Use Design Tokens?

Imagine you have picked a nice blue (#3b82f6) for your sheet's headers, borders, and accent elements. Without tokens, that color code is scattered across 30 different style settings. Want to try a different shade? You would need to find and change all 30. With a design token called color-primary set to #3b82f6, you change it in one place and every header, border, and accent updates instantly.

Tokens are especially valuable when:

• Iterating on your sheet's visual design — Try different color schemes in seconds.
• Maintaining consistency — Every component that uses spacing-medium has exactly the same spacing.
• Supporting dark mode — Color tokens can have separate light and dark mode values.
• Sharing themes — Tokens make it easy to apply the same visual style across different sheets.

Token Types

SheetArchitect organizes tokens into four categories:

Colors

Color tokens define the palette of your sheet. Common examples:

Color tokens can optionally have a dark mode value — a separate color used when the sheet is displayed in a dark theme context.

Spacing

Spacing tokens control margins, padding, and gaps between elements. Using consistent spacing tokens gives your sheet a professional, cohesive feel.

Typography

Font tokens define text appearance across your sheet.

Numbers

Number tokens are general-purpose numeric values for things like border widths, border radii, and other properties that do not fit neatly into the other categories.

Managing Tokens

You manage design tokens in two places:

From the Property Inspector

When you are editing a component's styles in the Property Inspector's Styles tab, your defined tokens are displayed and selectable. You can also create new tokens directly from the Styles tab when you realize you need a new value. Click the create token action and define it on the spot.

From the Sheet Settings

The sheet-level design tokens panel lets you see all your tokens at once, organized by type. From here you can:

• Add a new token — Pick a type, give it a name, and set its value.
• Edit a token's value — Change the value and watch the canvas preview update in real time.
• Set a dark mode value — For color tokens, provide an alternate value for dark mode display.
• Delete a token — Remove tokens you no longer need. Components that reference a deleted token will fall back to their inline value or browser defaults.

Using Tokens in Styles

When you set a style property on any component (via the Styles tab in the Property Inspector), you can reference your tokens instead of typing a raw value. The Styles tab shows available tokens so you can pick them from a list.

Behind the scenes, tokens are stored as CSS custom properties (also called CSS variables). A token named color-primary becomes --color-primary in the exported CSS. If you are writing custom CSS in the Style Editor, you can reference tokens using the var() syntax:

.my-header {
  color: var(--color-primary);
  padding: var(--spacing-md);
  font-size: var(--font-size-lg);
}

Using Tokens in CSS Code

If you are writing custom CSS in the Style Editor, you reference tokens using the standard var() function. See Design Tokens in CSS for detailed syntax, fallback values, and calc() usage.

How Tokens Are Exported

When you export your sheet, design tokens are converted into CSS custom properties defined on the sheet's root element. This means they work natively within the target VTT's CSS system — no special processing is needed.

The exported CSS looks something like:

:root {
  --color-primary: #3b82f6;
  --color-secondary: #6366f1;
  --color-background: #ffffff;
  --spacing-md: 16px;
  --font-family: "Segoe UI", sans-serif;
}

Every component that references a token uses the var(--token-name) syntax in its styles, so everything stays connected.

Tips for Effective Token Usage

• Start with a small set. You do not need to tokenize everything. Start with your primary and secondary colors, a spacing scale, and a font stack. Add more as patterns emerge.
• Use consistent naming. A predictable naming pattern like color-primary, color-secondary, spacing-sm, spacing-md makes tokens easy to remember and discover.
• Set dark mode values early if you plan to support both light and dark themes. It is easier to define both values upfront than to retrofit dark mode later.
• Preview changes live. One of the biggest advantages of tokens is instant feedback. Change a token value and watch the entire sheet update on the canvas.