Coder Legion - Recent posts tagged design-systems

Building a Design System Alone: What I Learned and What I Would Skip

Wed, 14 Oct 2026 05:13:20 +0000

Most of the writing about design systems is written by people who built them for large teams, at well-resourced companies, with dedicated time and tooling budgets. It is useful writing. It is also written for a situation that most designers and developers building real products will never be in.

The reality for a solo practitioner is different. You are not staffing a design systems team. You are not writing contribution guidelines for thirty engineers. You are one person trying to build something consistent enough that it does not become a liability as the product grows, without that effort becoming a second job that competes with the actual product.

I built a design system alone, in Figma, for a product I was designing and developing simultaneously. This post is about what that experience taught me: what was worth the investment, what I would approach differently, and what I wasted time on because I was solving for the wrong goal.

The wrong goal, it turned out, was building a system that scales. What I actually needed was a system that is consistent today and flexible enough to grow without being rebuilt. Those sound similar. They produce very different systems.

The wrong goal is building a system that scales. The right goal is building a system that is consistent today and flexible enough to grow without being rebuilt.

WHY THE WRONG GOAL IS SO EASY TO ADOPT

Design system content is aspirational by nature. The examples are polished. The documentation is thorough. The component libraries are comprehensive. Reading enough of it creates a mental model of what a design system is supposed to look like, and that model is almost always bigger and more elaborate than what a solo practitioner actually needs.

So you start building toward that model. You create a full token structure before you have designed enough screens to know which decisions are actually recurring. You document components before the components themselves are stable. You invest in a level of abstraction that makes sense when ten engineers are consuming the system and makes no sense when the only consumer is you.

The overhead accumulates quietly. Maintaining the system starts to feel like work that competes with using it. And at some point you realise that the system you built is designed for a team that does not exist yet, at a scale you have not reached, for a product whose requirements are still changing.

The discipline that actually serves a solo practitioner is narrower and more honest: build the minimum system that eliminates the decisions you would otherwise make repeatedly, and no more.

WHAT I BUILT IN FIGMA AND WHY

Everything lived in Figma. No Storybook, no design tokens exported to code, no separate documentation site. Just a well-organised Figma file that served as the single source of truth for every visual decision in the product.

The structure was straightforward.

A foundations page

One page for the decisions that everything else inherits from. Colour styles, text styles, spacing values, border radius, and shadow definitions. These were defined once and applied as Figma styles throughout every component and every screen.

The discipline here was restraint. Not every colour the product uses needs a named style. The ones that carry meaning, primary, secondary, surface, border, error, success, need names. The rest can be one-off values. Naming everything creates maintenance overhead without adding clarity.

A components page

One page for reusable UI elements. Buttons, inputs, cards, badges, navigation elements, modals. Each component built as a Figma component with variants for the states that actually exist in the product: default, hover, active, disabled, error.

The principle I applied consistently was to only build variants I had already designed in context. Not variants I might need. Variants that existed somewhere in the product already. This kept the component library grounded in real decisions rather than speculative ones, and it meant every component had a concrete use case rather than an abstract one.

A patterns page

One page for recurring compositions: form layouts, empty states, loading states, error states, page headers. These are not components in the atomic sense but they are decisions that recur and benefit from being made once rather than remade on every screen.

This page turned out to be more valuable than the components page in day to day practice, because the decisions it captured were higher level and more consequential. Getting the empty state pattern right once meant every empty state in the product communicated consistently, without revisiting the decision each time.

A patterns page turned out to be more valuable than the components page. Higher level decisions, made once, applied everywhere.

WHAT I WOULD APPROACH DIFFERENTLY

The honest answer is not that I made one big mistake I would undo. It is that I consistently solved for the wrong level of abstraction in the early stages, building infrastructure for decisions that had not stabilised yet.

I defined tokens before I had enough screens

Token structures make sense when you have enough design decisions to know which values are truly recurring and which are one-offs. In the early stages of a product, you do not have that information. You have guesses.

I built a colour token structure early, based on what I thought the product would need, and revised it three times as the product evolved. Each revision required updating every component that referenced the old tokens. The overhead was not catastrophic but it was real, and it was entirely self-inflicted.

