Skip to content

Builds on

Author: Shibin Das (d34dman)Last updated

Draft

Design System API isn't a fresh start. It continues work that many people have done in Drupal core, in contrib and in web standards, and it only exists because that work does. This page lists that work, so you can see what the module stands on and where its ideas come from. Credit for each item belongs to the people on its issue or project page.

Missing something, or is a relation wrong? Say so in the plan issue.

How to read the "relation" column: builds on means the module uses it directly; follows means it continues or depends on that work; same goal means it tackles the same problem from another side; complements means it fits next to it; workaround means the module works around a bug reported there. Statuses are as of 2026-10-04.

Drupal core

Design tokens

Issue Title Status Relation
#3531854 Add a Design Tokens & CSS variables API Closed (fixed) Builds on. Every contract token is declared through this API, in DTCG format.
#3533198 [Meta] Make Drupal the first "design-system native" CMS + Unify & simplify render & theme systems Active Same goal. The umbrella that the tokens and style utility APIs come from.
#3622909 Add remaining design tokens value types Active Follows. Color, border and shadow types; the module's interim color and shadow plugins go when this lands.
#3590100 Add support for design tokens aliases Active Follows. The module resolves {references} itself until core does.
#3624211 Add SDC specific design tokens Active Complements. Component tokens next to the shared semantic vocabulary.
#3628095 Design token discovery fails on a value of the wrong shape Active Workaround. Found while building on the API; the module catches the error until core does.
#3155531 Naming convention of color shades in the Drupal Design System Active Same goal. A shared, predictable color vocabulary.
#3296202 Support CSS custom properties in attachments Active Complements. A server-side way to emit custom properties.
#3267149 Front-end demo for core CSS custom property API Closed (fixed) Follows. Earlier work on a core custom-property API.
#2998210 Support CSS variables Closed (outdated) Follows. The first request to adopt CSS variables in core.

Components, styles and icons

Issue Title Status Relation
#3313520 Single-directory components in core Closed (fixed) Builds on. SDC is the component layer patterns are realized in.
#3340712 Add Single Directory Components as a new experimental module Closed (fixed) Builds on. The original SDC addition.
#3390712 Add component variants to SDC Closed (fixed) Builds on. Variants as data.
#3522644 Add an advanced variants notation to SDC Active Complements. Richer variant metadata.
#3517033 Add a style utility API Needs work Complements. Style utilities and settings such as color scheme, contrast and motion; contract rules can point at them instead of repeating them.
#3471494 Add an icon management API Closed (fixed) Complements. The icon side of a shared design contract.
#3365605 [Meta] Convert core UI components to use single directory components Active Same goal. Core UI as shared components instead of per-theme markup.
#3476854 SDC: Sharing through composer and discovery mechanism Active Complements. Sharing components across themes and projects.
#2702061 Unify & simplify render & theme system: component-based rendering (enables pattern library, style guides, interface previews, client-side re-rendering) Postponed Same goal. The long-standing plan for component-based rendering.
#3092431 [meta] Accommodate component-based theming Active Same goal. Component-based theming.
#3444525 Compatibility of SDC use with display/experience builders Closed (outdated) Complements. SDC as the shared surface for page builders.
#3470829 Support for CSS Cascade Layer import in CssOptimizer Active Complements. Aggregation support for the cascade layers the module's CSS uses.

The admin theme and core themes

