SurveyJS Design Tokens — CSS-Based Customization

SurveyJS themes use a unified design token system that allows you to style all four SurveyJS products—Form Library, Survey Creator, Dashboard, and PDF Generator—using the same set of CSS variables.

The design token system is organized into the following layers:

• Layer 0 – Palette
• Layer 1 – Base Tokens
• Layer 2 – System Primitives
• Layer 3 – Semantic Tokens
• Layer 4 – Individual Component Tokens

This guide starts with a quick customization example and then explains the design token architecture layer by layer.

Most customizations should be done through semantic tokens (Layer 3) and individual component tokens (Layer 4). Semantic tokens describe UI intent instead of raw values, which makes it possible to restyle large parts of the UI by overriding only a few variables. Individual component tokens allow you to customize specific UI elements without affecting the rest of the design system.

The following example changes the primary brand color, surface colors, and typography. The applyTheme method is available in Form Library, Survey Creator, Dashboard, and PDF Generator.

const customTheme = {
  "cssVariables": {
    // Primary brand color used across actions and interactive controls
    "--sjs2-color-project-brand-600": "#085DE5",

    // Main application surfaces
    "--sjs2-color-bg-basic-primary": "#F2F2F2",
    "--sjs2-color-bg-basic-secondary": "#E8EAEB",

    // Typography settings
    "--sjs2-typography-font-family-text": "Inter, sans-serif",
    "--sjs2-typography-font-size-default": "var(--sjs2-font-size-x250)"
  }
};

survey.applyTheme(customTheme);

creator.applyCreatorTheme(customTheme); // Apply to Survey Creator UI
creator.applyTheme(customTheme); // Apply to the survey being configured

dashboard.applyTheme(customTheme);

surveyPdf.applyTheme(customTheme);

All CSS customizations are applied over the Default Light theme. To customize another built-in theme, pass its object as the second parameter to the applyTheme method:

import { LayeredDarkPanelless } from "survey-core/themes";

const customTheme = {
  "cssVariables": {
    "--sjs2-color-project-brand-600": "#19B394"
  }
};

survey.applyTheme(customTheme, LayeredDarkPanelless);

Palette contains primitive tokens that define raw color material used by the designing system.

Base tokens define the primitive scales used to generate the rest of the design system. These tokens control spacing, sizing, typography rhythm, border radii, and opacity calculations.

In most cases, you should customize semantic tokens instead of base tokens. Override base tokens only when you want to globally change the visual scale of the entire UI, for example:

• Increase all spacing and paddings across the UI.
• Make all controls more rounded.
• Increase the default typography scale.
• Increase the size of interactive elements.

Sizing & Spacing Units

Shape & Borders

Typography Units

Effects

System primitives are generated scales derived from base tokens. These tokens should not be overridden directly.

Semantic tokens are the primary theming API. They describe UI intent rather than raw values.

For example:

• --sjs2-color-bg-brand-primary describes a primary brand-colored surface.
• --sjs2-color-fg-basic-secondary describes medium-emphasis text.
• --sjs2-radius-form describes the default rounding used for form controls.

Semantic tokens automatically propagate across the UI wherever that semantic role is used.

Most semantic tokens follow this naming pattern:

--sjs2-[domain]-[subdomain]-[role]-[variant]-[modifier]

Not every token includes all segments, but the segment order is always preserved.

Domains organize tokens by their purpose.

Roles define the semantic purpose of a token within the interface.

Color Roles

Typography Roles

Variants define emphasis levels.

Color Variants

Typography Variants

Modifiers define interaction states, emphasis adjustments, or contextual variations applied to a token.

Color Modifiers

Brand color tokens define the primary accent color used throughout the SurveyJS UI.

Changing the brand color updates:

• Brand-colored buttons
• Selected controls
• Input field focus indicators
• Progress indicators
• Interactive accents

Core Brand Colors

The core brand colors define the foundation for all brand-related semantic tokens.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the base brand color
    "--sjs2-color-project-brand-600": "#C003DD"
  }
});

Brand Backgrounds

Brand background tokens define surfaces and fills used for brand-colored UI elements.

Brand Foregrounds

Brand foreground tokens define text and icon colors used in brand-colored contexts.

Brand Borders

Brand border tokens define border colors used for brand-colored interactive elements and emphasis states.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the brand primary colors
    "--sjs2-color-bg-brand-primary": "#C003DD",
    "--sjs2-color-fg-brand-primary": "#5B0495",
    "--sjs2-color-border-brand-primary": "#126DFF"
  }
});

