Review brief: UX and Navigation¶
Try it yourself
Everything in this brief runs on the demo site: Drupal 11.5.0-beta1 with the module, its adapters, the Media Library pilot and demo content. You need DDEV 1.25 or newer:
git clone https://github.com/d34dman/design_system_api_demo.git
cd design_system_api_demo
ddev start && ddev install-demo # prints a one-time login link
Why this reaches your area¶
The project starts from a UX problem: contrib UI doesn't stay on admin routes. The Media Library widget, the Navigation bar, login forms and dialogs also render inside whatever frontend theme a site uses. UI styled against one admin theme looks broken there, and with no dedicated frontend theme in Drupal 12 core there is no frontend default to aim for. The proposal is one set of design names whose values change with the context the UI renders in, plus a place where site builders decide those values. Whether that's the right answer, and what the authoring side should feel like, is a UX question first.
Questions for you¶
- Is this the right problem? §3 describes the pain and the success criteria for the first milestone. Do they match what you see in the UX and usability work? → §3
- "Acceptable" on the frontend. Under a frontend theme that knows nothing about the contract, module UI falls back to deliberately plain defaults (screenshots below). Is plain-but-consistent the right goal there, or should module UI try to blend into the frontend theme? → Q2, Q9
- Navigation on frontend pages. The Navigation bar is admin UI on a frontend
page. From v2 we plan page-region contexts, so a region resolves admin values
inside a frontend page (scoped with CSS
@scope). Would Navigation use that, and are there other regions like it (Canvas, dialogs opened from the frontend)? → §9 - The authoring experience. §5 sketches where site builders and designers decide values: one context per screen, every value showing where it came from, reset to the default, live preview, rules that block publishing. Is that the right shape? → §5, Q8
- The v0 editor. For now authors edit a YAML file per theme in the admin UI (Appearance » Design system). Check validates a change and shows every resolved token, with the layer that sets its base value. Save validates and writes; it doesn't need a Check first. Is a YAML editor acceptable as a stopgap, or would even a minimal form serve authors much better?
What we built¶
- Context = theme in v0: admin routes resolve admin values, frontend routes
frontend values. The OS dark setting applies only on themes that declare dark
support (Olivero and Stark don't); Default Admin's dark values follow each user's
Appearance setting instead of the OS.
data-ds-mode="dark"works on any theme. The OS more-contrast setting applies on every theme, for the tokens whose values differ, and dark plus more contrast has its own combined values. - Contract defaults for the frontend: plain and readable, since Drupal 12 has no core frontend theme to borrow from.
- Author editor at
/admin/appearance/design-system: an overview of themes with their adapters and author values, and a YAML editor per theme with Check, Save and Remove. Save and Remove appear only when the web server can write the file; otherwise there is only Check. - Observed: on Stark the Navigation sidebar is drawn over the Media Library dialog; on Olivero the dialog is on top. We haven't confirmed the cause. It's outside the pilot, but it's the kind of admin-on-frontend clash §3 describes.
See it¶
| Pilot off | Pilot on | |
|---|---|---|
| Olivero |  |
 |
| Stark |  |
 |
Olivero with an author's brand values (ddev ds-brand on): the card borders follow
a brand palette, on Olivero only.
Known issues¶
Found in our own check of the code. Items marked Fixed name the commit that fixed them. We track the open ones ourselves; if one matters for your review, say so in this brief's issue.
- No rule checks author values. The rules apply to module CSS only, so an author can save a text color equal to its background.
- "Set by" in the token table names the source of the base value only, not of the Dark or More contrast values.
- The overview says to commit the author files, but the editor writes them on the server. On a site deployed from git, values edited there can be overwritten by the next deploy (Q16).
- Partly fixed (
bb2a125): a combined "mode=dark contrast=more" context now covers dark and more contrast on one element, nested in either order, or one from the OS and one from the page; since77237c5adata-ds-mode="light"region on an OS-dark page with OS more contrast keeps the contrast values. A person can choose light, dark or more contrast with the module's display preferences switch (8d66732). Still open: adapter themes keep their own values for the tokens they map, in every context. - The contract has no stacking (z-index) tokens, so it can't help with clashes like the Stark one above.
Read only these sections¶
- §1 Position
- §3 Problem statement
- §5 Registry and authoring experience
- §9 Layering and context
- Q2, Q8, Q9
What we heard¶
Nothing yet.
Edit note (2026-10-03): Corrected what the v0 editor does (Save doesn't need Check; "Set by" covers base values only; Save and Remove need a writable file), that OS dark mode applies only to themes that declare it, and the Stark overlap, whose cause is unconfirmed; added §9 to the reading list and a Known issues section, all found in a pre-review check of the code.
Edit note (2026-10-03, later): Marked the dark plus more-contrast issue fixed, with what remains, after bb2a125, and noted under "What we built" that Default Admin's dark values follow the user's Appearance setting after e37d733. Open known issues are now tracked by the maintainers instead of as separate issues.
Edit note (2026-10-04): Drupal 12 core has no dedicated frontend theme; the Standard profile uses Default Admin for the frontend too. Earlier wording said there was no frontend theme at all.
Edit note (2026-10-18): Updated Known issues for 77237c5 and the display preferences switch (8d66732); the demo site now runs Drupal 11.5.0-beta1 (the module supports ^11.5 || ^12).