Read more

Icons are everywhere, yet they’re probably the easiest thing in your design system to screw up. I’ve seen so many <Icon> components that overcomplicate the DOM while doing nothing to make accessibility easier to achieve.

If your <Icon> component wraps your <svg> element in a <div>- especially if that <div> has no classes- you’re already headed down the wrong path.1

I try to avoid having an <Icon> component at all, though there are some approaches that justify it- like using a custom icon font. We’ll dive into this later, but the prevalence of icon fonts like FontAwesome hints at the key to keeping icons dead simple: treating them like text.

Treating Icons Like Text

Icons should behave like text because they're fundamentally semantic content used to convey meaning. They’re usually inline elements that flow with surrounding text, which means they share the following traits:

• Context: Like words, icons represent concepts, actions, or information states. The rule of thumb with buttons, especially in headers or sidebars for navigation, is to either show the user with an icon or tell the user with a label but not both.

• Scalability: Icons should scale conformally with text when users adjust font sizes.

• Color: Icons typically inherit the color of surrounding text for visual consistency.

• Alignment: Icons need to align properly with text baselines and line heights.

Leveraging the browser’s ability to render text by setting the <svg> element’s fill attribute to "currentColor" and using em instead of rem for sizing allows these behaviors to emerge organically.

Recommended Props

Read more

Subscribe now

This weekend I learned about CSS's light-dark() function, which automatically adapts colors to user preferences without JavaScript.

Naturally, I wondered if we can recreate this behavior in TypeScript.

The challenge was deceptively complex because I wanted a solution that could handle live updates while staying memory-safe.

In this article, I'll show you how I achieved the desired behavior in tokens that maintain string compatibility while responding to system changes automatically.

Why It Matters

Design tokens are format-agnostic values that create a shared visual language between designers and engineers. Being format-agnostic means they transcend specific implementations like CSS or TypeScript.

Keeping the underlying logic consistent across these formats gives us three key advantages:

• Truthiness
  Tokens reflect actual design decisions, not CSS/TypeScript tokens or Figma variables, which eliminates interpretation gaps.

• Consistency
  No drift/errata between systems or hex value mismatches in different files.

• Resilience
  Update a token in one place and it propagates everywhere.

These three cover the critical needs: accuracy, reliability, and adaptability.

The Basic Implementation

We could easily implement this in TypeScript just by checking the (prefers-color-scheme: dark) query:

export const lightDark = (light: string, dark: string) => {
  const query = globalThis.matchMedia('(prefers-color-scheme: dark)');
  const isDark = query?.matches || false;

  return isDark ? dark : light;
};

The problem is that we’ll be passing around these values in the theme object.

The function above returns a value once, which means we would need to invoke it whenever we want to get the current value of that token.

More Advanced Requirements

In CSS, our theme tokens are defined like this:

--app-background-color: light-dark(var(--slate-100), var(--slate-900));
--text-color: light-dark(var(--slate-900), var(--slate-100));

That means that in TypeScript, our theme object needs to be instantiated likewise:

export interface Theme {
  readonly appBackgroundColor: string;
  readonly textColor: string;
}

export const THEME = Object.freeze<Theme>({
  appBackgroundColor: lightDark(SLATE[100], SLATE[900]),
  textColor: lightDark(SLATE[900], SLATE[100]),
});

This adds the following requirements to our implementation:

• Values returned by lightDark() must be auto-updated when the system theme is changed.

• This solution must not result in memory leaks. Basically, if we use event listeners we need to also use something like an AbortController to remove it if/when our theme object is cleaned up by garbage collection.

• Performance should be non-blocking. We need to keep in mind our core web vitals; a bad approach could degrade INP and CLS scores.

• Syntax and typing should be straightforward enough that this solution results in an intuitive developer experience.

In order for values to be auto-updated while maintaining the best syntax and typing, values returned by lightDark() must be string-like.

What this means is that the value must behave like a string when we pass it around, especially when we interpolate it in template strings (which is important for CSS-in-JS).

However, since everything in JavaScript is an object, the value can also have a prototype which is a subtype of String and/or use custom properties/methods that regular strings don’t have.

Possible Approaches

This table summarizes why there are really only two approaches worth considering. An ⨉ is a deal-breaker basically.

I ended up going with Per-Value Getters but I’ll give a brief overview of each approach with pros and cons below.

Proxy

Uses a JavaScript Proxy to create a theme object that dynamically resolves values when accessed. The proxy intercepts property lookups and returns either the light or dark value based on the current system theme.

What Is A Proxy Object?
Think of it like a wrapper object that can handle reactive side-effects. Example: SessionData with Proxy, where the Proxy syncs to the session cookie whenever a property of the SessionData object is updated.