Basic tokens define the default visual foundation used across the SurveyJS UI. These tokens control standard surfaces, text hierarchy, and borders used in forms, containers, and interactive controls.

Basic Backgrounds

Basic backgrounds define the default UI backgrounds used throughout forms, containers, and controls.

Basic Foregrounds

These tokens define the default foreground hierarchy used throughout the UI.

Basic Borders

Basic border tokens define the default border hierarchy used across SurveyJS components.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the basic primary colors
    "--sjs2-color-bg-basic-primary": "#FEFEFE",
    "--sjs2-color-fg-basic-primary": "#000000",
    "--sjs2-color-border-basic-primary": "#001536"
  }
});

Neutral tokens define high-contrast, non-brand visual styles used for generic actions, overlays, and utility UI elements.

Neutral Backgrounds

Neutral backgrounds provide high-contrast backgrounds independent of the primary brand color.

Neutral Foregrounds

Neutral foreground tokens provide contrast-safe foreground colors for neutral backgrounds.

Neutral Borders

Neutral border tokens define border colors used on neutral surfaces and high-contrast UI elements.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the neutral primary colors
    "--sjs2-color-bg-neutral-primary": "#131D37",
    "--sjs2-color-fg-neutral-primary": "#000000",
    "--sjs2-color-border-neutral-primary": "#D8E1F0"
  }
});

Note tokens define informational and non-critical visual styles used for guidance, contextual messaging, and informational actions.

Note Backgrounds

Note surfaces define informational and non-critical contextual backgrounds.

Note Foregrounds

Note foreground tokens define foreground colors for informational and non-critical messaging and serve as an additional color option where semantic usage is not important.

Note Borders

Note border tokens define border colors used for informational messages, indicators, and note-styled components.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the note primary colors
    "--sjs2-color-bg-note-primary": "#D278F9",
    "--sjs2-color-fg-note-primary": "#6901E7",
    "--sjs2-color-border-note-primary": "#8B2BE2"
  }
});

Positive tokens define success-related visual styles used for confirmations, completed states, and positive feedback.

Positive Backgrounds

Positive (success) background tokens are used for positive states, confirmations, and completed actions.

Positive Foregrounds

Positive (success) foreground tokens define text and icon colors for positive feedback states.

Positive Borders

Positive border tokens define border colors used for success messages, confirmations, and positive indicators.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the positive primary colors
    "--sjs2-color-bg-positive-primary": "#43C43F",
    "--sjs2-color-fg-positive-primary": "#36A732",
    "--sjs2-color-border-positive-primary": "#2E922B"
  }
});

Warning tokens define cautionary visual styles used for attention-requiring states and non-critical issues.

Warning Backgrounds

Warning background tokens are used for cautionary and attention-requiring states.

Warning Foregrounds

Warning foreground tokens define text and icon colors for warning states.

Warning Borders

Warning border tokens define border colors used for warning messages, caution indicators, and attention states.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the warning primary colors
    "--sjs2-color-bg-warning-primary": "#FFBD09",
    "--sjs2-color-fg-warning-primary": "#E2A500",
    "--sjs2-color-border-warning-primary": "#C98D00"
  }
});

Alert tokens define destructive and error-related visual styles used for validation errors, destructive actions, and critical feedback.

Alert Backgrounds

Alert background tokens are used for destructive, invalid, and error-related states.

Alert Foregrounds

Alert foreground tokens define text and icon colors for destructive and error states.

Alert Borders

Alert border tokens define border colors used for error states, destructive actions, and validation indicators.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the alert primary colors
    "--sjs2-color-bg-alert-primary": "#DD0000",
    "--sjs2-color-fg-alert-primary": "#B20000",
    "--sjs2-color-border-alert-primary": "#990000"
  }
});

Static tokens define fixed foreground and background contrast pairs. Unlike semantic backgrounds and foregrounds, these tokens are intended for contexts where predictable contrast is required regardless of the active theme. Static colors remain unchanged across light and dark themes variations.

Static Backgrounds

Static backgrounds define fixed foreground/background contrast pairs.

Static Foregrounds

Static foreground tokens provide fixed contrast colors intended for contextual surfaces.

Static Borders

Static border tokens define fixed border colors intended for contextual surfaces.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the static colors
    "--sjs2-color-bg-static-1-primary": "#FFFFFF",
    "--sjs2-color-bg-static-2-primary": "#000000".
    "--sjs2-color-fg-static-1-primary": "#E4EBF2",
    "--sjs2-color-fg-static-2-primary": "#1D252D",
    "--sjs2-color-border-static-1-primary": "#D5DCE3",
    "--sjs2-color-border-static-2-primary": "#1D252D"
  }
});