The better approach is to use direct Figma colour styles in the early stages and only introduce a token layer once the colour decisions have stabilised enough that you are confident they will not change shape again. Tokens are a tool for managing scale. They are overhead before you need that scale.

I documented components before they were stable

There is a version of design system discipline that says: document as you build. Write the usage guidelines for each component as you create it. That advice is right for a team where multiple people need to understand the decisions you made.

For a solo practitioner, it is premature. The components I documented earliest were the ones I revised most, which meant the documentation was wrong almost as soon as it was written. Keeping it accurate added work without adding value, because the only person reading it was me and I already knew what had changed.

I would now document only when a component is genuinely stable, meaning it has been used in multiple contexts and survived those uses without significant revision. Before that point, a brief annotation in the Figma file is enough.

I built components I was not ready to use

Early enthusiasm for the system led me to build components speculatively, for screens I had not designed yet, for interactions I had not fully thought through. Several of those components were never used. Others were used once and then revised so substantially that the original component bore no resemblance to what ended up in the product.

The constraint I now apply is simple: a component does not get built until it is needed by a screen I am actively designing. Not soon. Now. This keeps the library lean and ensures every component has a real use case driving its design rather than a hypothetical one.

WHAT WAS GENUINELY WORTH THE INVESTMENT

For all the caveats above, building a design system alone was worth doing. The discipline it imposed on the product was real and the compounding returns were visible over time.

Consistency became automatic rather than effortful. Once the foundations were defined, decisions that used to require deliberation became non-decisions.
Iteration got faster. Changing a primary colour across the entire product took thirty seconds because it was defined in one place. Without the system it would have taken hours and still missed something.
Handoff became possible. When the product reached a point where other people needed to build on it, the system gave them a foundation to work from rather than requiring them to reverse-engineer decisions from the existing screens.
The product felt more considered. Consistency at the component level produces a quality of finish that is difficult to achieve any other way, and it is immediately visible to anyone who interacts with the product professionally.

THE PRINCIPLE THAT WOULD HAVE SAVED ME TIME

If I could go back to the beginning with one piece of advice, it would be this: build the system in response to the product, not in anticipation of it.

Every component, every token, every pattern should exist because the product already needed it, not because a comprehensive design system would include it. The system grows as the product grows, and the decisions it captures are real ones rather than speculative ones.

This produces a smaller system than most design system content would have you build. It also produces a system you will actually maintain, because the overhead is proportional to the value it delivers, and because every part of it is grounded in a real decision that the product required you to make.

CLOSING THOUGHT

A design system built alone is not a smaller version of an enterprise design system. It is a different thing entirely: a personal discipline for making recurring decisions once and applying them consistently. The goal is not comprehensiveness. It is clarity, maintained over time, by one person, without it becoming the product instead of serving it.

AI Can Generate UI. Who Keeps It Consistent? — Roman Bakurov’s Developer Journey

Thu, 08 Oct 2026 09:48:37 +0000

AI Can Generate UI. Who Keeps It Consistent? — Roman Bakurov’s Developer Journey

“Generating UI is easy. Keeping it consistent is the hard part.”

For more than 15 years, Roman Bakurov has worked across UX, design and software development. That combination shaped the way he thinks about frontend engineering.

For Roman, interfaces were never simply a visual layer. He was interested in why a product worked the way it did, how people interacted with it, and how product decisions eventually became working software.

Today, he is the founder of Vellira, an open-source cross-platform design system for React and React Native.

But Vellira is about more than creating reusable UI components.

Roman is exploring a bigger question:

What happens to software quality when AI can generate UI faster than humans can review and maintain it?

From UX and Design to Frontend Engineering

Roman's journey began at the intersection of UX, design and development.

Frontend development attracted him because it provided an immediate connection between an idea and the person using it.

You could take a product rule or design idea and quickly see how it behaved in a real interface.

React was particularly appealing because of its compositional model. Complex interfaces could be constructed from smaller, predictable pieces with clear contracts.

But as products grew, Roman noticed that creating an individual component was rarely the difficult part.

The real challenge was keeping an entire product consistent.

