Subscribe now

Back in 1993, Donald Norman coined ‘user experience’ to remind us that emotions, behavior, and satisfaction should steer product decisions.

Design tokens- simple name‑value pairs for colors, type, spacing, and more- let us compose those experiences in code.

A clear token hierarchy allows for flexible theming and gives design and engineering a ubiquitous visual language.

One common approach bundles lower‑level options into higher‑level decisions. Many teams split tokens into three or four layers to keep things organized.

“How to convey the idea that, when designing a product, we’re not just assembling blocks… But we also want our user to feel something.”
— Audrey Hacq, Atomic Design & creativity

The Problem: Design systems treat tokens as subatomic design particles, ignoring human perception.

That misses the point by a mile.

Since we preach user experience, you'd expect these models to mirror how our minds work. Yet no framework nudges you to consider the user at every layer.

In this post, I’ll introduce a slight paradigm shift by mapping tokens with how our brains perceive digital interfaces.

The result isn’t an entirely novel token architecture but an evolution of existing 3-tier and 4-tier models into an experience‑first framework.

The model has four main layers of abstraction for tokens, each serving a distinct purpose:

Signals: Simple tokens that transmit discrete design information.
Qualia: Composite tokens representing instances of subjective consciousness.
Noemata: Component tokens as repeatable attributes of an experience.
Strata: Theme tokens for the manifold horizon in which experiences occur.

Each layer corresponds to a stage in the chain from raw design stimulus to experienced interface all within the framework of the user’s perspective, mirroring the progression from observation to sensation to realization.

We’ll go over these layers in more detail further down, describing their role and how they relate to both implementation and perception, with examples of what tokens in that layer look like.

To get the most out of it, we first need to understand how design tokens and the methods we use to create them are built on prior explorations of human perception as forms of art.

Why Perception Matters

It’s already there, implicitly.

Design is as much about psychology as it is aesthetics. A $primary-color draws user attention, a $spacing-L suggests a comfortable margin, and so on.

When we tune color scales using harmonious intervals or scale typography with musical precision, we’re guiding the user’s eye in a way that reduces cognitive friction and builds trust.

We’re also ensuring some valuable consistency on our end. If you’ve ever wasted time trying to figure out why --grey-150 exists when every other interval in every hue increments by 100, you know what I mean.

Colors, shapes, typography, and layout all work in concert to form a user's impression within milliseconds.

From Art To Interface

I studied a bit of art history in college for my Graphic Design major and can’t get enough of art movements and the philosophies behind them.

Soon after graduation I discovered Synchromism, a little-known short-lived early 20th-century movement that explored the relationship between color and music.

“Before investigating the analogy of colour intervals it is necessary to emphasise the fact that the psychological equivalent of the simultaneous perception of two or more sounds, is the simultaneous perception of two or more juxtaposed colours. Consequently the analogue of harmony in sound must be sought in juxtaposed colours. Melody in colour will therefore result from the espacement of colours, their isolation by intervening neutral tint, and also from the order in which colours lie on the field of vision.”

— Percival Tudor-Hart, “The Analogy of Sound and Color”, Cambridge Magazine 7, no. 21 (2 March 1918): 485

Synchromism In 30 Seconds

Synchromism was an art movement founded by Stanton Macdonald-Wright and Morgan Russell.

From a desire to create form from color alone, they used musical scales as a framework to build paintings from pure hue relationships (called synchromies), defining “color scales” to orchestrate visual harmony just as a symphony arranges sound.

Pick one hue as your central “note”. Add the third and fifth tones from the color spectrum like a musical chord, placing them in nearby shapes.

Synchromies show waves of colors moving in and out, often converging into a vortex that bursts outward in complex harmonies.

Like a light show without lasers.

Underpinning this methodology is a deep engagement with contemporary color science and music theory.

This rational basis aimed to deliver color that could be “heard” as well as seen.

Influence in Design Systems

Synchromism’s core insight (that harmonious aesthetic relationships can be composed like music) laid a conceptual foundation that guides modern design systems.

Though most prominent in color ramps and type scales, it can just as easily apply to spacing units, motion durations, and more.

Color Scales

Design systems often use what’s called a nonatonic (9-step) color scale from 100 to 900, with each interval 10% darker. An 18-step version denominated by 50 (5% darker) is octodecatonic.

These darkness intervals act like octaves, keeping each shade in harmony. HSL lightness shifts by a constant geometric ratio, like moving up scale degrees.

The terms nonatonic and octodecatonic come from musical scales and reference a stable central hue or “tonic” that usually sits at 500 or 450 (i.e. the median of the range).

Thankfully we don’t have to do all this by hand anymore, we can do it in CSS directly with color-mix():

Natural tinting and shading isn’t as simple as the current color mixed with white and black respectively; it often blends in complementary colors and other colors of light around it.

A better approach is to choose a more dynamic range implemented like so:

That said, we usually want to keep the tonic for fades:

For JavaScript/TypeScript tokens, we can reproduce color-mix() with Chroma.js:

Typographic Scales

If you aren’t already familiar with Spencer Mortensen’s breakdown of typographic scales, give it a read. It’s a classic!

In short, he lays out the following formula for creating harmonious typographic scales:

His rationale is as straightforward as it gets so it’s worth repeat here:

“A typographer chooses sizes from a typographic scale in the same way that a musician chooses notes from a musical scale.

Like a musical scale, a typographic scale is a scale, so it must obey the scaling property: if f is a size in the scale, then rf must also be a size in the scale, where r is the ratio of the scale.”

Guess what? We can do this directly in CSS too!

The following gives us a dodecatonic golden typographic scale (12-step scale where the ratio is the golden ratio):

The tonic (f₀) isn’t quite the median here but the scale works the same way.

We can tell by rendering each interval and visualizing an imaginary line at the edge or spaces in between. Notice how the line is curved for User Agent styling:

When typography is scalar, the line is straight:

Compositional Tokens

Humans understand the world not by isolating individual elements, but by weaving them together into a coherent context.

In fact, the very word "context" comes from the Latin contextus, meaning "to weave together," highlighting that context is something actively constructed rather than a static backdrop.

Cognitive scientists note that context creation is an active, two-sided process; we continuously integrate cues from the environment and in turn our understanding of the context influences how we perceive those cues.

In other words, context and content shape each other in tandem, much like threads woven into a single fabric. At the neural level, the brain literally binds together features of an environment or experience to create a unique context representation.

Research in memory formation shows that the hippocampus quickly constructs a “conjunctive” representation of the various features of a place or situation.

This bound representation means that even a small subset of those features can later trigger recall of the whole context through pattern completion.

In cognitive terms, what we see or hear is heavily influenced by surrounding cues and our expectations.

The same visual or UI element can feel completely different in a different setting or theme. This underscores why designing for perception means designing for context: the human brain will always interpret interface signals through whatever contextual frame is in place.

Signals

Generally speaking, a signal is a transmission of information from one part of a system to another. In design systems, they provide a finite palette of options from which more complex experiences emerge.

By thinking about them in terms of constraints, we enforce a baseline harmony and limit the design space to a controlled and ubiquitous vocabulary.

Wait- Aren’t Qualia Irreducible?

Philosophically, qualia refer to the subjective, irreducible experience of consciousness.

Whether or not irreducibility is true depends on if subjective consciousness fully emerges from the objective processes of the brain.

Regardless, it’s undoubtedly true that sensory experience involves signals transmitted through the nervous system. Our brains receive and process these signals to construct our perception of the world around us.

Given this, we can make an argument either way such that this paradigm becomes flexible enough for both 3-tier and 4-tier token architectures. In a 3-tier token architecture, signals simply become the most granular qualia.

Constraints

• Signal tokens are either discrete raw values or use other signals to compute a new signal.

• 1 token = 1 value

Examples

Signals should be used whenever you need a concrete value.

If you plan on computing scalar values for color and typography like we do above, it’s a good idea to have a set of core signals that include some of the terms and ratios mentioned earlier:

Signals can also be values for other things like breakpoints, spacing, border radii, shadows, and so on:

Naming

Since signals are often part of a scale or compound value, they’re usually named relative to similar signals (e.g. $red-400 vs $red-500 or $dark-red vs $light-red) within the same group. Numbers should provide consistency across intervals:

✅ GOOD: $red-fade-90, $red-fade-80
❌ BAD: $faded-red, $more-faded-red

Qualia

The term qualia (singular: quale, pronounced “kwol-ay”) comes from sense-data theory, referring to the subjective quality of conscious experience as properties of sense-data themselves.

When we see a button on a screen, properties like “red color, 10pt font, 4px radius” are parsed pre-attentively and then combined, almost like a form of sensory data compression.

What we actually experience is the overall look and feel as a prominent call to action.

Make It Make Sense

Imagine trying to describe what it feels like to see the color red to someone born totally blind.

Qualia are these immediate sensations. They capture “what it’s like” to experience a signal with meaningful context.

In reality, we don’t just run into the color red. Rather, we experience the “redness” of something like an apple or a can of Coca-Cola or a button on a screen.

As qualia, the redness of an apple isn’t equivalent to the redness of a can of Coca-Cola even if the two hues are exactly the same.

If signals are ingredients, qualia are flavors. They encourage us to start thinking in terms of low-level sensations rather than objective values.

Constraints

• Qualia may use raw values, signals, and other qualia.

• They should never use noemata or strata.

Examples

Qualia typically use signals either directly or in composite values to create new tokens with specialized meaning.

For example, a color scale might have signals for blue like $blue-100 used by qualia like $primary-color or $info-color.

Consider our typographic scale from earlier.

The scalar tokens —-f12, —-f11, —-f10, etc. are signals, while the heading tokens —-h1, —-h2, —-h3, etc. are qualia. Both types are used for font sizes, but the latter have specialized meaning as heading sizes.

These tokens can then compose more complex qualia for the headings as CSS font shorthands:

By packaging decisions in this way, qualia also help reduce errors. Use theme wherever you want to encapsulate a design decision with a purpose.

As a rule of thumb, if a style decision would appear in CSS as a shorthand or a group of properties, it’s a good candidate for a quale token.

Naming

Quale token names should capture meaning or usage. A good practice is to think, “How would I describe this token’s role to a colleague or stakeholder?”

For example, when naming and grouping color qualia, consider the underlying meaning. Words like “primary”, “secondary”, “tertiary” are about priority; system colors indicate intent:

❌ BAD: $red, $grey
✅ GOOD: $primary-color, $secondary-color
✅ GOOD: $error-color, $disabled-color

Noemata

In phenomenological terms, noemata (singular: noema) refer to the content of thought; essentially, something as it is experienced or intended in the mind.

This ensures that each component’s design supports its function.

Noematic Nuance

