Design System Guide. Chapter 5. UI Kit

The UI Kit is the most visible and tangible layer of a design system.
It is the layer that designers and developers interact with every day, which often creates the illusion that the UI Kit is the design system.

In reality, the UI Kit is a result of architectural decisions made at deeper levels: tokens, composition rules, allowable variability, and component responsibility.

The UI Kit should not be the place where decisions are made.
It should be the place where decisions are captured, verified, and reproduced.

One of the most common mistakes is to start building a design system with components.

A typical scenario looks like this:

• a new screen appears
  
• a new component is created for it
  
• then another one appears, "almost the same"
  
• later, a variant is added "for a special case"
  
• then yet another, because the previous one "doesn’t quite fit"

As a result, the UI Kit grows not because the product becomes more complex,
but because there is no composition-focused and systemic thinking.

Components start reflecting the history of screens rather than the architecture of the interface.

A mature system works in reverse:

• first, parameters and constraints are defined
  
• then basic elements are established
  
• and only after that do components appear as compositions, not unique entities

Composition is the ability to build interfaces from a limited set of stable elements,
rather than creating new entities for every scenario.

A good question when designing:

Can this be built from existing elements without breaking their role?

A bad question:

What new component do we need for this screen?

A composition-focused approach allows you to:

• drastically reduce the number of components
  
• increase reusability
  
• simplify maintenance
  
• maintain consistency between design and code
  

It’s important to understand:
composition is about architecture, not convenience.

In design systems, the atomic approach is useful not as terminology,
but as a hierarchy of responsibility.

Simplified, the system looks like this:

tokens → atoms → molecules → organisms → patterns → templates → pages

Templates and pages sit above the design system in the narrow sense.
They describe not elements and rules, but specific product scenarios and screens.

The design system must provide stable building blocks:

• tokens
  
• atoms
  
• molecules
  
• organisms
  
• patterns
  

Everything above depends on product context, business logic, and user flows.

Tokens are values, not interface elements.

They define:

• color roles
  
• sizes and spacing
  
• typography
  
• border radii
  
• elevation levels
  
• motion values
  

There is no interface at this level.
There are only agreements and constraints that the system must enforce.

Important:
Tokens do not “decorate” components, they limit design freedom.

Regardless of abstraction level,
all components in a design system are essentially made of atoms.

Atoms are the smallest interface elements that:

• implement tokens
  
• provide basic behavior
  
• define states
  
• ensure accessibility
  

Examples of atoms:

• text with defined typography
  
• icons
  
• interactive shell (button base)
  
• input without business logic
  
• focus-ring
  
• hit-area
  

A properly designed atom must not have external geometry.

This means:

• no margin
  
• no positioning
  
• no assumptions about context
  

An atom:

• does not know where it is used
  
• does not control spacing between neighbors
  
• does not affect layout
  

All external geometry:

• is applied at the molecule level
  
• or managed by layout systems
  

This rule makes atoms:

• reusable
  
• predictable
  
• safe for composition
  

If an atom is correctly defined, it:

• does not require local overrides
  
• behaves consistently in all contexts
  
• becomes the single "source of truth"
  

Any attempt to:

• override hover
  
• change focus
  
• add a unique state
  

above the atom is an architectural warning.

Molecules do not add behavior.

Their job is to:

• group atoms
  
• define their relative placement
  
• lock stable combinations
  

Examples:

• label + input + hint
  
• icon + text
  
• input + action
  

Molecules manage composition, not the essence of elements.

Organisms assemble molecules into more complex structures and manage layout.

They:

• do not change atoms
  
• do not duplicate states
  
• do not introduce unique logic
  

An organism is a scenario container, not a new interface element.

One of the most dangerous practices is adding behavior at the molecule or organism level.

Typical examples:

• separate hover for a button inside a card
  
• special focus in a modal
  
• unique disabled state for a form
  

Each such decision:

• breaks composition
  
• duplicates logic
  
• makes the system fragile
  

If a scenario requires different behavior, the problem is in the atom, not the composition.

A key question for the UI Kit:

Where does a variant end and a new component begin?

This often appears in buttons:

• sizes
  
• visual styles
  
• icons
  
• states
  

System rule:

• if role and behavior remain, it’s a variant
• if role changes, it’s a new component or pattern

A component without states is a placeholder, not a system element.

The UI Kit must define:

• the full set of mandatory states
  
• visual and behavioral differences
  
• transition rules
  

If states are defined locally:

• hover may be missing
  
• focus may be ignored
  
• loading may be inconsistent
  

This undermines:

• accessibility
  
• predictability
  
• trust in the system
  

Not all solutions fit in a single component.

Patterns define:

• repeatable scenarios
  
• expected behavior
  
• allowable composition
  

Examples:

• validated form
  
• destructive actions
  
• confirmation dialogs
  

Patterns protect the system from chaotic decisions.

The UI Kit must be reproducible in code without interpretation.

This means:

• consistent terminology
  
• matching parameters
  
• matching states
  

When composition is correct:

• fewer components
  
• fewer changes
  
• the system scales
  

The UI Kit is not an accelerator, but a constraint.

It is used to:

• prevent reinventing the same elements
  
• enforce agreements
  
• avoid creating exceptions
  

The less freedom within the UI Kit, the more stable the product.

A simple system test:

• a new atom is needed → system evolves
  
• a new molecule is needed → system scales
  
• a unique component is needed → system degenerates
  

A mature system solves problems through composition, not by creating new entities.

The UI Kit is not a collection of components,
but a layer where architectural decisions become visible and verifiable.

If the design system relies on:

• tokens
  
• atoms without external geometry
  
• composition instead of duplication
  
• limited variability
  

the system remains compact, stable, and manageable.

Atoms are the essence of all components.
Molecules and organisms only reuse them and manage composition.

This approach allows creating fewer components
while achieving greater flexibility as the product grows.