CSS¶

Every selector, property, and value form Lumen's CSS subset accepts. For the task-level introduction see Styling; for the markup surface see Tags and attributes.

Lumen implements a subset of CSS Selectors 4, Cascade 5, and Media Queries 5, plus a few properties of its own for parts that standard CSS cannot address. Anything outside the subset is reported as a warning and the declaration is dropped; the rest of the stylesheet still applies.

Grammar¶

stylesheet    := at_import* (at_media | rule)*
at_import     := "@import" '"' path '"' ";"
at_media      := "@media" media_query "{" rule* "}"
rule          := selector_list "{" declaration* "}"
selector_list := selector ("," selector)*
selector      := compound (combinator compound)*
combinator    := " " | ">" | "+" | "~"
compound      := tag? ("." class | "#" id | ":" pseudo_class)*
declaration   := ident ":" value "!important"? ";"

/* ... */ comments are stripped anywhere. !important is matched case-insensitively at the end of a value.

@import "other.css"; splices another stylesheet in place. Paths are relative to the importing file. Imports must come before any rule; one written later is an error, as is a cycle. They nest. Imported rules are placed before the importing file's own rules, so at equal specificity the importing file wins.

@media blocks nest up to 32 levels, as do :is(), :where(), and :not() arguments.

@import, @media, and @font-face are the at-rules Lumen implements. @keyframes and @font-face are kept as authored and handed to the web target, which writes them back out; the desktop ignores @keyframes. A url() inside a kept block names a file relative to the app directory, the same place an <image src> names one from, and a web build copies that file into the site and points the block at the copy.

On the desktop a @font-face reads font-family, src, font-weight, and font-style. src is tried in order and the first TrueType or OpenType file that loads is registered under the rule's font-family. local() entries and woff / woff2 files, named by extension or format(), are skipped, and a font-weight range keeps the weight the file declares. Other descriptors are ignored. Any other at-rule is skipped with a warning along with its whole block, and the rest of the stylesheet applies.

Pseudo-elements (::before and friends) are a parse error, not a warning.

Selectors¶

Simple selectors¶

A compound writes the tag first: button.primary#save.

Combinators¶

Each step takes the nearest candidate that matches it and does not reconsider: .a .b .c binds .b to the closest matching ancestor, and .a ~ .b ~ .c binds .b to the closest matching earlier sibling. A selector that would only match through a farther candidate misses.

Sibling steps resolve wherever the cascade runs: when the stylesheet is applied to the document, and when an element restyles after a class change from a script or an OS theme flip. A row a <for> adds after the app starts is resolved on its own before it joins the tree, so a rule that needs an ancestor or a sibling step reaches it at the next restyle of the document.

Pseudo-classes¶

State pseudo-classes select a routing slot rather than filtering elements: a rule written with one always applies, and the runtime swaps the value in when the element enters that state.

Structural pseudo-classes filter on where the element sits in the tree:

Sibling position is read from the live tree, so a restyle that runs against one element on its own still selects the same elements a whole-document pass would: after a theme flip, a class change from a script, or a <for> rebuild, .row:last-child is still only the last row.

:is(), :where(), and :not() take a comma-separated list of selectors, each of which may use combinators. The element being tested is the subject of every argument, so .row:not(.list > .row) matches a .row that is not a child of a .list.

Specificity¶

Specificity is the triple (a, b, c) compared lexicographically:

• a counts #id selectors.
• b counts classes and pseudo-classes.
• c counts tag names.

:is() and :not() take the specificity of their most specific argument. :where() contributes nothing.

Cascade¶

Declarations are ordered by, in decreasing priority:

1. Origin. The built-in skin sheets are user-agent origin; your CSS is author origin and wins, whatever the specificity.
2. Importance, per declaration. !important applies to the one declaration it is written on, not to its siblings in the same rule.
3. Specificity.
4. Source order, then position within a selector list. The last matching declaration wins.

