Component Layer

The component layer is the top tier in a three layer Figma token system. It contains highly specific tokens scoped to individual component families and their states. Tokens carry names like button-primary-bg, button-primary-text, card-elevated-surface, input-focus-ring, and modal-close-button. Every token in this layer aliases exclusively to a semantic token. Button primary bg points to surface brand. Surface brand points to blue 600. The primitive holds the hex. This chain of exactly three links lets teams handle component specific details without forcing those details into the semantic layer where they create bloat. The component layer remains completely mode agnostic. It knows nothing about light dark or brand variations. Those live in the semantic collection. When the semantic token changes its primitive target in dark mode every component token updates automatically. Scoping keeps the discipline tight. Component tokens apply only inside their family. No button token ever shows up in a card properties panel. This setup makes handoff to code straightforward. Tokens Studio exports the component collection into JSON that Style Dictionary turns into clean CSS variables or platform specific constants. The entire pipeline runs automatically so design and code stay in sync without manual exports.

The component layer is not a replacement for semantic tokens. It is not the place for raw values or hex codes. It is not your old styles with new names. Teams that stuff raw colors into component tokens build systems that shatter the first time a brand update lands. The layer does not carry global meaning. Success color belongs in semantics not as button success bg. The component layer does not tolerate shortcuts in the alias chain. Any token that points straight to a primitive bypasses the translation layer and turns theme switches into manual labor. It is not an optional piece for small teams. The moment you add a second theme the absence of this layer exposes the cracks in your architecture. Stop building flat systems and pretending they qualify as token architectures.

Concrete example. Shopify rebuilt their Polaris admin interface in 2022 after checkout flows demanded background treatments that clashed with global surface semantics. They added component tokens including checkout-button-bg and checkout-surface. These aliased cleanly to semantic surface-action and surface-primary. The product team later decided the checkout button required a distinct treatment during a payments redesign. The component token provided the exact override point. Semantic surface-action updated for new brand modes while the checkout button token stayed untouched. The alias chain of checkout-button-bg to surface-action to blue-500 to the hex value survived every change. No component updates required. Atlassian faced similar issues in 2021 with Jira versus Confluence surfaces. Component tokens like jira-header-bg aliased to semantic surface-elevated but allowed independent adjustment when Jira needed higher contrast. Dark mode flipped the semantic references and both products updated without touching their component definitions. Linear applied the same thinking to their 2024 status components. Status badge tokens pointed to semantic text colors but gave each status its own controlled token. Boolean variables in the component layer controlled visibility states for dropdown menus and modals. Number variables handled specific heights and gaps unique to each component family. These examples show the layer delivering precision at scale while the lower layers maintain consistency.

Introduce the component layer once your primitive and semantic layers pass a full audit and your components exceed fifteen in number. The layer becomes necessary the moment product requirements diverge from pure global rules. Deploy it in any system that supports dark mode brand themes or multiple product lines. The specificity prevents semantic pollution and keeps your alias chains clean. The layer excels in automated pipelines where Tokens Studio pushes changes to GitHub Actions that update code tokens in real time. Stripe ran exactly this setup in 2023 and eliminated weeks of manual sync work. Do not use the component layer before nailing the foundation layers. The structure collapses without solid primitives and semantics underneath. Avoid the layer on simple one page designs or personal projects that lack theming requirements. Never allow component tokens to reference primitives directly. That single mistake forces rebuilds when modes arrive. Enforce strict scoping so component tokens apply only to their families. Ignore these rules and your system becomes a suggestion instead of an architecture. The common mistakes of semantic to semantic aliasing and exposed primitives all compound when the component layer lacks proper governance.

Component collections belong in their own collection separate from semantics and primitives. Modes never touch the component layer. All variation happens below in semantics. This separation stops mode overrides from bleeding across concerns. Run the variable system audit with special attention to the component layer. Confirm every component token aliases to a semantic. Verify scoping limits application to the right families. Check that no raw values exist outside primitives. Systems that fail more than three audit items need full rebuilds not patches. The component layer reveals most architectural debt because it sits at the point where designers actually use the tokens.

The component layer gives teams precise control over components without turning the semantic layer into a messy catch all.