CSS Custom Properties (--var, var()) #121

Overview#

Implement CSS Custom Properties (CSS Variables) per the CSS Custom Properties for Cascading Variables Module Level 1 specification.

Requirements#

Parsing#

• Parse custom property declarations: --property-name: value
• Parse var() function references: var(--property-name) and var(--property-name, fallback)
• Custom property names are case-sensitive and must start with --
• Values can contain any valid CSS tokens (preserved as-is until substitution)

Cascade & Inheritance#

• Custom properties participate in the cascade (specificity, source order)
• Custom properties are inherited by default
• Support initial keyword to reset a custom property
• Resolve var() references during computed style resolution

Substitution#

• Replace var() references with the custom property's computed value
• Support fallback values: var(--missing, red) resolves to red if --missing is not defined
• Nested var() in fallback: var(--a, var(--b, blue))
• Detect and handle cyclic references (treat as invalid)

Integration#

• Integrate with existing CSS parser in crates/css/
• Integrate with style resolution in crates/style/

Acceptance Criteria#

• --custom: value declarations parse correctly
• var(--custom) resolves to the declared value
• var(--missing, fallback) returns the fallback
• Custom properties inherit through the DOM tree
• Cyclic references are detected and handled gracefully
• All existing tests continue to pass
• New unit tests cover parsing, inheritance, substitution, and cycles