Waypoint’s session cards come in four tracks (Design, Performance, Accessibility and Platform), and each track has its own color for the left border, the badge and the title hover state. The first version had a rule per track per element: twelve rules, and a thirteenth set every time marketing added a track.
\nCustom properties turn that into one rule per track and a card that reads its color from a single dial.
\n.session-card {\n border-inline-start: 6px solid var(--track-color, #64748b);\n}\n.session-card .badge {\n background: var(--track-color, #64748b);\n color: white;\n}\n\n.track-design { --track-color: #db2777; }\n.track-perf { --track-color: #0891b2; }<article class=\"session-card track-design\">…</article>Two things make this work. First, custom properties inherit: setting --track-color on the card makes it visible to the badge inside. Second, var() is resolved at the element that uses it, at computed-value time, so each card substitutes its own value. The second argument to var() is the fallback, used only when the property isn’t set at all.
Where you set a custom property matters. Global design tokens (brand colors, the spacing scale, font stacks) belong on :root, so every element inherits them. Component tokens such as --track-color belong on the component, so they stay local and one card can differ from its neighbour. Changing a property on :root from JavaScript forces the browser to recompute styles for the whole tree that uses it, so for something that changes often, like a pointer position, set it on the smallest element that needs it.
Think of --track-color as the card’s public API. Anyone can theme a card from outside, in a CMS template or a one-off campaign page, without knowing its internals.
Unregistered custom properties are just strings of tokens. The browser doesn’t know --track-color is supposed to be a color, so --track-color: 12px is a perfectly valid declaration. The problem appears later, when var() drops 12px into border-inline-start’s color.
That’s how Waypoint shipped a card with no track border at all and a see-through badge: the CMS wrote 12px into the color field, and nothing complained.
@property tells the browser what a custom property is:
@property --track-color {\n syntax: \"<color>\";\n inherits: true;\n initial-value: #64748b;\n}Now three things change:
\n<color> makes the property fall back safely: it behaves as unset, so an inherited property takes the parent’s value, which ends at the initial-value if nobody sets it. The bad card gets a slate grey border instead of none.getComputedStyle(card).getPropertyValue('--track-color') returns rgb(219, 39, 119), not the raw text you wrote.The syntax descriptor accepts types such as <color>, <length>, <length-percentage>, <number>, <percentage>, <angle>, <time> and <integer>, plus "*" for anything. initial-value is required unless the syntax is "*", and it must be computationally independent: 10px is fine, 2em isn’t.
Here’s a hover effect that’s only possible with registration. The card’s top edge is a gradient whose angle is a custom property:
\n@property --sheen-angle {\n syntax: \"<angle>\";\n inherits: false;\n initial-value: 90deg;\n}\n\n.session-card {\n background: linear-gradient(var(--sheen-angle), #f5f3ff, white 60%);\n transition: --sheen-angle 400ms ease;\n}\n.session-card:hover {\n --sheen-angle: 160deg;\n}Without @property, the browser can’t interpolate a token string, so the gradient snaps from one angle to the other. With it, the angle animates smoothly. inherits: false is right here: the angle belongs to this card’s background, and children shouldn’t receive it.
The exercise reproduces the CMS bug: one card’s --track-color is 12px. Register the property so bad values fall back to slate grey, and check that real track colors still come through. The next lesson keeps working on these cards with native nesting and :has(), which lets a card react to what’s inside it.
var() is used, so setting one on a parent re-themes every descendant that reads it.","A var() that produces an invalid value makes the property invalid at computed-value time; the browser uses the inherited or initial value, not your earlier declaration.","An unregistered custom property is an untyped string of tokens, so the browser can’t validate it or interpolate it in a transition.","@property gives a custom property a syntax, an initial value and an inheritance flag, which makes bad values fall back safely and lets the property animate."],"further":[{"title":"Using CSS custom properties (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties"},{"title":"@property (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@property"},{"title":"@property: giving superpowers to CSS variables (web.dev)","url":"https://web.dev/articles/at-property"}],"quiz":[{"q":"What padding does .card get?
.card {\n --space: blue;\n padding: 24px;\n padding: var(--space);\n}var() is checked later, after the cascade has already picked the last declaration."},{"text":"0, the initial value of padding.","why":"Correct. padding: var(--space) wins the cascade, then turns out invalid at computed-value time, so padding falls back to its initial value."},{"text":"The browser ignores --space and uses the var() fallback, which is empty.","why":"There’s no fallback in var(--space), and fallbacks are only used when the property is missing (guaranteed-invalid), not when its value is the wrong type."}],"answer":1},{"q":"You register @property --angle { syntax: '<angle>'; inherits: false; initial-value: 0deg; }. What does this give you that an unregistered --angle doesn’t?
--angle inside var().","why":"Unregistered custom properties work in var() too; registration isn’t required for substitution."},{"text":"Faster rendering, because typed properties skip the cascade.","why":"Registered properties go through the cascade like any other; registration changes parsing, validation and interpolation, not cascade cost."},{"text":"Smooth transitions and animations of --angle, because the browser knows how to interpolate angles.","why":"Correct. An untyped property can only flip discretely; a typed one interpolates, so a gradient driven by --angle can rotate smoothly."}],"answer":2},{"q":"Where should a session card’s accent color be set so that a .track-design card and everything inside it uses pink?
.track-design { --accent: #db2777; }, with the card’s rules reading var(--accent).","why":"Correct. Custom properties inherit, so the card and its title, badge and border all pick up the value."},{"text":":root { --accent: #db2777; } inside a .track-design media query.","why":"Media queries test the viewport, not the element, and :root would recolour every card on the page."},{"text":"On each child element separately, because custom properties don’t inherit.","why":"Unregistered custom properties always inherit, and registered ones inherit unless you set inherits: false."}],"answer":0},{"q":"A registered property has syntax: '<color>'; inherits: true; initial-value: gray, and a card sets --accent: 12px. Its parent doesn’t set --accent. What value does the card end up with?
<color>."},{"text":"gray, inherited from the parent, which has the initial value.","why":"Correct. The invalid value makes the property behave as unset, which for an inherited property means inherit, and the parent holds the initial value."},{"text":"Nothing; the whole card rule is dropped.","why":"Only the invalid declaration is affected, and the browser recovers by treating it as unset."}],"answer":1}],"exercise":{"kind":"web","mode":"dom","starter":{"html":"The CMS wrote 12px into the Lightning Talks card’s --track-color, so its border and badge lose their color. Register --track-color with @property as a <color> that inherits and has an initial value of #64748b (slate grey). The Design (#db2777) and Performance (#0891b2) cards must keep their colors, and the broken card should fall back to slate grey.
@property takes three descriptors: syntax, inherits and initial-value.","The syntax for a color is the string "<color>", with the quotes.","@property --track-color { syntax: “Once --track-color is registered as a <color>, the browser checks every value against that type. 12px fails, so on the Lightning Talks card the property behaves as unset; because it inherits, it takes the parent’s value, and the parent only has the initial value, #64748b. Valid track colors pass through and are now stored as real colors, which is why getComputedStyle reports rgb(219, 39, 119) instead of the text #db2777. Without registration, 12px was substituted into the border-inline-start shorthand, making the whole declaration invalid at computed-value time; every longhand reset to its initial value, including border-style: none, so the border vanished.