Issue Title Status Relation
#3556948 Merging Gin as Admin theme Closed (fixed) Builds on. Default Admin is the first theme an adapter fills the contract from.
#3599680 Consolidate, merge, and refactor Gin's CSS variable's into Admin theme's original variables. Closed (fixed) Builds on. Produced the --admin-* variables the adapter maps.
#3606571 Round 2 of consolidating CSS Variables Closed (fixed) Builds on. The second round of that consolidation.
#3605702 Remove remaining Gin and Claro implementation names from Default Admin theme Closed (fixed) Builds on. Neutral names the adapter can depend on.
#3623097 Remove remaining Gin and Claro implementation names from Default Admin theme, part 2 Closed (fixed) Builds on. Part 2 of #3605702.
#3582833 Consolidate, refactor, remove and untangle Claro's CSS from Default Admin theme Closed (fixed) Follows. Separates Default Admin from Claro.
#3590364 Part 2 of Consolidate, refactor, remove and untangle Claro's CSS from Default Admin theme Closed (fixed) Follows. Part 2 of #3582833.
#3576488 [meta] Admin theme: path to beta and stable Active Follows. The roadmap the Default Admin adapter tracks.
#3624359 Remove "lifecycle: experimental" from Admin's info.yml Fixed Follows. A stable target for the adapter.
#3582351 [Meta] Clean up CSS within Admin theme Active Complements. Cleaner theme CSS makes the adapter smaller.
#3619933 Drupal Admin Theme Colors Active Same goal. About 200 color combinations across accents, dark mode and more contrast; the module expresses them as tokens and contrast rules.
#3616500 default_admin: Create order to gray primitive CSS variables Active Complements. Orderly primitives under the semantic layer.
#3616502 default_admin: Check if certain colors can an be built from variables to allow easier overrides Active Same goal. Colors built from variables, so they can be overridden.
#3621155 Remove contrib-specific selectors from the Admin theme CSS Needs review Same goal. Modules style themselves against a contract, instead of themes styling modules.
#3628096 Default Admin attaches a library it doesn't define Active Found while building the adapter.
#3530852 [meta] Admin theme modernisation Closed (duplicate) Follows. The predecessor of the Gin-into-core work.
#3576460 [policy, no patch] Deprecate and remove Claro Closed (fixed) Follows. Themes leave core; a contract outlives them.
#3584638 [meta] Tasks to remove the Claro theme Fixed Follows.
#3590816 [policy, no patch] Deprecate Olivero and move to contrib Closed (fixed) Follows. Without a core frontend theme, modules need theme-neutral defaults.
#3595085 [meta] Tasks to remove the Olivero theme Fixed Follows.
#3590882 Standard profile should not include Olivero anymore, should provide guidance on how to get started Closed (fixed) Complements. No default frontend theme, so module defaults matter more.
#3581520 Add default styles for system messages for the front end Active Same goal. Core UI that works on any frontend theme.
#3217923 [Plan] Organize and refactor CSS color variables for Olivero Closed (fixed) Follows. An earlier per-theme color variable system.
#3339559 Claro: Update claro color variables Closed (fixed) Follows. An earlier per-theme color variable system.
#3050384 Provide a starterkit theme in core Closed (fixed) Complements. Generated themes are a natural place to fill the contract.

Accessibility and modes