Different buttons would appear.

Forms would behave differently.

Developers would interpret the same design rule in different ways.

And eventually, web and mobile implementations could begin evolving as if they were completely separate products.

That problem became the foundation for Vellira.

Why Roman Built Vellira

Vellira started from a practical problem.

A component library can provide reusable building blocks, but a library alone cannot guarantee consistency.

Someone can add local styling.

Someone can create a nearly identical component.

Someone can implement an existing behaviour differently.

Roman wanted consistency to be supported by the architecture itself rather than depending entirely on everyone remembering the rules.

Vellira began as a design system for React and React Native, with shared tokens, components, documentation, Storybook and testing.

Then AI changed the equation.

AI could suddenly generate working frontend code in seconds.

That made writing UI less of a bottleneck.

But it created another problem.

If AI can generate more UI, who makes sure all that UI follows the same rules?

One System, Two Runtimes

One of the challenges Roman faces with Vellira is supporting both web and React Native.

The platforms may need to provide similar experiences, but internally they are very different.

The web has the DOM, browser semantics, focus management, keyboard navigation and ARIA.

React Native has a different rendering model, event system and accessibility model.

Roman therefore doesn't believe the goal should be forcing both platforms to share exactly the same implementation.

Instead, the goal is:

One system of rules everywhere.

The meaning, component intent, states, sizes, tokens and core API principles should remain aligned.

The implementation can still respect the platform it runs on.

Consistency vs Flexibility

Design systems have another difficult balance.

Too much flexibility and the system becomes a collection of helpers that everyone uses differently.

Too much restriction and developers start working around the system.

Roman tries to separate the system contract from extension points.

Core states, sizes, intents, accessibility behaviour and design-token usage should remain predictable.

Composition and integration patterns can be more flexible.

The principle is simple:

A good API shouldn't make everything possible. It should make the correct path the easiest path.

Accessibility Is Not a Final Step

Accessibility is another area where Roman believes architecture matters.

It should not be something added after a component has already been designed.

Keyboard navigation, focus behaviour, semantics, screen-reader behaviour and interactive target sizes need to be considered while the API itself is being designed.

Roman also points out that accessibility is more than adding ARIA attributes.

A component can have the correct aria-label and still have broken keyboard navigation or poor focus management.

Accessibility is fundamentally about behaviour and semantics, not just attributes.

The Hard Part Isn't the Button

Ironically, the individual components are not the hardest part of Vellira.

Writing a Button component is relatively straightforward.

The harder problem is creating a process that makes sure every component:

uses the correct tokens
follows API conventions
supports the required states
preserves accessibility
has tests
has documentation
works across the required platforms

That changes the nature of the project.

Roman realised he wasn't simply building components.

He was building a production process for components.

CI, testing, documentation, release processes, compatibility, accessibility, developer experience and package distribution all became part of the same system.

When AI Starts Generating the UI

AI coding tools are already extremely effective at local development tasks.

They can implement components, refactor code, generate tests and help developers understand unfamiliar codebases.

The problem appears when those local solutions accumulate.

An AI-generated component might work perfectly while introducing a second way of doing something the system already has a standard solution for.

It might use a different token.

It might introduce a new pattern.

It might change an API.

It might implement the same principle slightly differently somewhere else.

Each decision can look reasonable on its own.

Together, they can slowly create a second architecture that nobody intentionally designed.

The more code AI produces, the more important that problem becomes.

Turning a Design System Into a Contract for AI

Roman believes the next stage of AI-assisted development needs more than better models.

It needs systems that define the boundaries of acceptable solutions.

Today, telling a human developer to “use our design system” may be enough.

For a machine, it isn't.

AI needs to understand the allowed component variants, tokens, states, composition rules, accessibility requirements and API constraints.

This leads to an interesting evolution:

A design system can become a contract between the product and AI.

The system is no longer only documentation for developers.

Its rules can become machine-readable and verifiable.

Humans and AI may use different representations of those rules, but the underlying system should remain consistent.

AI-Generated Code Needs More Than a Successful Build

Roman doesn't believe AI-generated code should be trusted simply because it compiles or looks correct.

He sees production validation as a series of independent layers.

