Theming

Theming allows you to customize the visual appearance of your site using design variables. This guide covers the theming system and how to customize your site's look and feel.

Design variables are named CSS custom properties that control visual aspects of your site:

• Colors: Primary, secondary, background, text colors
• Typography: Font families, sizes, weights, line heights
• Spacing: Margins, padding, gaps
• Layout: Container widths, grid columns
• Borders: Border widths, radii, styles
• Shadows: Box shadows, text shadows

The CMS uses a two-tier theming system:

1. Platform Defaults: Base values defined at the platform level
2. Site Overrides: Custom values specific to your site

When you customize a variable for your site, it overrides the platform default. Variables you don't customize continue to use the platform default.

To customize your site's theme:

1. Navigate to Sites → Select your site
2. Click Settings → Theme
3. Browse variables by category
4. Customize values as needed
5. Click Save

Control the color palette of your site:

Control text appearance:

Control margins, padding, and gaps:

Control page layout and structure:

Control border appearance:

Control shadow effects:

1. Navigate to Theme settings
2. Find the variable you want to customize
3. Enter a new value
4. Preview the change in real-time
5. Click Save to apply

Different variable types accept different value formats:

• Colors: Hex (#3b82f6), RGB (rgb(59, 130, 246)), HSL (hsl(217, 91%, 60%))
• Sizes: Pixels (16px), rems (1rem), percentages (100%)
• Fonts: Font family names ("Helvetica Neue", sans-serif)
• Weights: Numeric (400, 700) or keywords (normal, bold)
• Shadows: CSS shadow syntax (0 4px 6px rgba(0,0,0,0.1))

In the theme editor:

• Default values: Shown in grey
• Overridden values: Shown in blue with a "Reset" button
• Invalid values: Shown in red with an error message

To reset a variable to its platform default:

1. Navigate to Theme settings
2. Find the overridden variable (shown in blue)
3. Click Reset next to the variable
4. Click Save

To reset all variables:

1. Navigate to Theme settings
2. Click Reset All to Defaults
3. Confirm the action
4. Click Save

After saving theme changes:

1. Perform a site rebuild to apply changes to all published pages
2. Navigate to Sites → Select your site → Settings → Advanced
3. Click Rebuild Site

• Accessibility: Ensure sufficient contrast between text and background colors (WCAG AA: 4.5:1 for normal text)
• Consistency: Use a limited color palette (primary, secondary, accent)
• Brand alignment: Match your brand guidelines
• Test in context: Preview colors on actual content

• Readability: Use legible font sizes (minimum 16px for body text)
• Hierarchy: Create clear visual hierarchy with size and weight
• Line height: Use appropriate line height for readability (1.5 for body text)
• Font pairing: Limit to 2-3 font families maximum

• Consistency: Use a consistent spacing scale
• Rhythm: Create visual rhythm with consistent spacing
• Whitespace: Don't be afraid of whitespace — it improves readability
• Responsive: Consider how spacing scales on different devices

• System fonts: Use system fonts for better performance
• Web fonts: If using web fonts, limit to 2-3 weights
• Shadows: Use shadows sparingly — they impact rendering performance
• Colors: Prefer solid colors over gradients for better performance

To export your theme as JSON:

1. Navigate to Theme settings
2. Click Export Theme
3. Save the JSON file

This creates a JSON file with all your site overrides:

To import a theme from JSON:

1. Navigate to Theme settings
2. Click Import Theme
3. Select your JSON file
4. Review the changes
5. Click Apply

To copy a theme from one site to another:

1. Export the theme from the source site
2. Navigate to the destination site
3. Import the exported theme JSON

Breakpoints control responsive behavior. See Breakpoints for details on customizing breakpoints.

For a complete list of all available design variables with descriptions and defaults, visit:

Settings → Variables → Variable Reference

This page dynamically generates a reference from the platform's variable registry.

If theme changes don't appear on published pages:

1. Rebuild the site: Theme changes require a rebuild
2. Clear browser cache: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
3. Wait for CDN: CDN cache may take a few minutes to clear
4. Check overrides: Verify your overrides are saved

If you see an "Invalid value" error:

1. Check format: Ensure the value matches the expected format
2. Check units: Include units for size values (px, rem, %)
3. Check syntax: Verify CSS syntax for complex values (shadows, fonts)
4. Reset and retry: Reset to default and try again

If colors don't match expectations:

1. Check color format: Ensure hex, RGB, or HSL is correct
2. Check contrast: Verify sufficient contrast for accessibility
3. Check inheritance: Some components may override theme colors
4. Test in different browsers: Color rendering may vary slightly

• Design Variables — Technical details on design variables
• Publishing — Rebuild sites to apply theme changes
• Component Structure — How components use design variables