What this buys you

A one-class selector in your stylesheet overrides a five-class selector in DDS. You never have to out-specify the design system, never have to write !important, and never have to care how specific a DDS rule happens to be. That is the whole point: specificity wars are what make a design system something to fight rather than to build on.

The order above is declared once, up front, in dds/dds.css — before any @import. Declaring it up front is what makes it independent of load order: a layer's position is fixed by that statement, not by when its file happens to arrive.

The one thing to watch

If you put your own CSS into a DDS layer, you give up the advantage — you are back to competing on specificity inside that layer. Add a layer after dds.utilities if you want layered product styles, or simply leave yours unlayered.

Layers do not change how !important works, and for important declarations the order is reversed: an important rule in an earlier layer beats an important rule in a later one. It is a rule worth knowing and never worth relying on.

Level is structure, size is a class

Never skip a level to get a size. A section heading that needs to look small is still the next level down, with .dds-text-sm on it — which is how the headings on this page are done. Skipping from h2 to h4 leaves a gap in the outline that a screen-reader user reads as a missing section (WCAG 1.3.1).

text-wrap: balance is applied to every heading, so a two-line headline does not end in one orphaned word. It is capped by the browser at a few lines, so it stays cheap even on long ones. Body text gets text-wrap: pretty instead — same idea, but it only fixes the last line, which is what paragraphs need.

Headings carry no margin of their own. Vertical rhythm is the job of the container — see below — so a heading can sit at the very top of a card or a dialog with nothing to strip off.

The escape hatch, and when to use it

.dds-mbs-* and .dds-mbe-* set a single margin on one element, for the case a container cannot express: one item that needs to sit further from its neighbour than the rest.

Reaching for them repeatedly inside one block is the signal that the block wanted .dds-stack instead. Both are logical properties, so they follow writing direction rather than being fixed to top and bottom.

The top of the ramp is reachable now too

.dds-stack-3xl, .dds-mbs-3xl and .dds-mbe-3xl reach --dds-space-3xl (72px, "between major regions") the same way .dds-stack-ml reaches the ramp's one midpoint — a step defined in the primitive layer had no utility that could reach it, which forced an inline style anywhere a gap that size was needed (#136).