Pros:
✅ Single event listener for entire theme
✅ Optimal memory efficiency
✅ No per-access computation

Cons:
⚠️ Requires wrapper function (createTheme)
⚠️ Proxy behavior can be confusing to debug
⚠️ Less granular garbage collection

Per-Value Getters

Each value created by lightDark() checks the current state of the dark mode media query.

We must be cautious with this approach because repeatedly checking the media query on every property access might be inefficient if done very frequently.

In practice, the media query check is very fast.

Pros:
✅ Plain object syntax (no wrappers)
✅ Direct access to light/dark values
✅ Framework-agnostic implementation

Cons:
⚠️ Per-access computation cost
⚠️ Complex memory management

Value Objects

Explicit object-oriented approach where lightDark() values are object literals used by a Proxy to toggle between modes.

Pros:
✅ Optimal control and performance
✅ No hidden listeners
✅ Easy debugging

Cons:
❌ No automatic theme updates
❌ Doesn't match CSS behavior
⚠️ Verbose usage patterns
⚠️ Manual subscription management

In a simple application this could be okay, but for me this was a no-go right off the bat since I was going for 1-1 CSS behavior and return values must be string-like.

Event-Based

Traditional observer pattern with manual subscription and update propagation. Maintains a centralized store that notifies subscribers when theme changes.

Pros:
✅ Explicit control flow
✅ Framework-agnostic core
✅ Predictable updates

Cons:
❌ Manual subscription management
❌ No string-like behavior
⚠️ Memory leak potential
⚠️ Update propagation complexity

This approach might be okay in an application already using similar patterns, like Redux or Signals. But I wanted to do this with as few peer dependencies as possible, so this approach was out.

Why Not Use A Proxy Object?

When I first started thinking about my solution, I initially wanted to wrap the theme in a Proxy object to check the dark-mode query anytime we accessed a property.

The main blocker here was that the Proxy knows the theme’s keys and values but doesn’t know how those values were instantiated.

Not every theme token uses lightDark(), and we would need a way to flag token values under the hood to know which ones do and which ones don’t.

This is where the “string-like” requirement comes from. Early on, I was thinking about using a custom symbol that the Proxy could look for to determine if it should check the dark-mode query.

As I played around with it, I realized that this approach was over-complicating things a bit. Instead of creating custom symbols, I realized I could streamline things with existing symbols like Symbol.toPrimitive.

Proxy objects themselves can cause problems with reflection and typing because they’re not the actual objects we want, so I’m glad I was able to find a workaround.

Without Further Ado

The final implementation leverages JavaScript’s new(-ish) FinalizationRegistry (ES2021) for cleanup as well as clever primitive wrapping to create string-like theme values that auto-update when users change their system preferences.

The Code

'use client';

let query: MediaQueryList | undefined;
let isDark = false;
let refs = 0;

const handleThemeChange = ({ matches }: MediaQueryListEvent) => {
  isDark = matches;
};

const colors = new FinalizationRegistry(() => {
  if (--refs <= 0 && query) {
    query.removeEventListener('change', handleThemeChange);
    query = undefined;
  }
});

export const lightDark = (light: string, dark: string) => {
  if (!query) {
    query = globalThis.matchMedia('(prefers-color-scheme: dark)');
    isDark = darkModeQuery?.matches || false;

    query?.addEventListener('change', handleThemeChange);
  }

  if (query) {
    const color = Object.assign('', {
      valueOf: () => isDark ? dark : light,
      toString: () => color.valueOf(),
      [Symbol.toPrimitive]: (hint: string) =>
        hint === 'number'
          ? Number(color.valueOf())
          : color.valueOf(),
    });

    colors.register(color, null);
    refs++;
    
    return color;
  }

  return light;
};

The Demo

Try it out here

How It Works

• The first lightDark() call initializes a single dark mode media query listener, avoiding duplicate listeners across multiple calls.

• Object.assign('', {...}) fulfills our “string-like” requirement with custom versions of built-in string methods:

  • valueOf() checks the current query state and returns the right value

  • toString() ensures string coercion in template strings

  • [Symbol.toPrimitive] adds even better coercion for all primitives

• FinalizationRegistry tracks when colors are garbage collected. When the last color is cleaned up, it removes the listener for the dark mode query to prevent memory leaks.

• The refs counter ensures the media listener remains active while any theme object exists. When refs hits zero, resources clean up automatically.

• If the function is called server-side, only the light-mode color is returned since the dark mode query will be undefined.

Updating The Theme

1. User changes system theme → browser fires a change event on the query