Markup attributes beat CSS, for every property both surfaces can set. <tile width="50px"/> keeps its width against .t { width: 100px }.

What a tag is by default is a user-agent default, not markup, so any stylesheet rule overrides it: the direction of <row>, <column>, <scroll> and the other layout tags, the position: absolute and full inset of <overlay> and <dialog>, the centring of a <dialog>'s content, a <spacer>'s grow, and the vertical axis of a <scroll>. scroll="x" on an element is markup: it lays the children out in a row and outranks the tag's direction.

An element resolves from scratch each time it restyles: after a class or id change from a script, a set_style, a theme flip or a breakpoint crossing. A property that no rule, attribute or inline style sets any more goes back to its initial value, so removing a class takes with it everything only that class set. What the runtime itself holds while it runs stays: a hidden <if>'s display: none, an open popup's placement, a virtualized row's slot, a hover or press tint, a :disabled patch, and a transition in flight, which heads for the new value from wherever it is.

One exception keeps skins from repainting your surfaces: when you set a resting bg (in CSS or as an attribute, a colour, gradient, or image), a skin's :hover and :active background for that element is dropped. :checked, :selected, :disabled, and :drag-over backgrounds from the skin still stand until you name that state yourself.

Inheritance¶

These properties inherit from parent to child: text-color (color), selection-color, selection-text-color, caret-color, font-size, font-family, font-weight, line-height, text-align, wrap, max-lines, image-rendering, and cursor. Custom properties inherit through their own scope. Every other property applies only where it matches.

An inherited value acts as a zero-specificity base, so any matching rule or markup attribute on the child overrides it.

Error recovery¶

A declaration with an unknown property, an unparseable value, or an unresolvable var() is dropped and reported as a warning naming the selector and the property. The rest of the stylesheet applies. Duplicate warnings are reported once.

A declaration under a state pseudo-class that is not one of the state-routable properties below is accepted and has no effect.

Custom properties¶

Any declaration whose name starts with -- is a custom property. It is stored, not applied, and inherits to descendants.

:root {
  --accent: #33c7ce;
  --panel: #0c2c4a;
}

.card {
  bg: var(--panel);
  border: 1px solid var(--accent);
}

var(--name) substitutes the value; var(--name, fallback) uses the fallback when the name is unset. References resolve recursively up to 16 levels; a cycle or an unknown name with no fallback drops the declaration with a warning.

Custom properties cascade like other declarations, including !important, and a rule matched on an ancestor puts its values in scope for descendants. That makes :root.theme-dark { --panel: ... } a working theme switch.

The runtime reads two custom properties directly: --lumen-tooltip-delay (milliseconds) and --lumen-tooltip-offset (pixels), because <tooltip> collapses at parse time and no selector can reach it. The built-in skins define the --lumen-* token set they theme themselves with; redeclaring those names in your own :root block retints the skin.

@media¶

