Milfushi Design System

A production-ready React component library and design system built with TypeScript, Vite, and Turborepo. Includes a complete documentation site and interactive component showcase.

Overview

The Milfushi Design System is a monorepo containing:

• UI Package (packages/ui) - Production-ready React components with TypeScript support, Storybook stories, and design tokens
• Documentation Site (apps/docs) - Docusaurus-powered documentation with live component examples and integration guides
• Design Tokens - Comprehensive CSS custom properties for colors, typography, spacing, and more

Key Features

✅ Production-Ready Components

• Button, Input, Checkbox, Stack layout components
• Full TypeScript support with exported types
• 100% accessible (WCAG compliant)
• Built on semantic HTML

✅ Comprehensive Design Tokens

• 50+ CSS custom properties
• Colors (primary, secondary, semantic, grays)
• Typography system (sizes, weights, line heights)
• Spacing scale (xs to 3xl)
• Shadows, border radius, transitions, z-index utilities
• Light and dark mode support

✅ Multiple Documentation Surfaces

• Storybook for interactive component playground
• Docusaurus site with foundations and integration guides
• Live code examples in documentation
• Complete API reference for all components

✅ Optimized for Scale

• Tree-shakeable ES modules only
• Minimal bundle size (1.69 kB for UI package)
• Turborepo for fast builds
• Shared tooling across packages

---

Project Structure

design-system/
├── packages/
│   └── ui/                         # Component library + Storybook
│       ├── src/
│       │   ├── components/         # Button, Input, Checkbox, Stack
│       │   │   ├── Button/
│       │   │   ├── Input/
│       │   │   ├── Checkbox/
│       │   │   └── Stack/
│       │   ├── stories/            # Component stories
│       │   │   ├── Button.stories.ts
│       │   │   ├── Input.stories.ts
│       │   │   ├── Checkbox.stories.ts
│       │   │   └── Stack.stories.tsx
│       │   ├── tokens.css          # Design tokens
│       │   ├── components.css      # Component styles
│       │   └── index.ts            # Package exports
│       ├── .storybook/             # Storybook configuration
│       │   ├── main.ts             # Config
│       │   └── preview.tsx         # Global setup
│       ├── dist/                   # Built output
│       ├── vite.config.ts          # Vite build config
│       └── package.json
│
├── apps/
│   └── docs/                       # Docusaurus documentation site
│       ├── docs/
│       │   ├── components/         # Component documentation
│       │   ├── foundations/        # Design tokens, typography, colors
│       │   └── getting-started/    # Integration guides
│       ├── src/
│       │   └── components/ComponentPreview/  # Live demo component
│       ├── docusaurus.config.ts
│       └── package.json
│
├── turbo.json                      # Turborepo configuration
├── package.json                    # Root monorepo setup
└── README.md                       # This file

---

Technology Stack

Build & Bundling

• Vite - Next-generation frontend build tool
• Turborepo - High-performance build system for monorepos
• Rolldown - Bundler used by Vite

Component Development

• React 19 - UI library
• TypeScript - Static typing
• CSS Custom Properties - Design tokens

Documentation

• Docusaurus 3 - Documentation site generator
• Storybook 10 - Component development environment
• MDX - Markdown + React for interactive docs

Testing & Quality

• Vitest - Unit test framework
• Playwright - Browser testing
• Oxlint - Fast JavaScript/TypeScript linter
• TypeScript - Type checking

---

Installation & Setup

Prerequisites

• Node.js 20.0 or higher
• npm 9.0 or higher

Install Dependencies

npm install

This installs all dependencies for the root, packages, and apps using npm workspaces.

---

Available Commands

Development Servers

Start Documentation Site

npm run dev --workspace=apps/docs

Opens Docusaurus development server at http://localhost:3000

Features:

• Live component examples with <ComponentPreview> component
• Foundation documentation (colors, typography, spacing)
• Integration guide
• Hot module reloading

Start Storybook

npm run storybook --workspace=packages/ui

Opens Storybook at http://localhost:6006

Features:

• Interactive component showcase with live stories
• Auto-generated component documentation
• Interactive controls for props
• Accessibility testing addon
• Stories colocated with components

Build Commands

Build All Packages

npm run build

Builds the entire monorepo (UI package, Storybook, Docs) with Turborepo.

Build UI Package

npm run build --workspace=packages/ui

Outputs to packages/ui/dist/

• index.js - ES module with all components
• index.d.ts - TypeScript type definitions
• tokens.css - Design token CSS custom properties
• components.css - Pre-built component styles

Build Storybook

npm run build-storybook --workspace=packages/ui

Outputs to packages/ui/storybook-static/ Generates a static HTML site ready for deployment.

Build Docs Site

npm run build --workspace=apps/docs

Outputs to apps/docs/build/ Generates a static Docusaurus site ready for deployment.

Development Commands

Type Check

npm run typecheck

Checks TypeScript types across all packages (required by Turborepo pipeline).

Lint Code

npm run lint

Runs Oxlint across the monorepo.

Run Tests

npm run test

Runs Vitest for the Storybook component tests.

---

Using the UI Package

Installation (Workspace)

If in the same monorepo, the package is automatically available:

npm install @milfushi/ui

Import Components

import { Button, Input, Checkbox, Stack } from "@milfushi/ui";

This is the beginning of the README. Read the rest at the original. Read the full README ↗