Conceptually, noemata overlap with the Platonic idea of eidos, the essence of a thing—it’s “thingness”, if you will.

In programming terms, eidos is like an interface implemented by a class. It’s the mental contract that determines how language shapes reality.

Building on our red apple example from earlier, let’s break down the requirements for some eidetic analysis:

• it must be an apple

• it must be red (mostly)

The word “mostly” here is the key to understanding the nuance between eidos and noemata.

Say we have two red apples. One has a small spot of discoloration; the other has no perceivable discoloration. Both are red enough to be red apples but you probably think of one as fresher than the other.

In order to account for freshness at the eidos level, we have to increase language specificity from “red apple” to something like “fresh red apple” or “entirely red apple”, which narrows the noematic scope.

If we have two fresh (entirely) red apples, we can still perceive one as fresher than the other but now we need more sensory information like texture, firmness, maybe even aroma or taste.

Both eidos and noemata represent ideal forms. The nuance is that eidos defines what makes a thing that thing while noemata are the repeatable attributes of an experience of that thing.

Constraints

• Noemata may use any tokens from any other layer.

• In some cases they may also be another noema token.

• In rare cases they may be one-off values.

Examples

Use noemata tokens to organize design decisions by component. This way, if a particular component needs to be reskinned or adjusted, you can tweak its tokens without affecting others.

Noemata sometimes reference other noemata when it makes sense, though this usually happens intramodularly:

From time to time, it may be appropriate to reference noemata from other components:

Naming

Noema token names usually prefix the component or pattern name to group them:

❌ BAD: $color-background-dropdown
✅ GOOD: $dropdown-color

This way, anyone looking at the token name knows which component it belongs to and what aspect it controls.

It’s also helpful to mirror the component’s parts/states in the token names. When it comes to buttons and links specifically, we recommend the term “engaged” when pressed and hover states overlap instead of words like “active”. :active is a CSS pseudo-class and misusing this term can cause confusion.

By naming noemata tokens clearly, we capture the nuance of each component’s design in a way that is immediately understandable.

Strata

The contextual background or frame in which the user’s experience occurs is called their horizon.

A horizon links past experiences together and, in those connections, guides which new ones join the series. Those links then shape our overarching sense of reality.

The user’s horizon includes not just what is explicitly present in the viewport, but also the implied possibilities and potential experiences. The interstitial links of these experiences are the theme.

A theme is essentially a configuration.

Strata (singular: stratum), therefore, are the layers that configure the user’s horizon of experience.

Constraints

• Strata may use qualia and signal tokens.

• They may also reference another stratum token.

• They should never use noemata.

• In rare cases they may be one-off values.

Examples

Use strata to enable theming at scale.

While strata could be limited to specific pages or views, a good rule of thumb is to keep these tokens relevant to design elements used anywhere in the app:

They can also encapsulate categories of components:

As strata these tokens tell us that the system doesn’t have <Form> component; if it does, they become noemata.

Naming

Strata shouldn’t “know” the theme they’re in, meaning names should be theme-agnostic.

❌ BAD: $theme-brand-text-color
✅ GOOD: $text-color

Component Categorization

Beyond token architecture, a way to further align design systems with human understanding is to categorize UI components by their executive function.

For consistency, I’m sticking with words that end in “ation” but the taxonomy of executive function itself isn't a strict science. Teams should feel free to modify these categories and use different terms if it better suits their context.

Many UI components can serve multiple purposes, but this approach provides a useful lens for thinking about design intent.

For instance:

• Actuation/Activation - Components that cause something to become active or effective, or simply to "turn on":

  • <Button>/<Button.Group>

  • <Checkbox>/<Checkbox.Group>

  • <Radio>/<Radio.Group>

  • <Toggle>

• Adaptation - Components that allow the user experience to change or be changed in accordance with various edge cases:

  • <Autocomplete>

  • <CatchError>/<ErrorBoundary>

  • <ErrorPage>

  • <Loading>

  • <LanguageSelector>

  • <Image>

  • <NoResults>

  • <ThemeSwitcher>

  • <Skeleton>

  • <Video>

• Classification - Components that label, categorize, or filter content:

  • <Avatar>/<Avatar.Group>

  • <Chip> or <Pill>

  • <Label>

  • <Search>

  • <Tag>

• Explication - Components that explain or assist user understanding of the interface or content:

  • <BarChart>

  • <GeoChart>

  • <Histogram>

  • <Popover>

  • <Tooltip>

  • <TreeMap>

• Narration - Components that present content or guide through a temporal flow:

  • <Fade>

  • <ProgressBar>

  • <SlideIn>/<SlideOut>

  • <Stepper>

  • <Timeline>

• Organization - Components that bring content together to help users identify information and/or maintain consistency:

  • <Article>

  • <Carousel>

  • <Dashboard>

  • <Grid>

  • <Menu>

  • <Pagination>

  • <Select> or <Dropdown>

  • <Tabs>

  • <Table>/<DataGrid>

• Orientation - Components that help users navigate across pages and views:

  • <Breadcrumbs>

  • <Footer>

  • <Header>

  • <NavBar>

  • <Sidebar>

  • <Sitemap>

• Prioritization - Components that highlight or emphasize important information to grab attention:

  • <Alert>

  • <Badge>

  • <Banner>

  • <Callout>

  • <Drawer>

  • <Hero>

  • <Modal>

  • <Notification>/<Toast>

  • <Snackbar>

• Segmentation - Components that break or structure content into digestible sections:

  • <Accordion>

  • <Box>

  • <Card>

  • <Divider>

  • <List>

  • <Item>

  • <Page>

  • <Section>

On the surface, this approach might not appear to offer much more than traditional affordance-based component classifications. The main advantage of naming groups by the job they do is that conversations align to outcomes instead of surface form (“is this a button or a link?”).

You can plan to “improve actuation clarity across checkout” or “harden adaptation in low-connectivity scenarios,” then ship coordinated changes across multiple components with shared tokens and guidelines.

Specs can state, “This screen uses actuation and prioritization patterns,” which immediately maps to known tokens, behaviors, and even accessibility rules. Designers choose which function; engineers apply the corresponding patterns.

Instrumentation can also roll up by function: activation rate, time-to-orient, attention capture vs. dismissal, etc. Product decisions become “our prioritization patterns underperform on mobile,” not “this one toast is weird.”

Further, components like <ErrorBoundary>, <Image>, <Video>, <Skeleton>, etc. tend to be disregarded by Product as "utilities"; grouping them under Adaptation clarifies their actual value.

Likewise, <Menu> and <List> are both typically considered structural components in most design systems, and Product Developers often don’t understand the difference. This approach clarifies that a <List> is a method of segmentation while a <Menu> is more about organization.

The goal is to encourage thinking about why a component exists and to organize your library in a way that reflects those purposes. This can help ensure coverage and guide designers on what component to use for a given problem.

Final Thoughts

Embracing the construction of human perception as a guiding concept leads to a token architecture that is flexible, scalable, and truly user-centric.

By mirroring how humans construct and perceive contexts through meaningful combinations and nuanced variations, we create scalable design systems that feel naturally adaptive.

The user’s experience will be distinct where it matters, yet comfortably familiar underneath, because we’ve engineered our tokens the way the mind itself works: composing new experiences out of well-understood pieces, artfully woven together.

Up Next

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

Share

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

Feature teams move slower than they should. What takes a week could take a day. Simple changes somehow break unrelated things. New hires need months to become useful.

This isn't a people problem. It's a systems problem.

The root cause is excessive cognitive load. It's the mental weight developers carry to understand your code, your patterns, and your unique way of doing things. This load is the silent killer of velocity and quality.

Most advice on this focuses on cleaning up code. That's only a third of the battle. You can't just fix the symptoms. You need a strategy to fix the environment.

This article gives you that strategy. First, we'll unpack the complete cognitive load framework. Then, we'll reveal the most powerful tool to reduce it: engineering for inductive reasoning.

Your goal is to build a system where the right way to do things is the easiest way to discover. This is how you turn a team of good engineers into a high-performance engine.

Understanding Cognitive Load (Completely)

If you’ve read Cognitive Load Is What Matters on Github, then you’re already ahead of the curve. This is a great primer but only covers two types of mental overhead.

In software, we deal with three specific types of load. You must understand all three to fix the problem.

Here’s a more complete overview of how mental overhead is categorized according to cognitive load theory:

• Intrinsic
  Overhead associated directly with a topic- i.e. the code, the problem, the business logic, and so on. Essentially, this is what comes to mind when we think of complexity. Spaghetti code overloads working memory, making it more difficult to do our work.

• Germane
  Overhead required to create a permanent store of knowledge or “schema”. In cognitive psychology, a schema is a mental model of how everything fits together. Thus, germane overhead is the effort required to build up recognition- which works faster than recall.

• Extraneous
  Overhead added by how information is presented. It comes from how we write and document code, not what the code does. It's the mental energy spent deciphering a bad variable name or untangling a nested conditional.

Germane overhead is about building recognition but it’s rooted in the perceiver’s level of effort, whereas intrinsic overhead is about information itself and extraneous overhead is about its source.

These three types of mental overhead are not separate. They work together.

A complex task (high intrinsic load) becomes impossible when buried in messy code (high extraneous load). Both are made worse if the system itself becomes a niche skill that new hires must master (high germane load).

Your job is to manage the entire system. Ignoring one type just shifts the burden elsewhere. You need a tool that addresses all three at once.

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

This morning, LinkedIn suggested this post in my feed:

I will never, ever use reduce in Javascript.
.
.
”Reduce is more elegant.”
”Real devs use functional methods”
”Loops are old-school.”
”It’s just one line, bro.”

These are not principles.
They’re just disguised best practices.

But here’s the truth:
You’re not writing code for applause.
You’re writing it to be understood.

👎 .reduce() hides logic in syntax
👎 It often obscures the intent.
👎 It sacrifices readability for cleverness

You know what doesn’t do that?
✅ A simple for loop.

Because when the code breaks at 2AM,
It won’t be the code that saves you.

It’ll be the line you can actually read quickly.

The first line makes it clear right off the bat that this is rage bait. And particularly low-effort AI rage bait at that. It’s an opinion designed to be so outrageous and unconventional absurd that more seasoned engineers can’t help but comment, which in turn maximizes the author’s reach.

Content like this goes beyond basic ignorance or lack of experience/expertise into a level of technical disinformation that we as an industry need to get better at identifying and discouraging.

The key piece of context that pushes this into disinformation territory comes with a deeper understanding of the declarative paradigm itself, which focuses on making code more readable by building up small, compositional abstractions that can result in an almost DSL1-like experience at scale.

A Quick Primer On Declarative Programming

