# Usage This page covers advanced usage patterns for `@solid-design-system/tokens`. Make sure you've completed the Installation first. {/* prettier-ignore */} Theme Host {/* prettier-ignore */} Theme Consumer ## Switching themes ### System preference (Light/Dark Mode) To automatically respect the user's OS-level preference, use the `prefers-color-scheme` media query on your `` tags: ```css @import '@solid-design-system/tokens/dist/themes/ui-light/ui-light.css' (prefers-color-scheme: light); @import '@solid-design-system/tokens/dist/themes/ui-dark/ui-dark.css' (prefers-color-scheme: dark); ``` For further information on how to make this more dynamic, check out [this article](https://pepelsbey.dev/articles/native-light-dark/). ### Manual control (Class-based theming) For finer granularity, apply a theme class on `` or any wrapper element. Each theme class follows the pattern `sd-theme-[name]`. After importing, `ui-light` is automatically applied if no other theme class is set on ``. ```html ``` This makes it easy to toggle between themes programmatically, for example when the user switches between light and dark mode. ## Creating your own theme You can create your own theme by overriding CSS variables. There are two main types of tokens you can customize: ### Primitive tokens Primitive variables define the base values used across all components. They act as fallbacks for all other variables. Example — changing the primary color globally: ```css --sd-color-primary: 255 0 85; ``` This change will affect every component that uses the primary color. ### Semantic tokens Semantic tokens are divided into general and component-specific variables. #### General semantic tokens These let you target specific use cases without interfering with other parts that use the same primitive variable. Example — overriding only the primary background color: ```css --background-color-primary: 255 230 238; ``` This overrides only "primary background" usages while everything else falls back to the primitive tokens. #### Component-specific semantic tokens If you want to customize variables for a single component, override its semantic tokens. Example — changing only the primary background color of `sd-button`: ```css --sd-button--primary--default--default-color-background: 255 0 85; ``` The full list of available component-specific variables is documented on each component's `docs` page. Even if a component doesn't yet have full semantic variable support, you can still apply overrides within the component's scope using general semantic tokens: ```css sd-button { --background-color-primary: 255 0 85; } ``` This will only affect the primary background color inside `sd-button` components. ## Versioning & migration Make sure the **theme you load** (from `@solid-design-system/tokens`) is at a version **equal to or higher than** the highest `@solid-design-system/components` and `@solid-design-system/styles` version used anywhere on the page — including by any embedded consumers. ### Deprecated CSS variables (tokens) The following CSS variables (tokens) are deprecated. Please update your custom styles to use the recommended replacements. If you manage an environment that still requires the use of these variables, please refer to the Installation section on loading `legacy-variables.css`. #### Deprecated variables:
Deprecated variable Replacement
`--sd-button--size-lg-border-radius` `--sd-button-border-radius`
`--sd-button--size-md-border-radius` `--sd-button-border-radius`
`--sd-button--size-sm-border-radius` `--sd-button-border-radius`
`--sd-button--secondary--inverted--color-border` `--sd-button-secondary-inverted-color-border`
`--sd-form-control-color-icon` `--sd-form-control-color-icon-fill`
`--sd-menu-color-icon` `--sd-menu-item-color-icon-fill`
`--sd-menu-color-text` `--sd-menu-item-color-text`
`--sd-menu--disabled-color-icon` `--sd-menu-item--disabled-color-icon-fill`
`--sd-menu--disabled-color-text` `--sd-menu-item--disabled-color-text`
`--sd-tag-font-weight` `--sd-choice-control-font-weight`
`--sd-tag--disabled-color-border` `--sd-color-border-neutral-500`
`--sd-navigation-item--current-color-text` `--sd-navigation-item-color-text`
`--sd-option--disabled-color-border` `--sd-color-border-neutral-500`
`--sd-audio__timestamp-color-text` `--sd-color-text-neutral-700`
`--sd-accordion__chevron-color-text` `--sd-accordion-color-icon-fill`
`--sd-chip--primary-200-color-background` `--sd-chip--primary-low-color-background`
`--sd-chip--primary-200-color-border` `--sd-chip--primary-subtle-color-filled-border`
`--sd-chip--primary-300-color-background` `--sd-chip--primary-medium-color-background`
`--sd-chip--primary-300-color-border` `--sd-chip--primary-medium-color-filled-border`
`--sd-chip--primary-500-color-background` `--sd-chip--primary-high-color-background`
`--sd-chip--primary-500-color-border` `--sd-chip--primary-high-color-filled-border`
`--sd-chip--primary-500-color-text` `text-black`
`--sd-chip--white-color-border` `--sd-chip--white-color-filled-border`
`--sd-chip-font-size` `--sd-marker-font-size`
`--sd-chip-font-weight` `--sd-marker-font-weight`
`--sd-flag-border-radius` `--sd-chip-border-radius`
`--sd-flag-border-width` `--sd-chip-border-width`
`--sd-flag--neutral-200-color-background` `--sd-chip--neutral-low-color-background`
`--sd-flag--neutral-200-color-border` `--sd-chip--neutral-low-color-filled-border`
`--sd-flag--neutral-300-color-background` `--sd-chip--neutral-medium-color-background`
`--sd-flag--neutral-300-color-border` `--sd-chip--neutral-medium-color-filled-border`
`--sd-flag--neutral-500-color-background` `--sd-chip--neutral-high-color-background`
`--sd-flag--neutral-500-color-border` `--sd-chip--neutral-high-color-filled-border`
`--sd-flag--white-color-background` `--sd-chip--white-color-background`
`--sd-flag--white-color-border` `--sd-chip--white-color-filled-border`
## Using tokens As a Theme Consumer, you use design tokens (CSS variables, SCSS variables, or Tailwind utilities) to style your custom components. The theme — and therefore the resolved values of these tokens — is provided by the Theme Host. For setup instructions per format (CSS, SCSS, Tailwind), see the Installation page. ### Key principles - **Never import or bundle a theme CSS file.** The host provides the theme. Your components inherit it automatically. - **Use tokens instead of hard-coded values.** This keeps your styles in sync with the design system and ensures your app looks correct in any theme the host applies (light, dark, brand variants). - **Avoid deprecated CSS variables (tokens)** in your custom styling — check each component's documentation for current replacements. Deprecated variables will be removed in a future release. ## Primitive tokens Primitive tokens define the base values of the design system — colors, spacing, typography scales, etc. They are theme-independent raw values and act as the foundation for all other tokens. Use primitive tokens when no semantic token exists for your use case, or when you intentionally want to reference a fixed raw value regardless of context. This is not possible in TailwindCSS, which only exposes semantic tokens. {/* prettier-ignore */} CSS {/* prettier-ignore */} SCSS ```css .my-element { background-color: rgba(var(--sd-color-background-primary)); color: rgba(var(--sd-color-white)); } ``` ```scss @import '@solid-design-system/tokens/dist/scss'; .my-element { background-color: rgba($sd-color-primary); color: rgba($sd-color-white); } ```` ## Semantic tokens Semantic tokens give meaning to raw values — they describe the *intent* (e.g. "primary background", "error text") rather than the actual value. They resolve to primitive tokens under the hood, but can vary per theme. Prefer semantic tokens over primitive tokens in your custom components. This ensures your styles adapt automatically when the Theme Host switches themes (e.g. light → dark, brand variants). {/* prettier-ignore */} CSS {/* prettier-ignore */} SCSS {/* prettier-ignore */} TailwindCSS ```css .my-element { background-color: rgba(var(--sd-color-background-primary-100)); color: rgba(var(--sd-color-text-black)); } ```` ```scss @import '@solid-design-system/tokens/dist/scss'; .my-element { background-color: rgba($sd-color-background-primary-100); color: rgba($sd-color-text-black); } ```` ```html
...
```` ## Local development When developing in isolation (e.g. Storybook, local dev server), no Theme Host is present — so you need to import a theme yourself for testing purposes. Make sure this dev-only theme import does **not** end up in your production bundle. Use a dev-only entry point, Storybook-specific configuration, or a build-time condition that strips the import for production. Example for Storybook's `preview.js`: ```js ``` ## Optional: Standalone fallback If your app should be able to run standalone, you may add a runtime fallback that loads a theme. You can load the theme however fits your setup — including lazy loading via a dynamically injected `` tag. What matters is **scoping**: the fallback theme must never leak into the host's document. **Always scope the fallback theme to your own subtree.** Never inject unscoped theme variables into the host's document. Options include: - Wrapping the theme's CSS variables inside a selector targeting your app's root element (e.g. `#my-app { ... }`) - Injecting the theme `` inside a Shadow DOM boundary Injecting global, unscoped theme variables can silently override the host's theme and cause hard-to-debug styling issues across the entire page. ## Versioning coordination Coordinate with the Theme Host team on versioning: - The **theme the host loads** must be from a `@solid-design-system/tokens` version **equal to or higher than** the `@solid-design-system/components` and `@solid-design-system/styles` versions you deploy. - If you upgrade your components or styles, notify the host so they can upgrade their theme accordingly. - This will become a hard requirement in a future release — aligning now avoids breakage later. {/* */}