Utility tokens define application-level shadows, overlays, and layout surfaces used across SurveyJS containers.

Shadows

Backgrounds

Example:

survey.applyTheme({
  "cssVariables": {
    // Override a utility background color
    "--sjs2-color-utility-surface-survey": "#E4EBF2",
    "--sjs2-color-utility-surface-survey-panelless": "#FFFFFF"
  }
});

Radius tokens define corner shapes used across SurveyJS components. These tokens help maintain consistent component geometry.

Example:

survey.applyTheme({
  "cssVariables": {
    // Increase corner roundness
    "--sjs2-radius-form": "12px",
    "--sjs2-radius-form-item": "8px"
  }
});

Opacity tokens control transparency levels used for visibility states, interaction feedback, overlays, and disabled elements. These tokens help create consistent visual emphasis and interaction behavior across components.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the opacity for disabled elements
    "--sjs2-opacity-disabled": "var(--sjs2-opacity-x050)"
  }
});

Border effect tokens define shadow- and outline-based visual treatments applied around component edges. They control visual elevation, focus indication, interaction feedback, and surface emphasis across different component states.

Border effect values follow the box-shadow CSS property value structure:

offset-x offset-y blur spread color

For example:

"--sjs2-border-effect-floating-default": "0px 6px 20px 0px #000000"

Border effect tokens are built from lower-level primitives that define shadow geometry and positioning. These primitives feed semantic --sjs2-border-effect-* tokens for surfaces, triggers, floating layers, and component states. Updating primitives propagates changes across all dependent effects.

Floating border effects define elevation styling for transient UI layers that sit above the main surface (overlays, popovers, dropdowns).

Example:

survey.applyTheme({
  "cssVariables": {
    // Increase floating surface elevation
    "--sjs2-border-effect-floating-default": "0px 10px 32px 0px rgba(0, 0, 0, 0.18)"
  }
});

Surface border effects define state-driven styling for container-level components.

Example:

survey.applyTheme({
  "cssVariables": {
    // Increase surface outline emphasis
    "--sjs2-border-effect-surface-default": "0px 0px 0px 2px rgba(8, 93, 229, 0.14)"
  }
});

Trigger border effects define states for small interactive UI controls such as actions and buttons.

Example:

survey.applyTheme({
  "cssVariables": {
    // Customize trigger outline styling
    "--sjs2-border-effect-trigger-default": "0px 0px 0px 1px rgba(0, 21, 54, 0.24)"
  }
});

Form element border effects control the appearance of individual controls, such as input fields, checkboxes, radio buttons, and toggles. Unlike floating layers, surfaces, and triggers, form elements do not have dedicated semantic border effect tokens. Instead, their border effects are derived from border effect primitives, which allow you to customize all form elements consistently.

Example:

survey.applyTheme({
  "cssVariables": {
    // Increase the blur radius of focused form element border effects
    "--sjs2-border-blur-form-focused": "2px"
  }
});

Typography tokens define the text system used throughout the SurveyJS UI. They control font families, font weights, text sizing, and vertical rhythm to ensure consistent readability and visual hierarchy.

Font Families

These tokens define the primary typefaces across the interface.

Font Weights

These tokens define the font weights used across the interface.

Font Sizes

Typography size tokens define the text scale used throughout the UI.

Line Heights

Line height tokens define vertical spacing between lines of text.

Example:

survey.applyTheme({
  "cssVariables": {
    // Change the font family and increase the default font size and line height
    "--sjs2-typography-font-family-text": "Inter",
    "--sjs2-typography-font-size-default": "var(--sjs2-font-size-x250)",
    "--sjs2-typography-line-height-default": "var(--sjs2-line-height-x400)"
  }
});

Survey Creator tokens customize the appearance of Survey Creator elements. These tokens primarily control workspace surfaces and editor backgrounds.

Surfaces

Example:

creator.applyTheme({
  "cssVariables": {
    // Customize Survey Creator workspace surfaces
    "--sjs2-color-utility-surface-designer": "#edf9f7",
    "--sjs2-color-utility-surface-logic": "#f5fbfa",
    "--sjs2-color-utility-surface-json-editor": "#f7fafc"
  }
});

Dashboard tokens customize the appearance of SurveyJS Dashboard elements, including tables, charts, analytics views, and data visualizations.

Surface

Chart Colors (Axis & Grid)

These tokens define the colors used for the chart grid.

Chart Colors (Background)

These tokens define the default palette used in charts.

Chart Colors (Borders)