That can include:

type safety and builds
unit and interaction tests
accessibility checks
visual regression testing
design-token validation
API conventions
required component states
platform-specific behaviour
documentation
unexpected changes outside the intended scope

But even these checks are not always enough.

A component can pass tests and still implement something different from what the developer originally intended.

That creates another question:

Did the result preserve the meaning of the original task?

For Roman, reliable AI-assisted development needs to validate not only whether the code works, but whether it matches the intended outcome.

Building Vellira in Public

Open source has also changed Roman's understanding of what makes a project successful.

Code is only part of the developer experience.

A project also needs to explain why it exists, make installation understandable, provide useful examples, communicate its API clearly and help developers understand the architecture.

Documentation therefore becomes part of the product itself.

So do naming, package structure, examples, error messages and onboarding.

Building in public also creates another challenge.

Something that seems obvious to the person who has worked on a project for months may be completely unclear to someone opening the repository for the first time.

A good system has to make sense even to someone who wasn't present when the architectural decisions were made.

From Developer to Architect to Founder

Building Vellira has also changed Roman's role.

As a developer, he asks:

“Does this implementation work?”

As an architect:

“Will this still be the right decision for the whole system one or two years from now?”

And as a founder:

“Are we solving a problem that actually matters to other people?”

That last question is particularly important.

A technically interesting problem isn't automatically a valuable product problem.

Every architectural decision can affect documentation, tests, examples, multiple platforms and existing users.

The result is that Roman has become much more careful about decisions that appear convenient today but create hidden costs later.

The Future of UI Development

Roman's work with Vellira points toward an important shift in frontend development.

For years, developer productivity was largely about helping people write code faster.

AI has changed that equation.

Now machines can produce enormous amounts of UI code very quickly.

The challenge increasingly becomes deciding what should be generated, what rules it must follow, and how the result can be verified.

That makes the design system more important, not less.

It becomes the layer that defines consistency.

It provides the constraints.

It gives both humans and AI a shared understanding of how the product should behave.

And perhaps most importantly, it helps prevent speed from becoming chaos.

About Roman Bakurov

Roman Bakurov is the founder of Vellira, an open-source cross-platform design system for React and React Native.

His work focuses on design systems, developer tooling, accessibility and reliable infrastructure for AI-assisted UI development.

Vellira brings together shared design tokens, component tooling, documentation, automated quality checks and cross-platform development with the goal of making UI more consistent and maintainable.

View Roman Bakurov's profile on CoderLegion

Visit Vellira

CoderLegion Developer Stories

Real developers. Real journeys. Real experiences.

Developer Stories at CoderLegion gives developers an opportunity to share how they think, what they build, the problems they encounter and what they learn along the way.

Interview & Story by Mehadi Hasan

One Design System, Two Runtimes: Sharing Contracts Between React and React Native

Sat, 26 Sep 2026 09:42:11 +0000

A cross-platform design system sounds simple until the first real component forces the platforms apart.

React and React Native can expose the same product concept — a button, checkbox, input, modal — while relying on very different runtime primitives. The web has DOM attributes, anchors, CSS, hover and keyboard behavior. React Native has Pressable, native accessibility props, gesture events, and a completely different styling model.

Trying to hide all of those differences behind one implementation usually makes the API worse. In Vellira, I have been taking a different approach: share the semantic contract, not the runtime implementation.

That distinction has become one of the most useful architectural rules in the project.

The real goal is consistency, not identical code

When I started building Vellira, it was tempting to think about cross-platform components mainly as a code-sharing problem.

If a web button and a native button look similar, why not make them use as much of the same component code as possible?

Because the important thing users consume is not the internal component tree. It is the behavior and mental model of the public API.

For a button, developers should be able to learn concepts such as:

color
appearance
size
shape
loading
disabled
fullWidth
iconOnly

once and carry that knowledge between platforms.

The implementation underneath those concepts does not need to be the same.

This leads to a more useful definition of parity:

Cross-platform parity means shared semantics where the platforms agree, plus explicit platform-specific capabilities where they do not.

That is much stronger than forcing two different runtimes through the same abstraction.

Put shared semantics in a platform-neutral contract

