WCAG 2.1 AA compliant ⁕ Automatic theme switching
WCAG 2.1 AA compliant ⁕ Automatic theme switching
WCAG 2.1 AA compliant ⁕ Automatic theme switching
Contrast
Contrast
Light
Light
SIGN SYSTEM
SIGN SYSTEM
SIGN SYSTEM
SIGN SYSTEM
4-LAYER D
4-LAYER D
4-LAYER D
4-LAYER D
E
E
E
E
Company
Company
FreeDi
FreeDi
Timeline
Timeline
June 2024
June 2024
My Role
My Role
UX/UI Designer
UX/UI Designer
Duration
Duration
2 week foundation sprint → 6 months iterative refinement
2 week foundation sprint → 6 months iterative refinement
Platform
Platform
Web Application (Responsive)
Web Application (Responsive)
The Challenge: Can Three People Build Like Thirty?
The Challenge: Can Three People Build Like Thirty?
The Challenge: Can Three People Build Like Thirty?
The Challenge: Can Three People Build Like Thirty?
Small teams hit a wall: you can move fast OR maintain quality, but rarely both.
As Delib.org's solo designer with 2 developers, I was becoming the bottleneck.
I was answering 20+ questions daily while trying to design features.
I had two choices: Become a full-time spec machine, or build infrastructure that made the team self-sufficient.
I chose infrastructure - and had one week to prove it would work.
The requirements:
Accessibility: WCAG AA compliance - Light and Contrast themes mandatory
Responsive: 4 breakpoints (1920px to 390px) systematically
Efficiency: Developers must build independently
Scalability: Foundation that grows with the product
Small teams hit a wall: you can move fast OR maintain quality, but rarely both.
As Delib.org's solo designer with 2 developers, I was becoming the bottleneck.
I was answering 20+ questions daily while trying to design features.
I had two choices: Become a full-time spec machine, or build infrastructure that made the team self-sufficient.
I chose infrastructure - and had one week to prove it would work.
The requirements:
Accessibility: WCAG AA compliance - Light and Contrast themes mandatory
Responsive: 4 breakpoints (1920px to 390px) systematically
Efficiency: Developers must build independently
Scalability: Foundation that grows with the product
Systematic Responsive Adaptation
Systematic Responsive Adaptation
Systematic Responsive Adaptation
4 breakpoints • Automatic token scaling
4 breakpoints • Automatic token scaling
Desktop XL
1920px+
Desktop
1440px
Tablet
1024px
Mobile
390px
4 breakpoints • Automatic token scaling
239
Design Tokens
100%
WCAG AA Compliant
2
Themes
Solution: Build the Foundation First
Solution: Build the Foundation First
Solution: Build the Foundation First
I proposed spending one week building a design system before designing features.
This was a risk—features would be delayed—but the math was clear: upfront investment would save hours per feature long-term.
The business case:
• Eliminate repetitive decisions
• Automate accessibility compliance
• Enable developer self-service
• Prevent design debt before it accumulates
The solution:
A 239-token system organized in four levels, change one value at the top → everything below updates automatically.
Here's the structure:
Level 1 - Brand: Raw values (#4276BB, 16px) - the basic building blocks
Level 2 - Alias: Named references (color-primary-500) - semantic colors
Level 3 - Mapped: Semantic meaning (action-default, text-primary) - this is where themes switch
Level 4 - Components: UI elements (button-primary-bg) - the actual interface parts
The key insight:
Theme switching happens at Level 3 (Mapped). Everything below stays the same.
This means developers can't accidentally break accessibility - the architecture won't let them.
I proposed spending one week building a design system before designing features.
This was a risk—features would be delayed—but the math was clear: upfront investment would save hours per feature long-term.
The business case:
• Eliminate repetitive decisions
• Automate accessibility compliance
• Enable developer self-service
• Prevent design debt before it accumulates
The solution:
A 239-token system organized in four levels, change one value at the top → everything below updates automatically.
Here's the structure:
Level 1 - Brand: Raw values (#4276BB, 16px) - the basic building blocks
Level 2 - Alias: Named references (color-primary-500) - semantic colors
Level 3 - Mapped: Semantic meaning (action-default, text-primary) - this is where themes switch
Level 4 - Components: UI elements (button-primary-bg) - the actual interface parts
The key insight:
Theme switching happens at Level 3 (Mapped). Everything below stays the same.
This means developers can't accidentally break accessibility - the architecture won't let them.
Level 1: Brand
Raw values — the basic building blocks
4276BB
426742
D63C3C
1A1A2C
Level 2: Alias
Named references — semantic blocks
color-primary-500
color-success-600
color-error-500
color-neutral-900
Level 3: Mapped
Semantic meaning — where theme switching happens
action-default
success-text
error-default
text-primary
Level 4: Components
UI elements — the actual interface parts
button-primary-bg
alert-success-text
snackbar-urgent
card-heading-text
Level 1: Brand
Raw values — the basic building blocks
4276BB
426742
D63C3C
1A1A2C
Level 2: Alias
Named references — semantic blocks
color-primary-500
color-success-600
color-error-500
color-neutral-900
Level 3: Mapped
Semantic meaning — where theme switching happens
action-default
success-text
error-default
text-primary
Level 4: Components
UI elements — the actual interface parts
button-primary-bg
alert-success-text
snackbar-urgent
card-heading-text
Level 1: Brand
Raw values — the basic building blocks
4276BB
426742
D63C3C
1A1A2C
Level 2: Alias
Named references — semantic blocks
color-primary-500
color-success-600
color-error-500
color-neutral-900
Level 3: Mapped
Semantic meaning — where theme switching happens
action-default
success-text
error-default
text-primary
Level 4: Components
UI elements — the actual interface parts
button-primary-bg
alert-success-text
snackbar-urgent
card-heading-text
Token Architecture: Four Levels
Token Architecture: Four Levels
Token Architecture: Four Levels
Four-level token architecture where theme switching happens at the Mapped layer.
The Design System
The Design System
The Design System
Color System: Accessibility by Design
I built the color system with accessibility as a foundational requirement, not an afterthought.
Every text color was validated against WCAG AA standards (4.5:1 minimum contrast) before it became a token.
The structure:
9 color families: Red, Orange, Yellow, Green, Blue, Blue-dark, Purple, Pink, Grey
11 shades per family: 50 (lightest) to 950 (darkest)
2 themes: Light + Contrast (enhanced for visual impairments)
Systematic validation: Text tokens use 600+ shades, lighter shades reserved for backgrounds
Validated contrast ratios on white backgrounds:
Primary text (Neutral/900): 15.2:1 WCAG AAA
Secondary text (Neutral/800): 11.62:1 WCAG AAA
Interactive elements (Primary/700): 8.32:1 WCAG AA
Success states (Success/700): 6.46:1 WCAG AA
Error states (Error/500): 4.59:1 WCAG AA
Warning states (Warning/700): 6.55:1 WCAG AA
How it works: The Mapped token layer (text-primary, text-secondary, action, success, error) references pre-validated shades from the Alias layer.
Developers select semantic tokens like "action" or "error" - accessibility is guaranteed.
They can't accidentally create inaccessible combinations because the architecture prevents it.
I built the color system with accessibility as a foundational requirement, not an afterthought.
Every text color was validated against WCAG AA standards (4.5:1 minimum contrast) before it became a token.
The structure:
9 color families: Red, Orange, Yellow, Green, Blue, Blue-dark, Purple, Pink, Grey
11 shades per family: 50 (lightest) to 950 (darkest)
2 themes: Light + Contrast (enhanced for visual impairments)
Systematic validation: Text tokens use 600+ shades, lighter shades reserved for backgrounds
Validated contrast ratios on white backgrounds:
Primary text (Neutral/900): 15.2:1 WCAG AAA
Secondary text (Neutral/800): 11.62:1 WCAG AAA
Interactive elements (Primary/700): 8.32:1 WCAG AA
Success states (Success/700): 6.46:1 WCAG AA
Error states (Error/500): 4.59:1 WCAG AA
Warning states (Warning/700): 6.55:1 WCAG AA
How it works: The Mapped token layer (text-primary, text-secondary, action, success, error) references pre-validated shades from the Alias layer.
Developers select semantic tokens like "action" or "error" - accessibility is guaranteed.
They can't accidentally create inaccessible combinations because the architecture prevents it.
Light theme
Text/primary
Neutral/900 • #1A1A2C
Body text, headlines
15.2:1 WCAG AAA ✓
Contrast theme
Text/primary
Neutral/900 • #1B1B1F
Body text, headlines
17.16:1 WCAG AAA ✓
Light theme
Secondary Text
Neutral/800 • #2E2E4A
Supporting text, labels
11.62:1 WCAG AAA ✓
Contrast theme
Secondary Text
Neutral/900 • #303036
Supporting text, labels
18.27:1 WCAG AAA ✓
Light theme
Action / Links
Primary/600 • #365F97
Interactive elements
5.76:1 WCAG AAA ✓
Contrast theme
Action / Links
Primary/600 • #012FB6
Interactive elements
10.07:1 WCAG AAA ✓
Light theme
Success States
Success/700 • #426742
Success messages, confirmations
6.46:1 WCAG AAA ✓
Contrast theme
Success States
Success/700 • #1D6D1D
Success messages, confirmations
6.44:1 WCAG AAA ✓
Light theme
Error States
Error/500 • #D63C3C
Error messages, destructive actions
4.59:1 WCAG AA ✓
Contrast theme
Error States
Error/700 • #990000
Error messages, destructive actions
8.91:1 WCAG AA ✓
Light theme
Warning States
Warning/700 • #994500
Warnings, caution messages
6.55:1 WCAG AA ✓
Contrast theme
Warning States
Warning/700 • #993A00
Warnings, caution messages
7.09:1 WCAG AA ✓
Type Style
Desktop XL
Desktop
Tablet
Mobile
1920px+
1440px
1024px
390px
H1
Aa
76px
Aa
76px
Aa
56px
Aa
36px
H2
Aa
60px
Aa
60px
Aa
48px
Aa
32px
H3
Aa
48px
Aa
48px
Aa
40px
Aa
28px
H4
Aa
36px
Aa
36px
Aa
32px
Aa
26px
Body Large
The quick brown fox
20px
The quick brown fox
20px
The quick brown fox
20px
The quick brown fox
20px
Body Medium
The quick brown fox
16px
The quick brown fox
16px
The quick brown fox
16px
The quick brown fox
16px
Body Small
The quick brown fox
14px
The quick brown fox
14px
The quick brown fox
14px
The quick brown fox
14px
Type Style
Desktop XL
Desktop
Tablet
Mobile
1920px+
1440px
1024px
390px
H1
Aa
76px
Aa
76px
Aa
56px
Aa
36px
H2
Aa
60px
Aa
60px
Aa
48px
Aa
32px
H3
Aa
48px
Aa
48px
Aa
40px
Aa
28px
H4
Aa
36px
Aa
36px
Aa
32px
Aa
26px
Body Large
The quick brown fox
20px
The quick brown fox
20px
The quick brown fox
20px
The quick brown fox
20px
Body Medium
The quick brown fox
16px
The quick brown fox
16px
The quick brown fox
16px
The quick brown fox
16px
Body Small
The quick brown fox
14px
The quick brown fox
14px
The quick brown fox
14px
The quick brown fox
14px
Type Style
Desktop XL
Desktop
Tablet
Mobile
1920px+
1440px
1024px
390px
H1
Aa
76px
Aa
76px
Aa
56px
Aa
36px
H2
Aa
60px
Aa
60px
Aa
48px
Aa
32px
H3
Aa
48px
Aa
48px
Aa
40px
Aa
28px
H4
Aa
36px
Aa
36px
Aa
32px
Aa
26px
Body Large
The quick brown fox
20px
The quick brown fox
20px
The quick brown fox
20px
The quick brown fox
20px
Body Medium
The quick brown fox
16px
The quick brown fox
16px
The quick brown fox
16px
The quick brown fox
16px
Body Small
The quick brown fox
14px
The quick brown fox
14px
The quick brown fox
14px
The quick brown fox
14px
Typography Scale: Systematic Responsive Adaptation
Developers reference typography tokens → responsive behavior automatic
Developers reference typography tokens → responsive behavior automatic
Radius scale
2
4
8
12
16
20
24
96
Spacing scale
2
2
4
+2
8
+4
12
+4
16
+4
20
+4
24
+4
28
+4
32
+4
36
+4
99
Full
Radius scale
2
4
8
12
16
20
24
96
Spacing scale
2
2
4
+2
8
+4
12
+4
16
+4
20
+4
24
+4
28
+4
32
+4
36
+4
99
Full
Radius scale
2
4
8
12
16
20
24
96
Spacing scale
2
2
4
+2
8
+4
12
+4
16
+4
20
+4
24
+4
28
+4
32
+4
36
+4
99
Full
Spacing: Consistent Rhythm
Every spacing decision comes from the scale - no arbitrary values.
Used consistently for padding, margins, gaps, and border radius.
This creates visual rhythm automatically.
Click here
Button • Default State background
Click here
Button • Action-hovered background
Click here
Button • Action-focused border
Click here
Button • Action-selected background
Click here
Button • Action-disable background
Small
40px
Medium
48px
Large
56px
Default State
Primary/400 • #4276BB
4.62:1 WCAG AA ✓
Action-hover
Primary/400 • #518FE2
4.11:1 WCAG AA ✓
Action-focused
Primary/900 • #0C1C31
15.22:1 WCAG AA ✓
Action-selected
Primary/600 • #365F97
6.48:1 WCAG AA ✓
Action-disabled
Neutral/200 • #C1C1D7
7.55:1 WCAG AA ✓
Text-on-action
Neutral/white • #FFFFFF
4.62:1 WCAG AA ✓
Click here
Default State background
Click here
Default State background
Click here
Action-hover background
Click here
Action-selected background
Click here
Action-disable background
Small
40px
Medium
48px
Large
56px
Default State
Primary/400 • #4276BB
4.62:1 WCAG AA ✓
Action-hover
Primary/400 • #518FE2
4.11:1 WCAG AA ✓
Action-focused
Primary/900 • #0C1C31
15.22:1 WCAG AA ✓
Action-selected
Primary/600 • #365F97
6.48:1 WCAG AA ✓
Action-disabled
Neutral/200 • #C1C1D7
7.55:1 WCAG AA ✓
Text-on-action
Neutral/white • #FFFFFF
4.62:1 WCAG AA ✓
Click here
Button • Default State background
Click here
Button • Action-hovered background
Click here
Button • Action-focused border
Click here
Button • Action-selected background
Click here
Button • Action-disable background
Small
40px
Medium
48px
Large
56px
Default State
Primary/400 • #4276BB
4.62:1 WCAG AA ✓
Action-hover
Primary/400 • #518FE2
4.11:1 WCAG AA ✓
Action-focused
Primary/900 • #0C1C31
15.22:1 WCAG AA ✓
Action-selected
Primary/600 • #365F97
6.48:1 WCAG AA ✓
Action-disabled
Neutral/200 • #C1C1D7
7.55:1 WCAG AA ✓
Text-on-action
Neutral/white • #FFFFFF
4.62:1 WCAG AA ✓
Components: Accessible by Default
Components defined with mapped tokens → accessibility automatic
Quality Achieved:
• All text meets WCAG AA contrast standards (4.5:1 minimum)
• Keyboard users can navigate all interactive elements with visible focus indicators
• Design consistency maintained across typography, spacing, and colors
• Both themes stay accessible automatically—no manual compliance checks needed
Components defined with mapped tokens → accessibility automatic
Quality Achieved:
• All text meets WCAG AA contrast standards (4.5:1 minimum)
• Keyboard users can navigate all interactive elements with visible focus indicators
• Design consistency maintained across typography, spacing, and colors
• Both themes stay accessible automatically—no manual compliance checks needed
Responsive: Systematic Adaptation
Tokens auto-adapt. Developers select tokens, responsive behavior is handled systematically.
Tokens auto-adapt. Developers select tokens, responsive behavior is handled systematically.
Implementation
Implementation
Implementation
Theme switching Zero manual work
Light theme
text-primary: Neutral/900 (#1A1A2C)
text-primary: Neutral/900 (#1A1A2C)
text-secondary: Neutral/800 (#2E2E4A)
text-secondary: Neutral/800 (#2E2E4A)
header-question: Blue/500 (#037CC1)
header-question: Blue/500 (#037CC1)
suggestion-added: Yellow/500 (#FED62F)
suggestion-added: Yellow/500 (#FED62F)
All ratios: WCAG AA compliant
Contrast theme
text-primary: Neutral/900 (#1B1B1F)
text-primary: Neutral/900 (#1B1B1F)
text-secondary: Neutral/800 (#303036)
text-secondary: Neutral/800 (#303036)
header-question: Blue/500 (#005E85)
header-question: Blue/500 (#005E85)
suggestion-added: Yellow/500 (#FCC00D)
suggestion-added: Yellow/500 (#FCC00D)
All ratios: WCAG AA compliant
Clusters
Clusters
Node cards and UI elements use design system tokens for consistency.
Node cards and UI elements use design system tokens for consistency.
Consensus maps with multiple view modes
Color-coded zones maintain token consistency.
Color-coded zones maintain token consistency.
Voting results with bar charts
Interactive voting with bar charts use semantic tokens for automatic accessibility
Interactive voting with bar charts use semantic tokens for automatic accessibility
Real-time polarization tracking
Real-time polarization tracking
Scatter plots and tooltips using mapped tokens for data visualization.
Scatter plots and tooltips using mapped tokens for data visualization.
Features Built with the System Contrast theme
Features Built with the System Contrast theme
Features Built with the System Contrast theme
Features Built with the System Contrast theme
Results & Impact
Results & Impact
Results & Impact
Results & Impact
The token architecture transformed how our 3-person team builds—enabling systematic quality and developer independence.
The token architecture transformed how our 3-person team builds—enabling systematic quality and developer independence.
System Built:
• 239 tokens across 4 architectural levels
• 2 accessible themes (Light + Contrast)
• 4 responsive breakpoints handled systematically
• 20+ features using the system
Quality Achieved:
• 100% WCAG AA compliance—all text meets 4.5:1 minimum contrast
• Consistent spacing, typography, and colors across all interfaces
• Theme switching maintains compliance automatically
Developer Experience:
• Developers select semantic tokens—accessibility guaranteed by architecture
• Theme switching requires zero manual accessibility checks
• Responsive behavior handled systematically through tokens
• System prevents violations rather than catching them
• Developers select semantic tokens—accessibility guaranteed by architecture
• Theme switching requires zero manual accessibility checks
• Responsive behavior handled systematically through tokens
• System prevents violations rather than catching them
Outcome:
Small teams need smart systems.
By building accessibility and consistency into the token architecture, we achieved enterprise-level quality with 3 people—proving you don't need more headcount, you need better infrastructure.
Key Learning
Key Learning
Key Learning
Small teams need smart systems
Small teams need smart systems
Design systems are force multipliers when you're lean. We achieved enterprise-level quality with 3 people.
Design systems are force multipliers when you're lean. We achieved enterprise-level quality with 3 people.
Automation beats documentation
Automation beats documentation
Pre-validated tokens eliminate manual checking and human error. Good systems make correct implementation easier than incorrect.
Pre-validated tokens eliminate manual checking and human error. Good systems make correct implementation easier than incorrect.
Prevention beats correction
Prevention beats correction
Building accessibility into the foundation is 10x easier than retrofitting. We saved 80+ hours by making violations architecturally impossible.
Building accessibility into the foundation is 10x easier than retrofitting. We saved 80+ hours by making violations architecturally impossible.
Technical Specifications
Technical Specifications
Technical Specifications
Technical Specifications
Token Count: 239
Architecture: Brand → Alias → Mapped → Components
Color Tokens: 90+ across Light + Contrast themes
Spacing Scale: 19 tokens (0-88px)
Typography Tokens: 30+ with responsive scaling
Radius Tokens: 14 options (0-96px)
Token Count: 239
Architecture: Brand → Alias → Mapped → Components
Color Tokens: 90+ across Light + Contrast themes
Spacing Scale: 19 tokens (0-88px)
Typography Tokens: 30+ with responsive scaling
Radius Tokens: 14 options (0-96px)
Other projects
Full detailed view available on desktop