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 1 – Base Tokens
• Layer 2 – Primitive Scales
• Layer 3 – Semantic Tokens
• Layer 4 – Components 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);

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.

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

• Palette scale
  Defines raw color material used by the design system.

• Typography scale
  Defines font families, sizes, weights, line heights, and other typographic properties.

• Spacing scale
  Defines the standard increments used to control distances between UI elements.

• Sizing scale
  Defines standard dimensions for UI elements, such as widths, heights, and control sizes.

• Border width scale
  Defines standard widths for borders and outlines.

• Radius scale
  Defines standard corner radii for UI elements.

• Opacity scale
  Defines standard transparency levels for UI elements and visual effects.

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.

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

Example:

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

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

View Brand Color Tokens

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.

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"
  }
});

View Basic Color Tokens

Neutral tokens define high-contrast, non-brand visual styles used for generic actions, overlays, and utility 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"
  }
});

View Neutral Color Tokens

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

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"
  }
});

View Note (Informational) Color Tokens

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

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"
  }
});

View Positive Color Tokens

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

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"
  }
});

View Warning Color Tokens

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

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"
  }
});

View Alert Color Tokens

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.

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"
  }
});

View Static (Contextual) Color Tokens

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

Example:

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

View Utility Color Tokens

For individual component color customization, use tokens that start with --sjs2-color-component-*.

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"
  }
});

View Radius Tokens

For individual component size customization, use tokens that start with --sjs2-radius-component-*.

Size tokens define predefined size values used by UI components. They provide consistent dimensions and spacing across controls and other interface elements.

Example:

survey.applyTheme({
  "cssVariables": {
    // Make all medium-sized components use a larger size value
    "--sjs2-size-medium": "var(--sjs2-size-x700)",

    // Make compact components slightly larger
    "--sjs2-size-x-small": "var(--sjs2-size-x500)"
  }
});

View Size Tokens

For individual component size customization, use tokens that start with --sjs2-size-component-*.

Spacing tokens define semantic spacing values used by component layout tokens. They provide consistent distances between UI elements and help maintain visual rhythm across the interface.

View Spacing Tokens

For individual component spacing customization, use tokens that start with --sjs2-layout-component-*.

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)"
  }
});

View Opacity Tokens

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 floating layers, surfaces, triggers, and component states. Updating primitives propagates changes across all dependent effects.

Semantic border effect tokens include the following token groups:

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

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

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

Examples:

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

    // Increase surface outline emphasis
    "--sjs2-border-effect-surface-default": "0px 0px 0px 2px rgba(8, 93, 229, 0.14)",

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

For individual component border effect customization, use tokens that start with --sjs2-border-effect-component-*.

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.

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)"
  }
});

View Typography Tokens

For individual component typography customization, use tokens that start with the following:

• --sjs2-typography-font-family-component-*.
• --sjs2-typography-font-weight-component-*.
• --sjs2-typography-font-size-component-*.
• --sjs2-typography-line-height-component-*.

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

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"
  }
});

View Survey Creator Tokens

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

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"
  }
});

View Dashboard Tokens

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 primitive scale 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.

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"
  }
});

View Action Tokens

Panels group related survey content into structured containers. Use tokens containing the following patterns to customize different panel types:

Example:

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

View Panel Tokens

Question-related tokens control question titles, descriptions, layout, and supporting text. To customize them, use tokens containing -component-question-.

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)"
  }
});

View Question Tokens

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)"
  }
});

View Input Field Tokens

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"
  }
});

View Input Field Text Tokens

Selection controls expose separate tokens for selected and unselected states.

-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-checkbox-true-default-bg": "#063AC8",
    "--sjs2-color-component-checkbox-false-default-bg": "#E4EBF2",

    // Override the color of the radio button background
    "--sjs2-color-component-radio-true-default-bg": "#063AC8",
    "--sjs2-color-component-radio-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)"
  }
});

View Checkbox, Radio Button & Toggle Tokens

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)"
  }
});

View Slider Tokens

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)"
  }
});

View Tag Box Tokens

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)"
  }
});

View Validation Message Tokens

Page tokens customize page titles, descriptions, typography, and layout. Use tokens containing -component-page-.

Example:

survey.applyTheme({
  "cssVariables": {
    // 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)"
  }
});

View Page Tokens

Survey tokens customize survey titles, descriptions, typography, and layout. Use tokens containing -component-survey-.

Example:

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

View Survey Tokens

These tokens define styles for shared UI components used across SurveyJS products.

Complete Design Token List