2. handleThemeChange() updates isDark state accordingly

3. Subsequent valueOf() calls return new theme value, so all theme tokens automatically reflect the new state

Wrapping Up

I’m honestly pretty amazed at how I was able to do this.

While this solution uses a more modern memory management API, I have a feeling it could be tweaked to use WeakMaps or WeakSets for better compatibility if needed.

The result is theme values that simply work, adapting to user preferences while maintaining perfect interoperability with existing styling paradigms.

Up Next

Any thoughts on what else you’d like to see? Leave a comment or hop into chat and let me know!

Share

Subscribe now

Engineers building great design systems mockup their most impactful and valuable abstractions. They play with critical building blocks and ensure reliability before sharing them with others. And they look at how the code will be used from the perspective of an Engineer without any historical context, making adjustments along the way which create more opportunities for others to make correct assumptions.

Below is the procedural and mental framework I rolled out for doing just this when adding components to our design system at VividSeats. Our business goals require high delivery velocity for components inner-sourced by contributors across teams as part of ongoing feature work without sacrificing quality or flexibility in branding and themeability, for which our requirements and standards are about as advanced as it gets.

This process, combined with a healthy dose of scaffolding and automation, is designed to empower any Frontend Engineer at VividSeats to successfully build a design system component to our elevated standards, even without the pre-requisite specialized expertise that comes with a background in design or any focus on foundational work or design systems in previous roles.

👋 Hey, it’s Rob. Welcome to UI Engineering Excellence. If you enjoy this post, please hit the ❤️ button and share/restack 🔁 it with others who might find it helpful!

Share

Code Mockups For Enterprise-Strength Design System Components

ℹ️ A code mockup is both a process and a deliverable. We start by diving deep into requirements outlined in design mockups mapping out multiple potential paths to full viability. From there, we refine and converge on a single pattern, charting a roadmap for how it can evolve as the component grows in complexity. Along the way, we adapt and adjust, ensuring the solution aligns seamlessly with our business goals.

1. Identify Requirements & Constraints

1. Assess The Design Mockup (assuming we have one)
   Design mockups aren’t always a given, but when they are available, they serve as the source of truth throughout the development process. Once the component is delivered and live in production, the implementation itself takes over as the definitive reference point.

2. Identify Design Discrepancies & Constraints
   What design decisions—such as sizing, spacing, positioning, or alignment—change across different states? Are there clear boundaries or implicit constraints on how these differences can vary? Which aspects of the component need to be themeable, and which parts of the design remain stable ?

🎯 Goal: Gain just enough understanding to confidently start mocking up code.

2. Choose A Component Pattern

Our UI composition leans heavily on 3 core patterns:

Standalone Components
The component functions as a self-contained unit, with its complexity scaling based on the number and type of props—think Checkbox, Text, etc.
Example:

<Checkbox id="1" checked={checkAll}>{label1}</Checkbox>
<Checkbox id="2" checked={checkAll}>{label2}</Checkbox>

Compound Components
The component is multifaceted with specialized, often optional, subcomponents that are not reusable elsewhere.
Example:

<Checkbox.Group checked={checkAll}>
 <Checkbox>{label1}</Checkbox>
 <Checkbox>{label2}</Checkbox>
</Checkbox.Group>

Base Components
The component is reduced to essential presentation logic common across all variants and then used as the root node in explicit components for specialized variants.
Example:

<SuccessCheckbox />
<ErrorCheckbox />
<InfoCheckbox />
<WarningCheckbox />

🧠 Keep In Mind: Most organism-level components, as well as template/page/view-level components in the Design System, become Compound Components. These typically serve as base components for variants that live outside the Design System. On rare occasions, a compound component may also act as a base for variant components that remain within the Design System. When this happens, we refer to the pattern as a Compound-as-Base Hybrid.

3. Mock Up Multiple Approaches

Just as Designers draft and explore multiple solutions, Engineers contributing to the Design System should draft at least two or three usage mockups for the chosen pattern. This allows us to evaluate how seamlessly Engineers focused on feature work can leverage what we’re building to address common design and UX challenges. Key areas we often explore include:

1. Pattern Adequacy
   How many patterns should we evaluate for this component? More complex components are often compound components, while simpler, atomic components usually offer more flexibility. For example, <Button /> and <Icon /> are commonly used as base components inside and outside the Design System. Should we allow their variants to emerge organically as the system evolves, or explicitly define them upfront? If explicit, which variants make the most sense to include?

2. Design Responsibility
   How many assumptions do components, subcomponents, and variants make about styling their content? To what extent are subcomponents or variants allowed to be aware of or depend on the specifics of their content?

