Semantic Token

Semantic tokens live in the middle tier of any token system that survives beyond a single product. They take raw primitive values and give them jobs. A primitive holds color.blue.500 equals 3B82F6. The semantic token color-interactive-primary then points at that blue and declares its purpose. Every button link and badge references the semantic name. The component never touches the primitive directly. This separation means you can remap color-interactive-primary to a completely different primitive for dark mode or a full rebrand and every interface element updates without opening a single component file. The name becomes the contract. The value behind it becomes an implementation detail that can change at any time. IBM Carbon GitHub Primer and Shopify Polaris all treat this middle layer as non-negotiable infrastructure. Without it you are simply renaming your old hardcoded values and calling it progress.

Semantic tokens are not your primitive scale. They do not store raw values like hex codes or pixel measurements. That job belongs to the base layer. They are not component tokens either. Creating button-primary-background at the semantic level collapses your hierarchy into expensive find-and-replace theater. They are also not decorative aliases or clever names slapped on top of whatever looks good in Figma today. A semantic token must describe a clear role that appears consistently across the interface. If your token names still reference specific colors or specific components you have not built semantic tokens at all. You have built labeled spaghetti.

GitHub shipped their 2024 dark dimmed and high-contrast themes using exactly this pattern. Their semantic token fg-default resolves to different primitives depending on the active theme. In light mode it pulls a near-black. In dark dimmed it becomes a cool gray. The high-contrast version maps it to pure white. The search input the navigation bar and the comment threads all reference fg-default. None of them know or care which hex is active. Shopify Polaris uses color-bg-surface-tertiary as a semantic token for secondary containers. During their 2023 theme expansion they adjusted the underlying primitive values for their new dark palette. Every card modal and table updated instantly because no component referenced a primitive directly. IBM Carbon goes deeper with layer tokens. Their layer-01 semantic token handles page backgrounds while layer-02 manages cards sitting on those pages and layer-03 controls elements nested inside cards. Each layer token maps to entirely different primitives across Carbon's four official themes. Designers set these up in Figma variables released in 2023. Developers consume the matching CSS custom properties generated by Style Dictionary. The handoff contains zero ambiguity about intent because the semantic name documents the decision.

Roll out semantic tokens the moment your work touches more than two products or when stakeholders demand working dark mode. They pay for themselves the first time marketing changes the brand blue and you update one mapping instead of forty components. Use them in enterprise environments where nested surfaces and complex states multiply fast. IBM Carbon auditors check contrast once at the semantic level knowing that text-primary will always clear 4.5:1 against surface-default no matter which theme is active. Skip semantic tokens when you are a solo designer shipping a marketing site that updates twice a year. A single stylesheet beats an over-engineered token file every time. Avoid them during early MVP sprints where the visual direction still flips every two weeks. Premature semantic naming creates maintenance debt that feels worse than raw values. Never build them before you have tested actual components against real user flows. Jumping straight into color-accent-1 and color-accent-2 without validation produces tokens that confuse new team members and break during the first rebrand.

Semantic tokens turn your color palette into a decision engine that adapts without rewriting your components.