Frontend System Design · Lesson 71 of 86 · 4 min
Theming and Customization in Design Systems
This topic tests your ability to balance consistency and flexibility, a core trade-off in any scalable system.
After this lesson, you'll be able to articulate a clear strategy for theming a component library, defend your choice of technology, and explain how to handle common requirements like dark mode and white-labeling.
Choose Your Theming Strategy
You have two modern options: CSS custom properties (variables) or CSS-in-JS.
CSS variables are the baseline. They are native to the browser, have zero runtime cost, and work with any framework. You define your theme on a root element, and components consume them with var(). Switching themes is as simple as changing a data-theme attribute on a parent element.
CSS-in-JS libraries like Emotion or Styled Components use JavaScript objects for themes, passed down via React Context. This gives you the full power of JavaScript to create dynamic or computed styles. For example, you can generate a 10-step color palette from a single base color.
This power comes at a cost: increased bundle size, runtime overhead to serialize styles, and framework lock-in.
In an interview, frame this as a trade-off. Start with CSS variables for their performance and simplicity. Argue that you'd only introduce a CSS-in-JS theming solution if the design requirements call for complex, programmatic style logic that CSS cannot handle alone. A great answer suggests combining them: use a CSS-in-JS
ThemeProviderto set CSS variables on a component's root node, getting the best of both worlds.
Structure Your Theme with Design Tokens
A theme is a contract. It's a collection of design decisions, called "tokens," that your components will consume. Don't just invent them as you go; define them upfront.
Your theme object or list of CSS variables should cover these categories:
- Colors: Backgrounds, text, borders, interactive states (hover, focus).
- Typography: Font families, sizes, weights, line heights.
- Spacing: A scale for margins, padding, and gaps (e.g., 4px, 8px, 16px).
- Sizing: Consistent heights and widths for elements like inputs.
- Shadows, border radii, z-indices.
The trap: Using literal names for tokens. A token named --brand-blue is a problem when you need to support a second brand whose primary color is green. Name tokens by their role, not their value. Use --color-interactive-default or --background-surface-primary. This decouples the token's purpose from its specific implementation in any given theme.
Apply the Theme with CSS Variables
This is the most direct and debuggable way to implement theming. You define a default set of variables, typically under :root, and then override them for different themes using an attribute selector.
The JavaScript to switch themes is trivial: document.body.setAttribute('data-theme', 'dark').
/* Define the contract and the default (light) theme */
:root {
--color-background: #ffffff;
--color-text-primary: #1a1a1a;
--color-interactive: #007bff;
--spacing-md: 16px;
--border-radius-default: 4px;
}
/* Define the dark theme overrides */
[data-theme='dark'] {
--color-background: #1a1a1a;
--color-text-primary: #f0f0f0;
--color-interactive: #61dafb;
}
/* A component consuming the tokens */
.button {
background-color: var(--color-interactive);
color: var(--color-background); /* Note: color choice depends on contrast */
padding: 8px var(--spacing-md);
border-radius: var(--border-radius-default);
border: none;
cursor: pointer;
}
This approach also plays nicely with user preferences. You can use the prefers-color-scheme media query to set the default theme without any JavaScript at all.
Provide Controlled Customization
Theming provides consistency. Customization provides flexibility. Your job is to offer just enough flexibility without letting consumers break the system's integrity.
Styles should be applied in a clear order of precedence. This is the hierarchy you should enforce:
The best way to provide customization is through a limited set of props. A <Button> component shouldn't have props for color, backgroundColor, and padding. It should have props for variant (primary, destructive) and size (small, medium). These props map to a pre-approved set of styles that align with the design system.
For true one-off situations, provide an escape hatch like a style prop or, in CSS-in-JS, a css prop. This signals that the developer is intentionally deviating from the design system and taking responsibility for the result. Make the right thing easy, and the exceptional thing possible but explicit.
Answer the "White-Labeling" Question
A common interview prompt is: "How would you design a system to support multiple brands on the same page?" This is a test of your understanding of style scoping.
The CSS variables approach handles this well. Instead of applying data-theme to the <body>, you apply it to the root container of each branded section.
<div data-theme="brand-a">
<!-- All components inside here get Brand A's theme -->
<Button>Click me</Button>
</div>
<div data-theme="brand-b">
<!-- All components inside here get Brand B's theme -->
<Button>Click me</Button>
</div>
Because CSS variables are inherited and scoped to the DOM tree, the styles apply only within their respective containers. This is difficult to achieve with build-time tools like Sass and can be complex to manage with global ThemeProvider components from CSS-in-JS libraries. Being able to explain this specific pattern demonstrates a deep understanding of CSS architecture.
Try it
Take a component you've built for a personal project. Refactor it to use CSS variables for all hardcoded color, font-size, and spacing values. Define these variables in a :root selector. Then, add a [data-theme='dark'] rule that overrides the color variables to test your implementation.
Next: We'll cover how to build these systems inclusively in Accessibility in Component Libraries.
Lock it in — apply this lesson under interview conditions.