Language Reference
Each entry is one grammar rule, shown as a railroad diagram and its EBNF (ISO/IEC 14977).
source file
source file = { ( definition | group definition | rule ) , ";" } ;
source file is referencing:
Definitions and groups
define <name> as "<selector>" binds a friendly name to a CSS selector. A *
suffix declares an indexed family, so card-1, card-2 resolve to the 1st and
2nd matches of define card-* as ".card". group <name> as a, b, c names a
tuple; a rule written on @name expands to one rule per member.
definition
definition = "define" , ( wildcard name | identifier ) ,
"as" , quoted text ;
Items referencing definition:
definition is referencing:
group definition
group definition = "group" , identifier , "as" ,
identifier , { "," , identifier } ;
Items referencing group definition:
group definition is referencing:
Rules
Every rule (except count) begins with an element, then a relation and its
operands. Prefix the element with not to invert the whole rule, e.g.
popover not inside footer;. The five rule families follow.
rule
rule
= count rule
| spatial rule
| visual rule
| text or css rule
| alignment rule
;
Items referencing rule:
rule is referencing:
The subject prefix shared by every rule except count.
element
element = ( identifier | group reference ) ,
[ "not" ] ;
Items referencing element:
element is referencing:
Count rules
Count the elements matching a pattern, optionally filtered to visible or
absent ones. The target is an exact number, a comparator (>= 3), or an
inclusive range (2 to 5). Example: count visible card-* is >= 3;.
count rule
count rule = "count" , count scope , object pattern , "is" ,
( number
| comparator , number
| number , "to" , number
) ;
Items referencing count rule:
count rule is referencing:
Spatial rules
Geometry between boxes. near checks proximity in one or more directions;
inside / partially inside check containment with optional signed side
offsets; the directional relations (left-of, below, aligned-top, …) take a
target and optional distance; equal-gap-x / equal-gap-y assert even spacing
across a chain of targets. Example: badge inside page -8px top right;.
spatial rule
spatial rule
= element , "near" , identifier , near clause ,
{ near clause }
| element , "inside" , identifier , { inside clause }
| element , "partially" , "inside" , identifier ,
{ inside clause }
| element , relation , identifier , [ distance ]
| element , relation , distance
| element , ternary relation , identifier , identifier ,
[ distance ]
| element , ternary relation , "[" , identifier ,
identifier , { identifier } , "]" , [ distance ]
;
Items referencing spatial rule:
spatial rule is referencing:
A near clause: a distance plus the directions it applies to.
near clause
near clause = distance , direction , { direction } , [ "," ] ;
Items referencing near clause:
near clause is referencing:
An inside clause: a signed distance (offset) plus its sides.
inside clause
inside clause = signed distance , direction ,
{ direction } , [ "," ] ;
Items referencing inside clause:
inside clause is referencing:
Visual rules
Visibility and size. Size is absolute (sidebar width <= 320px) or expressed as
a percentage of another element's dimension (thumb width 100% of card/width).
visual rule
visual rule
= element , visibility relation
| element , size property , [ comparator ] , distance
| element , size property , [ comparator ] ,
percentage , "of" , identifier , "/" , size property
;
Items referencing visual rule:
visual rule is referencing:
Text and CSS rules
Assert against rendered text content or a computed CSS property. Text rules may
apply lowercase, uppercase, or singleline transforms before matching.
Example: headline text starts "Welcome"; or nav css display is "flex";.
text or css rule
text or css rule
= element , "text" , { text operation } , match mode ,
quoted text
| element , "css" , css property , match mode ,
quoted text
;
Items referencing text or css rule:
text or css rule is referencing:
Alignment rules
aligned matches shared edges or centers along an axis; centered centers an
element inside a target. Example: icon centered all inside button; or
title aligned horizontally top subtitle 4px;.
alignment rule
alignment rule
= element , "aligned" , aligned axis , aligned mode ,
identifier , [ distance ]
| element , "centered" , centered axis , "inside" ,
identifier , [ distance ]
;
Items referencing alignment rule:
alignment rule is referencing:
Terminal keyword sets
The fixed vocabularies referenced above.
relation
relation
= "below" | "above"
| "left-of" | "right-of"
| "aligned-top" | "aligned-bottom"
| "aligned-left" | "aligned-right"
| "wider-than" | "taller-than"
| "same-width" | "same-height"
| "distance-from-top"
;
Items referencing relation:
ternary relation
ternary relation = "equal-gap-x" | "equal-gap-y" ;
Items referencing ternary relation:
direction
direction = "left" | "right" | "top" | "bottom" ;
Items referencing direction:
visibility relation
visibility relation = "visible" | "absent" ;
Items referencing visibility relation:
count scope
count scope = "any" | "visible" | "absent" ;
Items referencing count scope:
size property
size property = "width" | "height" ;
Items referencing size property:
aligned axis
aligned axis = "horizontally" | "vertically" ;
Items referencing aligned axis:
centered axis
centered axis = "horizontally" | "vertically" | "all" ;
Items referencing centered axis:
aligned mode
aligned mode
= "all"
| "top"
| "bottom"
| "left"
| "right"
| "centered"
;
Items referencing aligned mode:
comparator
comparator = "<=" | ">=" | "<" | ">" ;
Items referencing comparator:
match mode
match mode
= "is"
| "contains"
| "starts"
| "ends"
| "matches"
;
Items referencing match mode:
text operation
text operation = "lowercase" | "uppercase" | "singleline" ;
Items referencing text operation:
Measurements
Distances and percentages, each available as a single value or an inclusive range.
distance
distance
= number , "to" , number , "px"
| number , "px"
;
Items referencing distance:
distance is referencing:
percentage
percentage
= number , "to" , number , "%"
| number , "%"
;
Items referencing percentage:
percentage is referencing:
signed distance
signed distance = signed number , "px" ;
Items referencing signed distance:
signed distance is referencing:
Lexical tokens
The regular (non-recursive) tokens, described as special sequences.
identifier
identifier = ? letter or _, then letters/digits/_/- (not ending in *) ? ;
Items referencing identifier:
wildcard name
wildcard name = ? identifier characters followed by a single * ? ;
Items referencing wildcard name:
group reference
group reference = ? "@" followed by identifier characters ? ;
Items referencing group reference:
object pattern
object pattern = ? CSS-ish pattern: letters digits . # * _ - ? ;
Items referencing object pattern:
css property
css property = ? a CSS property name, or a --custom-property ? ;
Items referencing css property:
quoted text
quoted text = ? a double-quoted string with backslash escapes ? ;
Items referencing quoted text:
number
number = ? one or more decimal digits ? ;
Items referencing number:
signed number
signed number = ? optional "-" then one or more decimal digits ? ;
Items referencing signed number:
comment
comment = ? "#" through to the end of the line ? ;