Issue Title Status Relation
#3606655 Make dark mode a first class citizen of Drupal core Needs review Same goal. The color-scheme preference becomes site-wide; the module's page-side contexts can follow it.
#3613964 Use Style API to manage dark mode in themes and user settings Active Same goal. Color scheme, contrast and reduced motion as style data, like the module's contexts.
#3619827 Ensure a style utility API supports Dark Mode & User Personalization Closed (duplicate) Same goal. Folded into the two issues above.
#3618721 Consider allowing site admins to set global values for light/dark mode Postponed Complements. A site-level default for the mode context.
#3604071 Change default to auto for light/dark mode Closed (fixed) Follows. Default Admin follows the OS setting by default.
#3614864 Adjust CSS for new global dark mode setting per user Active Complements. The admin theme side of the per-user setting.
#3614863 Adjust CSS for new global dark mode setting per user Active Complements. The Navigation side of the per-user setting.
#3612243 List of popular contrib modules that need to be updated to support Admin theme's dark mode Active Same goal. The problem the module solves: each contrib module patched per theme, instead of built once on tokens.
#3413207 META: Provide better support for color and contrast media queries Active Same goal. prefers-contrast and related media queries in core.
#3167032 [Meta] Track CSS forced-color standardization and browser support Active Complements. The forced-colors context.
#3327405 Convert -ms-high-contrast to forced-colors Needs work Complements. Standard forced colors in core CSS.
#3585823 [Meta] Improve the accessibility of the Default Admin theme Active Complements. The contract's must rules and contrast pairs target the same failures.
#3088562 [META] Assess Claro for WCAG colour contrast AA conformance Closed (fixed) Follows. An earlier contrast audit, now written as contrast-pair tests.
#3251278 [META] Designs for dark background layers and its color palette Closed (outdated) Follows. Earlier dark palette design work.
#2928103 [policy, no patch] Use "prefers-reduced-motion" media query to disable animations Active Complements. The contract's a11y/reduced-motion rule.
Issue Title Status Relation
#3506823 Media Library should not assume that the theme's base libraries are present Active Same goal. The Media Library pilot is styled once and works under any theme.
#3506826 Media Library should scope its styles Active Same goal. The pilot scopes Media Library styles to the module.
#3502895 Media Library item styles assume contextual module is present Closed (fixed) Follows. Media Library styling tied to one theme's assumptions.
#3096566 Copy media library styles from Seven to Claro Closed (fixed) Follows. The per-theme copy the pilot replaces with one token-based stylesheet.
#3614955 Move library overrides for Toolbar from Claro and Default Admin to Toolbar Closed (fixed) Same goal. A module owns its styling instead of each theme overriding it.
#3567146 Top bar background color should use CSS variable Closed (fixed) Same goal. Module UI colored by variables, not fixed values.
#3624877 Navigation icons contain hardcoded colors Needs review Same goal. The same, for icons.
#3438895 Add the new Navigation to core as an Experimental module Closed (fixed) Follows. Navigation is module UI on every theme, the case for shared tokens.
#3421969 [PLAN] New Navigation and Top Bar to replace Toolbar Roadmap: Path to Stable Active Follows.
#3557578 Mark Navigation as a stable module Closed (fixed) Follows.
#3560123 Deprecate the Toolbar module Closed (fixed) Follows.
#3586211 Remove the Toolbar module Closed (fixed) Follows.

Admin UI inside frontend themes

