DSSL specification
Status: working draft, written against the reference engine 0.16.3 (the bugs of chapter 12 were found on 0.16.2). This is not a standard. It is the document a browser team (or anyone writing a second implementation) would read to build DSSL without reading the JavaScript engine.
Why this exists
DSSL today is a JavaScript engine that writes inline styles. That is one way to run the language. It is not the language. CSS is a language that browsers implement natively, and this spec says what it would take to do the same for DSSL: what the text means, what every stage produces, and what a correct implementation has to do.
The Rust crate next to this folder (native/) is the reference implementation of this spec
that does not use JavaScript. It is checked against the JavaScript engine by running both on
the same inputs and comparing the results.
Chapters
| # | Chapter | What it fixes |
|---|---|---|
| 1 | Overview | The processing model, conformance levels, what CSS actually does |
| 2 | Syntax | Text to syntax tree: comments, blocks, declarations, raw |
| 3 | Values | Bare numbers, identifiers, functions, colors, alpha |
| 4 | Tokens | Design tokens and how they become custom properties |
| 5 | Cascade | Layers, order, states, media, containers, signals |
| 6 | Properties | The semantic properties and how each one expands |
| 7 | Motion | motion, animate, seen, stagger |
| 8 | Effects | Texture, aura, slider, glass, tilt, deform, fonts |
| 9 | Diagnostics | Errors, warnings, did-you-mean, lint |
| 10 | Resolved document | The exact output a resolver produces, and how conformance is tested |
| 11 | Browser integration | How a browser would host this, stage by stage |
| 12 | Known divergences | Places where the JavaScript engine does not yet match this spec |
Conventions
- MUST, MUST NOT, SHOULD and MAY are used the way RFC 2119 uses them.
- Every testable rule has an id such as
SYN-4orCAS-7. Conformance tests name the ids they cover. - Prose in the margin of a rule that starts with "Why:" is informative.
- Examples are executed. Every fenced
dsslblock is compiled byscripts/test-native-spec.mjsagainst the JavaScript engine, and must produce no errors. A block fenced asdssl errormust produce at least one. - The tables in the appendices are generated from the engine's own vocabulary modules by
scripts/gen-native-vocab.mjs. They are not edited by hand, so they cannot drift.
Normative and informative
Chapters 2 to 10 are normative. Chapters 1 and 11 are informative apart from the conformance levels defined in 1.4. Chapter 12 is a list of bugs, and is informative.
Where this spec and the JavaScript engine disagree, chapter 12 says which one is wrong and what the fix is. Until the engine is fixed, conformance tests for those cases are excluded from the comparison and listed by id.