Design System Development for Web Application

Web Application Design System Development

A design system is not a UI kit. A UI kit is a set of visual components in Figma. A design system is a living product: components in code, documentation, support processes, synchronization tools between design and implementation. It's infrastructure that teams use to create interfaces.

The difference becomes obvious at scale: one product with one team manages with a UI kit. Multiple products, multiple teams, multiple platforms — without a design system, drift begins: each team makes their own button version, and in a year the interface looks like different companies made it.

What a Design System Consists Of

1. Design Tokens — atomic level. Named variables for all visual decisions:

{
  "color": {
    "primary": {
      "50":  { "value": "#EFF6FF" },
      "500": { "value": "#3B82F6" },
      "900": { "value": "#1E3A5F" }
    },
    "semantic": {
      "background-default":  { "value": "{color.neutral.50}" },
      "text-primary":        { "value": "{color.neutral.900}" },
      "border-interactive":  { "value": "{color.primary.500}" }
    }
  },
  "spacing": {
    "xs": { "value": "4px" },
    "sm": { "value": "8px" },
    "md": { "value": "{spacing.sm} * 2" }
  }
}

Semantic tokens are the key difference from just a palette. color.primary.500 is a specific color. color.semantic.border-interactive is a role: the color of an interactive border, which is currently primary.500, but can become different on theme switch.

2. Component Library (Code) — React/Vue/Angular components implementing each UI kit element. For React stack, typical choice:

• Headless components (Radix UI, Headless UI, Ark UI) + custom styles via CSS Modules or Tailwind
• Ready-styled libraries (Shadcn/ui, Mantine, Ant Design) with token customization
• Fully custom implementation (for unique design requirements)

3. Documentation Site — Storybook as de-facto standard. Each component documented in isolation: all variants, all states, all props with types, code examples, accessibility requirements.

4. Figma Library — Published components in Figma, available to all organization files via Libraries. Synchronized with code library: same component and variant names.

5. Processes — contribution guidelines (proposing new components), versioning (semver for library), deprecation policy (retiring obsolete components), review process.

Deep Dive: Storybook and Test Integration

Storybook (v8 as of 2024) — de-facto standard for documenting component libraries. Each component described via stories — named usage examples:

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost', 'destructive'],
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
  },
};
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: { variant: 'primary', children: 'Click me' },
};

export const Disabled: Story = {
  args: { variant: 'primary', disabled: true, children: 'Disabled' },
};

Based on stories, automatically run:

• Chromatic (visual regression test) — screenshots each story and compares with baseline. Any visual change — diffs for review
• @storybook/addon-a11y — automatic accessibility check via axe-core right in Storybook
• Interaction tests — @storybook/test lets write behavior tests right in story files

This catches regression before deploy: developer changed button padding — Chromatic shows diff in all affected components.

Deep Dive: Design Token Pipeline

Token sync between Figma and code is the most painful part of design system. Working chain:

Figma Variables
    ↓ (export via Tokens Studio or Figma Variables API)
tokens.json (W3C Design Tokens format)
    ↓ (Style Dictionary transform)
┌─────────────────────────────────────────┐
│ CSS Custom Properties  → tokens.css     │
│ JavaScript object      → tokens.js      │
│ Tailwind config        → tailwind.config│
│ iOS Swift              → Colors.swift   │
│ Android XML            → colors.xml     │
└─────────────────────────────────────────┘

Style Dictionary configured via sd.config.json. Each platform gets its own transformer: CSS gets --color-primary-500, JS gets { color: { primary: { 500: '#3B82F6' } } }, Tailwind gets extend config with same values.

When token changes in Figma — designer exports new tokens.json, commits to repo, CI runs Style Dictionary, publishes new package version to npm (if monorepo) or just updates files. All connected products update via npm update.

Versioning and Governance

Design system is shared dependency. Contract violation breaks all connected products. Therefore:

• Semver: major — breaking changes (component renames, API changes), minor — new components, patch — bugfixes and visual tweaks
• Codeowners in Git: core component changes require maintainer review
• RFC process for new components — proposal document with use-cases, alternatives, API examples

Example monorepo structure for design system:

design-system/
├── packages/
│   ├── tokens/          # Design tokens, Style Dictionary
│   ├── icons/           # SVG icons + React components
│   ├── react/           # React component library
│   └── docs/            # Storybook
├── figma/               # Figma export files
└── .changeset/          # Changesets for versioning

When You Need Design System vs UI Kit

Timeline

MVP design system (tokens, 20–30 components in Storybook, basic docs) — 6–10 weeks. Full design system with token pipeline, Chromatic, contribution guide, Figma library — 3–6 months with ongoing maintenance.