Border colors default to their matching chart background colors.

Chart Colors (Foreground)

Foreground tokens define text and icon colors displayed on chart-colored surfaces.

Example:

dashboard.applyTheme({
  "cssVariables": {
    // Customize dashboard chart palette
    "--sjs2-color-data-chart-bg-color-1": "#4F46E5",
    "--sjs2-color-data-chart-bg-color-2": "#0EA5E9",
    "--sjs2-color-data-chart-bg-color-3": "#10B981",
    "--sjs2-color-data-chart-bg-color-4": "#F59E0B",
    "--sjs2-color-data-chart-bg-color-5": "#EF4444"
  }
});

When you apply a theme to a PDF document, only color tokens are applied. Layout-related tokens such as spacing, sizing, typography, border radius, and border width are configured separately through a PDF layout object. This separation exists because printed and PDF forms often require different spacing, typography, and proportions than web-based forms.

PDF Generator includes two predefined layout presets:

• Compact – Optimized for dense forms and reduced page count
• Spacious – Optimized for readability

These layout presets include system tokens, typography tokens, and PDF-specific tokens with -pdf- in their names. PDF-specific tokens specify the radius, border width, paddings, and gaps between elements in a generated PDF form. For a complete list of layout tokens, refer to the layout preset definitions on GitHub:

• compact.ts
• spacious.ts

Use the applyTheme() method to override colors, and the PDF-specific applyLayout() method to override layout and typography settings.

surveyPdf.applyTheme({
  "cssVariables": {
    // Override the primary brand color used in the PDF
    "--sjs2-color-project-brand-600": "#085DE5"
  }
});

surveyPdf.applyLayout({
  // Override the default font family
  "--sjs2-typography-font-family-text": "Noto Serif",
   // Override the border width used for questions
  "--sjs2-pdf-border-width-question": "var(--sjs2-border-width-x200)"
});

Individual component tokens allow you to override semantic token values for specific UI components without affecting the entire design system. These tokens provide component-level customization for colors, typography, spacing, borders, and radii.

Use component tokens when a specific component requires custom styling that differs from the shared system defaults.

Most component tokens follow this naming structure:

--sjs2-[domain]-[subdomain]-component-[component-name]-[role]-[variant]-[state]-[property]

The following token name segments were described earlier:

• Domains & Subdomains
• Roles
• Variants

Component segments target specific UI elements.

States define interactive or contextual appearance.

Property segments specify which visual aspect is styled.

Buttons, actions, and interactive controls derive their appearance from the brand, alert, and neutral semantic token groups by default. To customize them, use tokens containing -component-action-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override main action button colors
    "--sjs2-color-component-action-brand-primary-default-bg": "#FEE71B",
    "--sjs2-color-component-action-brand-primary-default-icon": "#000000",
    "--sjs2-color-component-action-brand-primary-default-label": "#000000",

    // Override alert button colors
    "--sjs2-color-component-action-alert-primary-default-bg": "#FE481B",
    "--sjs2-color-component-action-alert-primary-default-icon": "#FFFBFA",
    "--sjs2-color-component-action-alert-primary-default-label": "#FFFBFA"
  }
});

Complete Token List

Question panels group related survey content into structured containers on a surface. To customize them, use tokens containing -component-panel-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the corner radius and background color of panels
    "--sjs2-radius-component-panel": "var(--sjs2-radius-x250)",
    "--sjs2-color-component-panel-default-bg": "var(--sjs2-palette-gray-100)"
  }
});

Complete Token List

Question-related tokens control question titles, descriptions, and supporting text. Use tokens containing -component-question- to customize question titles and descriptions.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the color and font size of question titles and descriptions
    "--sjs2-color-component-question-default-title": "var(--sjs2-palette-gray-850)",
    "--sjs2-color-component-question-default-description": "var(--sjs2-palette-gray-600)",
    "--sjs2-typography-font-size-component-question-title": "var(--sjs2-font-size-x300)",
    "--sjs2-typography-font-size-component-question-description": "var(--sjs2-font-size-x150)"
  }
});

Complete Token List

Input field tokens control text containers, including text boxes, text areas, dropdown inputs, and button groups. Use tokens containing -component-formbox- to customize the input fields.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the corner radius of input fields
    "--sjs2-radius-component-formbox": "var(--sjs2-radius-round)",

    // Override the background and border colors of input fields
    "--sjs2-color-component-formbox-default-bg": "var(--sjs2-color-bg-basic-primary)",
    "--sjs2-color-component-formbox-default-border": "var(--sjs2-color-border-basic-primary)"
  }
});