Most examples of declarative programming in JS/TS focus on built-in array methods, so if you look it up or ask AI you’re likely to get an example like this one, where let’s say a new array is created from an existing array by removing null values and converting the remaining numeric values to strings:

const arr = [1, 2, 3, 4, null, 6, 7, null, 9, null];
const newArr = [] as Array<string>;

/* Imperative Approach */
for (let i = 0; i < arr.length; i++) {
  if (arr[i] !== null) {
    newArr.push(String(arr[i]));
  }
}

/* Declarative Approach */
const newArr = arr.filter((value) => value !== null).map(String);

While built-in Array methods like .filter(), .map(), and .reduce() are declarative, examples like these don’t fully illustrate why declarative code is advantageous beyond just eliminating a few lines of code here and there.

The paradigm itself is more about increasing readability by writing code in a way where the thing you want to do happens by simply calling a method .doTheThing() rather than describing how the thing is done. Declarative methods can use loops and other imperative control flows under the hood, so a slightly better example would be rewriting an implementation that starts out like this:

🗒️ Note
You probably won’t actually have this kind of business logic in a real app, but it gets the idea across so hear me out.

interface Person {
  readonly name: string;
  position: energy;
  position: number;
}

const alice: Person = {
  name: 'Alice',
  energy: 100,
  position: 0,
};

const move = (
  person: Person,
  speed: number,
  distance = 1,
  effort = speed,
) => {
  if (person.energy) {
    for (let i = distance; i > 0; i -= speed) {
      person.position += speed;
      person.energy -= effort;
    }
  }
};

const walk = (person: Person, distance = 1) =>
  move(person, 0.5, distance);

const run = (person: Person, distance = 1) =>
  move(person, 2, distance);

const jump = (person: Person, distance = 1) =>
  move(person, 1, distance, 1.5);

walk(alice, 10);
run(alice, 5);
jump(alice, 4);
walk(alice, 8);

While we do have our logic broken up into specialized functions, this code is not declarative because each function has to be told which Person is moving as a parameter, so we have to pass alice in as an argument every time. In a more functional approach, you could curry the move() function to get around this like so:

const move = (person: Person) =>
  (speed: number, distance = 1, effort = speed) => {
    if (person.energy) {
      for (let i = distance; i > 0; i -= speed) {
        person.position += speed;
        person.energy -= effort;
      }
    }
  };

const aliceMoves = move(alice);
const aliceWalks = (distance = 1) => aliceMoves(0.5, distance);
const aliceRuns = (distance = 1) => aliceMoves(2, distance);
const aliceJumps = (distance = 1) => aliceMoves(1, distance, 1.5);

aliceWalks(10);
aliceRuns(5);
aliceJumps(4);
aliceWalks(8);

This is a lot better in terms of readability but not so much scalability because we still need discrete functions for each person we want to move. In order to make this code declarative, we need to go beyond simply updating Alice’s position and return an updated copy of alice:

interface Person {
  position: number;
  readonly name: string;
  readonly move(speed: number, distance: number, effort: number) => this;
  readonly walk(distance: number) => this;
  readonly run(distance: number) => this;
  readonly jump(distance: number) => this;
}

const alice: Person = {
  name: 'Alice',
  energy: 100,
  position: 0,
  move(speed: number, distance = 1, effort = speed) {
    if (this.energy) {
      for (let i = distance; i > 0; i -= speed) {
        this.position += speed;
        this.energy -= effort;
      }
    }

    return this;
  },
  walk(distance = 1) {
    return this.move(0.5, distance);
  },
  run(distance = 1) {
    return this.move(2, distance);
  },
  jump(distance = 1) {
    return this.move(1, distance, 1.5);
  },
};

Writing our code this way allows us to move Alice like this:

alice.walk(10).run(5).jump(4).walk(8);

Like I said, you probably won’t actually shift a Person object’s position in a real app, but the same principles apply whenever you need a series of heterogeneous transformations (e.g., applying user profile updates, composing query filters, or processing form data.)

☝️ If this section was helpful let me know!
I’m considering writing up a more in-depth post that dives into this with more relevant examples; I might also do it as a 2-part series that builds on this and shows how I’ve used RxJS with React in the past to build web apps with declarative streams that have insane performance.

Technical Disinformation

Now that we understand what declarative methods like .reduce() are all about, we can start to get a better sense of why this kind of content isn’t eligible for the same benefits of the doubt we would typically afford the author of the rage bait from earlier, who has just under 3 years of experience at this point.

Given the examples above, we can see how the 👎 points being labelled as such is misleading. Except for the last one, the points themselves are fine but should be 👍 instead. Hiding logic in syntax is a feature of declarative code not a bug. It is, in fact, the point.

The only time I’ve seen .reduce() kinda sacrifice readability for cleverness is when it’s used to pipe async functions sequentially, like this:

asyncFunctions.reduce(
  (resolved, next) =>
    resolved
      .then((result) => next(result))
      .catch(console.error),
  Promise.resolve(),
);

In most cases though, it’s used to build objects from arrays in situations where Object.fromEntries() isn’t an option.

The final two sentences would normally get a pass as well (albeit with a raised eyebrow) but given how sus his whole post is already, I’m not inclined to start now. Anyone who’s actually had to respond to a production incident at 2am can tell you it’s not simple code that saves you, it’s your recognition- which is faster than recall- leveraging the mental shortcuts you’ve built up.

Newbz These Days!

In the beginning (of people teaching themselves to code,) we had books. Fat. Ass. Books. My dad had a book somewhere on one of his bookshelves on C++ that’s 30 years old now and girthier than my whole fist. Expert software engineers were the people who literally wrote the canonical book or manual on the technical subject of their expertise, or they made a name for themselves as the creator of that subject. Plenty did both.

Even in the 2010s, posting something like this on your Medium blog intentionally as an aspiring professional would be akin to shouting “I’m just an imposter, don’t hire me!”

The tradition of sharing knowledge in this way meant that people positioning themselves as rising stars still had to demonstrate a solid understanding of more sophisticated technique, or at least an eagerness to learn.

Aimee Knight and Lydia Hallie come to mind as engineers who stood out to me around this time as particularly admirable for their ability to bring others along with them as they entered the field and grew. As Juniors they had no problem talking shop with seasoned experts. If you take a look at Aimee's blog today, it’s as technical as one would expect from an expert software engineer. Lydia’s technical expertise and her desire to share it continues to speak for itself.

Juniors Cannot Be Junior Anymore

Bootcamps have flooded the industry with new Engineers, especially on the frontend. While the idea that this number doubles every 5 years is more of a myth these days, data from the most recent Stack Overflow Annual Developer Survey does show that the average Frontend Engineer has less than 8 years of experience.

I’ve definitely noticed the impact of this especially over the past few years; at least the last two organizations I've been at have had ICs under Staff that were a standard deviation below what I’d typically expect in terms of technical expertise at every level. And it’s not just me who’s noticed! In one of these roles this was a widely acknowledged fact amongst the Staff+ group.

At first I chalked it up to that organization having scaled too rapidly, but seeing this pattern across multiple organizations consecutively has made the talent gap in the industry crystal clear.

With the advent of AI upon us, Juniors by today’s standards have been all but replaced, along with some contractors who do team augmentation as an extra pair of hands. We don’t need new people who write code without having any idea how it works because we have AI for that now! And AI is at least much, much faster.

But companies aren’t just going to stop hiring Juniors. ICs get old after a while, and expensive, and become consultants or go into management or leadership or retire early. We still need new folks to start somewhere, so the job description needs a revamp. The problem for recent grads is that the job market, already oversaturated as it is, is insanely bottom-heavy.

The intensity of this competition effectively raises the bar and, I believe, will eventually close the talent gap. The demand for experts is decreasing2, but the value of expertise itself is actually increasing. What I would never tell a candidate I’m passing on is that you can have an Ivy League CS degree and 5 FAANG/MAMAA internships but there’s a line of folks out the door who are just as eager to learn and capable of doing so just as quickly, so if you’re only as technical as your AI then you aren’t going to yield the best return on investment.

💭 BTW
If you do actually have an Ivy League CS degree and 5 FAANG/MAMAA internships you’re gonna be fine. Eventually.

Wrapping This Up

Back to the LinkedIn post at the top, it should go without saying at this point that dishing out a blatantly bad technical opinion is probably a bad idea. It’s not that it won’t work- it unfortunately does work to a certain degree or else this guy wouldn’t be doing it.

Not sure how many followers he added but his comments were riddled with Seniors calling him out as a bad engineer (“sounds like a skill issue”). And that was unfortunately the whole idea. So I threw him on my blocklist, and I’m sure I wasn’t the only one.

But if I’m looking at the trade-offs, in the long-run, building an audience at the cost of connecting with more technical peers who strive to make a name for themselves by actually knowing what they’re talking about doesn’t seem worth it. These folks will someday surpass you both in talent and pay, if they aren’t already ahead. And this will lock you in as Yet Another Engineer Who Only Writes About Soft Skills, because the audience that you do have are going to be chalk full of vibe coders3 and Product/Growth Developers.

Look, I’m not even saying don’t ever use rage bait. We all do it sometimes; I have opinions in my Notes that, while genuine, definitely come across as rage bait-ey. What matters is that these are opinions I’ve formed as a result of a decade of industry experience; I’m not contriving them just to increase my numbers.

If you must resort to technical hot takes on LinkedIn, at least use The “Prove Me Wrong” variant so you don’t make yourself look like an asshole who is unable or unwilling to take feedback in code review.

🙏 BTW my subscribers are the best, my previous post on Aligning Components with Custom HTML Attributes achieved an 80% open rate and I can’t thank each of you enough for taking the time to read it!

Up Next

Any thoughts on what else you’d like to see? Leave a comment or hop into chat and let me know! I’ll be on vacation most of this month but have plenty to dive into as soon as I’m back.

Share

Subscribe now

Over the weekend, I found myself updating my personal React template repo and wanted add a few components to the pattern library.

I love the look and feel of HeroUI, so I initially built the UI with it. Since then, it’s introduced breaking changes pretty much every time I’ve done a dependency update even in minor versions. I finally ripped it out a few weeks ago and have been referring to HeroUI source code and documentation occasionally as I rebuild my core components.

Keeping changes to props (i.e. the contract) minimal is crucial to ensuring the scope stays manageable, so I pulled up the HeroUI docs as I started building out my new <Badge /> component on Saturday.

One thing I noticed right off the bat is that the HeroUI <Badge /> component wraps the <Avatar /> component and not the other way around:

<Badge color="primary" content="5" placement="bottom-right">
    <Avatar radius="md" size="lg" src="..." />
</Badge>

