| # 6. Properties |
|
|
| A declaration `prop: value` becomes zero or more *output declarations*. An output declaration |
| is either an ordinary CSS declaration `{ prop, value }`, or an *engine-native declaration* |
| whose property starts with `@` (6.8). |
|
|
| ## 6.1 Lookup order |
|
|
| - **PRP-1.** For each declaration, the resolver does the first of these that applies: |
| 1. If the value contains `!important` (VAL-15): report the error, emit nothing. |
| 2. If `prop` starts with `--`: it is a custom property (TOK-15, TOK-16). |
| 3. If `prop` is a semantic property (the names in 6.2 to 6.7, and appendix A): call that |
| property's expansion. It returns its own output declarations. |
| 4. If `prop` is `animation` or `animation-name`: resolve the value with `bareIdents: true` |
| and `unitless` per the unitless list. (Motion names are bare words, and must not be |
| reported as unknown values.) |
| 5. If the value is `fluid ...` and `prop` is in the fluid list: VAL-12 to VAL-14. |
| 6. If `prop` is not a known CSS property (appendix A): report |
| `unknown property "<prop>"`, hint = did-you-mean over the known properties and the |
| semantic property names. Emit nothing. |
| 7. Otherwise: one output declaration with the same property and the value resolved by |
| chapter 3. |
| |
| The known-property list holds every property that CSS defines, plus a few vendor ones. It is |
| generated from the engine's vocabulary module (appendix A). |
|
|
| Each output declaration also carries the `line` of the source declaration. |
|
|
| ```dssl error |
| .a { colour: red } |
| ``` |
|
|
| ## 6.2 Size and flow words |
|
|
| - **PRP-2.** `size: w [h]`. Two declarations `width` and `height`. The height defaults to the |
| width. Both are lengths. |
| - **PRP-3.** `circle: s`. `width: s`, `height: s`, `border-radius: 50%`. |
| - **PRP-4.** `z: n` is `z-index: n` (a plain number). `grow`, `shrink` are `flex-grow`, |
| `flex-shrink` (a plain number, default 1 when empty). `basis: l` is `flex-basis: l`. |
| - **PRP-5.** `cover [position]` is `position: <position or absolute>` and `inset: 0`. |
| `sticky [top]` is `position: sticky` and `top: <top or 0>`. |
| - **PRP-6.** `truncate` (no value) is `overflow: hidden`, `text-overflow: ellipsis`, |
| `white-space: nowrap`. |
| - **PRP-7.** `visually-hidden` (no value) is `position: absolute; width: 1px; height: 1px; |
| padding: 0; margin: -1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; |
| border: 0`, in that order. |
|
|
| ## 6.3 Row, column, grid, stack, place, center |
|
|
| *Place words* map to two values, `(cross, main)`: |
|
|
| | word | cross | main | |
| |---|---|---| |
| | `center` | `center` | `center` | |
| | `start` | `start` | `flex-start` | |
| | `end` | `end` | `flex-end` | |
| | `between` | `center` | `space-between` | |
| | `around` | `center` | `space-around` | |
| | `evenly` | `center` | `space-evenly` | |
| | `stretch` | `stretch` | `flex-start` | |
| | `baseline` | `baseline` | `flex-start` | |
|
|
| - **PRP-8.** `row: words` and `column: words` start with `display: flex` and |
| `flex-direction: row|column`, then read the words in order: |
| - `gap N`: `gap: N` (a length). Missing `N` is the error `gap needs a value`. |
| - `wrap` / `nowrap`: `flex-wrap`. |
| - `reverse`: the direction becomes `row-reverse` or `column-reverse`. |
| - `inline`: `display` becomes `inline-flex`. |
| - a place word: see PRP-9. |
| - anything else: error `unknown word "<w>" in <row|column>`, hint = did-you-mean over |
| `gap center start end between around evenly stretch baseline wrap nowrap reverse inline`. |
| - **PRP-9.** Each place word has an axis role. `between`, `around`, `evenly` are *main* |
| (they write `justify-content`). `stretch` and `baseline` are *cross* (they write |
| `align-items`). `center`, `start`, `end` are *both*: they write whichever axes have not been |
| written yet by an earlier word in this declaration. |
| - A word that writes an axis a second time overrides it, with a warning: |
| `two words in <dir> write <prop>: "<new>" overrides "<old>"`, or when the same word, `"<w>" |
| is written twice in <dir> - the second copy wins`. |
| - A *both* word with both axes already taken writes nothing and warns |
| `"<w>" has nowhere to go: justify-content came from "<a>", align-items came from "<b>"` |
| (or the "written twice" form when it is the same word). |
| - **PRP-10.** `grid: words`. Words `gap N` and `rows N` are taken out first. The rest are the |
| column spec: |
| - nothing: error `grid needs columns`, columns are `none`, |
| - one integer `N`: `repeat(N, 1fr)`, |
| - `auto-fill L` or `auto-fit L`: `repeat(auto-fill, minmax(L, 1fr))` with `L` a length, |
| - otherwise each word is a length, joined by spaces. |
| The output is `display: grid`, `grid-template-columns`, then `gap` if given, then |
| `grid-template-rows` if given (`repeat(N, 1fr)` for an integer, a length otherwise). |
| - **PRP-11.** `stack: word` (default `center`) is `display: grid`, |
| `place-items: <cross> <main>` and `@stack: "1"`. An unknown word is the error |
| `unknown place "<w>" in stack` and only `@stack` is emitted. |
| - **PRP-12.** `place: word` is `place-items` and `place-content`, both `<cross> <main>`. |
| Unknown: `unknown place "<w>"`. |
| - **PRP-13.** `center: both|x|y` (default `both`). `both`: `place-items: center center` and |
| `place-content: center center`. `x`: `justify-items: center`, `justify-content: center`. |
| `y`: `align-items: center`, `align-content: center`. Unknown: |
| `unknown center axis "<v>"`. |
| - **PRP-14.** `align: center|start|end|stretch|baseline` is `align-items` with that word. |
| Unknown: `unknown align "<v>"`. |
| |
| ```dssl |
| .toolbar { row: gap 8 between center } |
| .board { grid: 3 gap 12 } |
| .pane { stack: center } |
| .hero { center: both } |
| ``` |
|
|
| The first rule gives `display: flex; flex-direction: row; gap: 8px; |
| justify-content: space-between; align-items: center`. |
|
|
| ## 6.4 Text and look |
|
|
| - **PRP-15.** `font: size[/line-height] [color]`. DSSL's `font:` is not the CSS shorthand. |
| It writes `font-size` (a length, default `16`), then `line-height` (a plain number) if a `/` |
| part is there, then `color` if more words follow. |
| If the value looks like the CSS shorthand (it contains `"`, `'` or `,`, or its first word is |
| one of `italic oblique bold bolder lighter normal small-caps condensed expanded caption icon |
| menu message-box small-caption status-bar system-ui serif sans-serif monospace`, or it is a |
| weight `100`..`900` followed by a sized word), the result is the error |
| `font: "<v>" looks like the CSS font shorthand, but DSSL's font: means size, line height and |
| colour` and nothing is emitted. |
| - **PRP-16.** `fluid: a, b[, v0, v1]` is `font-size` through VAL-12 to VAL-14. |
| - **PRP-17.** `shadow` and `radius`: TOK-17, TOK-18. |
| - **PRP-18.** `text-stroke: width [color] [inside]`, or `none`. It writes |
| `-webkit-text-stroke: <width> <color>` (width in px if bare, color default `currentcolor`), |
| and `paint-order: stroke fill` unless `inside` is given. `none` writes |
| `-webkit-text-stroke: 0` and `paint-order: normal`. A missing or non-numeric width is the |
| error `text-stroke needs a width first`. |
| - **PRP-19.** `outline-shape: width [color]`, or `none`. It writes one `filter` made of four |
| `drop-shadow(x y 0 color)` terms for `(w,0)`, `(-w,0)`, `(0,w)`, `(0,-w)`. `none` is |
| `filter: none`. A missing width is the error `outline-shape needs a width first`. |
| - **PRP-20.** `rotate: v`. A bare number `n` is `n` degrees. `x|y|z n` and four numbers also |
| get `deg`. Anything else is resolved as a unitless value. |
|
|
| ## 6.5 transition |
|
|
| `transition: part, part, ...` or `none`. Each part is `duration [easing] [property]`. |
|
|
| - **PRP-21.** The duration is a number with an optional `ms` or `s` unit. A bare number is |
| milliseconds. The easing is an easing name (appendix A) or a `cubic-bezier(...)` or |
| `steps(...)` call. The property is a known CSS property, or one of the deform names |
| (`bend`, `bend-y`, `bend-up`, `fold`, `stretch`, which mean `transform`), and defaults to |
| `all`. The part becomes `<property> <duration> <easing>`, with the easing defaulting to |
| `ease`. Parts are joined by `, `. |
| - **PRP-22.** If a part does not start with a time but contains one (the CSS habit, |
| `color .2s ease`), the error is `transition: the CSS form (property first) is not DSSL`, |
| with a hint that rewrites the part in DSSL order. A part with no time at all is the error |
| `transition duration "<d>" is not a time`. An unknown property is |
| `unknown transition property "<p>"`. A part with an error is dropped. If no part survives, |
| nothing is emitted. |
|
|
| ## 6.6 gradient |
|
|
| `gradient: layer + layer + ...`. The first layer is on top. Each layer is a *kind sentence* |
| optionally followed by *layer options*. |
|
|
| - **PRP-23.** Layers are split on a top-level `+` that has white space on both sides. |
| - **PRP-24.** Layer options may follow the sentence, in any order, each at the end of the text: |
| `tile W [H]` (background size, bare numbers are px, H defaults to W), `offset X Y` |
| (background position) and one of `no-repeat`, `repeat-x`, `repeat-y`. |
| - **PRP-25.** If the layer (after options) starts with a CSS gradient function, `url(`, |
| `image-set(` or `-webkit-`, it is resolved as an ordinary value. Otherwise it is a sentence. |
| - **PRP-26.** A sentence is `[repeating] linear|radial|conic <head> <stops>` or |
| `mesh <base>, <blob>, ...`. The output is the CSS function `linear-gradient(...)`, |
| `radial-gradient(...)`, `conic-gradient(...)` (with `repeating-` first when asked). |
| - **PRP-27.** Stops are separated by `->` or by commas. Each is a color (a token, hex, named |
| color, color function, alpha form) with up to two trailing positions, or a lone position |
| (a midpoint hint). Bare numbers in positions are px (degrees for `conic`), except `0` |
| which stays `0`. A stop word that is a plain word but not a color name is the error |
| `gradient stop "<s>" is not a color`. |
| - **PRP-28.** A *linear* head is an angle (a bare number is degrees, `45deg` also works) or |
| `to <side> [<side>]`. Default `180deg`. A *radial* head is made of `circle`, `ellipse`, |
| position words, lengths and `at`. A *conic* head is `from <angle>` and/or `at <position>`. |
| Anything else is an error saying what is not part of the gradient. An interpolation space |
| (`in oklch`, `in hsl longer hue`, ...) may end the head. |
| - **PRP-29.** `mesh` takes a base color first (an item without `at`), then blobs |
| `color at X Y [size S]` (size defaults to 60%). Each blob is |
| `radial-gradient(circle farthest-side at X Y, color, transparent S)`. The base is |
| `linear-gradient(base, base)`. The blobs come first, the base last. |
| - **PRP-30.** Errors: `gradient needs a kind: ...`, `gradient needs at least two stops`, |
| `"<s>" is a midpoint, so it has to sit between two colours`, `a gradient stop is missing its |
| color`, `mesh needs a base colour and at least one blob`, `mesh item "<i>" needs a position`, |
| `mesh needs a base colour first (an item without "at")`. |
| - **PRP-31.** `gradient:` writes `background-image` marked as coming from a gradient, plus |
| `background-size`, `background-position` and `background-repeat` only when some layer set |
| one (with `auto`, `0 0` and `repeat` for the layers that did not). |
| - **PRP-32.** `gradient-text: layers` writes the same image, then `background-clip: text`, |
| `-webkit-background-clip: text`, `color: transparent`, `-webkit-text-fill-color: transparent`. |
| - **PRP-33.** `gradient-flow: duration [easing] [alternate|alternate-reverse]` or `none` |
| writes `@gradient-flow` with `{ duration (ms), easing, direction }`. `none` and an empty |
| value write `@gradient-flow: null`. The easing default is `linear` and the direction |
| default is `normal`. |
|
|
| ```dssl |
| .stripes { gradient: repeating linear 45, #fff 0 10, color.ink 10 20 } |
| .blend { gradient: linear 90 in oklch, #ff0055 -> #00d4ff } |
| .sheen { gradient: radial at top left, #fff/40 -> transparent + linear 135, #123 -> #456 } |
| ``` |
|
|
| ## 6.7 yield |
|
|
| `yield: name name ...` hands properties back to ordinary CSS. |
|
|
| - **PRP-34.** The names are separated by spaces or commas and lowercased. Each MUST be a known |
| CSS property or a semantic property name, otherwise the error |
| `yield: "<n>" is not a CSS property` and nothing is emitted. An empty list is the error |
| `yield needs the properties to hand back`. `none` writes `@yield: null`. Otherwise it writes |
| `@yield` with the list of names. |
| - **PRP-35.** For a name that is a shorthand, its longhands are handed back too (`padding` |
| hands back `padding-top` and the rest). |
|
|
| ## 6.8 Engine-native declarations |
|
|
| Declarations whose property starts with `@` are not CSS. They describe behavior that needs |
| more than a computed style. Each is produced by exactly one DSSL property and consumed by the |
| feature it belongs to. |
|
|
| | Output property | Produced by | Value | Chapter | |
| |---|---|---|---| |
| | `@animate` | `animate:` | a spec record, or null | 7 | |
| | `@stagger` | `stagger:` | milliseconds or null | 7 | |
| | `@overlap` | `overlap:` | `allow`, `deny`, `auto` | 8.6 | |
| | `@stack` | `stack:` | `"1"` | 6.3 | |
| | `@bend`, `@bend-y`, `@bend-up`, `@fold` | `bend`, `bend-y`, `bend-up`, `fold` | degrees | 8.5 | |
| | `@stretch` | `stretch:` | `{ factor, axis }` | 8.5 | |
| | `@bend-around` | `bend-around:` | degrees | 8.5 | |
| | `@gradient-flow` | `gradient-flow:` | spec record or null | 6.6 | |
| | `@texture` | `texture:` | list of layers or null | 8.1 | |
| | `@aura-glow`, `@aura-particles` | the aura family | list of layers or null | 8.2 | |
| | `@slider` | `slider:` | spec record | 8.3 | |
| | `@tilt` | `tilt:` | spec record or null | 8.4 | |
| | `@yield` | `yield:` | list of names or null | 6.7 | |
|
|
| - **PRP-36.** Engine-native declarations are not CSS and a host MUST NOT pass them to the |
| style system as properties. A Level 3 implementation combines them with the rule for each |
| feature. The default combination is the CSS one: for each name, the last in cascade order |
| wins. Exceptions are `@animate` (all of them are kept, 7.2) and `@yield` (names accumulate, |
| 5.11). |
|
|
| ## 6.9 behavior and use |
|
|
| ```dssl |
| behavior focus-ring { |
| outline: 2 solid color.accent |
| outline-offset: 2 |
| } |
| |
| .btn { use focus-ring } |
| ``` |
|
|
| - **PRP-37.** A top-level `behavior name { ... }` defines a named block of declarations and |
| nested blocks. A second block with the same name is the error `behavior "<n>" is defined |
| twice`. Behaviors are collected before the walk, so a behavior may be used above its |
| definition. `behavior` is allowed only at the top level. |
| - **PRP-38.** `use name` inside a block replays the behavior's children there, as if they had |
| been written in that place, with the same context. An unknown name is |
| `unknown behavior "<n>"` with a did-you-mean over the defined names. A behavior that uses |
| itself, directly or through others, is `behavior cycle involving "<n>"`. |
| - **PRP-39.** The declarations of a behavior are resolved at the place they are used, so |
| tokens, conditions and layers there apply to them. |
|
|
