1.  Design system /
  2.  Documentation /

Components

Nikita Pazin · 3 December 2025 · ~ 8 minute read
Content

The main building blocks of a design system are components. The usability, consistency, and scalability of the entire project depend on their proper organization and description.

Component Types

Within a design system, two types of components are typically distinguished. They differ in purpose, level of abstraction, and documentation approach.

Implemented Components (Design → Code)

Opposite color control scheme in the Atlassian design system

These are components that have a concrete implementation in code and are available in Storybook. Developers use them directly when assembling interfaces.

For implemented components, documentation acts as a bridge between design and code. It describes visual appearance, behavior, states, and usage constraints.

When a project has a single source of truth for documentation, there is usually no ambiguity about where component descriptions should live, both from a design and a development perspective.

However, when multiple sources exist, which is often the case (for example, a documentation portal and Storybook), drawing a clear boundary between where different pieces of information belong becomes significantly more challenging.

A universal approach in such situations is to start from the target audience. Figma component documentation is primarily used by designers and managers, while code-level component documentation is used by developers. If certain topics are relevant to both groups, it is better to duplicate that information intentionally.

It is essential for documentation to reflect all logically possible component states. This is especially critical for complex components that, by default, include the states of their internal subcomponents. States that are unavailable or intentionally restricted should be explicitly described, along with the reasons for those limitations.

Design (Compositional) Components (Design-only)

These are components that:

  • Exist only in Figma;
  • Do not have a one-to-one correspondence with a single code component;
  • Represent stable combinations of multiple base components, such as standard page headers, pre-footer blocks, or frequently repeated content patterns.

Their primary goal is to speed up the design process, reduce the number of variations, and formalize recommended compositions. In documentation, such components are described as usage patterns rather than standalone implementation units.

Differences in Documentation Approach

Documentation explicitly accounts for the differences between component types.

Implemented Components

For implemented components, documentation focuses primarily on:

  • Precise alignment between design and code;
  • State variants and modifiers;
  • Usage limitations and constraints;
  • Clear links to Storybook and the codebase.

Design-only Components

For design-only components, descriptions focus on:

  • Purpose and usage scenarios;
  • Composition, including which base components they consist of;
  • Rules for combination and scaling;
  • Recommendations for adapting to different contexts.

Component Page Structure

Each page dedicated to a specific component should follow a predictable and consistent structure. The recommended structure is outlined below.

The recommended level of detail depends on the target audience and the specifics of the project. The standard approach is to provide the minimum necessary information, as excessive detail will complicate the updating of documentation.

Component Version

  • Component Version In addition to Storybook versioning, it is useful to maintain versioning for individual components both in Storybook and in Figma. Ideally, this versioning should be shared.

Real-World Examples From Existing Design Systems

A recommended format is A.BB.CCC, where:

  • A — UI kit version;
  • BB — component design version;
  • CCC — component functional version.
  • Change Summary A brief description of changes compared to the previous version.
  • Description and Purpose A concise explanation of what the component is and which problem it solves.
  • Component Type An explicit indication of whether the component is implemented (Design → Code) or design-only. Visual differentiation is highly recommended.
  • When to Use / When Not to Use Clear recommendations and anti-patterns describing appropriate and inappropriate usage scenarios.
  • Appearance and Variations Whenever possible, examples of the component in all valid states should be provided. This is especially important for complex components. If certain variants are invalid or do not make sense in practice, these cases should be documented explicitly.
  • Behavior and Interaction For interactive components, overall behavior should be described. Ideally, this section includes a link to the implemented component in Storybook. If this is not possible, an interactive prototype should be provided instead.
  • Composition and Dependencies A description of which other components are used internally or commonly combined with the component.
  • Combined Usage A dedicated block with examples of common combinations and links to relevant usage patterns.

Component pages should link to the following internal project resources:

  • Storybook (specific component or variant set);
  • Figma(master component or library). In many cases, the UI kit contains only state representations, while detailed interaction logic and developer-facing specifications live in a separate file. For internal documentation, it is recommended to link to both.
  • Pattern and composition guidelines;
  • Token sections (colors, typography, spacing), especially when component usage allows variability;
  • Related components that are logically connected.

This approach allows a component page to function as a navigation hub between design, code, and usage patterns.

Information about combined component usage should be placed either in a dedicated subsection on the component page or in a specialized design system section focused on patterns and compositions.

In both cases, cross-references are required.

Presentation Format

Recommended presentation includes:

  • Visual examples such as mockups or diagrams;
  • A list of allowed and disallowed combinations;
  • An explanation of which problems a specific combination is intended to solve.

Documenting Elementary Particles

Document particles as a foundation layer: tokens and primitive UI rules. This includes color and typography tokens, spacing units, icon rules, border radii, focus styles, and the base interactive states. The key is consistency and predictability, because everything above depends on these definitions.

A good documentation unit at this level is a “token page” or a “primitive page” that explains naming, allowed values, and usage constraints. For example, a spacing scale with rules for when 4px steps are allowed inside components and when 16px steps are required for layout alignment.

Documenting Base Blocks (Complex Components)

Document complex components as reusable implementation units. At this level, the system should describe what the component does, how it behaves in states, which variations are supported, and what constraints exist. Edge cases are essential: empty data, long strings, validation errors, disabled states, loading, and permissions.

This is where bridging design and code matters most. A component page should link to its Figma source and to its implementation (for example, Storybook), so designers and developers can rely on the same specification. If a component includes other components, document that composition explicitly.