The bigger picture¶
This module is the first piece of a larger goal: make the design system a first-class part of Drupal, described once and used by everything that renders.
What's missing¶
Drupal describes a lot about itself. Entities, fields and config come with schemas. Tool API now does the same for processes: each tool declares its typed inputs and outputs, so workflow engines, ECA and AI agents can all use it the same way.
Rendering has nothing like that. Drupal renders in many ways: render arrays, Twig templates, theme hooks, CSS libraries, Single Directory Components, and now React code components in Canvas, which can also render on the server. Each of them decides on its own what a button looks like. SDC gets closest: its schema says which props a component takes. But that describes one component's inputs, not the design it belongs to.
So there is no place to ask "what is a button on this site, and how should it look and behave here?" Every theme, module and framework answers for itself, and the answers drift apart.
The goal¶
One description of the design that every way of rendering reads from:
- Tokens: the named values: colors, spacing, type, borders. They change with the context (theme, light or dark, more contrast, forced colors).
- Patterns: what a button, a dialog or a card is: its parts, states, keyboard behaviour and accessibility requirements.
- Rules: what you must, should and may do with them, in a form that people, linters and other tools can all read.
- Authoring: how content is structured and written, not only how UI looks.
A Twig template, an SDC, a React component in Canvas and a module's admin form all take their answers from that description. Each stays free to render in its own way. They just stop disagreeing about the design.
Who it's for¶
- Module developers build UI once and it fits every theme, admin or frontend.
- Theme developers fill in one set of values instead of patching contrib markup.
- Site builders and designers change the design in one place and see the source of every value.
- Front-end developers working in Twig, SDC or React use the same names.
- People using the site get consistent behaviour, dark mode, more contrast and forced colors that work across the whole site, not only where a theme took care.
- Tools (linters, documentation, design tools and AI assistants) read the same description. Generated UI is one use of it, not the reason for it.
What it isn't¶
- Not a component library. Component libraries, in any framework, implement the design system. They don't define it. Concept §1
- Not a replacement for SDC, Canvas or themes. It gives them a shared source to read from.
- Not Twig versus React. It works the same for both, because the result reaches the page as plain CSS custom properties and, outside CSS, through a PHP API.
Where this module fits¶
| Step | What it adds | Status |
|---|---|---|
| v0 | Tokens: one vocabulary, per-context values, theme adapters, Media Library pilot | Built, in review |
| v1 | The first pattern (Dialog) with a spec and a conformance test | Next |
| v2 | More patterns, SDC realizations, Navigation and Canvas on the same page, content patterns | Planned |
| v3 | Authoring UI for the design system, exports to design and AI tools | Planned |
The steps are a direction, not a promise. The vocabulary, the patterns and where all this should live are decided with the people who maintain the parts it touches. Concept §11 · Reviews