Tokens Helix has two layers of tokens. You use the second layer, the semantic tokens. LayerShapeWho may use itPrimitive--_helix-neutral-500@fusion.dev/helix-styles onlySemantic--helix-color-primaryAny code, including yours Each semantic token is named for its purpose. The name does not describe its value. Every token belongs to exactly one of sixteen categories: color scrollbar space radii font text weight leading tracking border shadow material duration easing size layer The leading underscore marks a token as private. We may rename or re-space any --_helix- token without notice. Code that uses a primitive token can break when you update Helix, so use the semantic tokens. Surface tokens A surface's depth is its distance from the page, in whichever direction has room. The page is white in light mode and black in dark mode. In light mode nothing is lighter than white, so a raised surface is darker than the page. background: the page. surface: a plane on the page, such as a card or a panel you own. surface-raised: something lifted that still lies on the page, such as a selected tab's pill, a hovered row, or an option under the pointer. The page surrounds it on all sides, so its fill sets it apart. On a white page, that fill is one step darker. surface-overlay: something over the page, such as a menu, a popover, a dialog, or the thumb of a switch or a segmented control. Its shadow and the content it covers set it apart, so on a white page it is white. surface-sunken: a well that holds a value, such as an input's fill, a track, or a groove. Use raised and overlay for different jobs. They are the same color in dark mode, so one token can seem to do both jobs. In light mode they need opposite fills. A hovered row must be darker than a white page, and a thumb must be lighter than the groove it sits in. If a surface looks almost right in dark mode and wrong in light mode, it usually uses the wrong one of these two tokens. Per-component hooks helix-card { --card-padding: var(--helix-space-lg); } --card-padding is a hook that the card component exposes. Hooks are separate from the Helix tokens. Each component documents its own hooks, and each hook defaults to a semantic token. Use a hook to adjust one component. Use the semantic tokens to change every component. What fails the build The build fails on four kinds of error: A raw value where a token exists, such as #e5e5e5 where a neutral token fits. A primitive token used outside @fusion.dev/helix-styles. A reference to a token that does not exist. A component hook that nothing reads, or a primitive token that nothing resolves to. The third check would be worth running on its own. When a token is renamed, a reference to the old name resolves to nothing. The property falls back to a browser default without a warning. The code looks correct, and the component loses its styles. Color modes Each token declares its light and dark values in one declaration: --helix-color-surface: light-dark(var(--_helix-neutral-50), var(--_helix-neutral-900)); The color-scheme property alone decides which value applies. You set the color mode with one attribute, and no token is declared twice. Set data-color-mode="light" or "dark" on any element to set the mode for that element and everything inside it. color-scheme inherits, so one attribute shows a light preview inside a dark page. Without the attribute, the mode follows the operating system.