Automattic Design System

System architecture

The WordPress design system is implemented as a combination of theming infrastructure and UI component implementations, supported by shared design tokens. These layers form a scalable foundation for building consistent, themeable, and accessible user interfaces across the WordPress admin and plugin ecosystem.

Code Implementation

The design system’s code implementation is split into two primary packages within the Gutenberg repository:

  • @wordpress/theme provides the theming foundation and runtime customization layer.
    • Defines the system’s design tokens (color, typography, spacing, etc.) as CSS custom properties.
    • Exposes a <ThemeProvider> React component that synchronizes tokens across the application through context and CSS variable injection.
    • Supports user and plugin customization, enabling shared themes and personalized appearances without duplicating logic.
    • Handles dynamic color generation to ensure accessible contrast across light, dark, and custom accent themes.
  • @wordpress/ui implements the design system’s primitives and foundational React components.
    • Built using the design tokens and theme context provided by @wordpress/theme.
    • Distributed using npm, and is not available under window.wp, ensuring modularity and future versioning.
    • Designed for composability so that components can be used independently, composed into higher-order patterns, or extended by plugins.
    • Prioritizes accessibility, responsiveness, and performance through minimal abstractions and semantic markup.

How these layers interact:

  1. Design tokens define the shared vocabulary for color, spacing, typography, and other foundational properties.
  2. The ThemeProvider exposes these tokens as runtime variables, applying theme customizations (e.g., density, accent color, user preferences).
  3. UI components consume the tokens and theme context to render consistent, theme-aware interfaces.
  4. Plugins and admin screens import only the components or tokens they need, minimizing bundle size and avoiding dependency conflicts.

Token structure

The token system follows a semantic naming convention that emphasizes function over appearance. All public tokens are exported as CSS custom properties that conform to the Design Token Community Group (DTCG) spec, for example --wpds-color-fg-content-neutral.

Color tokens follow this structure:

--wpds-color-<element>-<role>[-<tone>][-<emphasis>][-<state>]

Where:

  • element describes the layer being colored, such as bg (background), fg (foreground), or stroke.
  • role communicates the semantic usage, e.g. surface, interactive, content, track, thumb, or focus.
  • tone indicates the tonal ramp applied, most commonly neutral, brand (primary), and occasionally info, success, caution, warning, or error.
  • emphasis (optional) distinguishes intensity. Today we use strong and weak; when omitted it represents the default emphasis.
  • state (optional) captures UI state such as active or disabled.

Some tokens omit segments that are not relevant to their role (for example, --wpds-color-stroke-focus-brand has no emphasis or state). The same pattern is used for other semantic groups aligning naming across the design system.

Examples

  • --wpds-color-fg-content-neutral – default foreground color for body copy.
  • --wpds-color-bg-interactive-brand-strong-active – active state background for primary interactive elements like ‘Solid’ buttons.
  • --wpds-color-stroke-surface-info-strong – strong informational stroke for surface outlines.

Descriptions for every token are generated in packages/theme/docs/ds-tokens.md, providing designers and engineers with usage guidance.

Themes and application

Themes are generated from a set of seed colors defined in packages/theme/src/color-ramps/lib/constants.ts. We derive:

  • One neutral ramp from the bg seed, which powers foundational surfaces, fills, and neutral strokes.
  • Multiple accent ramps from the primary, info, success, caution, warning, and error seeds. These ramps produce the brand and status tones that map onto interactive, content, and surface tokens.

The ramp builder (packages/theme/src/color-ramps) guarantees required contrast pairings via automated checks, and the resulting values are mapped to the semantic tokens listed above. Because token names remain stable across themes, changing a theme only requires supplying new seed colors—the consuming components, Figma libraries, and CSS references stay untouched.

Connecting Tokens to design

Tokens are integrated at both atomic and component levels. In Figma they are imported and exposed as variables to ensure accurate mockups. In code, the generated map in packages/theme/src/design-tokens.ts is consumed by the theme provider, so both disciplines rely on the same source of truth.

This unified approach ensures that:

  • Components remain visually consistent across modes and platforms.
  • Themes can be modified, swapped, or extended without refactoring components.
  • Designers and developers speak the same visual language.

Why Tokens matter

The semantic token system helps deliver:

  • Accessibility: All fg/bg pairings are curated to meet WCAG contrast standards.
  • Visual clarity: Grouped by role and tone for intuitive usage.
  • Theming: Easy to extend or switch themes without disrupting components.
  • Improved handoff: Shared vocabulary and structure for both design and code.
  • Maintainability: Systematic naming and values reduce drift and duplication.

By focusing on function and consistency, the token system supports scalable, inclusive design across the entire product ecosystem.