--dds-space-4xl (96px, exactly 2x --dds-space-2xl) goes one step further, with matching .dds-stack-4xl, .dds-mbs-4xl and .dds-mbe-4xl utilities (#137) — hero-scale headroom above any named region, added ahead of a specific page adopting it. Shipped first at 100px, then corrected to 96px for fitting the ramp's multiplicative relationships better than a value chosen for being close to a round number.

A custom property cannot be used in a query

@media (min-width: var(--dds-breakpoint-tablet)) does not work, in any browser. A query condition is evaluated before custom properties are resolved, so the value is never substituted and the query simply never matches — silently, with no error.

So every query writes its own literal, and these four names are documentation rather than something the browser enforces. scripts/check-reference.mjs compares the documented set against every width actually used in the CSS, which is what keeps the two from drifting apart.

A track's minimum is its content, and that is how one wide thing widens a page

A grid track sized auto, and any grid or flex item, cannot be narrower than its own min-content. So a single descendant that refuses to become narrow — a table without its scroll region, a max-content column, a long unbroken identifier — makes its track wider than the viewport, and every sibling in that track is stretched to match.

That is what turns one local overflow into a page-wide symptom. The grids inside compute their column count against a width the screen does not have and put the later columns off-screen, so each of them looks like a wrapping bug while wrapping exactly as written. Anything laying children out in a track therefore constrains both: grid-template-columns: minmax(0, 1fr) on the track and min-inline-size: 0 on the items. Constraining only the track moves the inflation one level down.

If the role you need is not here, add it — do not borrow a near one

This is the rule that gets broken most quietly. A <use> pointing at the wrong role resolves, renders, passes every check in scripts/, and ships a picture that means something else. Only a person reading the markup ever notices.

Four had accumulated before this note existed: a sun on the “Show password” button, a document on both the upload zone and the download link, and the navigation hamburger on a toolbar’s overflow menu. Each was one line from correct. What was missing was not care — it was an icon, and permission to add one.

So: adding a line to ICON_MAP in scripts/build-icons.mjs and re-running the build is the cheap, expected, correct move. Ionicons has around 1,300 icons; Dessau DS ships the handful it names. The constraint is that every icon earns a role name and a caller — not that the set stays at its current size. A Unicode glyph is not the escape hatch either: a typed check mark is announced as “check mark” in the middle of a sentence and renders in whatever font happens to have it, which is why scripts/check-icons.mjs rejects twenty-five characters by name.

One icon, one meaning — and directions come as a set

The corollary of role naming: a role means one thing everywhere. menu is the hamburger and means site navigation, so an overflow menu is more, not a second use of the hamburger. document is a file, so getting one is download and sending one is upload. A picture that means two unrelated things teaches a reader that it means neither.

Directions are the one exception to “every icon has a caller”. All four chevrons and all four arrows are in the set, including chevron-up, arrow-up and arrow-down, which nothing here points at today — “up” is meaningful because “down” is, not because a page happens to use it this week. Those three are declared in ICON_MAP with the reason, marked data-dds-vocabulary in the sprite, and listed by check-icons.mjs on every run, so the exemption is argued rather than silent.

A disclosure still rotates chevron-down through 180° rather than swapping symbols: the rotation animates the change and keeps both states unmistakably the same control. That is a good technique — it just was not a reason for the vocabulary to have a hole in it.

The name is the role, not the picture

#dds-icon-error, not #dds-icon-alert-circle. Markup refers to what the icon means, so swapping which Ionicon backs a role — or replacing Ionicons entirely — changes one line in scripts/build-icons.mjs and no markup at all. A set named after shapes hard-codes today's drawing into every page.

Where fill and stroke live, and why not in CSS

.dds-icon sets size and nothing else — no fill, no stroke, no stroke-width. That looks like an omission and is the opposite.

Ionicons carries those as inline attributes, tuned per path: an outline icon has fill:none with a stroke, and the solid details inside it have a fill and no stroke. A CSS declaration beats a presentation attribute, so fill: currentColor in the stylesheet filled every outline icon in solid, and the paths that rely on fill:none disappeared entirely. Both at once, which is why it read as "the icons are broken" rather than as a specificity problem.

Theme awareness comes from the build instead: scripts/build-icons.mjs replaces Ionicons' hard-coded #000 with currentColor, so an icon takes the colour of its container — including inside a button whose text colour changes on hover.

Sized in em, and always accompanied

The size is in em, so an icon matches whatever text it sits beside at any font size, with no per-context override.

Every icon in Dessau DS is aria-hidden="true" and focusable="false". An icon never carries meaning alone: a control's name is real text, visible or in a .dds-sr-only span. An icon-only button with no accessible name is announced as "button", and a status shown only as a shape and a colour is unavailable to a good share of readers. focusable="false" is there for older Internet-Explorer-era behaviour where an inline SVG became a tab stop; it costs nothing and removes a whole class of stray focus.

The sprite is inlined into each page by scripts/sync-icons.mjs — not fetched. A <use href="sprite.svg#id"> pointing at an external file does not work from file:// and needs a request before anything renders. scripts/check-icons.mjs verifies every <use> resolves to a symbol that is present, because one that does not renders as empty space, silently.

Where the underline is dropped, and why that is allowed

Navigation links, a brand link, a link styled as a button, a card whose whole surface is clickable — none of these are underlined, because none of them are ambiguous. The rule protects a link inside a run of text, where without an underline it is distinguishable only by hue.

Hover thickens the underline as well as changing the colour, so the feedback survives for someone who cannot see the hue change. The same reasoning applies throughout Dessau DS: no state is ever carried by colour on its own.

A link's text has to make sense read on its own. “Read the full programme”, not “click here” — a screen-reader user can list every link on the page, and in that list “here” appears with nothing to attach it to.

Both halves, or neither

::selection is the one place where setting a background without also setting a colour is actively harmful. The browser will not adjust the text for you, so a themed highlight under unthemed text produces a selection that is unreadable — and only while it is selected, which is the hardest state to catch in review.

accent-color is bound to the action colour for the same reason: checkboxes, radios and range thumbs are painted by the platform, and left alone they stay the operating system's blue on every surface Dessau DS draws.