Role System

Semantic roles give meaning to your colors beyond their appearance. They represent the purpose and intent of colors in your design system. WebShades uses the family defintion to alias the shades to semantic roles.

How Roles Are Derived from Scales

Semantic roles are automatically assigned based on your color family and the scales generated. WebShades creates role mappings that connect specific shades to semantic purposes:

Primary colors typically use shades 500-700 for main actions and highlights
Text colors use shades 900-950 for body text, 700-800 for muted text
Surface colors use shades 50-200 for backgrounds, 300-400 for elevated surfaces
Border colors use shades 200-300 for subtle borders, 400-500 for stronger borders

Intent-Based Tokens

Text Tokens

text.faint: Very subtle text, typically shade 400-500

text.muted: Secondary text, typically shade 600-700

text.default: Primary body text, typically shade 900-950

text.strong: Emphasized text, typically shade 950

Surface Levels

surface.50: Base background

surface.100: Slightly elevated (cards, panels)

surface.200: Moderately elevated (modals, dropdowns)

surface.300: Highly elevated (tooltips, popovers)

Border Levels

border.faint: Subtle dividers, typically shade 200

border.default: Standard borders, typically shade 300-400

border.strong: Prominent borders, typically shade 500-600

Semantic Colors

success: Green family, for positive actions and states

danger: Red family, for destructive actions and errors

warning: Yellow/orange family, for cautionary states

info: Blue family, for informational messages

How Dark Mode Is Generated

WebShades automatically generates dark mode variants for all semantic roles. The dark mode generation uses inverted lightness curves:

Light mode shade 50 becomes dark mode shade 950
Light mode shade 500 stays roughly the same (mid-tone)
Light mode shade 950 becomes dark mode shade 50

This ensures that text remains readable, surfaces have proper contrast, and semantic meanings are preserved in both light and dark modes.

Scale Generation

Neutral Engine

Feedback

Unlock Exports