@media (prefers-color-scheme: dark) and (min-width: 700px) {
  .card { bg: #101014; }
}

Features are joined with and. Comma-separated query lists, or, and not are not supported.

Lumen reads the OS color scheme and the window size. It does not read the motion or contrast preference from the OS yet, so prefers-reduced-motion and prefers-contrast only ever match no-preference. Give people an in-app switch for anything heavily animated or low-contrast.

Value forms¶

Gradients¶

The bg property accepts three gradient functions. Each stop is a colour with an optional position, given as a percentage or a 0..1 number. Stops without a position are distributed evenly, and all stops are sorted by position.

.a { bg: linear-gradient(90deg, #101014, #202028 60%, #303040); }
.b { bg: radial-gradient(#ffffff, #000000); }
.c { bg: conic-gradient(from 45deg, #ff0000, #00ff00, #0000ff); }

• linear-gradient([<angle>deg,] <stop>, <stop>, ...). The angle defaults to 180deg, top to bottom. At least two stops.
• radial-gradient(<stop>, <stop>, ...). The centre is fixed at the middle of the box and the radius covers it. At least two stops.
• conic-gradient([from <angle>[deg],] <stop>, <stop>, ...). The start angle defaults to 0. At least two stops.

Background images¶

bg also takes an image, named with url(). The path may be double-quoted, single-quoted, or bare, and it resolves against the app directory the same way an <image src> does, and loads and caches the same way. Under lumenc run, saving the image file shows the new picture without a restart, as it does for an <image>; see hot reload.

:root { --hero: url("art/day.png"); }
:root.night { --hero: url("art/night.png"); }

.banner {
  bg: var(--hero);
  bg-fit: contain;
  radius: 12px;
}

The image paints as the element's background: behind its content and children, under its border, and clipped to its corner radius. It fills the border box, and bg-fit decides how, with the values fit takes on an <image>: cover (the default), contain, fill, none, and scale-down. none keeps the image's own size at the top-left corner; the others centre it. The image never sizes its element: give the element a size, or let its content size it.

An image replaces the colour: bg holds one value, so set the colour on a parent if you want one showing through transparent pixels. An <image> element ignores a bg image; its src is its one source.

Masks¶

mask-image paints an element, its border and everything inside it through the alpha of an image: where the image is opaque the element shows, where it is transparent nothing of it does. Paired with bg, it colors an icon with any color, gradient, or theme token, so one icon file serves every theme:

.tool-icon {
  width: 20px;
  height: 20px;
  bg: var(--text);
  mask-image: url("icons/pencil.svg");
  mask-size: contain;
  mask-repeat: no-repeat;
  mask-position: center;
}
.tool.active .tool-icon { bg: var(--on-accent); }

The image is a raster image or an SVG, named with url() and resolved and loaded the way a bg image is. It is laid out in the element's border box and nothing of the element shows outside that box. Until the image has loaded, or when it fails to load, nothing of the element shows, as on the web.

• mask-size: contain, cover, or a width and an optional height, each a length, a percentage of the box, or auto (one auto keeps the image's proportions; the default auto is the image's own size).
• mask-repeat: repeat (the default), no-repeat, repeat-x, repeat-y, or one of repeat / no-repeat per axis.
• mask-position: one or two of left, center, right, top, bottom, a length, or a percentage; the default is the top-left corner.

The masks are a subset of the web's: one image layer, used through its alpha. Lumen has no mask shorthand, gradients as mask images, several layers, mask-mode, mask-origin, mask-clip, mask-composite, the space and round repeats, edge offsets such as right 4px top 2px in mask-position, or the -webkit-mask-* spellings. A web build writes the same four properties, which every current browser reads.

Shadows¶

box-shadow: [inset] <x> <y> <blur> [<spread>] <#color> [, ...]

inset draws the shadow inside the box. Multiple shadows are comma separated and paint in order. shadow is an accepted synonym.

Property catalogue¶

The Lumen short names and the standard CSS names below are interchangeable: color for text-color, background and background-color for bg, border-radius for radius, flex-grow for grow, flex-shrink for shrink, justify-content for justify, object-fit for fit, and white-space for wrap.

Layout¶

overflow: scroll makes an element a live scroll container. overflow: hidden cuts its descendants off at the element's box without making it scrollable; inside a scroll container that clip travels with the element as the content scrolls.

An element's own text lays out as an item of its own, sized to the words, so justify-content places it along the main axis the same way it places a child: justify-content: center on a button centres its label. It applies on a horizontal main axis only, and an authored text-align wins where both are set.

Minimum sizes and shrinking¶

Items on a flex line that does not fit shrink, in proportion to their size, until they reach their minimum size. Left at the default auto, that minimum is the smaller of the element's own content and its authored width / height: a box with nothing in it shrinks to nothing, a box holding a 250px child stops at 250px, and a box whose child is wider than its authored width still stops at that width.

Two properties change it:

• min-width: 0 / min-height: 0 drops the floor entirely, so the element shrinks past its content and the content overflows. This is what a long unbreakable label usually wants.
• shrink: 0 takes the element off the shrinking list, so it keeps its authored size and the line overflows instead.

overflow: hidden and overflow: scroll also drop the automatic floor to zero, since the element clips its own content. So does a <scroll> (or any element with a scroll attribute), on both axes: a grow: 1 scroller in a fixed-height column takes the space it is given and scrolls the rest. An authored min-width / min-height still sets the floor.

Positioning¶

Every element is a containing block. position: absolute takes an element out of the flow and resolves its inset against its parent's padding box, whichever element that parent happens to be; there is no position: static and no search up the tree for a positioned ancestor. So the wrapper you want an element pinned inside is the element you write it under, and no position: relative is needed on that wrapper.

A side you leave unset is auto. With no inset at all the element keeps its content size where it would have sat in the flow; with two sides set, such as inset: 4 8 auto auto or inset-block-start plus inset-inline-end, it keeps its size against that corner. Set opposite sides, as inset: 0 does, to stretch it between them. An element with no parent at all, such as one a Rust plugin spawns as a root of its own, resolves its inset against the window.

An out-of-flow child contributes nothing to its parent's content size. A parent that is content-sized on an axis and has only absolutely positioned children therefore measures zero on that axis, and a child with inset: 0 fills that zero. Nothing appears:

.stage { overflow: hidden; }  /* height comes from content: none */

<column class="stage">
  <overlay>...</overlay>
</column>

Size the parent to fix it: give it a height (or width on the horizontal axis), grow: 1 so it takes the free space on its own line, or an inset of its own if it is absolutely positioned too. One in-flow child works as well, since the parent then measures that child. With overflow: hidden on the parent, as above, the collapsed subtree is clipped away entirely rather than spilling into view, so the symptom is a blank window.

lumenc lint reports this shape as collapsed_containing_block and names the child it found.

Logical properties¶

Each takes a px number (the inset-* ones also take auto) and resolves against the element's writing direction, which comes from dir in the markup or, with none authored, from the app's locale.

• padding-inline-start, padding-inline-end, padding-block-start, padding-block-end
• margin-inline-start, margin-inline-end, margin-block-start, margin-block-end
• inset-inline-start, inset-inline-end, inset-block-start, inset-block-end
• border-inline-start-width, border-inline-end-width, border-block-start-width, border-block-end-width

Grid¶

Track lists take plain track sizes. repeat(), named lines, and span are not supported. Line numbers outside the range of a 16-bit integer are clamped with a warning.

Visuals¶

opacity fades an element together with everything inside it, as one picture, the way CSS does: an opaque child still hides its parent's background, and the two fade once. Nested opacities compound. An element with no visible children fades its background, border, and text one by one, so where its own border or text overlaps its background, the background shows through faintly. The renderer keeps the picture of a faded element with children from one frame to the next while nothing inside it changes, so animating its opacity does not repaint its contents.

image-rendering picks how a raster image drawn at another size than its own is sampled: an <image>, a bg: url(...) image, and the images and pixel buffers drawn on a <canvas>. auto and smooth blend neighbouring pixels; pixelated and crisp-edges take the nearest pixel, so scaled-up pixel art keeps hard edges. It inherits, so setting it on a container reaches every image inside. A canvas's paths and text are drawn at the element's size rather than scaled from a bitmap, so the property changes only the images and pixel buffers drawn on it.

disabled-opacity sets how much a disabled element dims when neither :disabled { bg } nor :disabled { opacity } was authored. knob-color, knob-inset, thumb-size, and popup-gap reach widget parts that have no selector of their own.

Borders and outlines¶

solid and none are the supported border styles; dashed, dotted, and the rest are rejected with a warning. A shorthand that omits the style but names a width or a colour resolves to solid. Without a style there is no border: the computed width is zero and nothing paints.

Borders participate in layout under box-sizing.

Text¶

The shaper resolves the first available family in a font-family list, honouring the generic keywords, and falls back to the platform sans-serif. lighter and bolder are rejected: they need the parent's computed weight.

Any font-weight from 1 to 1000 is accepted. A variable font renders the weight you author wherever its weight axis covers the value; a family built from separate faces renders the nearest weight it ships, chosen the way CSS chooses it (from 400-500 look up to 500 first, then down; below 400 look down first; above 500 look up first). So font-weight: 650 against a family with a regular and a bold face draws the bold face, and measures as that face.

text-overflow: ellipsis elides overflowing single-line text unless you also author wrap and max-lines, in which case your multi-line clamp is ellipsized instead.

Text input¶

These apply to <input> and <textarea>.

The caret blink phase is shared by the whole app, so caret-blink sets one period for every input; it is applied when styles are reapplied, not at startup.

Interaction states¶

State-routable properties, and where each state's value lands:

bg under a state takes a colour; a gradient or an image there is dropped with a warning. bg under :hover, :focus, and :focus-visible shares one slot, so the three cannot differ. outline under :focus-visible gets its own slot and wins over :focus while focus came from the keyboard.

On a <toggle> or <switch> track, :disabled { bg } wins over :checked { bg }, so a disabled control that happens to be on shows the disabled fill rather than the checked one.

The same swaps are reachable as plain properties, which is often shorter:

Progress¶

progress-duration is the indeterminate sweep period and progress-chunk the fraction of the track the moving chunk covers.

Transitions¶

.card {
  transition: bg 150ms ease-out, opacity 100ms linear;
}

Animatable properties: opacity, background-color (background, bg), color (text-color), and border-color. all stands for all four. Any other name in a transition list is ignored with a warning; layout properties are deliberately excluded so a transition never re-runs layout every frame.

An entry that names no easing gets ease. A second duration in an entry is a delay, which Lumen warns about and ignores: a transition always starts on the tick the value changes. transition-delay is warned about and ignored for the same reason.

The transition shorthand resets the longhands. Otherwise transition-property defines the list and the duration and easing lists cycle over it; a duration list without a property list produces nothing.

Animations¶

@keyframes spin {
  from { transform: rotate(0deg); }
  to   { transform: rotate(360deg); }
}

.spinner {
  animation: spin 2s linear infinite;
}

These reach the web target and do nothing on the desktop, which has no keyframe engine; transition is what animates a desktop app. Values are written out as authored, so the browser reads the standard CSS meaning of each one.

A @keyframes block is browser CSS, not Lumen's dialect: its body is carried through untouched, so a keyframe declares background, transform and opacity rather than bg. A block written inside @media is emitted inside the same query.

Scrollbars¶

scrollbar-color and scrollbar-width are the standard CSS properties; the rest are Lumen's own geometry and timing controls for the overlay scrollbar.

Scrolling and focus¶

Pointer cursor¶

The keywords are the standard set: auto, default, none, context-menu, help, pointer, progress, wait, cell, crosshair, text, vertical-text, alias, copy, move, no-drop, not-allowed, grab, grabbing, e-resize, n-resize, ne-resize, nw-resize, s-resize, se-resize, sw-resize, w-resize, ew-resize, ns-resize, nesw-resize, nwse-resize, col-resize, row-resize, all-scroll, zoom-in, and zoom-out. auto shows the platform arrow and none hides the pointer.

.canvas { cursor: url("cursors/pen.png") 2 14, crosshair; }

A url() names a raster image relative to the app directory, the way a bg: url(...) does; the two numbers are its hotspot in image pixels from the top-left corner, which is the default. The first image that loads is shown at its own pixel size, and the keyword stands in while it loads or when none does. The keyword is required, as on the web.

The pointer shows the cursor of the element under it. The value inherits, so a container's cursor reaches everything inside it until a descendant declares its own; an element that declares one receives hover even with no background. The user-agent sheet gives <input> and <textarea> cursor: text, <a> cursor: pointer, and a <split>'s gutters col-resize in a row and row-resize in a column; every other element, buttons included, shows the arrow until a stylesheet says otherwise. The thumb of a scrollbar or a <slider> shows grab under the pointer and grabbing while dragged; no selector reaches those parts.

Web target mapping¶

Built for the web, an app ships its stylesheet as real CSS and the browser runs the cascade. Most of what you write arrives unchanged; this section is the rest.

Selectors¶

A tag selector becomes the class the element carries in the document, inside :where(): button is emitted as :where(.lm-button). The wrapper keeps the tag weighing nothing, so it still loses to a class the way it does everywhere else.

The four states no browser selector covers are mirrored onto attributes:

:checked and :disabled keep the browser's own state beside the mirror, because a <checkbox> is a real checkbox there and a <toggle> is a button. Every other selector, :hover and the structural pseudo-classes included, is emitted as written.

Rules are written out in the order Lumen's cascade puts them in, so where the browser cannot tell two rules apart it picks the one Lumen picks.

Property names¶

The Lumen short names are emitted under their standard spelling:

justify: between, around, and evenly are emitted as space-between, space-around, and space-evenly.

States written as properties¶

A property that names a state becomes a rule of its own, written beside the rule it came from:

Lengths¶

A bare number is pixels in Lumen and nothing at all in CSS, so padding: 8 16 is emitted as padding: 8px 16px.

A length that reaches a property through var() is var(--gap) whatever the token holds, so the unit goes on the definition instead: a custom property the stylesheet uses only in places where a bare number means pixels is emitted with px on it, and --gap: 8 becomes --gap: 8px. Writing the unit yourself is still clearer, and a token that already has one is left alone.

A token used both where a number means pixels and where it means a plain number cannot be both, so it is emitted as authored and lumenc web names it in a warning. Split it into two tokens, or write the unit on the one that needs it.

Gradient stop positions travel as written; write them as percentages.

Background image placement¶

A bg image is copied into the site's assets/ like an <image src>, and the url() is rewritten to point at the copy, whether it is written on bg, in a bg attribute, or in a custom property a theme swaps. A bg that is an image, or reads a token holding one, also gains background-size, background-position, background-repeat: no-repeat, and background-origin: border-box, so it sits in the box the way the desktop draws it. bg-fit is emitted as the --lm-bg-size and --lm-bg-position custom properties those read, registered so they do not inherit. Browsers have no scale-down for a background, so it is emitted as contain, which also enlarges an image smaller than the box.

Properties with no browser equivalent¶

The knobs that reach widget parts no selector can address are emitted as custom properties, --lm- plus the property name: knob-color becomes --lm-knob-color. The browser ignores them and Lumen reads them back off the element, so they keep working, and you can read one yourself with var(--lm-knob-color).

This covers knob-color, knob-inset, thumb-size, popup-gap, caret-width, caret-blink, password-character, disabled-opacity, progress-duration, progress-chunk, sensitivity, inertia, and the scrollbar-* geometry and timing properties. The ones measured in pixels carry px like any other length. scrollbar-color and scrollbar-width are standard CSS and are emitted as themselves; a scrollbar-color naming only a thumb gains transparent for the track, which CSS requires.

knob-color, knob-inset and thumb-size are also what the emitted stylesheet draws a control's parts from. A <toggle>, a <switch> and a <slider> are one element in a page and a track plus a knob on the desktop, so the knob is drawn as a pseudo-element from those three values, and a <checkbox>, a <radio> and a <progress> are drawn from the state the runtime marks them with. Anything an app's own CSS says about the control still wins.

What is not emitted¶

Selector matching differs in one way worth knowing. Lumen's matcher takes the nearest candidate for each step and does not reconsider, and a browser's does; a selector that relies on that difference matches more elements on the web than it does on the desktop.