Complete Token List

Input text tokens control text color, placeholder styling, and other editable input field content. They derive from basic foreground colors by default. To override them, use tokens containing -component-input-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the input value color in default and disabled states
    "--sjs2-color-component-input-default-value": "#2C2625",
    "--sjs2-color-component-input-disabled-value": "#D8D1D0"
  }
});

Complete Token List

Selection controls expose separate tokens for selected and unselected states.

Use tokens containing:

• -component-check- – Checkboxes and radio buttons
• -component-toggle- – ON/OFF toggles (switches)
• -component-boolean- / -component-boolean-item- – Yes/No (Boolean) question toggles
• -component-buttongroup-item- – Button group items

-true- or -false- in the token name indicates the control state.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the color of the checkbox background
    "--sjs2-color-component-check-true-default-bg": "#063AC8",
    "--sjs2-color-component-check-false-default-bg": "#E4EBF2",

    // Override the color of the ON/OFF toggle background
    "--sjs2-color-component-toggle-true-default-bg": "#063AC8",
    "--sjs2-color-component-toggle-false-default-bg": "#E4EBF2",

    // Override the color of the Yes/No (Boolean) question value
    "--sjs2-color-component-boolean-item-true-default-value": "var(--sjs2-color-fg-neutral-on-primary)",
    "--sjs2-color-component-boolean-item-false-default-value": "var(--sjs2-color-fg-neutral-primary)",

    // Override the color of the button group item value
    "--sjs2-color-component-buttongroup-item-true-default-value": "var(--sjs2-color-fg-brand-on-primary)",
    "--sjs2-color-component-buttongroup-item-false-default-value": "var(--sjs2-color-fg-brand-primary)"
  }
});

Complete Token List

Slider tokens customize track, thumb, and interaction visuals. For customization, use tokens containing -component-slider-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the slider thumb color
    "--sjs2-color-component-slider-default-thumb": "var(--sjs2-palette-gray-900)"
  }
});

Complete Token List

Tag box tokens customize selected item tags in multi-select dropdowns. For customization, use tokens containing -component-tagbox-item-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the colors of the tag background, border, and label
    "--sjs2-color-component-tagbox-item-default-bg": "var(--sjs2-color-bg-brand-primary)",
    "--sjs2-color-component-tagbox-item-default-border": "var(--sjs2-color-border-brand-primary)",
    "--sjs2-color-component-tagbox-item-default-label": "var(--sjs2-color-fg-brand-on-primary)"
  }
});

Complete Token List

Validation message tokens customize error, warning, and informational messages in forms. Use tokens containing -component-message-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the colors of the background, icon, and text in error messages
    "--sjs2-color-component-message-error-bg": "var(--sjs2-color-bg-alert-primary)",
    "--sjs2-color-component-message-error-icon": "var(--sjs2-color-fg-alert-on-primary)",
    "--sjs2-color-component-message-error-text": "var(--sjs2-color-fg-alert-on-primary)",

    // Override the colors of the background, icon, and text in warning messages
    "--sjs2-color-component-message-warning-bg": "var(--sjs2-color-bg-warning-primary)",
    "--sjs2-color-component-message-warning-icon": "var(--sjs2-color-fg-warning-on-primary)",
    "--sjs2-color-component-message-warning-text": "var(--sjs2-color-fg-warning-on-primary)",

    // Override the colors of the background, icon, and text in info messages
    "--sjs2-color-component-message-info-bg": "var(--sjs2-color-bg-note-primary)",
    "--sjs2-color-component-message-info-icon": "var(--sjs2-color-fg-note-on-primary)",
    "--sjs2-color-component-message-info-text": "var(--sjs2-color-fg-note-on-primary)",

    // Override the corner radius of all validation messages
    "--sjs2-radius-component-message": "var(--sjs2-radius-x200)"
  }
});

Complete Token List

Header and page tokens customize survey titles, descriptions, and typography. Use tokens containing -component-header- or -component-page-.

Example:

survey.applyTheme({
  "cssVariables": {
    // Override the font family of the survey title and description
    "--sjs2-typography-font-family-component-header-title": "Playfair Display",
    "--sjs2-typography-font-family-component-header-description": "Inter",

    // Override the colors of page titles and descriptions
    "--sjs2-color-component-page-default-title": "var(--sjs2-color-fg-brand-primary)",
    "--sjs2-color-component-page-default-description": "var(--sjs2-color-fg-basic-primary)"
  }
});

Complete Token List

Refer to the following file in GitHub to view the full list of available tokens:

base-theme.scss