Chapter 51: Design Systems and Component Libraries

The Kit components from the previous chapters are a component library. The token system from Chapter 50 is a foundation for theming. Put together, they’re the start of a design system — but design systems are something more than a component library plus tokens, and the discipline of building one is its own field with its own history, vocabulary, and tooling.

This chapter is about that field. The design systems industry. Atomic design. Style Dictionary and the W3C Design Tokens Community Group. Storybook as the standard component-development environment. The Shadcn-style component-copying paradigm and what it changed. The chapter’s job is to connect the platform-first architecture this book has been building to the broader design-systems practice the industry has developed over the past decade.

The connection matters because most teams that adopt Kit-style architecture will be building (or extending, or replacing) a design system. The architectural decisions from Parts IV and V — custom elements as the component primitive, the token system from Chapter 50, the metadata protocol for component participation — fit into the design-systems discipline naturally. The patterns this chapter names are the bridge.

Brad Frost and Atomic Design

The modern design-systems discipline has a clear origin moment.

Brad Frost published Atomic Design in 2013 as a blog post, then in 2016 as a self-published book. The book proposed a vocabulary for breaking interfaces into structurally meaningful parts:

• Atoms — the smallest UI elements (buttons, inputs, labels).
• Molecules — groups of atoms that function together (a labelled form field, a search input with submit button).
• Organisms — larger compositions of molecules (a navigation bar, a card with content and actions).
• Templates — page-level layouts that show how organisms compose.
• Pages — specific instances of templates with real content.

The vocabulary borrowed from chemistry as a mnemonic. The substance was an architectural commitment: the design system should be composable, with each level made from the levels below, and the team should think about consistency at each level.

Frost’s contribution wasn’t the specific atomic/molecular vocabulary (which has been argued about for years; some teams use it, some don’t). It was the discipline of thinking about UI as a layered composition with named units and intentional relationships. That discipline became the foundation of how serious teams build design systems.

Frost has continued working in the design-systems space — running consulting work through his agency Brad Frost Web, speaking at conferences, contributing to the design-system community’s shared vocabulary. The work has been mostly thankless and steadily influential. Many of the design systems shipped at major companies over the past decade owe a piece of their thinking to Frost’s articulation of the discipline.

For the Kit architecture, atomic design maps cleanly onto the component library:

• kit-button, kit-input, kit-icon are atoms.
• kit-field (wrapping label + input + error) is a molecule.
• kit-form-section, kit-toolbar, kit-card are organisms.
• Page layouts and route templates are higher-level compositions.

The vocabulary is borrowed; the architecture is platform-native; the discipline is consistent.

Design Tokens as a Discipline

Tokens have been part of design for a long time. Photoshop swatches. Sketch styles. CSS preprocessor variables. The modern design tokens discipline — tokens as first-class artifacts in a design system, named, documented, transformable across platforms, governed as code — is younger and has its own community.

Style Dictionary, originally created by Danny Banks at Amazon (released as open source in 2017), was one of the first widely-adopted token-transformer tools. The tool takes token definitions in JSON and produces output for any target platform — CSS custom properties for web, iOS Swift constants, Android XML, JavaScript modules, Sass variables, anything else a project’s pipeline needs. The tool’s value is making one source of truth for tokens work across the design system’s distribution targets.

For web-only applications, Style Dictionary is often more machinery than necessary (Chapter 50’s CSS-custom-property approach handles the web case directly). For applications that ship to web and iOS and Android, the tool earns its place — the tokens are defined once and consumed everywhere with consistent values.

The W3C Design Tokens Community Group (DTCG), formed in 2020, has been standardizing the format design tokens are expressed in. The group’s specification — Design Tokens Format Module, currently in working-draft form — defines a JSON schema for declaring tokens that any tool can consume. Once the standard ratifies, the whole tooling ecosystem (Style Dictionary, Tokens Studio, Specify, Supernova) can interoperate.

Jina Anne has been one of the DTCG’s co-chairs since its founding, alongside Kaelig Deloumeau-Prigent (Adobe), Drew Bridewell (Adobe), and others. Anne’s broader work in design systems — at Salesforce on the Lightning Design System, at Slack, as the curator of the Clarity Design Conference — has been one of the longest-running careers in the discipline. The community’s vocabulary for tokens, governance, and design-system practice owes significant work to her articulation.

For the Kit architecture, the tokens are CSS custom properties (Chapter 50). For applications that don’t need to ship beyond the web, this is sufficient. For applications that do — design systems shipping to web, iOS, and Android simultaneously — Style Dictionary plus a small adapter that produces the CSS-custom-property output is the standard path. The Kit tokens become the web target of a multi-target token system; the same tokens get transformed into Swift constants for iOS and Kotlin constants for Android by the same toolchain.

Storybook and Component-First Development

