playbooks

home / skills / harborgrid-justin / lexiflow-premium / design-system-token-architecture

design-system-token-architecture skill

/frontend/.github-skills/design-system-token-architecture

This skill helps architect scalable design token propagation using React Context and CSS-in-JS, enabling dynamic theming and efficient token updates.

npx playbooks add skill harborgrid-justin/lexiflow-premium --skill design-system-token-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
824 B
---
name: design-system-token-architecture
description: Architect scalable design token propagation using React Context and CSS-in-JS/Variables.
---

# Design System Token Architecture

## Summary
Architect scalable design token propagation using React Context and CSS-in-JS/Variables.

## Key Capabilities
- Define semantic token layers (Primitive vs. Component).
- Implement dynamic theming with runtime token switching.
- Optimization re-renders when swapping global themes.

## PhD-Level Challenges
- Manage type-safety for deeply nested token schemas.
- Analyze the performance cost of CSS generation at runtime.
- Synchronize token updates across micro-frontends.

## Acceptance Criteria
- Demonstrate a multi-theme switching capability.
- Provide a token schema definition file.
- Benchmark theme switch render cost.

Overview

This skill architects a scalable design token propagation strategy for React apps using Context plus CSS-in-JS and CSS variables. It focuses on clear token layering (primitive vs component), runtime theme switching, and minimizing re-renders during global theme updates. The goal is a predictable, type-safe token system suitable for single apps and micro-frontends.

How this skill works

The skill defines a token schema and separates primitive tokens (colors, spacing, type) from component-level tokens derived from them. A ThemeProvider exposes tokens via React Context and also writes CSS variables to a top-level element so CSS-in-JS and plain styles can consume them. It includes runtime theme switching that updates Context values and CSS variables with minimal React re-renders, plus tools to benchmark rendering cost.

When to use it

  • Building a component library that must support multiple themes at runtime
  • Needing consistent tokens across React components and legacy CSS
  • Sharing design tokens between micro-frontends without full framework coupling
  • Optimizing theme switches to avoid unnecessary React re-renders
  • Enforcing a single source of truth for visual styles across apps

Best practices

  • Keep primitive tokens minimal and explicit (colors, spacing, type) and derive component tokens from them
  • Use a typed token schema (TypeScript interfaces) to ensure deep type-safety across nested token shapes
  • Write CSS variables for the primitives at root so both CSS-in-JS and classic styles read the same values
  • Batch Context updates and limit subscribed components to reduce re-render surface during theme changes
  • Measure runtime CSS generation cost and prefer precomputed variants when switching themes frequently

Example use cases

  • A multi-tenant SaaS that offers branded themes per customer and needs instant clientside switching
  • A design system that must be consumed by React apps and legacy pages simultaneously
  • A micro-frontend architecture where each sub-app reads the same token set via CSS variables
  • Performance audits where theme switch render time must be benchmarked and optimized

FAQ

Can this work without CSS-in-JS?

Yes. The approach writes CSS variables to a root element so plain CSS or preprocessor outputs read the same tokens.

How do you avoid excessive re-renders on theme switch?

Limit Context consumers, memoize derived tokens, and update CSS variables directly for style-only changes to avoid React tree updates.