Alpha Design System

Alpha Design System is a React component library and token layer for building accessible product UI. It ships with Storybook as the single place to browse components, read MDX documentation, and watch design tokens update live when you switch theme or light/dark mode in the toolbar.

If you landed here from GitHub, the fastest way to understand the system is to run Storybook locally: you get interactive controls, accessibility checks, and docs pages (including Getting Started → Overview and token galleries) without wiring anything into an app first.

After npm install / pnpm install, Git uses .githooks via core.hooksPath (see the prepare script in package.json). Commits whose first line starts with feature: trigger a post-commit update to src/docs/changelog.mdx.

Why open Storybook?

• See components in isolation — Button, Input, Textarea, Label, and FormField with variants, sizes, loading states, and composition patterns (asChild, form layouts).
• Token-driven visuals — Colors, typography, and radius resolve from CSS variables; switch Theme and Mode in the Storybook toolbar to compare Theme 1 / Theme 2 and light / dark without touching code.
• Documentation in one surface — MDX pages explain adoption, token usage, and guardrails next to live Canvas examples.

npm install
npm run storybook

Then open http://localhost:6006 (default port). Start from Getting Started → Overview in the sidebar, then explore Components and Design Tokens.

Overview

| Area | What it is | | --- | --- | | Stack | React 19, TypeScript, Vite 8, Tailwind CSS 4, Radix primitives, CVA, Storybook 10 | | Styling | Semantic tokens in src/styles/theme.css and Tailwind @theme — prefer tokens over ad-hoc colors and dark: sprawl | | Accessibility | Radix-based patterns, Storybook a11y addon, and components wired for labels, hints, and invalid states | | Testing | Vitest with the Storybook project (npm run test:storybook) |

Components live under src/components/. Docs and token showcases live under src/docs/.

Distribution (npm and shadcn registry)

This repo ships the same components in two ways.

npm package

Peers: react, react-dom, and Tailwind CSS v4.

pnpm add alpha-design-system

Import tokens in your app CSS entry (example):

@import "alpha-design-system/styles.css";

Usage:

// Prefer subpath imports so the bundler only resolves what you use:
import { Button } from "alpha-design-system/button";

// Barrel import (root) re-exports every public component; avoid it unless you need many at once.
import { Button } from "alpha-design-system";

Subpaths follow package.json exports (e.g. alpha-design-system/drawer, alpha-design-system/chart).

shadcn registry (copy files into a project)

After deploy (e.g. Vercel), registry files are served at /r/<name>.json. Merging to main rebuilds them.

npx shadcn@latest add https://alpha-design-system-five.vercel.app/r/button.json

Components that use cn depend on the utils registry item via registryDependencies.

Adding a component

1. Add src/components/<name>/<name>.tsx and index.ts (same layout as existing folders).
2. Run pnpm run build:lib or node scripts/build-registry.mjs to refresh registry.json, package.json exports, and src/index.ts from the filesystem.
3. If the change should ship on npm, include a Changeset: pnpm changeset and commit .changeset/*.md in your PR.

Releases (Changesets + GitHub Actions)

• After merges to main, a Version Packages PR is opened or updated; merging it runs npm publish and creates a GitHub Release.
• Manual: GitHub Actions → Release → Run workflow, or locally pnpm release after versions are bumped.

Add an NPM_TOKEN secret (npm automation token) to the repository.

Scripts

| Command | Description | | --- | --- | | pnpm run dev | Vite dev server for the app shell | | pnpm run storybook | Storybook dev server on port 6006 | | pnpm run build-storybook | Static Storybook build | | pnpm run test:storybook | Vitest (Storybook project) | | pnpm run build:lib | Registry sync + library build to dist/ | | pnpm run registry:build | Registry sync + shadcn build → public/r/*.json | | pnpm run build | build:lib + registry:build + build-storybook | | pnpm run build:app | App shell: tsc -b + vite build | | pnpm run lint | ESLint | | pnpm run typecheck | tsc -b |

Adopting in your own project (short version)

1. Load the theme stylesheet (e.g. import alpha-design-system/styles.css or copy src/styles/theme.css from this repo).
2. Import components from the npm package or via shadcn add URLs (see above).
3. Mirror data-theme / .dark on the document root if you want the same theme switching as Storybook.

For token naming and conventions, the design-token reference used in this workspace is documented in-repo (see src/docs/ and related scripts under scripts/).

License

Published npm package and source are under the MIT License unless noted otherwise in specific files.

Built with Vite + React + TypeScript. ESLint is configured for type-aware rules where applicable; extend eslint.config.js as your product grows.