Principle:Langgenius Dify Theming
| Knowledge Sources | Dify |
|---|---|
| Domains | Frontend, Theming |
| Last Updated | 2026-02-12 07:00 GMT |
Overview
Theming defines the variable system that supports light and dark mode switching through comprehensive color, spacing, and visual tokens across the Dify frontend.
Description
The Theming principle governs how the Dify frontend supports multiple visual themes, primarily light and dark modes, through a CSS custom property-based token system. Each theme is defined as a complete set of variable values that are applied to the document root, allowing the entire application to switch appearance by swapping one set of variable definitions for another. Components never reference hardcoded color values; instead, they reference semantic tokens that resolve to different values depending on the active theme.
The token system is organized into layers of abstraction. Primitive tokens define the raw color palette (e.g., specific hex values for each shade of blue). Semantic tokens reference primitives and assign contextual meaning (e.g., primary-action, error-text, surface-background). Component tokens reference semantic tokens for specific UI element states (e.g., button-hover-bg, input-border-focus). This layered approach allows theme changes to cascade correctly through all three levels.
Beyond colors, the theming system addresses spacing tokens, shadow definitions, border styles, and opacity values that may differ between themes. Dark mode, for example, typically uses lighter shadows and adjusted border colors to maintain visual hierarchy on dark backgrounds. The comprehensive nature of the token system ensures that theme switching produces a polished result rather than simply inverting colors, which would produce poor contrast and readability in many cases.
Usage
Use this principle when:
- Defining new semantic or component-level theme tokens
- Adding theme-aware styles to new or existing components
- Extending the theming system to support additional visual modes beyond light and dark
Theoretical Basis
Theming is based on the Abstraction Layer pattern, where visual values are indirected through semantic tokens to decouple component styling from specific color values. The multi-tier token system follows the same principles as compiler intermediate representations, providing progressively more abstract levels of description. The approach aligns with the W3C design tokens specification, which standardizes the format and semantics of cross-platform design tokens.