Prior art in Drupal¶
This page covers the Drupal core and contrib work that Design System API sits next to. For each item it gives where that work stands and what it means for the module's design. Builds on is the full credit list. This page covers fewer items in more depth, and gives each a position.
Statuses are as of 2026-10-04. Refresh them before quoting. For how this fits the wider prior art, see the overview.
How to read the positions: build on means the module uses it directly; same goal means it tackles the same problem from another side; align means the module should fit its model rather than compete; use case means it creates a problem the module has to solve; complement and integrate mean it fits next to the module or could realize the contract; differentiate means the module deliberately takes another path; superseded means core now covers it.
Where things stand¶
- Core now ships the token storage half. The Design Tokens API stores DTCG-format tokens and per-selector overrides. It's marked experimental, and color tokens and aliases are follow-ups. What it doesn't have is a shared vocabulary that every theme fills.
- Drupal 12 has one admin theme and no dedicated frontend theme in core. Default Admin is the only core admin theme, and Claro and Olivero move to contrib. The Standard profile installs only Default Admin and uses it for the frontend too. Real sites replace the frontend theme with a contrib or custom one, and contrib UI then has to fit whatever that theme is.
- Several efforts are moving the same way. The design-system-native meta, UI Suite, dark mode and contrast as core settings, and Media Library's theme-independence issues all point at a design contract. Default Admin's semantic tier gives admin UI a shared set of names; we found no shared names that also work across frontend themes.
- Drupal 12 is in beta, and the Drupal CMS stack still targets Drupal 11. The current Canvas, Mercury and Gin releases require Drupal 11.
Core APIs¶
Core Design Tokens API (#3531854) · build on¶
Committed to main on 2026-09-07 and shipped in Drupal 12.0.0-beta1. The 11.x backport
is merged but not in a tagged release yet. The code marks the API as experimental.
Tokens are declared in DTCG-format {provider}.tokens.yml files (maintainers have
discussed renaming them). A DesignToken config entity stores overrides per CSS
selector scope and is available through JSON:API. The initial types are dimension,
fontFamily, fontWeight, number and typography. There's no color type yet (#3622909).
Aliases (#3590100) and SDC tokens (#3624211) are follow-up issues, and core doesn't
attach the generated CSS to pages yet.
For the module: this is the plumbing for v0. The module adds what's missing: a shared semantic vocabulary, contract ownership, provenance and rules. Until core has a color type, the module reads its own color tokens. Building on the API surfaced #3628095: discovery fails on a value of the wrong shape.
Issue #3531854 · #3622909 · #3590100
Single Directory Components (SDC) · build on¶
SDC has been part of the core theme system since 10.3. The separate sdc module was
deprecated in 10.3 and has been an obsolete, hidden stub since 11.0. component.yml
has status, props, slots, variants (added in 11.2), replaces and
libraryOverrides.
For the module: SDC defines a component interface, but nothing that several
themes fulfil. The module makes a pattern spec an abstract, SDC-shaped interface, and
proposes an "implements" relation next to replaces.
Change record · Annotated component.yml
Design-system native CMS meta (#3533198) · same goal¶
[Meta] Make Drupal the first "design-system native" CMS + Unify & simplify render & theme systems. Active. The umbrella issue that tracks the Tokens and Style Utility APIs.
For the module: the direction this work continues. The contract is one answer to that meta issue.
Core Style Utility API (#3517033) · align¶
Needs work. {theme}.styles.yml declares utility-class options that are applied
through #styles. Its author reports that Canvas is waiting for it.
For the module: rules can point at style utilities instead of adding a new mechanism.
Core themes and UI¶
Default Admin theme and --admin-* tokens · build on¶
The Gin-based Default Admin theme (merged in #3556948) is the only core admin theme in
Drupal 12, and it's no longer experimental (#3624359). Its tokens are consolidated in
one --admin-* namespace with primitive, semantic and component tiers. The
consolidation issue describes the semantic tier as the public API that components
consume, for the theme and for contrib that builds on it. Dark mode uses
light-dark().
For the module: a shared admin vocabulary, tied to one theme's namespace. The module treats it as the reference admin realization of neutral contract names.
#3556948 · Token consolidation · Round 2
Drupal 12 core removals: Claro, Olivero, Search · use case¶
Claro, Olivero and Search were removed from core (the removal metas #3584638 and
3595085 are fixed) and have contrib releases (drupal/claro 3.0.0,¶
drupal/olivero 2.0.0, drupal/search 1.0.0). In 12.0.0-beta1, core/themes
contains Default Admin, Stark and Starterkit; the Umami demo profile still bundles its
own theme. The Standard profile installs only Default Admin and uses it as both the
admin and the default theme.
For the module: with one core admin theme, admin consistency looks solved. The open problem is the same contrib UI on frontend pages: a stock install renders the frontend in the admin theme, and real sites replace it with a contrib or custom theme that contrib UI then has to fit. So the contract owns its frontend defaults instead of deriving them from one theme.
Claro removal · Olivero removal · Default Admin naming cleanup
Navigation module · use case¶
Stable since 11.3 (#3557578), and the default in Standard and recipes since 11.4. Toolbar is removed in 12 (#3586211).
For the module: admin UI rendered on frontend pages. This is the main test case for context scoping.
Dark mode and user preferences (#3606655, #3613964) · same goal¶
Make dark mode a first class citizen of Drupal core (Needs review), and use the Style API for color scheme, contrast and reduced motion in themes and user settings (Active). #3612243 tracks popular contrib modules that will need updates to support Default Admin's dark mode.
For the module: core's version of the module's page-side contexts. The contract's dark and contrast contexts should follow these settings. #3612243 shows contrib adopting Default Admin's variables module by module; a shared contract would give those modules one set of names to target under every theme.
#3606655 · #3613964 · #3612243
Media Library styling in themes (#3506823, #3506826) · same goal¶
Media Library shouldn't assume the theme's base libraries are present, and should scope its styles. Both issues are Active. They came out of Experience Builder's (now Canvas) work on embedding Media Library.
For the module: this is what the Media Library pilot does: it's styled once, against the contract, and works under any theme.
Drupal CMS and Canvas¶
Drupal Canvas · complement¶
Canvas 1.0.0 was released on 2025-12-04, and Canvas is the default page builder in
Drupal CMS 2.0 (January 2026). There's no Drupal 12 release yet: 1.12.0 requires
^11.3. Code components are written in the browser with Preact (React imports map
to Preact) and Tailwind 4. Global CSS still carries most styling variables. Canvas
has a Brand kit entity for fonts and, since 1.11, a Color entity that maps named
colors to CSS variables, but no general design-system or token entity.
For the module: the Canvas editing UI is a second design system on the same page. The module can map Canvas colors, global CSS and shadcn variable names to the contract and to core tokens.
Project · Drupal CMS 2.0 and Canvas · Code components
Canvas Styles and drupal/ui · integrate¶
Canvas Styles (1.0.0-beta1, 2026-05-01) is a form for editing Canvas CSS variables. It says it may be a stopgap until equivalent functionality ships in Canvas. drupal/ui (development only, no tagged release) is a recipe that ships shadcn/ui as Canvas code components and uses shadcn's variable names as its token contract.
For the module: candidate realizations of the contract.
Mercury (Drupal CMS theme) · align¶
A Tailwind 4 + SDC theme whose tokens are its own Tailwind @theme names in
src/theme.css (1.0.0 on 2026-01-27; requires ^11.3, no Drupal 12 release yet).
It isn't meant to be subthemed: sites override its theme.css, or fork the theme.
For the module: Mercury, Default Admin and other themes each use their own token names, so a module can't target one set of names across them. That's the gap the vocabulary fills, not a flaw in Mercury.
Contrib¶
UI Suite ecosystem · align closely¶
UI Patterns 2, UI Skins (CSS variables declared in YAML, values set by site builders), UI Styles, UI Icons and Display Builder. UI Suite maintainers led core's Icon and Design Tokens APIs and the proposed Style Utility API, drawing on UI Icons, UI Styles and UI Skins (and, for tokens, the Design Tokens contrib module). Their framing: Drupal as the first design-system native CMS. UI Skins defines its own CSS variables today; a 2.x proof of concept against core's API is Needs work (#3553233).
For the module: the nearest existing effort. UI Suite puts declarations in themes; the module adds a contract that themes implement. It's meant as an extension of their model, not a competitor.
UI Patterns · UI Skins · #3553233 · Design-system native CMS
Storybook module and SDC Styleguide · complement¶
Both render SDC components for documentation and visual testing.
For the module: useful for documenting pattern specs and running visual tests under every theme.
Design Tokens contrib · superseded¶
An earlier contrib token module (no tagged release; last changed on 2024-12-31). Core's Design Tokens API credits it for its DTCG parsing and CSS serialization approach.
For the module: core's API now covers this ground, so the module builds on core.
Direction¶
Core JavaScript strategy · differentiate¶
The 2017 proposal to experiment with React for admin UIs didn't lead to a React admin in core. HTMX has shipped with core since 11.2, with a PHP API since 11.3, alongside Twig and SDC. Canvas uses Preact.
For the module: stay framework-agnostic: tokens as CSS variables, patterns as specs, rules as data.
_Edit note (2026-10-04): checked again against primary sources. The Standard profile
uses Default Admin as its frontend theme (it doesn't install "no frontend theme"); the
sdc module is an obsolete stub, not removed; the UI Skins proof of concept is
3553233; Mercury isn't copied with Starterkit and requires ^11.3, not 11.3 only;¶
HTMX shipped in 11.2. Also noted that the Tokens API is experimental, Canvas' Color and Brand kit entities, credit to the Design Tokens module, and fixed wording on #3533198,