A different piece of the design-systems toolchain is Storybook — the component-development environment that lets designers and developers view, manipulate, and document components in isolation, separate from any application they happen to be used in.

Storybook started as a side project in 2016 (by Arunoda Susiripala and Norbert de Langen). The tool grew into one of the most-adopted pieces of frontend tooling in the industry. By 2025, Storybook is used by Adobe, Airbnb, Atlassian, Salesforce, GitHub, Twitter (now X), and most of the major design-system teams. The tool’s value is significant — components developed in Storybook get exercised in isolation, documented with examples, tested visually, and reviewed by designers without requiring the broader application.

A story in Storybook is a defined configuration of a component — a specific set of props, a specific state, a specific context. The story renders the component in the Storybook UI, and the developer can interact with controls to change the configuration in real time. Stories function as both documentation and as the unit of visual testing.

For Kit components, the Storybook story format works directly. Lit components can be rendered as stories. The Lit team maintains official Storybook integration. A typical story file:

import { html } from 'lit'
import type { Meta, StoryObj } from '@storybook/web-components'

const meta: Meta = {
  title: 'Components/kit-button',
  component: 'kit-button',
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary', 'ghost', 'danger'] },
    size: { control: 'select', options: ['sm', 'md', 'lg'] },
    disabled: { control: 'boolean' },
    loading: { control: 'boolean' }
  }
}

export default meta

export const Default: StoryObj = {
  render: (args) => html`
    <kit-button
      variant=${args.variant}
      size=${args.size}
      ?disabled=${args.disabled}
      ?loading=${args.loading}
    >
      Click me
    </kit-button>
  `
}

export const Primary: StoryObj = {
  args: { variant: 'primary' },
  render: Default.render
}

export const Loading: StoryObj = {
  args: { loading: true, variant: 'primary' },
  render: Default.render
}

The stories become both documentation and visual-regression-test fixtures. A team can review every component’s appearance across its variants without running the full application. Designers can verify visual changes against the canonical stories. Automated tools (Chromatic, Percy, Loki) can take screenshots of the stories and detect unintended visual changes between commits.

The pattern compounds. As the Kit library grows, the Storybook documentation grows alongside it. New developers can browse the available components, see their props, and copy working examples directly into the application.

Shadcn and Component-Copying

A more recent shift in design-system distribution is worth naming because it represents a fundamentally different model.

shadcn/ui (Shadcn for short) is a project started by a developer named Shadcn (the pseudonym is also the project name) in 2023. The project distributes a set of React components — built on Radix primitives, styled with Tailwind — that look polished and work well. The unusual thing is the distribution model: Shadcn isn’t an npm package. The components aren’t installed as a dependency. Instead, the project provides a CLI that copies the component source code into the user’s repository. The user owns the code from that point forward.

This is a different relationship between the design system and the application. With a traditional component library (Material UI, Mantine, Chakra), the components are dependencies — they live in node_modules, the team imports them, the team updates them by updating the package, the team can’t easily modify them without forking. With Shadcn, the components are the team’s own code — they live in the repo, the team modifies them freely, the team controls the upgrade cadence, the team avoids the supply-chain risk of the dependency.

The model has real benefits. The components stop being a black box. Visual regressions become trackable in the team’s own commit history. Customization is unconstrained. Supply-chain risk drops (the components are the team’s code, not a third-party dependency that could change). Bundle size becomes more controllable (the team can delete unused parts).

The model also has costs. Updates aren’t automatic — when Shadcn improves a component, the team has to manually re-copy the new version (or merge the changes). Multiple projects can’t share the components without each copying them. The team takes on maintenance responsibility for every component they copy.

For different applications, different trade-offs apply. A long-running enterprise application with strict supply-chain requirements benefits from the copy model. A small project that wants to ship quickly without taking on maintenance benefits from the dependency model. Both models are valid.

For the Kit architecture, both distribution models work. Kit can ship as an npm package (the dependency model) for applications that want it that way. Kit’s components can also be designed to be copyable — small enough that a team can copy kit-button.ts into their repo, modify it for their design system, and own the result. The platform-first orientation actually makes the copy model easier (the components have few dependencies, so copying one doesn’t drag in much else).

The Shadcn paradigm is itself an argument the rest of this book has been making in different forms. Smaller dependency surface. Code the team owns. Resistance to framework churn. The platform as the substrate. Shadcn applies the argument to component distribution; Kit applies it to the architecture as a whole.

How a Design System Adopts the Kit Architecture

For a team building a design system using Kit, the workflow follows a recognizable pattern.

Define the tokens. Colors, spacing, typography, radii, shadows, animations. Either as CSS custom properties directly (the Chapter 50 approach) or as Style Dictionary source for multi-target distribution. The tokens are the foundation.

Build the atoms. Buttons, inputs, icons, labels — the smallest units of the design system. Each one is a custom element built with Lit, participating in the metadata protocol, consuming tokens, exposing public custom properties for theming.

