Code examples are simplified for this article, not taken from client projects.

As a frontend team grows, you end up with five slightly different buttons, three date pickers and a modal that behaves differently on every page. A shared component library fixes that. At Squareflo, I contributed reusable components to our in-house UI library, and it saved us a lot of development time because teams stopped rebuilding the same things.

A library only saves time if people choose to use it. This post walks through how I'd build one, from the folder structure to publishing.

Step 1: Decide What Belongs in the Library

Not every component should be shared. I sort candidates like this:

  • Yes: generic building blocks used in more than one place, such as Button, Input, Select, Modal, Tooltip, Table, Toast.
  • Maybe: composite patterns that repeat with little variation, like PageHeader, EmptyState or ConfirmDialog.
  • No: components that encode one feature's business logic. Those stay in the app.

Tip

Start small. A handful of well-documented components will get more use than fifty half-finished ones. Add a component when the same need shows up in a second place.

Step 2: Set Up the Project

I use TypeScript, tsup for bundling, and React as a peer dependency so apps don't end up with two copies of React:

mkdir ui && cd ui
npm init -y
npm install -D typescript tsup react react-dom @types/react @types/react-dom
{
  "name": "@acme/ui",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js",
      "require": "./dist/index.cjs"
    },
    "./styles.css": "./dist/index.css"
  },
  "files": ["dist"],
  "sideEffects": ["**/*.css"],
  "peerDependencies": {
    "react": ">=18",
    "react-dom": ">=18"
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts --clean"
  }
}
Diagram: design tokens feed components, which are built into the @acme/ui package that apps install
The big picture: tokens feed components, components ship as one versioned package, and apps depend only on that package.

Organize the source so each component is self-contained:

src/
  components/
    Button/
      Button.tsx
      Button.css
      Button.test.tsx
      index.ts
  tokens.css
  index.ts        <- the public API: only what's exported here is supported

Step 3: Define Design Tokens First

Components drift apart when colors and spacing are hard-coded. Put them in one place as CSS custom properties:

/* tokens.css */
:root {
  --ui-color-primary: #1e88e5;
  --ui-color-primary-hover: #1565c0;
  --ui-color-danger: #e53935;
  --ui-color-text: #1f2328;
  --ui-radius: 8px;
  --ui-space-2: 8px;
  --ui-space-3: 12px;
  --ui-space-4: 16px;
  --ui-font: system-ui, -apple-system, "Segoe UI", sans-serif;
}

Components only reference tokens, never raw values. To add dark mode or a second brand later, you override the variables and leave the components alone.

Step 4: Build the First Component

This Button shows the patterns I follow in every component:

// src/components/Button/Button.tsx
import { forwardRef, type ButtonHTMLAttributes } from "react";
import "./Button.css";

type Variant = "primary" | "secondary" | "danger";
type Size = "sm" | "md" | "lg";

export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: Variant;
  size?: Size;
  loading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(
  { variant = "primary", size = "md", loading = false, disabled, className, children, ...rest },
  ref,
) {
  const classes = ["ui-button", `ui-button--${variant}`, `ui-button--${size}`, className].filter(Boolean).join(" ");

  return (
    <button
      ref={ref}
      type="button"
      className={classes}
      disabled={disabled || loading}
      aria-busy={loading || undefined}
      {...rest}
    >
      {loading && <span className="ui-button__spinner" aria-hidden="true" />}
      {children}
    </button>
  );
});

A few things to notice:

  • It extends the native button props, so onClick, aria-*, form, name and anything else a normal <button> accepts are passed through ...rest.
  • It forwards refs, so apps can focus it or attach tooltips and popovers. (In React 19, ref can also be passed as a regular prop, but forwardRef keeps you compatible with React 18 apps.)
  • It defaults to type="button", which prevents accidental form submits. variant and size have defaults too.
  • className is added to the component's own classes, so apps can add layout tweaks and keep your styles.
  • While loading, the button is disabled and sets aria-busy.