This implementation makes sense but feels rudimentary. I wanted to know if I could achieve something that expresses the presentation logic as an avatar with a badge rather than a badge over an avatar, something like this instead:

<Avatar
  badge={<Badge color="primary" placement="bottom-right">5</Badge>}
  radius="md"
  size="lg"
  src="..."
/>

We might have a traditional badge, with a number or icon representing something of priority like notifications or a word like “PRO”. We might also use it to indicate online status or selection within a group, so being able to change the badge position is actually a requirement!

It just so happens that I had a standardized implementation for an alignment prop lying around that could work in this case in theory so I decided to break the existing BadgeProps contract.

This approach is nothing new or novel— any Engineer who uses CSS somewhat regularly or at least has deeper than a surface-level understanding of it could ideate a solution like this on their own, but I figure it’s worth sharing in the hopes that someone finds it helpful!

Alignment Tokens

As tokens, alignment prop values describe a position relative to one or two perpendicular sides of a box, in this case the Box Model.

If you’re wondering why I’m calling it a “9-anchor” system when there are only 8 visible anchors in the screenshot, it’s because we want to use these for positioning rather than sizing so we can imagine the 9th anchor being directly in the center.

Since we’re operating on a 2-dimensional plane, I broke these tokens down into two enums- one for each axis:

export enum HorizontalAlignment {
    Left = 'left',
    Center = 'center',
    Right = 'right',
}

export enum VerticalAlignment {
    Bottom = 'bottom',
    Center = 'center',
    Top = 'top',
}

If you’re a technical design nerd like I am, you may have the urge to yell at your screen that VerticalAlignment.Center should be VerticalAlignment.Middle! And you wouldn’t necessarily be wrong, but in this implementation I’ve found it’s actually better not to distinguish between horizontal and vertical center. Keep reading and you’ll see why!

Anyhow, these two enums are fed into token types like so for prop signatures:

export type ScalarAlignment = `${VerticalAlignment}` | `${HorizontalAlignment}`;

export type CompoundAlignment = `${VerticalAlignment}${'-' | ' '}${HorizontalAlignment}`;

export type Alignment = ScalarAlignment | CompoundAlignment;

Notice how we’re using template string literal types. Using a string enum in a template string literal type expands the enum type into a union of its values. This allows our Product Developer (so… future me) to use a discrete horizontal or vertical alignment value like “top”, “center”, “left”, etc. or a compound horizontal and vertical value separated by either a dash or space e.g. “top-center”, “bottom right”, etc.

Provided to a component, the value is simply passed directly to the root element as an HTML data-* custom attribute:

<span
    className={css}
    style={{ ...style, borderRadius: circle ? '50%' : radius }}
    data-alignment={alignment}
    ref={ref}
>
    {children ? children : <>&nbsp;</>}
</span>

Leveraging CSS Attribute Selectors

Now that we have a custom attribute to select, we can control our badge position externally.

You can easily make this DRY in SCSS with a mixin or placeholder selector. For this example I’m using avatar’s stylesheet, but may end up moving most of the below to src/App.css since I’m using PostCSS Modules:

// Avatar.module.css

.avatar {
    position: relative;

    [data-alignment] {
        position: absolute;
    }

    [data-alignment$="left"] {
        left: 0;
    }

    [data-alignment$="right"] {
        right: 0;
    }

    [data-alignment^="top"] {
        top: 0;
    }

    [data-alignment^="bottom"] {
        bottom: 0;
    }

    [data-alignment]:not([data-alignment^="top"]):not([data-alignment^="bottom"]):not([data-alignment$="left"]):not([data-alignment$="right"]):not([data-alignment*="center"]),
    [data-alignment$="top"],
    [data-alignment$="bottom"],
    [data-alignment$="center"] {
        left: 50%;
        transform: translateX(-50%);
    }

    [data-alignment]:not([data-alignment^="top"]):not([data-alignment^="bottom"]):not([data-alignment$="left"]):not([data-alignment$="right"]):not([data-alignment*="center"]),
    [data-alignment^="left"],
    [data-alignment^="right"],
    [data-alignment^="center"] {
        transform: translateY(-50%);
        top: 50%;
    }
}

Let’s break this down:

