Skip to main content

Designing Best Practices

Use Consistent, Semantic Naming Conventions​

  • Follow a structured hierarchy such as: category.component.role.state

Example: color.button.primary.hover

  • Use semantic names that describe intent, not literal values.
  • Preferred: color.text.primary
  • Avoid: color.blue-500
  • Maintain stable naming conventions and update token names only when their role or intent changes.

Carbon and Material Design systems both emphasize structured, purpose-driven naming for scalability.

Keep the Global Token Set Minimal and Abstract​

  • Global tokens should define brand identity and core foundations such as:
  • Colors
  • Spacing
  • Typography
  • Radius
  • Shadows
  • Avoid embedding component-specific tokens (like button colors) at the global level.
  • Limit the total number of global tokens to only what’s necessary for cross-component reuse.

Carbon recommends clear separation of core versus component tokens to avoid bloat.

Define a Clear Token Hierarchy​

  • Establish a hierarchy such as:
    Global → Alias (Semantic) → Component → State

  • Component tokens should reference semantic tokens, not raw color or spacing values.

  • Document token inheritance so updates cascade predictably across the system.

Material Design’s token architecture encourages layered abstraction to preserve theme flexibility.

Separate Variants from States​

  • Treat variants (e.g., filled, outlined, text) as visual types.
  • Treat states (e.g., default, hover, pressed, disabled) as interaction modes.
  • Keep state styling consistent across all variants to maintain accessibility and predictability.
  • Document the difference clearly to avoid confusion during design handoffs.

Test All Changes in Preview Before Publishing​

  • Always validate token and variant changes before applying them globally.
  • Use preview or staging environments to confirm updates visually.
  • Check:
  • Light and dark theme behavior
  • Accessibility contrast ratios
  • Cross-component visual consistency

Material Design emphasizes testing in context since tokens are foundational design decisions.

Keep Figma and Style Workspace in Sync​

  • Regularly sync design tokens from Figma to the Style Workspace to prevent drift.
  • Ensure both tools reflect the same JSON schema and naming conventions.
  • Re-generate and apply outputs (CSS/JSON) after each update to maintain parity across design and code.

Document Usage and Intent for Every Token and Component​

  • Each token should specify:
  • What it controls
  • Where it’s applied
  • Its intended purpose
  • Document component variants with their respective states and platform mappings.
  • Maintain a changelog or version history to track major updates.

Carbon’s v11 migration and Material’s component documentation both model transparent evolution and change tracking.

Support Theming and Platform-Agnostic Outputs​

  • Define tokens to work across multiple platforms such as Web, Android, iOS, and Desktop.
  • Avoid hard-coded color or spacing values outside tokens.
  • Use the Style Dictionary pipeline to generate CSS, JSON, or SCSS outputs for consistent integration.

Both Carbon and Material treat tokens as the single source of truth for cross-platform theming.

Audit and Refactor Periodically​

  • Remove unused or redundant tokens regularly.
  • Validate accessibility, including contrast and focus states, during each audit.
  • Align audit cycles with release milestones to keep the design system lean and maintainable.