/* src/components/Button/Button.css */
.ui-button {
  display: inline-flex;
  align-items: center;
  gap: var(--ui-space-2);
  border: 0;
  border-radius: var(--ui-radius);
  font-family: var(--ui-font);
  font-weight: 600;
  cursor: pointer;
  color: #fff;
  background: var(--ui-color-primary);
}
.ui-button:hover:not(:disabled) { background: var(--ui-color-primary-hover); }
.ui-button:disabled { opacity: 0.6; cursor: not-allowed; }
.ui-button:focus-visible { outline: 3px solid var(--ui-color-primary); outline-offset: 2px; }

.ui-button--sm { padding: 6px 10px; font-size: 13px; }
.ui-button--md { padding: var(--ui-space-2) var(--ui-space-4); font-size: 15px; }
.ui-button--lg { padding: var(--ui-space-3) 20px; font-size: 17px; }

.ui-button--secondary { background: transparent; color: var(--ui-color-primary); box-shadow: inset 0 0 0 1px currentColor; }
.ui-button--danger { background: var(--ui-color-danger); }

Warning

Never remove the focus outline without replacing it. Keyboard users rely on it, and :focus-visible shows it only when it's needed.

Step 5: Export a Deliberate Public API

// src/index.ts
import "./tokens.css";

export { Button } from "./components/Button";
export type { ButtonProps } from "./components/Button";

Anything not exported from index.ts is private, so you can refactor it without breaking apps.

When tsup builds the library, the CSS imported by your components is collected into dist/index.css (exposed as @acme/ui/styles.css in package.json). Apps import it once at their entry point, then use components anywhere:

// In the app, e.g. main.tsx or app/layout.tsx
import "@acme/ui/styles.css";
import { Button } from "@acme/ui";

export function SaveBar() {
  return <Button onClick={() => console.log("saved")}>Save changes</Button>;
}

Step 6: Document Every Component

If developers can't quickly see what a component does, they'll build their own. I use Storybook for this. Each component gets "stories" showing its states:

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

const meta: Meta<typeof Button> = { title: "Components/Button", component: Button };
export default meta;

type Story = StoryObj<typeof Button>;

export const Primary: Story = { args: { children: "Save changes" } };
export const Secondary: Story = { args: { children: "Cancel", variant: "secondary" } };
export const Danger: Story = { args: { children: "Delete", variant: "danger" } };
export const Loading: Story = { args: { children: "Saving…", loading: true } };

Deploy Storybook somewhere the whole team can reach it, and link it from your README.

Step 7: Test What the User Does

Query by role and label, and click the way a user would. Class names change too often to test against. With Testing Library:

// src/components/Button/Button.test.tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Button } from "./Button";

test("calls onClick when clicked", async () => {
  const onClick = vi.fn();
  render(<Button onClick={onClick}>Save</Button>);
  await userEvent.click(screen.getByRole("button", { name: "Save" }));
  expect(onClick).toHaveBeenCalledOnce();
});

test("is disabled while loading", () => {
  render(<Button loading>Save</Button>);
  expect(screen.getByRole("button", { name: "Save" })).toBeDisabled();
});

(These examples use Vitest's vi.fn() and a jsdom test environment. toBeDisabled() comes from @testing-library/jest-dom, loaded in your test setup file. With Jest, use jest.fn() and toHaveBeenCalledTimes(1).)

Step 8: Version and Release Carefully

Apps depend on your library the same way clients depend on an API, so follow semantic versioning:

  • Patch (1.4.2 → 1.4.3): bug fixes only.
  • Minor (1.4.3 → 1.5.0): new components or new optional props.
  • Major (1.5.0 → 2.0.0): anything that can break an app, such as removed props or changed defaults.

Keep a changelog, and for breaking changes write a short migration note. Tools like Changesets automate the version bumps and changelog for you.

Step 9: Make Adoption Easy

A library nobody uses doesn't save anyone time. These habits help:

  • Sit with feature teams and swap a few hand-built components for library ones together. You'll find the gaps quickly.
  • Accept contributions, and write a short guide on how to add a component.
  • In code review, point people to the library component instead of approving another one-off.
  • Track how many screens use library components. It's a useful number to show leadership.

Summary

Start with a few core components, type and test them, document them in Storybook, and version the package the way you'd version an API. Add new components when a real need shows up in more than one place.