Scaling a Design System with CSS Variables
Scaling a Design System with CSS Variables
How we scaled the design system with CSS variables to enable consistency and long-term product growth.
50%
Fewer styling defects in QA
30%
Increased DevOps Onboarding
20%
Reduction in CSS Payload
50%
Fewer styling defects in QA
30%
Increased DevOps Onboarding
20%
Reduction in CSS Payload
CLIENT
Government Agency
Government Agency
PROJECT TYPE
Design System Enhancement
Design System Enhancement
TIMELINE
4 months
4 months
ROLE
Ops and Tooling Focus Area Lead
Ops and Tooling Focus Area Lead
DESIGN TOOLS
Figma, Storybook, Mural, Notion
Figma, Storybook, Mural, Notion
STRATEGY
Project Management
UX Strategy
Accessibility
UX Outcomes
Research
PROJECT OVERVIEW
PROJECT OVERVIEW
The Government agency’s frontend application faced ongoing issues from fragmented and redundant CSS, causing frequent regressions, confusion among developers, and maintenance bottlenecks. To improve the design system’s scalability and reduce styling bugs, I led a strategic effort to refactor and standardize CSS variables across the agency’s design system. This initiative created a shared design-development language, enabled faster UI updates, and improved consistency across 30+ product teams.
THE CHALLENGE
THE CHALLENGE
The design system lacked visual consistency and engineering efficiency due to hardcoded styles and an unstructured token system. This led to increased technical debt, slow updates, and misalignment between design and development. A scalable, standardized React CSS variable framework was needed to improve maintainability, streamline collaboration, and support long-term growth.
THE PROBLEM STATEMENT
THE PROBLEM STATEMENT
As a designer, I want to transform an inconsistent, hardcoded design system into a scaleable framework using CSS variables to reduce technical debt, improve visual consistency, and strengthen alignment between design and development.
"Every time I touch a component, I feel like I have to decipher someone else's spaghetti code."
"Every time I touch a component, I feel like I have to decipher someone else's spaghetti code."
Lead Frontend Developer
THE OUTCOME
Successful CSS Variables 101 Workshops
Result: Team-wide alignment and adoption
Design System Integration
Result: Seamless adoption path
Defined Global CSS Variables
Result: Single Source of truth
Shortened Handoff Times
Result: Quicker Delivery
Clear Documentation
Result: Self-service capability
CSS Variable Architecture: A Systematic Approach for Our Color System
Semantic variables mapped to core design primitives that gives styling meaningful context.
--default
Used for: text, icons
Light Mode
#0A0A0A
Dark Mode
#DEDEDE
--primary
Used for: primary actions
Light Mode
#1B4AA1
Dark Mode
#B6CFFC
--secondary
Used for: secondary actions
Light Mode
#B3C4E3
Dark Mode
#DAE3F2
--accent
Used for: highlights, interactive feedback
Light Mode
#79A6F2
Dark Mode
#DCE6F7
--muted
Used for: subtle backgrounds
Light Mode
#F0F0F0
Dark Mode
#E8E8E8
--border
Used for: borders
Light Mode
#B8B8B8
Dark Mode
#EDEEF0
--destructive
Used for: error states and messages
Light Mode
#D4183D
Dark Mode
#FAB1C0
--warning
Used for: non-critical errors
Light Mode
#E3C027
Dark Mode
#FAEAA5
--success
Used for: positive actions, completed tasks, and valid states
Light Mode
#29C233
Dark Mode
#BBF2BE
--info
Used for: Non-urgent information
Light Mode
#228AE6
Dark Mode
#DCE6F7
--surface
Used for: visual hierarchy and depth
Light Mode
#E0E0E0
Dark Mode
#5E5E5E
--overlay
Used for: primary actions
Light Mode
rgba(0, 0, 0, 0.2)
Dark Mode
#D9E7FF
Addressing Skepticism Early Built Trust and Accelerated Adoption
To address initial skepticism, we ran workshops with cross-functional teams, demonstrating real-world benefits, guided hands-on training, and showcased immediate improvements in maintainability.
Challenges in Gaining Buy-In
"Converting everything will take forever"
Developer worried about LOE and team capacity.
"Will this slow down our builds?"
Developer questions impact on current work
Sighs…"Great another thing to learn."
Developer worried about complexity
How We Overcame These Challenges
Live Demonstrations
Showed the simplicity of updating root CSS file.
Provided Quick Proof-of-Concept
Showed faster debugging and fewer build
related errors
Successful CSS Variables 101 Workshops
Showed how variables enables easier
global updates.
Adopting CSS variables delivered clear improvements
50%
Fewer Styling Defects
Reduced UI consistencies
across products
20%
Smaller CSS Payload
Reduced custom code and the need to build UI elements from scratch
30%
Quicker Developer Onboarding
Created Single Source of Truth, Reduced feature specific UI rebuilds
100%
Adoption Success
Complete integration across design and development teams
Having centralized styling with CSS variables has made testing significantly better. Updates are predictable and we are no longer firefighting styling issues every release. Our QA team can focus on validating real functionality.
Quality Impact
-QA Lead
What CSS Variables Made Possible
Implementing CSS variables not only transformed our styling approach for the greater by replacing fragmented, hardcoded values with a centralized and scalable system, but it also improved developer efficiency, reduced technical debt, and future-proofed the design system for future growth.
Reduced Technical Debt
Significantly reduced duplicated CSS.
Improved Developer Efficiency
Improved build quality and made deployments
more reliable.
Future Proof Foundation
Created a scalable foundation that grows with the business needs.
Team Confidence
Created a reliable source of truth for designers and developers.
THE PROCESS: Our Three Phased Strategy That Shaped Success
We implemented CSS variables to centralize styling, reduce technical debt, improve consistency, scale the design system, and strengthen design-development alignment.
Audit the Existing
System
Conducted workshops and audits to identify undocumented styles, redundant values and hard coded overrides.
Validated pain points through interviews with developers and designers.
What We Found
85+ duplicate color values
200+ hardcoded styles across components
Create Scalable Taxonomy
Led the creation of the CSS variable framework for core design primitives (colors, spacing, typography, and effects)
Led the creation of the CSS semantic variable framework to support reusable components and UI patterns.
Defined naming conventions that mapped 1:1 between Figma and code.
Facilitated taxonomy reviews with 30+ stakeholders for cross-team alignment
Drive
Implementation
Partnered with engineers to implement the variables in code and refactor legacy components
Integrated tokens into Figma libraries and developed documentation for usage.
Established a process to scale semantic variables across the design system for long-term maintainability and consistency.
CHALLENGES
Duplicative Stylesheets Across Components
Impact: Maintenance inefficiencies
Rising UX and technical debt
Impact: Slowed team velocity
Developer Confusion With Inconsistent Patterns
Impact: Slowed feature delivery
Fragmented CSS across 30+ product teams
Impact: Diversion of UI patterns and visual styles
Frequent UI Regressions
Impact: Increased quality issues in production
CHALLENGES
Fragmented CSS across 30+ product teams
Impact: Diversion of UI patterns and visual styles
Frequent UI Regressions
Impact: Increased quality issues in production
Rising Technical Debt
Impact: Slowed team velocity
Developer Confusion Caused by Inconsistent Patterns
Impact: Slowed feature delivery
Duplicative Stylesheets Across Components
Impact: Maintenance inefficiencies
Rising UX and technical debt
Impact: Slowed team velocity
Developer Confusion Caused by Inconsistent Patterns
Impact: Slowed feature delivery
THE PROCESS: Our Three Phased Strategy That Shaped Success
We implemented design tokens and CSS variables to centralize styling, reduce technical debt, improve consistency, scale the design system, and strengthen design-development alignment.
Audit the Existing
System
Conducted workshops and audits to identify undocumented styles, redundant values and hard coded overrides.
Validated pain points through interviews with developers and designers.
What We Found
200+ hardcoded styles across components
85+ duplicate color values
85+ duplicate color values
200+ hardcoded styles across components
Conducted workshops and audits to identify undocumented styles, redundant values and hard coded overrides.
Validated pain points through interviews with developers and designers.
What We Found
What We Found
Create Scalable
Taxonomy
Led the creation of the design token framework for core design primitives (colors, spacing, typography, and effects)
Led the creation of the semantic design token framework to support reusable components and UI patterns.
Defined naming conventions that mapped 1:1 between Figma and code.
Facilitated taxonomy reviews with 30+ stakeholders for cross-team alignment
Led the creation of the CSS variable framework for core design primitives (colors, spacing, typography, and effects)
Defined naming conventions that mapped 1:1 between Figma and code.
Led the creation of the CSS semantic variable framework to support reusable components and UI patterns.
Facilitated taxonomy reviews with 30+ stakeholders for cross-team alignment
Drive
Implementation
Partnered with engineers to implement the variables in code and refactor legacy components
Integrated tokens into Figma libraries and developed documentation for usage.
Established a process to scale semantic variables across the design system for long-term maintainability and consistency.
Drive
Implementation
Partnered with engineers to implement the variables in code and refactor legacy components
Integrated tokens into Figma libraries and developed documentation for usage.
Established a process to scale semantic variables across the design system for long-term maintainability and consistency.
THE OUTCOME
Successful CSS Variables 101 Workshops
Result: Team-wide alignment and adoption
Defined Global CSS Variables
Result: Single Source of truth
Design System Integration
Result: Seamless adoption path
Design System Integration
Result: Seamless adoption path
Defined Global CSS Variables
Result: Single Source of truth
Shortened Handoff Times
Result: Quicker Delivery
Clear Documentation
Result: Self-service capability
Clear Documentation
Result: Self-service capability
CSS Variable Architecture: A Systematic Approach for Our Color System
Semantic variables mapped to core design primitives that gives styling meaningful context.
--default
Used for: text, icons
Light Mode
#0A0A0A
Dark Mode
#DEDEDE
--primary
Used for: primary actions
Light Mode
#0E5AE8
Dark Mode
#B6CFFC
--secondary
Used for: secondary actions
Light Mode
#B3C4E3
Dark Mode
#DAE3F2
--accent
Used for: highlights, interactive feedback
Light Mode
#79A6F2
Dark Mode
#DCE6F7
--muted
Used for: subtle backgrounds
Light Mode
#F0F0F0
Dark Mode
#E8E8E8
--border
Used for: borders
Light Mode
#B8B8B8
Dark Mode
#EDEEF0
--destructive
Used for: error states and messages
Light Mode
#D4183D
Dark Mode
#FAB1C0
--success
Used for: positive actions, completed tasks, and valid states
Light Mode
#31B03A
Dark Mode
#BBF2BE
--warning
Used for: non-critical errors
Light Mode
#E3C027
Dark Mode
#FAEAA5
--info
Used for: Non-urgent information
Light Mode
#228AE6
Dark Mode
#DCE6F7
--surface
Used for: visual hierarchy and depth
Light Mode
#E0E0E0
Dark Mode
#5E5E5E
--overlay
Used for: primary actions
Light Mode
rgba(0, 0, 0, 0.2)
Dark Mode
#D9E7FF
Addressing Skepticism Early Built Trust and Accelerated Adoption
To address initial skepticism, we ran workshops with cross-functional teams, demonstrating real-world benefits, guided hands-on training, and showcased immediate improvements in maintainability.
Challenges in Gaining Buy-In
"Converting everything will take forever"
Developer worried about LOE and team capacity.
"Converting everything will take forever"
Developer worried about LOE and team capacity.
"Will this slow down our builds?"
Developer questions impact on current work
"Will this slow down our builds?"
Developer questions impact on current work
Sighs…"Great another thing to learn."
Developer worried about complexity
Sighs…"Great another thing to learn."
Developer worried about complexity
How We Overcame These Challenges
Live Demonstrations
Showed the simplicity of updating root CSS file.
Provided Quick Proof-of-Concept
Showed faster debugging and fewer build related errors
Successful CSS Variables 101 Workshops
Showed how variables enables easier global updates.
How We Overcame These Challenges
Live Demonstrations
Showed the simplicity of updating root CSS file.
Provided Quick Proof-of-Concept
Showed faster debugging and fewer build related errors
Successful CSS Variables 101 Workshops
Showed how variables enables easier global updates.
Adopting CSS variables delivered clear improvements
50%
Fewer Styling Defects
Reduced UI consistencies
across products
20%
Smaller CSS Payload
Reduced custom code and the need to
build UI elements from scratch
30%
Quicker Developer Onboarding
Created Single Source of Truth,
Reduced feature specific UI rebuilds
100%
Adoption Success
Complete integration across design
and development teams
50%
Fewer Styling Defects
Reduced UI consistencies
across products
20%
Smaller CSS Payload
Reduced custom code and the need to
build UI elements from scratch
30%
Quicker Developer Onboarding
Created Single Source of Truth,
Reduced feature specific UI rebuilds
100%
Adoption Success
Complete integration across design
and development teams
Having centralized styling with CSS variables has made testing significantly better. Updates are predictable and we are no longer firefighting styling issues every release. Our QA team can focus on validating real functionality.
Quality Impact
-QA Lead
Quality Impact
Having centralized styling with CSS variables has made testing significantly better. Updates are predictable and we are no longer firefighting styling issues every release. Our QA team can focus on validating real functionality.
-QA Lead
What CSS Variables Made Possible
Implementing CSS variables not only transformed our styling approach for the greater by replacing fragmented, hardcoded values with a centralized and scalable system, but it also improved developer efficiency, reduced technical debt, and future-proofed the design system for future growth.
Reduced Technical Debt
Significantly reduced duplicated CSS.
Improved Developer Efficiency
Improved build quality and made deployments more reliable.
Future Proof Foundation
Created a foundation that grows with the business needs.
Team Confidence
Created a reliable source of truth for designers and developers.
Quicker Developer Onboarding
Created Single Source of Truth,
Reduced feature specific UI rebuilds