Design Variables

Design variables are CSS custom properties that control the visual appearance of your site. This guide covers using design variables in components and defining new variables.

Design variables are named CSS custom properties defined at the platform level with optional site-level overrides:

Reference design variables in your component.css:

Provide fallback values for variables that might not be defined:

Syntax: var(--variable-name, fallback-value)

Variables are organized into categories:

Available color variables:

• --color-primary: Primary brand color
• --color-secondary: Secondary brand color
• --color-background: Page background
• --color-text: Primary text color
• --color-text-muted: Secondary text color
• --color-border: Border color
• --color-success: Success state
• --color-warning: Warning state
• --color-error: Error state

Available typography variables:

• --font-family-base: Body text font
• --font-family-heading: Heading font
• --font-size-base: Base font size (16px)
• --font-size-sm: Small text (14px)
• --font-size-lg: Large text (18px)
• --font-size-xl: Extra large text (20px)
• --font-weight-normal: Normal weight (400)
• --font-weight-medium: Medium weight (500)
• --font-weight-bold: Bold weight (700)
• --line-height-base: Base line height (1.5)
• --line-height-heading: Heading line height (1.2)

Available spacing variables:

• --spacing-xs: 4px
• --spacing-sm: 8px
• --spacing-md: 16px
• --spacing-lg: 24px
• --spacing-xl: 32px
• --spacing-2xl: 48px

Available layout variables:

• --container-max-width: Maximum content width (1280px)
• --container-padding: Container padding (16px)
• --grid-gap: Grid gap (16px)
• --grid-columns: Grid columns (12)

Available border variables:

• --border-width: Default border width (1px)
• --border-radius-sm: Small radius (4px)
• --border-radius-md: Medium radius (8px)
• --border-radius-lg: Large radius (12px)
• --border-radius-full: Full radius (9999px)

Available shadow variables:

• --shadow-sm: Small shadow
• --shadow-md: Medium shadow
• --shadow-lg: Large shadow

Every built-in component (button, teaser, title, rich-text, site-navigation, page-list, percentage-bar, image, comments, container, table) exposes its per-component CSS custom properties as platform design variables in the Components category. Editing them in Platform → Variables or Site → Theme restyles every instance of that component site-wide — colours, padding, radii, typography, hover states, etc. Values default to the concrete CSS defaults, or to a var(--…) chain that lets the component pick up a global colour (e.g. --button-primary-bg defaults to var(--color-primary, #0066cc) so overriding --color-primary is usually enough).

Component variables are named --<component>-<property> (e.g. --teaser-padding, --button-primary-hover-bg, --percentage-bar-fg) and are searchable from the Design Variables Reference.

Components can define new design variables in variables.json:

Each variable definition requires:

• name: Variable name (must start with --)
• category: One of color, spacing, typography, layout, border, shadow, component, other
• description: Human-readable description
• defaultValue: Default CSS value

• Start with --: All CSS custom properties start with --
• Use kebab-case: --hero-min-height, not --heroMinHeight
• Be descriptive: --card-padding, not --cp
• Include component name: --hero-overlay-opacity, not --overlay-opacity

After defining variables, use them in your component CSS:

All design variables (platform defaults and component-defined) are stored in the Variable Registry.

To view all available variables:

1. Navigate to Settings → Variables
2. Browse variables by category
3. View descriptions and default values

When a component defines a variable that already exists:

• Platform default is preserved: The existing default value is not overwritten
• Component can use the variable: The component can reference the existing variable
• Sites can override: Sites can override the variable value

Platform defaults are defined at the platform level and apply to all sites:

Sites can override platform defaults:

When rendering a page:

1. Load platform defaults from Variable Registry
2. Load site overrides from Site Theme
3. Merge: site overrides take precedence
4. Inject resolved variables into page <head>

Use variables with media queries for responsive design:

The platform provides breakpoint variables:

Available breakpoint variables:

• --bp-tablet: 768px (default)
• --bp-small-desktop: 1024px (default)
• --bp-desktop: 1280px (default)

Sites can override breakpoint values in their theme settings.

Use variables for:

• Colors that should match the site theme
• Spacing that should be consistent across components
• Typography that should match the site's font settings
• Layout dimensions that should be configurable

Don't use variables for:

• Component-specific values that shouldn't be themed
• Values that are intrinsic to the component's design
• One-off values that won't be reused

• Be specific: --card-border-radius, not --radius
• Include context: --hero-min-height, not --min-height
• Use semantic names: --color-primary, not --color-blue
• Follow conventions: Use existing variable patterns

Always provide fallback values for custom variables:

This ensures the component works even if the variable isn't defined.

Document your custom variables:

• Provide clear descriptions in variables.json
• Explain when and how to use each variable
• Include example values in descriptions

Test your component with different variable values:

1. Create a test site
2. Override variables in the site theme
3. Publish a page with your component
4. Verify the component adapts correctly

Test that fallback values work:

1. Remove variable definitions
2. Verify the component still renders correctly
3. Check that fallback values are applied

If a variable isn't being applied:

1. Check variable name: Ensure the name matches exactly (case-sensitive)
2. Check syntax: Verify var(--variable-name) syntax is correct
3. Check specificity: Ensure CSS specificity isn't overriding the variable
4. Rebuild site: Perform a site rebuild to apply variable changes

If a variable has the wrong value:

1. Check site overrides: Verify the site theme settings
2. Check platform defaults: Review the Variable Registry
3. Check component definition: Verify variables.json is correct
4. Clear cache: Clear browser and CDN cache

• Component Structure — Define variables in variables.json
• Theming — Customize variables at the site level
• Building Sites — Best practices for using variables