.avatar {
    position: relative;

    [data-alignment] {
        position: absolute;
    }

This code helps us position the component relative to the underlying content. The second rule in particular makes it easier to align the component by giving us a mechanism that lets us start at 0 on a pixel coordinate grid from each side of the content.

It’s worth noting that because we’re using absolute positioning, position: relative; in the containing component is required for this to work properly.

[data-alignment$="left"] {
    left: 0;
}

[data-alignment$="right"] {
    right: 0;
}

These selectors target any alignment values ending in “left” or “right”. We know compound values always end with a horizontal alignment, so this covers “*-left”, “*-right”, “left”, and “right”.

[data-alignment^="top"] {
    top: 0;
}

[data-alignment^="bottom"] {
    bottom: 0;
}

These selectors do the same thing but for vertical alignment. Compound values always start with a vertical alignment, so we use ^= instead of $= to match the beginning of the string rather than the end. So now we’ve also taken care of “top-*”, “bottom-*”, “top”, and “bottom”.

Here’s where it gets a little weird:

[data-alignment]:not([data-alignment^="top"]):not([data-alignment^="bottom"]):not([data-alignment$="left"]):not([data-alignment$="right"]):not([data-alignment*="center"]),
[data-alignment$="top"],
[data-alignment$="bottom"],
[data-alignment$="center"] {
    left: 50%;
    transform: translateX(-50%);
}

[data-alignment]:not([data-alignment^="top"]):not([data-alignment^="bottom"]):not([data-alignment$="left"]):not([data-alignment$="right"]):not([data-alignment*="center"]),
[data-alignment^="left"],
[data-alignment^="right"],
[data-alignment^="center"] {
    transform: translateY(-50%);
    top: 50%;
}

Being the astute reader you are, you probably noticed that the attribute selector operators have flipped, so now we’re using ^= for horizontal alignment $= for vertical. We already know that a compound value always begins with a vertical alignment and ends with a horizontal alignment, so by swapping the operators we can isolate discrete values, and that’s what this code does.

As a requirement, whenever we use a discrete alignment value like “top” or “left”, it should be evaluated as a compound value where the missing axis is assumed to be “center”. So “top” should be evaluated as “top-center”, “left” should be evaluated as “center-left”… you get the idea!

This styling centers the alignable component both when “center” is explicit and implicit. And this right here is why we don’t distinguish between horizontal “center” and vertical “middle”! Plus, semantically it’s just much nicer to be able to say “center” rather than “middle-center”.

Now, for an avatar component, having a badge in the direct center feels like a potential use case I’d disregard as YAGNI. But who knows, I’ve seen stranger things out there.

[data-alignment]:not([data-alignment^="top"]):not([data-alignment^="bottom"]):not([data-alignment$="left"]):not([data-alignment$="right"]):not([data-alignment*="center"])

Lastly, I want to point out this line. It’s a part of both of these last two selectors and it plays in important role in graceful degradation by ensuring that any invalid value renders the component in the direct center, as if the value were “center-center” or just “center”.

I’ve found a few edge cases (like alignment=“bright”) that can break this but for the most part it’s pretty solid, I’d feel fine handing this off to QE at this point if I did this at Vivid Seats. That said, I haven’t even started with animations yet and I’ll be nervous about transform: translate; when I do. If I want to be able to animate the badge with a slide in/out, I may have to figure out another approach.

I’m guessing that’s why HeroUI’s <Badge> is the container.

Share

Subscribe now

Let's be real. What we're calling vibe coding today—people throwing vague prompts at AI and expecting magic—isn't just another step in programming's evolution. It's a fundamental rupture in how we create software.

I've been watching Engineers react to this shift with skeptical fascination. The fascination comes from seeing people with zero technical knowledge suddenly building dope shit by describing what they want in plain English. The skepticism? That it mostly actually works… at least until it doesn’t.

What's Actually Happening Here

The term "vibe coding" captures something real: the collapse of traditional knowledge barriers in software creation. But underneath the memes and the moral panic, something more interesting is happening.

Programming has always been about layers of abstraction. We started with machine code, moved to assembly, jumped to higher-level languages, then frameworks, and now we're approaching a layer where natural language itself becomes the interface to computation.

This one doesn't just hide implementation details. It hides the very concept of implementation.

Not Just Another Tool in the Box

Whenever new technology emerges, there's this predictable chorus of "it's just another tool" or "real engineers will still be valuable." That's comforting but misses the point.

AI isn't just another abstraction layer like high-level languages were to assembly. Previous abstractions required you to understand programming concepts. They just made them more convenient. You still needed to think algorithmically.

This is different. A great model doesn't just abstract away implementation. It abstracts away the need to think like a programmer at all.

That's not an incremental change. That's a phase transition.

Language Creates New Possibilities

What's also fascinating is how the term "vibe coding" itself is shaping reality. By naming this practice, by giving legitimacy to what would previously have been dismissed as "not real programming," we're creating space for entirely new approaches to software creation.

The term validates non-traditional paths into tech. It challenges the gatekeeping that's been baked into software culture. It suggests that technical intuition might be as valuable as technical knowledge.

And, I’ll admit, that can be frustrating as hell to someone who spent years mastering the craft.

Where This Actually Leads

Most discussions about AI and coding fall into simplistic traps: either "AI will replace programmers" or "AI is just a tool that makes programmers more productive."

The reality is messier and more interesting.

What we're witnessing isn't the death of programming. It's a bifurcation. Two distinct disciplines are emerging from what was once a single field:

1. System Engineering
   Designing, architecting, and maintaining the complex systems that underpin our digital world. This requires deep technical knowledge and won't be replaced by vibes anytime soon.

2. Product Engineering
   Creating specific solutions to business problems using AI as the primary implementation layer. This is where vibe coding thrives, and it's becoming its own discipline with its own expertise.

These aren't the same field anymore. They require different skills, different mindsets, and different types of people.

The New Knowledge Hierarchy

Here's where things get really interesting. Vibe coding doesn't eliminate the need for expertise. It creates demand for new types of expertise:

• Prompt Engineering
  Not just writing good prompts, but understanding the conceptual boundaries of what current AI can and cannot accomplish.

• Result Verification
  Developing reliable methods to verify that AI-generated code actually does what it's supposed to do, without necessarily understanding all implementation details.

• System Design
  Creating architectures that work reliably even when individual components are generated by AI with varying levels of reliability.

None of these are simple skills. They're just different from traditional programming skills, and they'll be valuable in different contexts.

What Actually Matters Now

The most valuable people in this new landscape won't be those who cling to traditional programming or those who blindly embrace vibe coding. They'll be those who can bridge these worlds. People who understand enough about implementation to know what's possible, but who can translate between human intent and computational reality.

If you're panicking about AI replacing Software Engineers, you're headed down the wrong path. The real question is: how does your role evolve when implementation is no longer the bottleneck?

Some possibilities:

• Becoming the person who can frame problems in ways that make them easily solvable

• Developing expertise in verifying and validating solutions

• Building the frameworks and platforms that make AI-assisted development reliable

• Creating the tools that let others build with confidence

Learning From Historical Parallels

The closest parallel to what's happening now isn't any previous programming paradigm shift. It's what happened to other fields when they were transformed by computation.

Think about graphic design before and after desktop publishing. Or architecture before and after CAD. Or animation before and after computer graphics.

In each case, the field didn't disappear. It transformed. Some traditional skills became less valuable. New skills emerged. The nature of expertise shifted.

The people who thrived weren't those who resisted change or those who abandoned all traditional knowledge. They were those who understood which fundamentals remained valuable and which needed to evolve.

The Only Path Forward

The future belongs to those who can navigate the middle ground. People who can bring enough technical knowledge to avoid AI's pitfalls, but enough flexibility to leverage its capabilities.

AI isn't just another tool. Nor is it the end of programming either. It's the beginning of something different. Something that will eventually just be called "coding" again, but will mean something new.

The question isn't whether you embrace AI or resist it. The question is: what aspects of software creation still require human expertise, and how do you position yourself at that intersection?

That's where the opportunities are. That's where the future is being built.

And it's going to be a wild ride!

Share

Subscribe now

Over the past month, I've been exploring how AI can accelerate the code mockup process for design system components. We started with a structured methodology, then moved into comparing leading AI models like ChatGPT o3, Claude 3.5 Sonnet, and DeepSeek R1.

Today, Anthropic released Claude Code and Claude 3.7 Sonnet, a new model with an extended reasoning mode to mirror the complex chain-of-thought that precedes output by ChatGPT o3-mini-high and DeepSeek R1.

DeepSeek shattered my expectations by demonstrating that AI doesn’t necessarily always get worse as complexity increases, though Claude 3.5 Sonnet proved an impressively close runner-up. Can Claude 3.7 Sonnet’s reasoning one-up DeepSeek’s?

Let’s find out!

Testing The Same Components

To maintain consistency with my previous tests, I evaluated Claude 3.7 Sonnet against the same three components:

• <Kbd /> - Our atomic component representing keyboard keys

• <Breadcrumbs /> - Our molecular component for navigational breadcrumbs

• <Table /> - Our complex organism component for data display

Let's dive in and see how Claude 3.7 Sonnet performed in each case.

<Kbd />
✅ Passable Rough Draft

• Pattern: Standalone Component

• Approach #1: Individual Key Components

// Single key
<Kbd>A</Kbd>

// Key combination (manual arrangement)
<span>
  <Kbd>Ctrl</Kbd>
  <span>+</span>
  <Kbd>C</Kbd>
</span>

// With styling variants
<Kbd size="small" variant="outline">Tab</Kbd>

// Using special key constants
<Kbd>{KEY_SYMBOLS.COMMAND}</Kbd>

• Approach #2: Combination Support Built-in

// Single key
<Kbd>A</Kbd>

// Key combination as array
<Kbd keys={["Ctrl", "C"]} />

// Custom separator
<Kbd keys={["Cmd", "Option", "Esc"]} separator="+" />

// With styling variants
<Kbd keys={["Shift", "Tab"]} size="small" variant="outline" />

// Using key binding object
<Kbd keyBinding={{ 
  modifier: ["Ctrl", "Alt"],
  key: "Delete"
}} />

• Discrete Props:

  • Kbd: keys, keyBinding, separator, size, variant

• Ancillary Resources:

  • Functions: normalizeKeyNames(), formatKeyBinding()

  • Types: KeyBinding, KbdProps, KbdSize, KbdVariant

  • Constants: KBD_SIZE, KBD_VARIANT, KEY_SYMBOLS, PLATFORM_KEYS

Review

The last test for this component was the first time Claude really "wow!"’d me. Unlike ChatGPT o3-mini-high and DeepSeek R1, which considered but rejected a compound component approach, Claude’s lack of explicit reasoning actually led to a more exploratory result—one that felt closer to something that might actually be submitted to VSDS at VividSeats.

That said, Claude 3.7 also skipped the compound component approach, allowing some logical flaws to slip through.

• Approach #1 is simple and straightforward, but the way spans are used makes it unclear what the actual implementation would accomplish without variants.

• Approach #2 is cleaner, and while I initially questioned whether it was distinct enough, the switch from text child to a keys prop makes it a valid alternative.

• However, the difference between key and keyBinding is unclear beyond passing keyBinding to formatKeyBinding(). The extra structure for labelling modifiers also feels unnecessary.

Even if modifiers are needed labels, I’d avoid passing objects through props when possible—key/value pairs usually should just be explicit props instead:

<Kbd modifier={['Ctrl', 'Alt']} key="Delete" />

The best parts of this result are:
✅ Cross-platform considerations
✅ Well-aligned ancillary resources
✅ Better code quality (const assertions!?)

It would be even better if KbdSize and KbdVariant were inferred from the KBD_SIZE and KBD_VARIANT constants via typeof, but that’s something for review.

Overall, some details in the usage snippets are a bit dubious, but the output is solid enough to present. Now, let’s see what happens when we give Claude 3.7 more to work with!

<Breadcrumbs />
⚠️ Questionable

• Pattern: Compound component

• Approach #1: Compound Component with Explicit Items

  • Subcomponents: Breadcrumbs.Item

<Breadcrumbs testId="site-breadcrumbs">
  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item>
  <Breadcrumbs.Item href="/products/electronics">Electronics</Breadcrumbs.Item>
  <Breadcrumbs.Item active>Smartphones</Breadcrumbs.Item>
</Breadcrumbs>

• Approach #2: Compound Component with Custom Separator

  • Subcomponents: Breadcrumbs.Item, Breadcrumbs.Separator

<Breadcrumbs 
  testId="custom-breadcrumbs"
  separator={<Breadcrumbs.Separator>/</Breadcrumbs.Separator>}
>
  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
  <Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item>
  <Breadcrumbs.Item active>Categories</Breadcrumbs.Item>
</Breadcrumbs>

• Approach #3: Combination Support Built-in

const items: BreadcrumbItem[] = [
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Electronics', href: '/products/electronics' },
  { label: 'Smartphones', active: true }
];

<Breadcrumbs 
  testId="data-driven-breadcrumbs"
  items={items} 
/>

• Discrete Props:

  • Breadcrumbs: maxDisplayed, items (Approach #3), separator, truncate, onCollapse(), onExpand()

  • Breadcrumbs.Item: active, href, icon, onPress()

• Ancillary Resources:

  • Hooks: useBreadcrumbsContext(), useCollapsedItems()

  • Functions: formatBreadcrumbs()

  • Types: BreadcrumbItem, BreadcrumbsContextValue

  • Enums: BreadcrumbDisplayMode

  • Constants: DEFAULT_SEPARATOR, DEFAULT_MAX_DISPLAYED

Review

Approach #1 and Approach #3 are both passable, Approach #2 is not since it’s really just the same as Approach #1 but with an extra subcomponent. Unfortunately, this is enough of a loss of credibility to keep this result in the Questionable category, though it’s presentable if we just remove Approach #2.

Again, the code snippets are much better than Claude 3.5. The hooks make more sense and they align with other resources (e.g. useBreadcrumbsContext() and BreadcrumbsContextValue.) Interestingly, Claude 3.7 also described the return type of useCollapsedItems(), which is an object that includes some state and a method toggleCollapse().

For anyone curious about what BreadcrumbDisplayMode is, here you go!

enum BreadcrumbDisplayMode {
  All = "all",
  Collapsed = "collapsed",
  FirstLast = "firstLast"
}

<Table />
✅ Passable Rough Draft

• Pattern: Compound component

• Variants:

• Subcomponents:

• Approach #1: Full Compound Structure with Context

// Usage example
const BasicTable = () => (
  <Table testId="user-data-table">
    <Table.Caption>List of active users</Table.Caption>
    <Table.Header>
      <Table.Row>
        <Table.HeaderCell>Name</Table.HeaderCell>
        <Table.HeaderCell>Email</Table.HeaderCell>
        <Table.HeaderCell>Role</Table.HeaderCell>
      </Table.Row>
    </Table.Header>
    <Table.Body>
      {users.map((user) => (
        <Table.Row key={user.id}>
          <Table.Cell>{user.name}</Table.Cell>
          <Table.Cell>{user.email}</Table.Cell>
          <Table.Cell>{user.role}</Table.Cell>
        </Table.Row>
      ))}
    </Table.Body>
    <Table.Footer>
      <Table.Row>
        <Table.Cell colSpan={3}>Total Users: {users.length}</Table.Cell>
      </Table.Row>
    </Table.Footer>
  </Table>
);

// Sortable example
const SortableTable = () => {
  const [sortConfig, setSortConfig] = useState<SortConfig>({ key: 'name', direction: 'ascending' });
  
  const handleSort = (key: string) => {
    // Sort logic here
  };
  
  return (
    <Table testId="sortable-user-table">
      <Table.Header>
        <Table.Row>
          <Table.HeaderCell sortable onSort={() => handleSort('name')} sortDirection={sortConfig.key === 'name' ? sortConfig.direction : undefined}>
            Name
          </Table.HeaderCell>
          <Table.HeaderCell sortable onSort={() => handleSort('email')} sortDirection={sortConfig.key === 'email' ? sortConfig.direction : undefined}>
            Email
          </Table.HeaderCell>
          <Table.HeaderCell>Role</Table.HeaderCell>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        {/* Sorted users */}
      </Table.Body>
    </Table>
  );
};

• Approach #2: Compositional with Column Definition

// Usage example
const ColumnDefinedTable = () => {
  const columns: Array<ColumnDefinition> = [
    { key: 'name', header: 'Name', sortable: true },
    { key: 'email', header: 'Email', sortable: true },
    { key: 'role', header: 'Role' }
  ];
  
  return (
    <Table 
      testId="user-table-defined" 
      columns={columns}
      data={users}
      caption="List of active users"
      onSort={(key, direction) => { /* Handle sort */ }}
    >
      <Table.Pagination 
        totalItems={users.length} 
        itemsPerPage={10} 
        onPageChange={(page) => { /* Handle page change */ }} 
      />
    </Table>
  );
};

// With custom cell rendering
const CustomCellTable = () => {
  const columns: Array<ColumnDefinition> = [
    { 
      key: 'name', 
      header: 'Name', 
      render: (user) => <strong>{user.name}</strong> 
    },
    { 
      key: 'status', 
      header: 'Status', 
      render: (user) => (
        <Table.StatusCell status={user.status} />
      )
    },
    { 
      key: 'actions', 
      header: 'Actions', 
      render: (user) => (
        <Table.ActionCell>
          <Button onPress={() => editUser(user)}>Edit</Button>
          <Button onPress={() => deleteUser(user)}>Delete</Button>
        </Table.ActionCell>
      )
    }
  ];
  
  return (
    <Table 
      testId="custom-cell-table" 
      columns={columns}
      data={users}
    />
  );
};

• Discrete Props:

  • Table: columns, data (Approach #2), striped, bordered, compact, hoverable, sortConfig, onSort()

  • Table.Row: selected, onPress()

  • Table.Cell: colSpan, rowSpan, align, truncate

  • Table.HeaderCell: colSpan, rowSpan, align, sortable, sortDirection, onSort()

  • Table.Pagination: currentPage, totalItems, itemsPerPage, onPageChange()

• Ancillary Resources:

  • Hooks: useSortableTable(), useSelectableTable(), usePaginatedTable(), useTable()

  • Functions: sortTableData(), filterTableData(), paginateTableData()

  • Types: ColumnDefinition, SortConfig, SortableTableResult, SelectableTableOptions, SelectableTableResult, PaginationOptions, PaginatedTableResult, TableContext

  • Enums: SortDirection, TableCellAlignment

  • Constants: DEFAULT_ITEMS_PER_PAGE, DEFAULT_PAGE_SIZES, DEFAULT_SORT_DIRECTION

Review

At first glance, both approaches feel over-engineered, and I wasn’t sure Approach #2 was distinct enough to be a true alternative. But looking closer, I noticed something I hadn’t seen before.

Compound components are only mutually exclusive to standalone components—they’re often used as base components both inside and outside the design system. When this happens within the design system, we call it a Compound-as-Base Hybrid.

Typically, compound components take subcomponents as children, but some cases invert this relationship, allowing a subcomponent (often a Group) to take the parent as children instead.

A New Pattern Emerges

Approach #2 does something interesting with Table.ActionCell and Table.StatusCell. Instead of using Table.Cell as just another subcomponent, Claude 3.7 treats it as a base subcomponent—essentially creating a base pattern within a compound component.

I’ve seen entire compound components used as base components, but I’ve never come across a compound component with a base subcomponent like this.

Potential Controversy

Is this a novel pattern or just so rare that I haven't encountered it before? Hard to say. Typically, base component variants are more generic—for example, atomic components like Button use system colors (error, info, success, warning, etc.) to compose specialized variants like InfoButton, SuccessButton, etc.

For more complex components, specialized variants are usually built outside the design system, composing agnostic design system components into business-specific variants—think a Card component spawning NewsCard, BlogCard, and OfferCard.

The biggest mistake teams make when building design systems is overfitting components to their specific business problems. And while it’s okay to tailor implementation details to company needs, a design system’s core purpose is to solve common, business-agnostic UI challenges.

A good design system should be flexible enough that if your org pivoted to a new industry, you could rebuild your platform using the same components. If your design system is entangled with business logic, you’re doing it wrong.

Applying This Pattern

This is where this new pattern could be controversial. For atomic components, specialization typically aligns with business-agnostic concerns like intent and system colors. But are Table.ActionCell and Table.StatusCell really business-agnostic enough to live in the design system?

Some might argue this makes the pattern an anti-pattern, but I see potential use cases—particularly in something like a Form component, where Form.Input could act as a base for specialized variants like Form.NumericalInput, Form.ColorInput, Form.PhoneInput, Form.EmailInput, etc.

Bringing this to the VSDS team would spark quite a debate—a roundtable discussion, if you will. And honestly? We love a good roundtable!

Share

Subscribe now

A Refresher On Code Mockups

Last week, I introduced code mockups—a structured approach to designing UI components before they’re built. This method improves scalability and maintainability, but it’s time-consuming, requiring deep exploration, iteration, and validation.

AI has the potential to change that. By automating pattern exploration, generating usage examples, and enforcing best practices, Engineers can iterate on AI-assisted scaffolding—focusing on high-impact decisions instead of repetitive setup.

In this article, I’ll explore how AI enhanced the code mockup workflow, making it faster, more efficient, and accessible. Plus, I’ll share how we’re applying it at Vivid Seats to streamline design system development.

Let’s dive in.

What Are We Working With?

1. The Workflow

Copy everything from Code Mockups For Enterprise-Strength Design System Components to the end and paste it in The Prompt, replacing {{WORKFLOW}}. Remember to strip out any promotional sections.

2. The Template

Copy everything in the code block below and paste it in The Prompt, replacing {{TEMPLATE}}:

# Code Mockup: <Component /> [Template]

**Category:**

**Pattern:**

Choose One:

- Standalone Component
- Compound Component
- Base Component
- Compound-as-Base-Hybrid

**Key Stakeholders:**

- Recommend: _Your Name_
- Sponsor: _Design System Maintainer Name_
- Implement: _The Engineer doing the work if known_

> **High-level Details**
> _The code below is meant to give an idea of what the implementation in
> Next might look like from a birds-eye view. It is not meant to (and
> will not) be 100% correct; actual implementation details may vary._

## Pattern Notes

> **DELETE BEFORE REVIEW**
> _Add any details to this section that explain alterations of the
> pattern or ways we might expect the pattern to evolve or change as
> this component scales in complexity. Remove the entire section if you
> have no notes prior to review._

## Variants

> **DELETE BEFORE REVIEW**
> _Delete this entire section if this is not a **Compound Component** or
> **Compound-as-Base-Hybrid**. Otherwise, rename the below keeping the
> naming convention for **Base Components** using the name of the base
> as the suffix in variant names (e.g. variants of a base component
> `Button` should be named `ThisButton`, `ThatButton`, etc.)_

Component will be used as a base in the following shared components:

- `VariantComponent`
- `VariantComponent`
- `VariantComponent`
- `VariantComponent`

## Composition Strategy

> **DELETE BEFORE REVIEW**
> _Add mocked up component usage code snippets in this section._

### Approach #1:

### Approach #2:

## Props

### Component

> **DELETE BEFORE REVIEW**
> _Add to the following set of minimum required props. Check our prop
> standards to ensure consistency in our component contracts.
> Review guidelines to ensure props avoid becoming interdependent.
> Leave comments or footnotes exploring alternative approaches for
> specific prop(s) as needed._

| PROP      | TYPE                                        | USAGE    |
| --------- | ------------------------------------------- | -------- |
| as        | `keyof JSX.IntrinsicElements | ElementType` | OPTIONAL |
| className | `string`                                    | OPTIONAL |
| error     | `Error  | null`                             | OPTIONAL |
| loading   | `boolean`                                   | OPTIONAL |
| testId    | `string`                                    | OPTIONAL |

### Component.SubComponent

> **DELETE BEFORE REVIEW**
> _Add to the following set of minimum required props. Check our prop
> standards to ensure consistency in our component contracts.
> Review guidelines to ensure props avoid becoming interdependent.
> Leave comments or footnotes exploring alternative approaches for
> specific prop(s) as needed._

| PROP      | TYPE                                        | USAGE    |
| --------- | ------------------------------------------- | -------- |
| as        | `keyof JSX.IntrinsicElements | ElementType` | OPTIONAL |
| className | `string`                                    | OPTIONAL |
| error     | `Error  | null`                             | OPTIONAL |
| loading   | `boolean`                                   | OPTIONAL |
| testId    | `string`                                    | OPTIONAL |

> **DELETE BEFORE REVIEW**
> _Add one of these sections for each subcomponent if the component is a
> **Compound Component** or **Compound-As-Base-Hybrid**. Remove this
> entire section if the component is a **Standard Component** or **Base
> Component**._

> **DELETE BEFORE REVIEW**
> _The following section(s) are optional but recommended so that we
> don’t keep reinventing wheels._

## Utils

### Hooks

### Functions

### Types & Interfaces

### Enums & Constants

3. The Prompt

• [text surrounded by brackets] is optional.

• {{TEXT}} using handlebars syntax indicates where specific content should be injected.

• (pick one: foo|bar|baz) indicates where you should pick one of the provided options.

Write a Code Mockup for a new <Component /> component[ implemented as a (pick: standard|compound|base) component].

Here's the workflow for writing a Code Mockup:

"{{WORKFLOW}}"

Here is the list of all Standardized Props for context:

| PROP            | TYPE                                         | USAGE    |
| --------------- | -------------------------------------------- | -------- |
| as              | `keyof JSX.IntrinsicElements \| ElementType` | OPTIONAL |
| animated        | `boolean`                                    | OPTIONAL |
| className       | `string`                                     | OPTIONAL |
| children        | ReactNode                                    | OPTIONAL |
| disabled        | `boolean`                                    | OPTIONAL |
| error           | `Error  \| null`                             | OPTIONAL |
| fullWidth       | `boolean`                                    | OPTIONAL |
| loading         | `boolean`                                    | OPTIONAL |
| testId          | `string`                                     | REQUIRED |
| onPress()       | `PressEventHandler`                          | OPTIONAL |
| onPressEnter()  | `EnterEventHandler`                          | OPTIONAL |
| onPressEscape() | `EscapeEventHandler`                         | OPTIONAL |
| onPressSpace()  | `SpaceEventHandler`                          | OPTIONAL |
| onPressTab()    | `TabEventHandler`                            | OPTIONAL |
| onTabBack()     | `TabBackEventHandler`                        | OPTIONAL |


Use this template for the Code Mockup:

```Markdown
{{TEMPLATE}}
```

[Optionally, add a short description of the differing approaches you're looking into in your mockups. Design Responsibility? Splitting up components? Any other details that are relevant?]

The response may be output as regular text; markdown from the template may be applied instead of preserved. Do not complete the Key Stakeholders section, as it will be filled out later. Remember that code mockups for design system components are about abstracting the underlying mechanics, so do not generate any code which includes implementation details of this component or its potential ancillary dependencies. Utility functions, hooks, enums, constants, etc should be described in juxtaposition to each other with regard to potential approaches. Prop and ancillary types and interfaces are an exception to this rule, since they are separate from implementation. Remember when naming types and interfaces that they should not know they are types and interfaces respectively, so do not prefix names with `T` or `I`, nor include any other such redundancy like ending the name with `Type`, or `Data` for types/interfaces that represent data. Generics and type parameters should use capitalized single letter names from the letter `T`, incrementing one letter of the alphabet for each additional generic or type parameter. Arrays should use generic syntax (i.e. `Array<T>` instead of `T[]`.) Do not use object literal types unless writing a mapped type, since index mapping and key remapping are not allowed in interfaces. Properties in interfaces should be `readonly` except in cases where they are intentionally mutable; likewise, arrays should be typed as `ReadonlyArray`s unless they are intentionally mutated in place. Destructure type and value imports from React rather than using the `React` namespace with a default import named React. Do not use "style" props like `marginTop` or `border` unless they are already included on the list of Standardized Props. Keep usage snippets as focused as possible, and do not include surrounding boilerplate unless absolutely necessary.

The Results

I trialed and refined this process with multiple models to see which provides the best jumping-off point, and the results were not what I was expecting.

I wanted to see how AI would handle heterogenous levels of complexity, so I experimented with the following components:

• <Kbd />
  An atomic component so simple one might wonder why it exists at all when one could just use the <kbd> HTML element directly.

• <Breadcrumbs />
  A molecule component just complex enough that it can be implemented with any of the three main patterns described in The Workflow.

• <Table />
  An organism component too complex to be anything other than a compound component.

The only prompt which specified the pattern was the prompt for the Table component. Other than this, I was hands off and did not add any context or details about how the component could or should be built.

ChatGPT o3

<Kbd /> - ⚠️ Questionable
ChatGPT o3

• Pattern: Standalone component

• Approach #1: Basic Usage

<Kbd testId="kbd-basic">Enter</Kbd>

• Approach #2: Composite Key Sequence

<Kbd className="custom-kbd" testId="kbd-sequence">
  <span>Ctrl</span> + <span>Shift</span> + <span>Esc</span>
</Kbd>

• No discrete props

• No ancillary resources

Review

Approach #1 closely follows the behavior of the <kbd> HTML element, making it a familiar and intuitive choice.

Approach #2 is interesting because it supports multiple keys, though the usage snippet demonstrates bad technique by wrapping keys in spans.

It also looks like the AI misunderstood the testId prop being marked as REQUIRED in the Standardized Props table. This designation simply means the component must support testId, not that every instance must include it. In general, props—especially standardized ones—should rarely be mandatory unless there's a compelling reason to enforce their usage.

<Breadcrumbs /> - ❌ Not Passable
ChatGPT o3

• Pattern: Compound component

• Subcomponents: Breadcrumbs.Item

• Approach #1: (the AI did not name either approach)

<Breadcrumbs testId="breadcrumbs">
  <Breadcrumbs.Item as="a" href="/" testId="breadcrumb-home">
    Home
  </Breadcrumbs.Item>
  <Breadcrumbs.Item as="a" href="/products" testId="breadcrumb-products">
    Products
  </Breadcrumbs.Item>
  <Breadcrumbs.Item testId="breadcrumb-current">
    Current Page
  </Breadcrumbs.Item>
</Breadcrumbs>

• Approach #2:

const breadcrumbItems = [
  { label: 'Home', href: '/', testId: 'breadcrumb-home' },
  { label: 'Products', href: '/products', testId: 'breadcrumb-products' },
  { label: 'Current Page', testId: 'breadcrumb-current' },
];

<Breadcrumbs testId="breadcrumbs" className="custom-breadcrumbs">
  {breadcrumbItems.map((item, index) => (
    <Breadcrumbs.Item 
      key={index}
      as={item.href ? 'a' : 'span'}
      href={item.href}
      testId={item.testId}
      disabled={item.disabled}
    >
      {item.label}
    </Breadcrumbs.Item>
  ))}
</Breadcrumbs>

• No discrete props

• Ancillary Resources:

  • Hooks: useBreadcrumbsContext() and an optional useResponsiveBreadcrumbs() hook to handle dynamic layout adjustments

  • Functions: formatBreadcrumbs()

  • Types: BreadcrumbsProps, BreadcrumbItemProps

  • Constants: BREADCRUMBS_SEPARATOR

Review

This fails because it’s essentially the same approach served two different ways.

The subcomponent naming is lacking in refinement—Breadcrumbs.Item feels okay but a bit generic and uninspired. A more semantic choice like Breadcrumbs.Crumb or a more streamlined option like Breadcrumbs.Link would improve clarity and usability.

Then there’s formatBreadcrumbs()—which, as far as I can tell, isn’t even being used. The output describes it as a function that converts data into an array of Breadcrumbs.Item subcomponents, but the usage snippets either handle this conversion manually or skip it altogether by passing subcomponents as children. Even if it were used, it should probably be a custom hook since it’s returning presentation logic, not just transformed data.

<Table /> - ❌ Not Passable
ChatGPT o3

• Pattern: Compound component (the output implies more of a Compound-as-Base Hybrid by including specialized variants)

• Variants: DataTable, SortableTable, PaginatedTable, ResponsiveTable

• Subcomponents: Table.Header, Table.Row, Table.Cell, Table.Body, Table.Footer, Table.Caption

• Approach #1: Basic Table Structure

<Table testId="basic-table" className="custom-table">
  <Table.Header>
    <Table.Row>
      <Table.Cell as="th">Name</Table.Cell>
      <Table.Cell as="th">Age</Table.Cell>
      <Table.Cell as="th">Location</Table.Cell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Jane Doe</Table.Cell>
      <Table.Cell>29</Table.Cell>
      <Table.Cell>New York</Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>John Smith</Table.Cell>
      <Table.Cell>34</Table.Cell>
      <Table.Cell>San Francisco</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

• Approach #2: Table with Footer and Optional Caption

  I decided to omit the code snippet for this to save space since its the same as the above but with:

<Table.Caption>Employee Directory</Table.Caption>

• No discrete props

• Ancillary Resources:

  • Hooks: useTableSort() and an optional useTablePagination() hook

  • Functions: calculateColumnWidths(), mergeCellStyles()

  • Types: Prop types for each subcomponent

  • Enums: TableSortDirection (e.g. ASC and DESC)

  • Constants: DEFAULT_CELL_PADDING

Review

This fails pretty much right off the bat because the usage snippets show Table.Header and Table.Footer in both approaches but the title of Approach #2 implies that basic table structure should not include a header and footer.

Also, only standardized props? No discrete props? Not even a sortOrder prop that uses a TableSortDirection?

Claude 3.5 Sonnet

<Kbd /> - ✅ Passable Rough Draft
Claude 3.5 Sonnet

• Pattern: Standalone or Compound Component

• Approach #1: Single Component with Key Combinations

// Individual key
<Kbd>⌘</Kbd>

// Key combination
<Kbd>⌘ + K</Kbd>

// Sequential combination
<Kbd>g g</Kbd>

// With custom separator
<Kbd separator="+">⌘ K</Kbd>

// Nested in text
Press <Kbd>⌘</Kbd> + <Kbd>K</Kbd> to open the command palette

• Approach #2: Compound Component with Specialized Parts

  • Subcomponents: Kbd.Key, Kbd.Group, Kbd.Separator

// Individual key
<Kbd.Key>⌘</Kbd.Key>

// Key combination
<Kbd.Group>
  <Kbd.Key>⌘</Kbd.Key>
  <Kbd.Separator>+</Kbd.Separator>
  <Kbd.Key>K</Kbd.Key>
</Kbd.Group>

// Sequential combination
<Kbd.Group sequential>
  <Kbd.Key>g</Kbd.Key>
  <Kbd.Key>g</Kbd.Key>
</Kbd.Group>

• Discrete Props:

  • Kbd: separator, size, variant

  • Kbd.Group: sequential

• Ancillary Resources:

  • Types: Prop types for the component in Approach #1 and for each subcomponent in Approach #2 except for Kbd.Separator

  • Enums: KbdSize, KbdVariant

  • Constants: DEFAULT_KBD_SEPARATOR

Review

The difference in quality between this and ChatGPT o3 is Grand Canyon huge. This is mind-blowingly better. Multiple patterns, discrete props, utils, the works! On a component this simple, output this good can be used with only minor refinement.

If an Engineer at Vivid Seats brought this forward for review with the VSDS team, my main feedback would be that Kbd.Key should just be the parent Kbd so we don’t bloat complexity with redundant subcomponents. While compound components typically take multiple subcomponents as children, in some cases they can use an inverted form which allows for a subcomponent (typically Group) to take the parent as children instead.

I would also dig in a bit to understand why including variants is necessary to meet requirements for this component. It’s not out of the realm of possibility, but without a mockup backing it up it feels over-Engineered. If we actually have a business case for KbdVariants, then naturally a question of whether we should consider a Base Component pattern for these variants would follow.

Also, the Kbd.Separator subcomponent is unnecessary. Given the way keyboard commands chain together, we have no reason not to assume that “+” should be the operator until or unless business requirements make it clear otherwise. That said, if we kept this subcomponent, it should use a string-only semantic as prop instead of accepting a text child each time so that we can rely on DEFAULT_KBD_SEPARATOR unless we need to override it.

<Kbd.Separator as="+" />

Lastly, size should be fontSize, if we include a specialized prop for this at all. As an inline element, it’s size should scale conformally with the size of the text it contains, so there’s no need for an enum like KbdSize.

I’d probably still lean towards Approach #1, but this at least gave us an idea of what another possibility might look like, even if just to confirm it’s too much. All in all, a very impressive jumping-off point.

<Breadcrumbs /> - ✅ Passable Rough Draft
Claude 3.5 Sonnet

• Pattern: Standalone or Compound Component

• Approach #1: Data-Driven Composition

<Breadcrumbs
  items={[
    { label: "Dashboard", href: "/dashboard" },
    { label: "Projects", href: "/dashboard/projects" },
    { label: "Project Details" }
  ]}
/>

• Approach #2: Explicit Composition

  • Subcomponents: Breadcrumbs.Item, Breadcrumbs.Separator

<Breadcrumbs>
  <Breadcrumbs.Item>
    <Link href="/dashboard">Dashboard</Link>
  </Breadcrumbs.Item>
  <Breadcrumbs.Separator>/</Breadcrumbs.Separator>
  <Breadcrumbs.Item>
    <Link href="/dashboard/projects">Projects</Link>
  </Breadcrumbs.Item>
  <Breadcrumbs.Separator>/</Breadcrumbs.Separator>
  <Breadcrumbs.Item aria-current="page">
    Project Details
  </Breadcrumbs.Item>
</Breadcrumbs>

• Discrete Props:

  • Breadcrumbs: separator

  • Breadcrumbs.Item: current

• Ancillary Resources:

  • Hooks: useBreadcrumbs() vs useRouteAsBreadcrumbs()

  • Functions: createBreadcrumbsFromPath() vs createBreadcrumbsFromRoutes()

  • Types: BreadcrumbItem, BreadcrumbContext

Review

Some criticism from the Kbd component carry over, like Breadcrumbs.Separator using children instead of a prop as needed. But the output is, again, miles better than ChatGPT o3.

The best thing about this output is that it includes Link, showing how we can use other components compositionally. It also clearly juxtaposes two approaches for hooks and reflects the potential downstream impact of these approaches in subsequent utility functions.

Claude 3.5 Sonnet also used the Pattern Notes section to outline four ways we might want to change or improve the component in the future.

I would lean towards Approach #2 and give it a semantic as prop so that we can streamline the usage like this:

<Breadcrumbs>
  <Breadcrumbs.Item as={Link} href="/dashboard">
    Dashboard
  </Breadcrumbs.Item>
  <Breadcrumbs.Separator />
  <Breadcrumbs.Item as={Link} href="/dashboard/projects">
    Projects
  </Breadcrumbs.Item>
  <Breadcrumbs.Separator />
  <Breadcrumbs.Item aria-current="page">
    Project Details
  </Breadcrumbs.Item>
</Breadcrumbs>

<Table /> - ⚠️ Questionable
Claude 3.5 Sonnet

• Pattern: Compound Component

• Subcomponents: Table.Header, Table.Body, Table.Row, Table.Body, Table.Pagination

• Approach #1: Explicit Structure

<Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell sortable>Name</Table.HeaderCell>
      <Table.HeaderCell>Email</Table.HeaderCell>
      <Table.HeaderCell align="right">Status</Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell>Jane Cooper</Table.Cell>
      <Table.Cell>jane@example.com</Table.Cell>
      <Table.Cell align="right">Active</Table.Cell>
    </Table.Row>
  </Table.Body>
  <Table.Footer>
    <Table.Pagination />
  </Table.Footer>
</Table>

• Approach #2: Data-Driven

<Table 
  data={users}
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'email', header: 'Email' },
    { key: 'status', header: 'Status', align: 'right' }
  ]}
>
  <Table.Header />
  <Table.Body>
    {(row) => (
      <Table.Row key={row.id}>
        <Table.Cell>{row.name}</Table.Cell>
        <Table.Cell>{row.email}</Table.Cell>
        <Table.Cell align="right">{row.status}</Table.Cell>
      </Table.Row>
    )}
  </Table.Body>
  <Table.Pagination />
</Table>

• Discrete Props:

  • Table: data, columns, sortable

  • Table.Header: sticky

  • Table.HeaderCell: align, sortable, sortDirection, onSort

  • Table.Row: selected

  • Table.Pagination: page, pageSize, onPageChange()

• Ancillary Resources:

  • Events: SortEvent, SortEventHandler, PageChangeEvent, PageChangeEventHandler

  • Hooks: useTableSort(), useTablePagination(), useTableSelection(), useTableFilters()

  • Types: Column, TableData, SortState, Alignment, SortDirection, RenderFunction<T>

Review

The output for this one reaches the limits I think for what AI will be able to do here on its own, at least for now.

These two approaches aren’t really mutually exclusive, you’ll probably end up doing both depending on how the component is used throughout the app. Better approaches would be to compare heterogeneous levels of design responsibility, or alternatively juxtaposing a basic compound component with no pagination, sorting, filtering, etc against a more complex version with this more advanced functionality to get a sense of how the component might scale or be built iteratively.

And this is why Tables are hard. At its core, the Table component operates as an ordered functional pipeline, where raw data flows through a series of pure transformations in a specific order before rendering. Each transformation is a function that takes the current dataset and returns a new, modified version:

paginate(sort(filter(search(data))))

We see a hook for filtering, but only sorting seems to be really thought out.

The best part of this output is that there are custom events! Custom events are also hard because they require special handling, don’t propagate predictably, and break framework optimizations. Instead of subclassing Event or using CustomEvent, extend native event types by defining subtypes in TypeScript for safer, more predictable behavior. Since we know that SortEvent and PageChangeEvent would be dispatched by pressing a button, we should type them like this:

type SortEvent<T> = PointerEvent<T>
type SortEventHandler<T> = PointerEventHandler<T>

type PageChangeEvent<T> = PointerEvent<T>
type PageChangeEventHandler<T> = PointerEventHandler<T>

In VSDS, we have a custom PressEvent to make it easier to share code between Mobile and Web, so we would create subtypes of that instead. The output, however, included only basic interfaces for these events.

interface SortEvent {
  readonly column: string
  readonly direction: SortDirection
}

interface PageChangeEvent {
  readonly page: number
  readonly pageSize: number
}

This might be a quirk we can iron out with more explicit direction in the prompt, but for now it— combined with the rudimentary approaches are enough to put this one in the Questionable category, but not at all a bad start!

DeepSeek R1

<Kbd /> - ⚠️ Questionable
DeepSeek R1

• Pattern: Standalone Component

• Approach #1: Basic Semantic Usage

// Single key
<Kbd testId="enter-key">Enter</Kbd>

// Disabled state
<Kbd disabled testId="disabled-key">⌘</Kbd>

// Custom element with animation
<Kbd as="span" animated testId="animated-key">Tab</Kbd>

• Approach #2: Keyboard Shortcut Grouping

// Composition with other elements
<div className="shortcut-group">
  <Kbd testId="mod1">Ctrl</Kbd> + 
  <Kbd testId="mod2">Alt</Kbd> + 
  <Kbd testId="main-key">Del</Kbd>
</div>

• No Discrete Props

• Ancillary Resources:

  • Types: StandardKbdProps

Review

This output feels a lot closer to ChatGPT o3. It doesn’t actually give us two different approaches, just two different use-cases. Most interestingly though is that, according to DeepSeek’s exposed inner monologue, it briefly considered a compound component before deciding not to explore that pattern. This makes me think that with a bit of massaging, the prompt could be Engineered to yield more exploratory results.

We don’t really need more than one pattern here, so this output is Questionable at best.

<Breadcrumbs /> - ✅ Passable Rough Draft
DeepSeek R1

• Pattern: Compound Component

• Approach #1: Explicit Composition

  • Subcomponents: Breadcrumbs.Item, Breadcrumbs.Separator

<Breadcrumbs testId="nav-trail">
  <Breadcrumbs.Item href="/">Home</Breadcrumbs.Item>
  <Breadcrumbs.Separator />
  <Breadcrumbs.Item href="/products">Products</Breadcrumbs.Item>
  <Breadcrumbs.Separator>
    <IconChevronRight size={12} />
  </Breadcrumbs.Separator>
  <Breadcrumbs.Item isCurrent>Winter Collection</Breadcrumbs.Item>
</Breadcrumbs>

• Approach #2: Automated Separation

<Breadcrumbs 
  testId="auto-trail"
  separator={<IconSlash size={10} />}
  items={[
    { href: '/', content: 'Home' },
    { href: '/settings', content: 'Settings' },
    { content: 'Profile' }
  ]}
/>

• Discrete Props:

  • Breadcrumbs: items, separator

  • Breadcrumbs.Item: isCurrent

• Ancillary Resources:

  • Hooks: useBreadcrumbItems()

  • Types: BreadcrumbItem, BreadcrumbSeparatorProps

  • Constants: BREADCRUMB_ARIA_LABEL, CURRENT_PAGE_ARIA_LABEL

Review

This output is really interesting because it felt Questionable at first but, after thinking over it a bit, I’ve realized that this Passable and actually slightly outperformed Claude 3.5 Sonnet.

Approach #2 is a bit worse than its Claude counterpart. I mean really, an IconSlash component? But this does at least give a sense of how things could be handled compositionally, and its easy enough to revise this part to separator=”/”.

Approach #1 is a bit better than its Claude counterpart because Breadcrumbs.Separator is used correctly as a self-closing childless element.

<Table /> - ✅ Passable Rough Draft
DeepSeek R1

• Pattern: Compound Component

• Subcomponents: Table.Header, Table.Head, Table.Body, Table.Row, Table.Cell

• Approach #1: Basic Composition

<Table testId="user-table" fullWidth>
  <Table.Header>
    <Table.Head>Name</Table.Head>
    <Table.Head align="end">Age</Table.Head>
  </Table.Header>
  
  <Table.Body>
    <Table.Row>
      <Table.Cell>John Doe</Table.Cell>
      <Table.Cell align="end">30</Table.Cell>
    </Table.Row>
    
    <Table.Row disabled>
      <Table.Cell>Jane Smith</Table.Cell>
      <Table.Cell align="end" loading>{/* Shows skeleton */}</Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

• Approach #2: Enhanced Features

<Table testId="sortable-table" error={fetchError}>
  <Table.Header>
    <Table.Head 
      sortable 
      sortDirection="asc"
      onSort={handleSort}
    >
      Name
    </Table.Head>
    
    <Table.Head 
      align="end"
      sortable
      sortDirection="desc"
      onSort={handleAgeSort}
    >
      Age
    </Table.Head>
  </Table.Header>

  {!fetchError && (
    <Table.Body loading={isLoading}>
      {/* Skeleton rows when loading */}
      {data.map((item) => (
        <Table.Row key={item.id}>
          <Table.Cell>{item.name}</Table.Cell>
          <Table.Cell align="end">{item.age}</Table.Cell>
        </Table.Row>
      ))}
    </Table.Body>
  )}
</Table>

• Discrete Props:

  • Table.Head: align, sortable, sortDirection, onSort

  • Table.Cell: align, colSpan

• Ancillary Resources:

  • Events: SortEvent, SortEventHandler

  • Types: Alignment, SortDirection

  • Constants: ALIGN_CLASSES, SORT_ICON_DIRECTION

Review

This output is wild! DeepSeek R1’s MoE reasoning shines through here. Though not as sophisticated as a code mockup for a Table component realistically would be, which may also touch on heterogenous levels of design responsibility, this output at least considers how our Table might impact the wider codebase as more is added to it.

And the code just feels cleaner than what we got out of ChatGPT o3 or Claude 3.5 Sonnet. That said, though, this output does have the same issues with custom events as Claude 3.5 Sonnet, so I’m pretty sure we need to be more explicit about expectations for custom events in the prompt.

Key Takeaways

This experiment showed that AI can accelerate UI code mockups, but human oversight is still essential. More importantly, I assumed that AI would get worse as components got more complex, but this did not turn out to be the case. In fact:

🔹 DeepSeek R1 is best for more complex components – Claude 3.5 Sonnet and ChatGPT o3 both struggled proportionally as components grew in complexity.

🔹 Claude 3.5 Sonnet is best for everything else – ChatGPT o3 lagged behind in generating substantive approaches, but Claude handled atomic and molecule-level components with ease.

AI isn’t ready to take on everything from planning to execution, but it can speed up ideation and exploration. The future of AI-assisted UI development isn’t just about velocity—it’s about leveraging AI to achieve new professional levels of craftsmanship without hitting any speed bumps.

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

Read more

Subscribe now

As [YEAR]…

Read more