Vellira keeps the common Button vocabulary in @vellira-ui/types.

A simplified view of the shared contract looks like this:

export type ButtonSize = 'sm' | 'md' | 'lg';

export type ButtonColor =
  | 'primary'
  | 'neutral'
  | 'success'
  | 'warning'
  | 'danger';

export type ButtonAppearance =
  | 'solid'
  | 'outline'
  | 'ghost'
  | 'soft'
  | 'link';

export interface BaseButtonProps {
  color?: ButtonColor;
  appearance?: ButtonAppearance;
  size?: ButtonSize;
  shape?: 'square' | 'rounded' | 'pill';
  fullWidth?: boolean;
  loading?: boolean;
  loadingText?: string;
  disabled?: boolean;
  iconOnly?: boolean;
}

There is nothing web-specific or native-specific in that interface. It describes what a Vellira button means.

That shared layer gives both implementations a stable semantic center. If appearance="soft" exists on both platforms, it should represent the same design intent. If loading disables interaction, that rule should be understood consistently too.

This is where I want reuse to be strongest.

Let each platform extend the contract honestly

Once the common semantics are defined, the platform packages can extend them instead of pretending their runtimes are identical.

On the web, ButtonProps extends the shared contract and normal HTML button behavior. It can also expose anchor-related properties such as href, target, and rel.

export interface ButtonProps
  extends
    BaseButtonProps,
    Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color'>,
    Pick<
      AnchorHTMLAttributes<HTMLAnchorElement>,
      'href' | 'target' | 'rel' | 'download'
    > {
  children?: ReactNode;
  iconStart?: ReactNode;
  iconEnd?: ReactNode;
  tooltip?: string;
  badge?: ReactNode;
  shortcut?: ReactNode;
  asChild?: boolean;
}

React Native starts from the same BaseButtonProps, but the runtime-specific surface is different. It builds on PressableProps, exposes onPress, native styles, and accessibility properties that belong to the native platform.

export interface ButtonProps
  extends BaseButtonProps, Omit<PressableProps, /* platform exclusions */> {
  children?: ReactNode;
  iconStart?: ButtonIconElement;
  iconEnd?: ButtonIconElement;
  iconSize?: number;
  onPress?: (event: GestureResponderEvent) => void;
  style?: StyleProp<ViewStyle>;
  textStyle?: StyleProp<TextStyle>;
  accessibilityLabel?: string;
  testID?: string;
}

The two APIs are clearly related, but they are not artificially identical.

That is intentional.

A web developer still gets normal web capabilities. A React Native developer still gets normal native capabilities. The design system owns the common semantics without becoming an abstraction tax on either platform.

Healthy divergence is part of a good cross-platform API

Some differences should not be normalized away.

For example, a web button can naturally compose with an anchor or another DOM element. That is where properties such as href or Vellira's asChild capability make sense.

React Native does not have an HTML anchor element. Inventing a fake href prop just to make the type signatures look more symmetrical would create parity on paper while making the native API less natural.

The same rule applies in the opposite direction. React Native has concepts such as StyleProp<ViewStyle>, testID, and native press events. Wrapping every one of those in invented cross-platform names would make the system harder to understand and harder to debug.

So I use a simple test when deciding whether something belongs in the shared contract:

Does this property describe product-level component behavior, or does it describe the runtime that implements it?

Product-level behavior is a strong candidate for the shared layer. Runtime behavior usually stays with the platform package.

That distinction keeps the common API small enough to remain meaningful.

Component props are only one layer of cross-platform consistency.

Visual decisions such as spacing, radii, typography scales, colors, and semantic states also need a common source of truth. Those decisions can be represented as tokens and consumed differently by CSS on the web and native style objects in React Native.

The important architectural point is the same: share the decision, adapt the execution.

A radius token does not require the web and native styling engines to work the same way. It only requires both implementations to resolve the same design intent.

This is a useful pattern because it prevents "cross-platform" from turning into "lowest common denominator". Shared semantics stay centralized while each renderer remains free to use the platform correctly.

Test parity at the contract boundary

Once implementations are separate, drift becomes the next problem.