3. Structural Flexibility
   How easily should we be able to rearrange or conditionally render parts of the component? What is the visual or spatial “scope” in these cases—specific content, entire sections, full tabs? Do the variants need to be reusable enough to justify creating discrete components for each?

4. Prop Composition
   How does this component's contract influence the broader system? Does it introduce any new standardized props? If we adjust the type signature of existing standardized props to enhance shared functionality across components, will we need to revisit and update other components using the same prop to maintain the library’s integrity?

☝️ Tip: Keep your mockups lean and to-the-point. Prioritize usage examples and focus on how the code “feels” to read and write when achieving the desired state.

4. (Optional) Mock Up Props

1. List Standardized Props
   Which props from other components are reusable in this component?

2. List Discrete Props
   Identify the props unique to this specific component. Which of these are required, and which are optional? What are their default values? Can we include any pass-through props without exposing underlying implementation details? If using a base component pattern, determine which base component props are abstracted by and omitted from the variant components.

3. Limit Style/Design Props
   Are we helping Engineers focused on feature work make accurate assumptions? For example, if the component requires flexible width, should we provide a width prop for explicit, potentially complex values, or opt for a simpler fullWidth prop to streamline usage?

4. Explore Multiple Techniques
   When design decisions like alignment, size, and roundedness are tightly coupled, should we simplify with a single prop or maintain flexibility by using granular props for each decision? What are the trade-offs, and how does each approach look in practice?

5. Customize Discrete Events
   Can we make event handling more granular and reusable for common scenarios? For example, instead of accepting a generic onKeyDown() handler to augment functionality when the “Tab” key is pressed, could we introduce an onPressTab() prop that leverages a custom TabEventHandler to handle more specific custom TabEvents? (Hint: You best believe we can!)

6. Standardize Type Signatures
   Do we need to introduce new utility hooks or types to support newly standardized props, such as custom event handlers?

🎯 Goal: Make it easy for any consumer (including your future self) to intuitively understand how to use this component and confidently make accurate assumptions, even when facing gaps in technical expertise or domain knowledge.

5. (Optional) Mock Up Reusable Utils

1. Identify or Create Helper Hooks, Utilities, or Types
   e.g. useVerticalAlignment(), useQueryParamState(), EscapeEvent/EscapeEventHandler/useEscapeEvents(), or defining notable constants and enums.

2. Centralize Reusable Utils
   Consolidate logic or styling transformations to streamline the process of building Design System components and reduce duplication.

3. Explore Multiple Options (As Needed)

   For particularly large or complex enums, would breaking them into smaller pieces improve usability? How should functional hooks, like those for filtering and sorting, be composed to handle overlapping or chained behaviors effectively? Consider the trade-offs and implementation details for these approaches.

🎯 Goal: Keep the code DRY and self-documenting while avoiding duplicated logic in each component.

6. (Required) Review With Maintainers

1. Share Final Mockup / Chosen Approach

   Present usage examples to the Design System group. If the work will be carried out by another Engineer, ensure they’re involved in the review process.

2. Gather Feedback

   Verify that the proposed implementation adheres to Design System guidelines, naming conventions, WCAG compliance, and other key standards.

3. Discuss Future Use

   Consider whether the pattern or component could be valuable for other teams or projects. Explore how distribution logic might evolve as the business’s brand composition changes.

4. Achieve Consensus

   Secure approval from the Design System maintainers and move forward with development.

🎯 Goal: Validate the approach and maintain consistency with system-wide standards.

7. Make Adjustments

1. Tweak the Pattern(s)

   Make minor adjustments as unforeseen challenges arise.

2. Strategically Plan Rewrites

   Identify when a shift from one pattern to another might be necessary. If the component becomes overly complex, should it be broken into smaller pieces or rewritten using a more sophisticated pattern?

3. Add Snippets in Storybook

   Create a Storybook story for each design/state variation from the design mockup. Ensure the resulting code snippets precisely match the code mockup for each variant.

🎯 Goal: Deliver a polished, thoughtfully refined implementation, ready for actual build or integration.

Summary

1. Identify Requirements & Constraints

2. Choose a Component Pattern

3. Mock Up Multiple Approaches

4. (Optional) Mock Up Props

5. (Optional) Mock Up Reusable Utils

6. (Required) Review With Maintainers

7. Make Adjustments

👋 Connect with me on LinkedIn.

PS: If you’re enjoying UI Engineering Excellence, hitting the ❤️ button and sharing/restacking 🔁 goes a long way in helping me grow the publication. Please take a moment to help spread the word. Thank you!

Share

Subscribe now

As [YEAR]…

Read more

Subscribe now

Read more