design systems · 2024 · 4 months · gov
Scaling a Design System with CSS Variables
Scaling a Design System with CSS Variables
Scaling a Design System with CSS Variables
50%
Fewer styling defects in QA
30%
Increased DevOps Onboarding
20%
Reduction in CSS Payload
client
government agency · USCIS
role
ops & tooling UX lead
ops & tooling
UX lead
timeline
5 months
tools
axure · figma · storybook · mural · notion
axure · figma · storybook ·
mural · notion
project overview
The agency's frontend application had been running into the same problem on every release: fragmented, redundant CSS causing frequent UI regressions, confused developers, and a maintenance backlog that was growing faster than the team could clear it. I led
a strategic effort to refactor and standardize CSS variables across
the design system, creating a shared design-development language
that unlocked faster UI updates and consistent behavior across
30+ product teams.
The agency's frontend application had been running into the same problem on every release: fragmented, redundant CSS causing frequent UI regressions, confused developers, and a maintenance backlog that was growing faster than the team could clear it. I led a strategic effort to refactor and standardize CSS variables across the design system, creating a shared design-development language that unlocked faster UI updates and consistent behavior across
30+ product teams.
The agency's frontend application had been running into the same problem on every release: fragmented, redundant CSS causing frequent UI regressions, confused developers, and a maintenance backlog that was growing faster than the team could clear it. I led
a strategic effort to refactor and standardize CSS variables across
the design system, creating a shared design-development language
that unlocked faster UI updates and consistent behavior across
30+ product teams.
the challenge
The design system lacked visual consistency and engineering efficiency because styling was hardcoded and the token system was unstructured. Technical debt kept compounding, updates kept slowing, and design and development kept drifting apart. A scalable, standardized CSS variable framework was the only thing that could keep the team shipping.
The design system lacked visual consistency and engineering efficiency because styling was hardcoded and the token system was unstructured. Technical debt kept compounding, updates kept slowing, and design and development kept drifting apart. A scalable, standardized CSS variable framework was the only thing that could keep the team shipping.
what we were up against
"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, USCIS
the challenges
Five problems the team had learned to live with.
Five problems the team had learned to live with.
05 issues
01
Fragmented CSS across 30+ product teams.
Fragmented CSS across 30+ product teams.
impact · diverging UI patterns and visual styles
impact · diverging UI patterns
and visual styles
impact · diverging UI patterns
and visual styles
02
Frequent UI regressions on every release.
Frequent UI regressions on every release.
impact · quality issues leaking into production
impact · quality issues leaking
into production
03
Rising technical debt.
Rising technical debt.
impact · slowed team velocity
04
Developer confusion caused by inconsistent patterns.
Developer confusion caused by inconsistent patterns.
impact · slowed feature delivery
05
Duplicative stylesheets across components.
Duplicative stylesheets across components.
impact · maintenance inefficiencies that compounded every sprint
impact · maintenance inefficiencies that
compounded every sprint
impact · maintenance inefficiencies
that compounded every sprint
the problem statement
"As a designer, I want to transform an inconsistent, hardcoded design system into a scalable framework using CSS variables to reduce technical debt, improve
visual consistency, and strengthen alignment between design and development."
"As a designer, I want to transform an inconsistent, hardcoded design system into a scalable framework using CSS variables to reduce technical debt, improve
visual consistency, and strengthen alignment between design and development."
the process · 03 phases
Three phases that made the system scale.
We introduced design tokens and CSS variables to centralize styling, reduce technical debt, improve consistency, and strengthen alignment between design and development without stopping the release train.
01
phase 01
Audit the existing system.
Ran workshops and audits with designers and developers to map every undocumented style, redundant value, and hardcoded override, then pressure-tested the findings with interviews.
what we found
— 85+ duplicate color values scattered across the codebase.
— 200+ hardcoded styles baked into individual components.
Ideation Workshop
02
phase 02
Create a scalable taxonomy.
The audit made one thing clear: the system didn't need more styles, it needed a shared language. I led the creation of a design token framework: primitives first, then semantics with naming conventions that mapped 1:1 between Figma and code.
how we built it
— Built the primitive token framework for core design decisions: colors, spacing, typography, effects.
— Layered a semantic token framework on top to support reusable components and UI patterns.
— Defined naming conventions that mapped 1:1 between Figma and code, so there was no translation layer between design and engineering.
— Facilitated taxonomy reviews with 30+ stakeholders to make sure every team's use case was represented.
03
phase 03
Drive implementation.
Partnered with engineers to implement the variables in code and refactor legacy components, integrated tokens into Figma libraries, and built the docs around them. Then established a scaling process so semantic variables could keep growing with the system, not outside it.
how we shipped it
— Partnered directly with engineers to implement variables in code and refactor legacy components.
— Integrated tokens into Figma libraries and wrote the usage documentation alongside them.
— Established a process to scale semantic variables across the design system for long-term maintainability.
the process · 03 phases
Three phases that made the system scale.
We introduced design tokens and CSS variables to centralize styling, reduce technical debt, improve consistency, and strengthen alignment between design and development without stopping the release train.
01
phase 01
Audit the existing system.
Ran workshops and audits with designers and developers to map every undocumented style, redundant value, and hardcoded override, then pressure-tested the findings with interviews.
what we found
— 85+ duplicate color values scattered across the codebase.
— 200+ hardcoded styles baked into individual components.
Ideation Workshop
02
phase 02
Create a scalable taxonomy.
The audit made one thing clear: the system didn't need more styles, it needed a shared language. I led the creation of a design token framework: primitives first, then semantics with naming conventions that mapped 1:1 between Figma and code.
how we built it
— Built the primitive token framework for core design decisions: colors, spacing, typography, effects.
— Layered a semantic token framework on top to support reusable components and UI patterns.
— Defined naming conventions that mapped 1:1 between Figma and code, so there was no translation layer between design and engineering.
— Facilitated taxonomy reviews with 30+ stakeholders to make sure every team's use case was represented.
03
phase 03
Drive implementation.
Partnered with engineers to implement the variables in code and refactor legacy components, integrated tokens into Figma libraries, and built the docs around them. Then established a scaling process so semantic variables could keep growing with the system, not outside it.
how we shipped it
— Partnered directly with engineers to implement variables in code and refactor legacy components.
— Integrated tokens into Figma libraries and wrote the usage documentation alongside them.
— Established a process to scale semantic variables across the design system for long-term maintainability.
the taxonomy · 12 semantic tokens
CSS variable architecture: A systematic approach for our system.
CSS variable architecture: A systematic approach for our system.
CSS variable architecture: A systematic approach for our system.
Semantic variables mapped to core design primitives, each one giving styling a meaningful context the team could actually reason about. Every color token ships with a light-mode and dark-mode value that stays in sync between Figma and code. Here is a few tokens in our system…
the taxonomy · Color semantic tokens
--default
used for · text, icons
light · #0A0A0A
dark · #DEDEDE
--primary
used for · primary actions
light · #0E5AE8
dark · #B6CFFC
--secondary
used for · secondary actions
light · #B3C4E3
dark · #DAE3F2
--accent
used for · highlights, interactive feedback
light · #79A6F2
dark · #DCE6F7
--muted
used for · subtle backgrounds
light · #F0F0F0
dark · #E8E8E8
--border
used for · borders
light · #B8B8B8
dark · #EDEEF0
--destructive
used for · error states and messages
light · #D4183D
dark · #FAB1C0
--success
used for · positive actions, completed tasks, valid states
light · #31B03A
dark · #BBF2BE
--warning
used for · non-critical errors
light · #E3C027
dark · #FAEAA5
--info
used for · non-urgent information
light · #228AE6
dark · #DCE6F7
--surface
used for · visual hierarchy and depth
light · #E0E0E0
dark · #5E5E5E
--overlay
used for · modal backdrops, scrim
light · rgba(0,0,0,0.2)
dark · #D9E7FF
SPACING tokens
--space-xs
--space-sm
--space-md
--space-lg
--space-xl
BORDER RADIUS tokens
--radius-sm
--radius-md
--radius-lg
OPACITY tokens
--opacity-overlay
--opacity-disabled
--opacity-subtle
TYPOGRAPHY tokens
--text-heading-large
--text-heading-default
--text-body-default
--text-body-small
--text-placeholder
--text-support
--text-label
the pushback · then the payoff
Addressing skepticism early built trust and accelerated adoption.
Addressing skepticism early built trust and accelerated adoption.
To address the initial skepticism, we ran workshops with cross-functional teams, did live demos on real product code, and showcased immediate wins in maintainability. Here's what we heard and what we did about it.
To address the initial skepticism, we ran workshops with cross-functional teams, did live demos on real product code, and showcased immediate wins in maintainability. Here's what we heard and what we did about it.
the pushback
"Converting everything will take forever."
"Converting everything will take forever."
developer · worried about LOE and team capacity
developer · worried about LOE and
team capacity
"Will this slow down our builds?"
"Will this slow down our builds?"
developer · questioning impact on current work
developer · questioning impact on
current work
"Great… another thing to learn."
"Great… another thing to learn."
developer · worried about complexity overhead
developer · worried about complexity
overhead
the response
Quick proof-of-concept.
Quick proof-of-concept.
Refactored one component end-to-end to show faster debugging and fewer build-related errors, then scaled the pattern from there.
Refactored one component end-to-end to show faster debugging and fewer build-related errors, then scaled the pattern from there.
Live demonstrations.
Live demonstrations.
Showed the simplicity of updating a single root CSS file and watching every component respond; no build slowdown, no hidden cost.
Showed the simplicity of updating a single root CSS file and watching every component respond; no build slowdown, no hidden cost.
CSS Variables 101 workshops.
CSS Variables 101 workshops.
Walked every team through the model and showed how variables make global updates easier, not harder. Adoption followed.
Walked every team through the model and showed how variables make global updates easier, not harder. Adoption followed.
adoption results · the numbers
Adopting CSS variables delivered clear, measurable improvements.
Adopting CSS variables delivered clear, measurable improvements.
Adopting CSS variables delivered clear, measurable improvements.
+50%
+50%
fewer styling defects
fewer styling
defects
Reduced UI inconsistencies across 30+ product teams.
Reduced UI inconsistencies across 30+ product teams.
+20%
+20%
smaller CSS payload
smaller CSS
payload
Cut custom code and the need to rebuild UI elements from scratch.
Cut custom code and the need to rebuild UI elements from scratch.
+30%
+30%
quicker dev onboarding
quicker dev
onboarding
Single source of truth replaced feature-specific UI rebuilds.
Single source of truth replaced feature-specific UI rebuilds.
100%
100%
adoption success
Complete integration across design and development teams.
Complete integration across design and development teams.
from QA · after launch
"Centralized styling with CSS variables made testing significantly better. Updates are predictable and we're no longer firefighting styling issues every release. Our QA team can focus on validating real functionality."
"Centralized styling with CSS variables made testing significantly better. Updates are predictable and we're no longer firefighting styling issues every release. Our QA team can focus on validating real functionality."
QA Lead
what it made possible
What CSS variables made possible.
What CSS variables made possible.
What CSS variables made possible.
Replacing fragmented, hardcoded values with a centralized, scalable system didn't just clean up the styling layer. It improved developer efficiency, reduced technical debt, and future-proofed the design system for whatever came next.
Replacing fragmented, hardcoded values with a centralized, scalable system didn't just clean up the styling layer. It improved developer efficiency, reduced technical debt, and future-proofed the design system for whatever came next.
01
Reduced technical debt.
Reduced technical debt.
Cut duplicated CSS significantly and stopped new duplication at the source.
Cut duplicated CSS significantly and stopped new duplication at the source.
02
Improved developer efficiency.
Improved developer efficiency.
Build quality improved and deployments became reliably predictable.
Build quality improved and deployments became reliably predictable.
03
Future-proof foundation.
Future-proof foundation.
Built a foundation that grows with business needs instead of working around them.
Built a foundation that grows with business needs instead of working around them.
04
Team confidence.
Team confidence.
A reliable source of truth that designers and developers could both trust.
A reliable source of truth that designers and developers could both trust.
annjalina.k
Senior UX/Product designer based in Maryland. Research, systems thinking, measurable outcomes.
colophon
built in framer
fraunces + inter + jetbrains mono
© 2016–2026 · all rights reserved
annjalina.k
Senior UX/Product designer based in Maryland. Research, systems thinking, measurable outcomes.
colophon
built in Framer
set in Fraunces & Inter
© 2016–2026 · all rights reserved