Design Tokens in CSS

Design tokens are named values -- colors, spacing, fonts, borders -- that you define once and reference throughout your sheet. In the Style Editor, you use them as CSS custom properties (also called CSS variables). This keeps your visual theme consistent and easy to change.

If you have not set up design tokens yet, see Design Tokens in the Layout Editor section for how to create and manage them through the visual interface.

Using Tokens with var()

Reference any design token in your CSS using the var() function. Prefix the token name with --:

.section-header {
  background-color: var(--primary-color);
  color: var(--text-light);
  padding: var(--spacing-md);
  font-family: var(--font-heading);
  border-radius: var(--border-radius);
}

Each var(--token-name) is replaced with the token's value when the CSS is applied. If you change a token's value in the Design Tokens panel, every place that references it updates automatically in the preview.

Providing Fallback Values

You can add a fallback value after a comma inside var(). The fallback is used if the token is not defined:

.highlight {
  color: var(--accent-color, #e65100);
  border-width: var(--border-width, 2px);
}

This is useful when:

  • You want your CSS to work even if someone removes a token
  • You are building styles that might be used with different token sets
  • You want to document what value you expect the token to hold
lightbulb

Fallback values are a safety net, not a substitute for defining tokens. If you find yourself relying on fallbacks frequently, consider adding the missing tokens to your token definitions instead.

Combining Tokens with calc()

You can combine tokens with calc() for computed values:

.indented-section {
  /* Double the standard spacing */
  padding-left: calc(var(--spacing-md) * 2);
}

.sidebar {
  /* Take full width minus spacing on both sides */
  width: calc(100% - var(--spacing-lg) - var(--spacing-lg));
}

How Tokens Are Exported

When you export your sheet, design tokens become CSS custom properties defined in a :root block at the very top of your exported sheet.css file:

:root {
  --primary-color: #1a365d;
  --secondary-color: #2b6cb0;
  --text-dark: #1a202c;
  --text-light: #ffffff;
  --spacing-sm: 4px;
  --spacing-md: 8px;
  --spacing-lg: 16px;
  --font-heading: Georgia, serif;
  --font-body: Arial, sans-serif;
  --border-radius: 4px;
}

Because :root custom properties are standard CSS, they work natively on Roll20 without any special handling. Roll20 does not need to know anything about Sheet Architect -- the exported CSS is plain, standards-compliant CSS.

Best Practices

Define All Visual Values as Tokens

Whenever you find yourself typing a color code, a pixel value for spacing, or a font name directly in your CSS, consider making it a token instead. A good rule of thumb:

  • Every color should be a token (--primary-color, --bg-surface, --border-color, --text-muted)
  • Spacing values used in more than one place should be tokens (--spacing-xs, --spacing-sm, --spacing-md, --spacing-lg)
  • Font choices should be tokens (--font-heading, --font-body)
  • Border radii and other repeated visual values should be tokens

Use a Naming Convention

Pick a naming convention and stick with it. Some common approaches:

  • By purpose: --primary-color, --danger-color, --success-color
  • By location: --header-bg, --sidebar-border, --input-text
  • By scale: --spacing-xs, --spacing-sm, --spacing-md, --spacing-lg, --spacing-xl
info

Consistent naming makes your CSS easier to read. When you see var(--spacing-md) in a rule, you immediately know it is a medium spacing value, even without checking the token panel.

Theme Variants

Because all your visual values flow through tokens, creating an alternate theme (like a dark mode toggle or a printer-friendly view) becomes straightforward -- you just redefine the token values under a different selector:

/* Default theme (defined in tokens panel) */

/* Dark theme override */
.sheet-dark-mode {
  --primary-color: #90cdf4;
  --bg-surface: #1a202c;
  --text-dark: #e2e8f0;
  --border-color: #4a5568;
}

When elements have the sheet-dark-mode class, all your existing styles automatically pick up the dark theme values. You do not need to rewrite any of your other CSS.