Skip to content

Prior art

Author: Shibin Das (d34dman)Last updated

Draft

What already exists for a design-system contract that Drupal themes implement and contrib modules, in any framework, consume. Each page looks at one area. For every item it gives where the work stands and what the module takes from it, builds on or avoids. Builds on is the full credit list.

Sections

  • Drupal: the core APIs, core themes, Drupal CMS and Canvas, and contrib work the module sits next to, with a position on each.
  • Tokens and theming: token formats, tiers and naming, host-injected variables, and the CSS for several design systems on one page.
  • Patterns and behaviour: behaviour and accessibility specs, native HTML and components, and how host platforms keep third-party UI consistent.
  • Data, AI and governance: registries and documentation platforms, MCP servers and AI context files, rules and linters, and governance.

Summary

  • Drupal core already ships the token storage half. The core Design Tokens API (#3531854) uses the W3C DTCG format in {provider}.tokens.yml and stores overrides per CSS selector. It's marked experimental, and color tokens and aliases are follow-ups. The module builds on it rather than next to it.
  • The standards are stable. DTCG 2025.10, a W3C Community Group final report, has Format, Color and Resolver modules, which together cover token files, layering and modes. CSS @scope has been Baseline since March 2026, and custom properties inherit into Shadow DOM. In the light DOM, all the CSS needed for several design systems on one page now exists; shadow roots inherit the variables but not @scope or the page's layer order.
  • Platform ecosystems have settled on one approach. VS Code, Figma plugins, Salesforce, Shopify and Atlassian Forge all ship host-owned semantic CSS variables. Salesforce and Atlassian also ship linters that enforce them, as Shopify did for Polaris React. The stricter platforms provide host-owned web components, or render the extension's UI themselves.
  • The component layer is the first to break. The VS Code Webview UI Toolkit was archived in January 2025 after FAST Foundation, the part of FAST it was built on, was deprecated. Only the --vscode-* variables survived. Tokens and specs belong in the contract, and realizations stay replaceable.
  • Drupal 12 leaves one admin theme and no dedicated frontend theme in core. The Standard profile uses Default Admin for the frontend too, and real sites replace it with a contrib or custom theme. Matching the admin theme is no longer the hard part: contrib UI that matches it still looks out of place under the site's frontend theme.

Gaps we found

None of the standards, vendor tools or Drupal projects we reviewed cover these. They are what the Design System API adds:

  • A shared vocabulary across themes: semantic names that every theme implements and contrib codes against. Default Admin's semantic tier does this for admin UI only; frontend themes each choose their own names.
  • Graded rules as data: must/should/may rules with stable IDs, rationale and examples. The vendor MCP servers we reviewed return guidelines as prose.
  • Per-realization conformance: Figma Code Connect maps implementations to design components; we found no conformance status in it.
  • Provenance after layering: the DTCG Resolver and documentation platforms resolve values, but don't record which layer each one came from.
  • Context resolution: admin, frontend and Canvas design systems resolved correctly within one page.

Edit note (2026-10-04): checked again against primary sources. Corrected the Drupal 12 frontend theme (Standard uses Default Admin), the linter claim (Salesforce and Atlassian, formerly Shopify; not VS Code or Figma), FAST Foundation rather than FAST, and DTCG 2025.10's three modules. Noted the Tokens API is experimental, the Shadow DOM limits, and scoped the gaps to what we reviewed.