Component Token

Component tokens sit at the final targeted layer of any real design token system. They exist only when a specific component must break from the semantic default for a valid reason. The three tier model starts with primitives holding raw values like color.blue.500 equals hex 3b82f6 or radius.large equals 12 pixels. Semantic tokens add purpose by mapping those primitives to roles such as color.surface.default or color.interactive.primary. Component tokens then declare that this exact button background or this exact card shadow gets a different mapping. The token name usually reads like button.background.critical or card.shadow.elevated. It never points straight to a primitive. It always references a semantic token so your dark mode swaps and rebrands continue to work everywhere. The name itself becomes living documentation that travels with the decision. Change the primitive once and every linked component updates without hunting through Figma layers or CSS files.

Component tokens are not your default styling method. They are not a fancy label slapped on every variant you ship. If you need a component token for standard buttons cards and links you have built the semantic layer wrong. They are not renamed hardcodes. Storing hex dc2626 inside a danger button token simply recreates the old maintenance nightmare with extra steps. They are not required for every state hover focus or disabled. Shopify Polaris ships most of its components using only semantic tokens. Overusing component tokens turns your clean hierarchy into a rat nest that breaks the moment someone updates one critical red. They are not an excuse to skip semantic thinking. Jumping from primitives straight to component tokens is how teams end up maintaining 400 disconnected values instead of a coherent system.

Shopify Polaris keeps component tokens sparse and deliberate. Their default button consumes semantic tokens for background text and border. The critical variant introduces component tokens such as button.background.critical.default and button.background.critical.hover that point at the semantic feedback.critical role instead of interactive.primary. When Polaris updated its critical red across the entire admin in 2023 one primitive change updated every destructive button checkout error state and banner without a single find and replace. IBM Carbon uses them more aggressively because its enterprise products contain deeply nested surfaces. The data table component defines table.header.background and table.row.divider that differ from page level surface tokens to maintain scannability in dense dashboards. These live in the component token file so designers know the divergence is intentional. GitHub Primer applies the same logic to its warning flash component. The component tokens override default borders with attention specific semantic values. When Primer shipped its dimmed dark theme in 2024 the component tokens needed zero edits because they referenced semantic tokens that already handled the theme swap. Atlassian follows a parallel pattern in its nested navigation where certain interactive states require tighter focus rings than the global semantic focus token permits. In Figma this appears as scoped variables created only after the semantic collection is locked.

Reach for component tokens once your semantic foundation has stabilized and you hit a genuine conflict no semantic token can solve cleanly. A pricing tier card might need a brand specific accent border that differs from the standard interactive border to match marketing guidelines. Create the component token card.border.accent and point it at the right semantic role. Complex enterprise modals often demand their own elevation values so they float correctly above layered surfaces. Floating action buttons in dense mobile views frequently require larger shadow values than the global semantic shadow.medium. Mature systems at IBM Shopify and Atlassian use them to keep consistency across dozens of products while still allowing controlled exceptions. They become lifesavers when retrofitting dark mode onto an existing codebase because the overrides stay logical instead of turning into one off CSS hacks.

Leave component tokens alone during early chaotic phases. A two person startup iterating weekly on its MVP gains nothing from the extra maintenance. Stick to semantic tokens until the visual language stops changing every sprint. Marketing sites run by non designers need nothing beyond basic CSS variables. If you are still debating your core palette in Q1 do not create component overrides. The worst failure mode is using component tokens to patch a weak semantic layer. One Series B fintech team in 2022 generated 180 component tokens before realizing their semantic roles were too vague. They spent four months ripping them out. If more than 15 percent of your components require overrides audit the semantic tier first. You probably need richer semantic names not more snowflake component tokens. The test is brutal but simple. Can this decision live at the semantic level without breaking anything else. If yes kill the component token.

Component tokens are the surgical override you deploy only when the shared rules truly do not fit.