It is easy for the web Button to gain a new appearance or loading rule while the React Native Button silently falls behind. Separate implementations therefore need explicit validation around the things that are supposed to stay aligned.

In Vellira, both Button implementations have their own tests and Storybook coverage. The shared types define a common vocabulary, while platform tests verify actual runtime behavior.

That gives two different kinds of confidence:

Contract confidence — the shared semantic API is defined in one place.
Runtime confidence — each implementation proves that the contract behaves correctly on its own platform.

I prefer this over a large shared implementation with a growing number of platform conditionals. A shared file can look beautifully DRY while still hiding platform-specific bugs.

Separate runtime tests make those differences visible.

A practical three-layer model

The pattern I am converging on in Vellira can be summarized as three layers.

1. Shared semantics

Define the concepts developers should learn once:

size
appearance
color
loading
disabled
shape

These belong in platform-neutral types and design contracts.

2. Platform API

Extend those concepts with capabilities developers expect from the runtime:

Web:          href, target, DOM attributes, asChild
React Native: onPress, accessibilityLabel, style, testID

Do not disguise real platform differences.

3. Platform implementation

Use the native tools of each runtime:

Web:          DOM + CSS
React Native: Pressable + native styles

The implementation can diverge significantly as long as the shared semantics remain trustworthy.

What this changes when designing new components

This architecture also changes how I think about adding components.

Instead of beginning with "How can I reuse the most code?", I begin with questions like:

What behavior is actually common to both platforms?
Which names should mean the same thing everywhere?
Which states must have equivalent semantics?
Which capabilities are genuinely platform-specific?
What should be validated so parity cannot drift accidentally?

Only after those questions are answered does implementation reuse become interesting.

Sometimes there will be useful shared code below the component layer. Sometimes the correct answer is two mostly independent implementations. Both are acceptable if the public contract stays coherent.

This makes the design system easier to evolve because platform differences are treated as architecture inputs, not inconvenient exceptions.

The rule I keep coming back to

The most useful lesson so far is that cross-platform design systems do not need maximum code sharing. They need maximum semantic clarity.

Developers should feel that the React and React Native packages belong to the same system. They should recognize the vocabulary, states, design decisions, and interaction intent. But they should not have to give up the strengths of their platform to get that consistency.

For Vellira, that means sharing contracts aggressively and implementations selectively.

It is a smaller abstraction, but a much more durable one.

You can explore the project in the Vellira documentation or browse the implementation on GitHub.

Coder Legion - Recent posts tagged design-systems

Building a Design System Alone: What I Learned and What I Would Skip

WHY THE WRONG GOAL IS SO EASY TO ADOPT

WHAT I BUILT IN FIGMA AND WHY

A foundations page

A components page

A patterns page

WHAT I WOULD APPROACH DIFFERENTLY

I defined tokens before I had enough screens

I documented components before they were stable

I built components I was not ready to use

WHAT WAS GENUINELY WORTH THE INVESTMENT

THE PRINCIPLE THAT WOULD HAVE SAVED ME TIME

CLOSING THOUGHT

AI Can Generate UI. Who Keeps It Consistent? — Roman Bakurov’s Developer Journey

AI Can Generate UI. Who Keeps It Consistent? — Roman Bakurov’s Developer Journey

From UX and Design to Frontend Engineering

Why Roman Built Vellira

One System, Two Runtimes

Consistency vs Flexibility

Accessibility Is Not a Final Step

The Hard Part Isn't the Button

When AI Starts Generating the UI

Turning a Design System Into a Contract for AI

AI-Generated Code Needs More Than a Successful Build

Building Vellira in Public

From Developer to Architect to Founder

The Future of UI Development

About Roman Bakurov

CoderLegion Developer Stories

One Design System, Two Runtimes: Sharing Contracts Between React and React Native

The real goal is consistency, not identical code

Put shared semantics in a platform-neutral contract

Let each platform extend the contract honestly

Healthy divergence is part of a good cross-platform API

Share design decisions separately from component implementations

Test parity at the contract boundary

A practical three-layer model

1. Shared semantics

2. Platform API

3. Platform implementation

What this changes when designing new components

The rule I keep coming back to