1. Overview

1.1 What DSSL is

DSSL is a style language. A DSSL file is plain text. It holds tokens (named design values), rules (selector blocks), states, conditions, motions and a few effect descriptions. A DSSL implementation reads that text and decides how every element in a document should look.

A DSSL file describes a result. It does not say how to reach it. That is the whole idea of a style language, and it is what makes native support possible: the author says what, the engine decides how.

1.2 What CSS does (and what that means for DSSL)

CSS is not compiled. There is no step that turns a stylesheet into machine code or into some other language that the browser then runs. A browser engine is an interpreter for a declarative language, and it keeps the interpreted form alive for as long as the page lives.

Here is what a browser does with a stylesheet, in order:

Tokenize and parse. The engine's own code (C++ in Chrome and Safari, Rust in Firefox) reads the text and builds rule objects. The collection of rule objects is the CSSOM.
Style resolution. For every element, the engine finds the rules whose selectors match, sorts them by the cascade (origin, layer, specificity, order), picks the winning declaration for each property, and resolves it into a computed value. The result is one computed style per element.
Layout. Using the computed styles, the engine works out the size and position of every box.
Paint. The engine turns boxes and computed values into drawing commands: fill this rectangle, draw this text, blur that shadow.
Composite. Painted layers are combined on the GPU and shown.

Engines do optimise stage 2. They index rules by class, id and tag so they do not test every selector against every element, they cache results, and some compile selectors to machine code. None of that changes what a stylesheet means. It is an implementation detail.

Every CSS property is built-in code inside the engine. background is a paint routine, width is a layout input, border-radius changes the shape that paint clips to. Nothing in this path runs JavaScript.

What native DSSL means

Native DSSL means a browser reads DSSL text with its own parser and feeds the result into the same stages. Which stages matter depends on the feature:

DSSL feature	CSS stage it joins	What the engine must add
Syntax, tokens, semantic properties (`row:`, `radius:`, `fluid`)	1 and 2	A DSSL parser. After that, they are ordinary computed values.
Layers, states, media, containers	2	Nothing new: the cascade already has these concepts.
`@signal`	2	A way for the page to set named values the cascade can read.
`motion`, `animate`	2 and 4	Mapping to the engine's existing keyframe animation.
`texture`, `aura`, `glass`, `slider`	4	New drawing code, the way `box-shadow` once was new.
`fold`, `bend-around`, `tilt`, `overlap`	3 and 4	Hooks that see box sizes, so they must run during or after layout.

The first four rows are small. The last two rows are where real engineering is needed, and chapter 11 says exactly what.

1.3 Processing model

An implementation takes DSSL source text and a document, and produces styled output. The model has six stages. A conforming implementation does not have to run them as separate passes, but its results MUST be the same as if it had.

source text
   |  1. decode, strip comments, split into logical lines
   v
syntax tree                      (chapter 2)
   |  2. classify headers, resolve values, expand semantic properties,
   |     flatten nesting, collect tokens and motions
   v
resolved document                (chapters 3 to 8, output defined in chapter 10)
   |  3. for each element: match rules, apply conditions
   v
matched rules
   |  4. sort by (layer, order), last declaration per property wins
   v
declared values                  (chapter 5)
   |  5. compute: same as CSS from here
   v
computed style + effect descriptors
   |  6. layout and paint, supplied by the host
   v
pixels

Stages 1 and 2 need no document. They are pure functions of the source text (and the tokens and motions that earlier files defined, see 4.5). That is why they can be tested without a browser, and why this repository tests them by comparing outputs.

1.4 Conformance levels

An implementation claims a level. Each level includes the one before it.

Level	Name	What it must do
1	Parser	Stage 1. Produce the syntax tree and the syntax errors defined in chapter 2.
2	Resolver	Stages 1 and 2. Produce a resolved document equal to the reference output (chapter 10), including errors and warnings.
3	Style engine	Stages 1 to 5. Give every element the declared values chapter 5 defines.
4	Renderer	Stage 6 for the effects in chapter 8: texture, aura, slider, glass, tilt, deform.

The reference crate in this repository aims at level 2 first, then 3 and 4. It is not there yet: native/README.md says exactly where it stands.

1.5 Selectors are CSS selectors

DSSL does not define a selector language. Selectors are CSS selectors as defined by the Selectors specification, and matching is done by the host. This is how the JavaScript engine works too: it calls Element.matches.

Two things sit on top of that:

State words. A block header that is exactly one of the state words (chapter 2) means "the parent selector plus this pseudo-class". hover { ... } inside .card means .card:hover.
seen. :seen is not a CSS pseudo-class. It is defined in 5.7.

A selector goes through the resolver as text. The resolver only looks at it to find pseudo-elements (5.8) and to scan states. It never rewrites one except to join nested selectors (5.3).

1.6 Versioning

The spec has the same version as the language it describes. This draft describes DSSL 0.16. A change that makes a previously valid source invalid, or changes what a valid source means, is listed in the changelog of the language and raises the second number.

1.7 What is out of scope

The selector language (see 1.5).
Layout and paint for ordinary CSS properties. DSSL passes those through unchanged.
The CSS value grammar. DSSL checks that a word is a known CSS word and gives numbers their units. It does not check that a value is valid for its property. The host does that when it computes the style.
The editor extension, the designer and the build tools (dssl check, dssl build, dssl import). Chapter 11 says how the build lane relates to native support.