Tokens decide which values a module's UI uses, not which theme rules reach it. Keeping a frontend theme's CSS out of admin UI on the same page is an older, separate problem (Q17). Core already ships two answers, both reset fences: the off-canvas dialog's reset (core/misc/dialog/off-canvas/css/reset.css), an ID-scoped all: revert with its own styles re-applied under the same ID, and Navigation's data-drupal-admin-styles reset (#3511280).

Issue Title Status Relation
#2195695 Admin UIs on the front-end are difficult to theme Active Same problem. Open since 2014; weighs iframes, a scoped reset, Shadow DOM and rendering admin UI with the admin theme. Pointed out by seanB in the Media Library review.
#3511280 Front-end theme styles can bleed into Navigation Fixed (11.3, 2025) Follows. Core's second fence: Navigation and the top bar carry data-drupal-admin-styles; a zero-specificity all: revert plus Navigation's own rules raised to ID strength with :is(#extra-specificity-hack, [data-drupal-admin-styles]) (change record). A generic marker already in core.
#2826722 Add a 'fence' around settings tray with aggressive CSS reset Closed (fixed) Follows. The off-canvas reset core ships today.
#2853208 [META] Determine best method ensure consistent theming of Off Canvas Tray Closed (fixed) Follows. Why the reset won over the alternatives.
#2853222 Explore using an IFrame to sandbox CSS for the Off Canvas tray Closed (fixed) Follows. The iframe route, explored and not taken.
#2632584 Add a "public admin" theme subtype so that admin themes can have subthemes for front-end UI components Closed (outdated) Same goal. Admin styling that travels to the frontend.
#3103375 Let themes indicate whether they work as front-end and/or admin themes Needs work Complements. A theme declaring its side; the contract's contexts say the same for values.
#3103380 Allow rendering dialogs using the admin theme Active Complements. Fixes templates and libraries; leaking CSS still needs a boundary.
#3103382 Allow specifying which theme should be used for rendering a render array Postponed Complements. The render-side half of a region that belongs to another design system.

Earlier ideas

From the Ideas queue (now on GitLab); all closed, and the history this work continues.

Issue Title Status Relation
#1804488 [meta] Introduce a Theme Component Library Closed (duplicate) Same goal. A shared component library for themes.
#3090894 Replace color module with a CSS-Variables based module to provide configurable theme parameters Closed (outdated) Same goal. Themes configured through CSS variables.
#2894237 Make core themes more robust in Windows High-Contrast mode Closed (duplicate) Follows. High contrast across all core themes.
#2916453 Decide on committing to and adopting W3C Web Components standards Closed (duplicate) Complements. Custom elements as realizations.
#3017785 Designs for a new admin theme Closed (fixed) Follows. The Claro design system, Drupal's first admin design language.
#3167121 Make Claro the default admin theme Closed (fixed) Follows. An earlier admin theme succession.
#2796001 [prototype] Create design for a Media Library Closed (fixed) Follows. The original Media Library design.
#3476882 [Policy] Move Toolbar module to contrib Closed (fixed) Follows. The policy behind Navigation as the default.

Drupal contrib and initiatives

Project What it is Relation
UI Suite The "design system meets content management system" initiative, origin of core's Tokens, Style and Icon APIs Follows, closely. UI Suite puts the design system in the theme; this module adds a contract that themes implement.
UI Patterns SDC components as plugins and sources in displays Complements. Pattern specs stay SDC-shaped, so UI Patterns can place their realizations.
UI Skins Themes declare CSS variables and themes (modes, schemes); site builders set them Same goal. The closest to the module's token and context layer.
UI Styles Themes declare utility-class styles; site builders apply them Follows. The origin of core's style utility API (#3517033).
UI Icons Site building on core's Icon API Follows. The contrib-to-core path the module expects for tokens.
Display Builder A design-system-native visual builder Complements. A consumer that could use the same names on every theme.
UI Suite DaisyUI, Bootstrap, USWDS, DSFR Themes implementing external design systems Complements. Candidates for adapters.
Gin The contrib admin theme Default Admin was merged from Builds on. A Gin adapter is planned once Gin supports Drupal 12.
Gin Toolbar Gin's toolbar on frontend pages Follows. Earlier admin UI on frontend pages.
Drupal Canvas The page builder in Drupal CMS, with SDC and code components and a global CSS library Complements. Its global CSS variables are ad-hoc tokens the contract can map.
Canvas Styles, UI (shadcn recipe) A form for Canvas' global CSS variables; shadcn components and their CSS variables for Canvas Same goal. CSS variables already used as a token contract.
Mercury, Byte The Drupal CMS theme (Tailwind and SDC) and a site template built on it Complements. Every clone names its tokens anew, which is the gap the vocabulary fills.
Drupal CMS and its design system brief The packaged product and the 2024 track that produced Mercury Same goal. A shared default design system, delivered as one theme.
Starshot Demo Design System, CivicTheme Full design systems shipped as themes Complements.
Design Tokens An earlier contrib token module (no releases) Follows. An earlier attempt; core's API supersedes it.
SDC Devel An SDC validator Complements. A model for checking declarations by rule.
Style Guide, SDC Styleguide, Storybook Previews of elements and components Complements. Ways to see a realization under every theme.
Emulsify Tools Companion to the Emulsify component-driven theme system Complements. Another token and component pipeline.

Outside Drupal, Backdrop CMS has a Design Tokens module with a similar idea.

Standards

Other ecosystems

The approach, a host-owned set of semantic CSS variables, often enforced by a linter, is how other platforms keep third-party UI consistent. The module learns from:

Edit note (2026-10-04): not every platform listed ships a linter (Salesforce and Atlassian do, Shopify did for Polaris React; VS Code and Figma don't), so the Other ecosystems intro now says "often".