Northstar Design System

A React + TypeScript + Vite-based design system using shadcn/ui, Tailwind CSS, Storybook, and Cypress for component development, documentation, and testing.

Table of Contents

• Getting Started
• Code Generation
  • Component Codegen
  • Design Tokens Codegen
  • Storybook Codegen
• Storybook
• Cypress
• Build & Lint
• Project Structure

Getting Started

1. Install dependencies:

   npm install

2. Start the development server:

   npm run dev

Code Generation

Component Codegen

To scaffold a new component (using shadcn/ui, wrapper, and Storybook story):

npm run component:codegen

• You will be prompted to select a component (e.g., button, calendar, etc.).
• This will:
  1. Run npx shadcn@latest add <component> to add the base UI component.
  2. Generate a wrapper component in src/components/<Component>/<Component>.tsx and an index.ts.
  3. Generate a Storybook story in the same folder.

How it works:
See scripts/components-codegen/components-codegen.sh, scripts/components-codegen/components-codegen.ts, and scripts/storybook-codegen/storybook-codegen.ts.

Design Tokens Codegen

To update Tailwind config from design tokens (e.g., from Penpot):

npm run theme:codegen

• This reads scripts/penpot-codegen/design-tokens.json and generates tailwind.config.js with the mapped tokens.

How it works:
See scripts/penpot-codegen/design-tokens-tailwind-codegen.ts.

Storybook Codegen

Storybook stories are auto-generated for each new component via the component codegen script.
You can also run the storybook codegen script directly:

node scripts/storybook-codegen/storybook-codegen.ts <ComponentPath>

Storybook

To start Storybook for interactive component development and documentation:

npm run storybook

• This will also start Tailwind in watch mode for live style updates.

To build static Storybook docs:

npm run build-storybook

Cypress

To run Cypress component tests:

npm run cypress:open

• This opens the Cypress UI for running and debugging tests.

Build & Lint

• Build the library:

  npm run build

• Lint the codebase:

  npm run lint

Project Structure

• src/components — All components (UI, wrappers, and stories)
• src/lib — Utilities (e.g., cn function)
• src/index.ts — Entry point for exports
• tailwind.config.js — Tailwind CSS config (auto-generated from design tokens)
• scripts — Codegen and automation scripts
• .storybook — Storybook configuration

References

• shadcn/ui Documentation
• Storybook Documentation
• Cypress Documentation