# 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](01-overview.md) | The processing model, conformance levels, what CSS actually does |
| 2 | [Syntax](02-syntax.md) | Text to syntax tree: comments, blocks, declarations, raw |
| 3 | [Values](03-values.md) | Bare numbers, identifiers, functions, colors, alpha |
| 4 | [Tokens](04-tokens.md) | Design tokens and how they become custom properties |
| 5 | [Cascade](05-cascade.md) | Layers, order, states, media, containers, signals |
| 6 | [Properties](06-properties.md) | The semantic properties and how each one expands |
| 7 | [Motion](07-motion.md) | `motion`, `animate`, `seen`, `stagger` |
| 8 | [Effects](08-effects.md) | Texture, aura, slider, glass, tilt, deform, fonts |
| 9 | [Diagnostics](09-diagnostics.md) | Errors, warnings, did-you-mean, lint |
| 10 | [Resolved document](10-resolved-document.md) | The exact output a resolver produces, and how conformance is tested |
| 11 | [Browser integration](11-browser-integration.md) | How a browser would host this, stage by stage |
| 12 | [Known divergences](12-known-divergences.md) | 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-4` or `CAS-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 `dssl` block is compiled by
  `scripts/test-native-spec.mjs` against the JavaScript engine, and must produce no errors.
  A block fenced as `dssl error` must 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.