Build the molecules and organisms. Composed pieces — labelled form fields, search bars, cards, dialogs, navigation. Each one composes atoms. Each one has consistent visual treatment because each one consumes the same tokens.

Document in Storybook. Each component gets stories for its variants, sizes, states. The stories become the design system’s visible artifact — what the design team reviews, what new developers learn from, what visual-regression tests run against.

Govern through cascade layers. The design system’s styles live in kit.components. The application’s overrides live in app.overrides. The layer ordering makes the governance explicit.

Distribute. Either as an npm package (the dependency model), as copyable component source (the Shadcn model), or as a hybrid (an npm package that’s intentionally small enough to vendor when needed). Each model fits different teams’ needs.

Integrate with the runtime. When the application is built on the Kit runtime (Part IV), the components participate naturally through the metadata protocol. Events flow up through boundaries. Commands route to handlers. Modules respond. The design system’s components and the application’s capabilities compose without further wiring.

The workflow scales. A small team can ship a basic design system in days. A large team can build a comprehensive system over months. Each iteration adds components, tokens, stories, and documentation. The platform-first foundation means the work compounds rather than churning — the components built in 2025 still work in 2030, because they’re real custom elements on a stable platform.

What This Means for Modern Frontend

The design-systems discipline this chapter has been describing maps cleanly onto the platform-first architecture. The Kit components are the implementation; the design-systems vocabulary (atoms, tokens, stories, layers, governance) is the practice. The two are independent but compatible.

A team that already has a design system in Figma can implement it as Kit components. A team building from scratch can use the design-systems vocabulary to organize the work. A team migrating from a React-based design system (Material UI, Chakra, Mantine, Radix-plus-Tailwind, Shadcn) can replace components one at a time, with the rest of the system continuing to work during the migration (because the platform — DOM, custom elements, CSS, the cascade — is the substrate, and the substrate doesn’t care which renderer produced any specific element).

The platform-first design system isn’t better in every dimension than the framework-bound alternatives. The framework-bound systems have ecosystem advantages, hiring advantages, and ergonomic advantages in the specific framework they target. The platform-first system has longevity advantages, supply-chain advantages, framework-independence advantages, and AI-readiness advantages. The choice depends on the application’s time horizon, the team’s priorities, and the product’s specific requirements.

For applications that benefit from the platform-first trade-offs — long-running products, enterprise systems, government services, applications with strict supply-chain requirements, products being built for AI-generated UI futures — the design system this book describes is the right shape. The architecture from Part IV provides the runtime. The components from Part V provide the visual layer. The design-systems discipline this chapter has been describing provides the practice. Part VI ships the maintained version as Kitsune.

Bridge to Kitsune

Part V ends here. The Kit component library is sketched. The styling system is in place. The design-systems discipline is connected.

Part VI ships the maintained version. Kitsune as a framework. The architecture from Parts IV and V, polished, tested, documented, with the integration adapters and the production-ready ergonomics real applications need. The Kitsune chapters build on everything that’s come before; the principles, the runtime, the components, the styling all carry forward. The polish layer is what turns the educational implementation into a tool teams can adopt for real work.

Part VII covers production concerns. Part VIII engages with the future.

Exercise: Build a Mini Design System

Take three or four Kit components — kit-button, kit-field, kit-text-field, kit-card — and document them as the start of a design system.

For each component:

1. Write a Storybook story file with at least three variants (default, primary, disabled, loading, etc. — depending on the component).
2. Add prose documentation explaining when to use the component, what props it accepts, and what accessibility properties it preserves.
3. Add visual-regression test fixtures (screenshots of each variant, optionally captured automatically with Chromatic or Playwright).
4. Document the design tokens the component consumes.

Then take a small application — a settings page, a profile editor, a sign-up flow — and rebuild it using the design system. Notice:

1. Which components were available? Which did you wish existed?
2. How did the tokens make styling consistent across the application?
3. How did the Storybook documentation help during development?
4. If a new team member joined, how long would it take them to be productive against this design system?

Now think about the broader trajectory:

1. If you wanted to share this design system with another project, would you ship it as an npm package or as copyable component source? Which fits your situation better?
2. If you wanted to ship the same tokens to iOS and Android, what would you need to add? (A token transformer like Style Dictionary; perhaps a CI workflow that publishes the platform-specific outputs alongside the npm package.)
3. If you adopted the architecture from Part IV, how would the design system’s components integrate? (Through the metadata protocol, boundary attribution, and the runtime’s event/command bus.)

The exercise is the bridge from component library to design system. The components are the implementation. The design-systems discipline is the practice that makes the components useful at scale. Part V’s job has been building the implementation; this chapter has been about the practice.

Part V ends here. The architecture has a runtime, a shell, boundaries, a metadata bridge, a data layer, diagnostics, a component library, a styling system, and a design-systems integration. Part VI ships the maintained version.