jayBird Design System

Enterprise-wide component library and design system for jayBird US.

🎨 Overview

The jayBird Design System is a comprehensive collection of reusable React components built with:

• React 19 - Latest React features
• TypeScript - Type-safe development
• Tailwind CSS - Utility-first styling
• Radix UI - Accessible component primitives
• Storybook - Component documentation and development

📚 Documentation

View the component library: jaybird-design-system.pages.dev (after deployment)

🚀 Quick Start

Installation

This package is published to GitHub Packages. You need to configure your project to authenticate with GitHub Packages.

1. Create or update .npmrc in your project root:

@jaybird-us:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}

2. Set up authentication:

Create a GitHub Personal Access Token with read:packages scope at https://github.com/settings/tokens

Then set the environment variable:

export NPM_TOKEN=your_github_token_here

Or add to your ~/.npmrc (not recommended for teams):

//npm.pkg.github.com/:_authToken=your_github_token_here

3. Install the package:

npm install @jaybird-us/design-system

Configuration (Required)

1. Configure Tailwind CSS v4

Add the @source directive to your CSS file to include design system classes:

/* src/index.css or app/globals.css */
@import "tailwindcss";

@source "../node_modules/@jybrd/design-system";  /* Required for Tailwind v4 */

@custom-variant dark (&:is(.dark *));

/* Theme variables - copy from design system or use your own */
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.147 0.004 49.25);
  --primary: oklch(0.216 0.006 56.043);
  --primary-foreground: oklch(0.985 0.001 106.423);
  /* ... see globals.css for full theme */
}

Note: Without the @source directive, Tailwind v4 won't scan node_modules and classes like bg-background, shadow-border/60, etc. won't be compiled.

2. Import Styles (Alternative)

Or import the design system's pre-configured styles:

// In your entry point (main.tsx, App.tsx, or layout.tsx)
import '@jybrd/design-system/styles'

Usage

import { Button } from '@jybrd/design-system/components/ui/button'
import { AppShell } from '@jybrd/design-system/compounds/app-shell'
import { DataTable } from '@jybrd/design-system/compounds/data-table'

export default function App() {
  return (
    <AppShell fullScreen>
      <AppShell.Sidebar>
        {/* Navigation */}
      </AppShell.Sidebar>
      <AppShell.Main>
        <AppShell.Header title="Dashboard" />
        <AppShell.Body>
          <Button>Click me</Button>
          <DataTable columns={columns} data={data} />
        </AppShell.Body>
      </AppShell.Main>
    </AppShell>
  )
}

📦 Package Updates

Automatic Updates

To always use the latest version of the design system:

{
  "dependencies": {
    "@jaybird-us/design-system": "^1.0.0"
  }
}

Run npm update to get the latest compatible version.

Controlled Updates

To lock to a specific version:

{
  "dependencies": {
    "@jaybird-us/design-system": "1.0.0"
  }
}

Versioning

This project follows Semantic Versioning:

• Major (1.x.x): Breaking changes
• Minor (x.1.x): New features, backward compatible
• Patch (x.x.1): Bug fixes, backward compatible

See CHANGELOG.md for version history and migration guides.

🏗️ Development

Prerequisites

• Node.js 20+
• npm or pnpm

Setup

# Clone the repository
git clone https://github.com/jaybird-us/design-system.git
cd design-system

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Run tests
npm test

Available Scripts

• npm run storybook - Start Storybook development server
• npm run build-storybook - Build Storybook for production
• npm run dev - Start Next.js development server
• npm run build - Build Next.js application
• npm test - Run tests with Vitest
• npm run lint - Run ESLint
• npm run registry:build - Build component registry

📦 Component Categories

Elements (Primitives)

• Inputs: Button, Input, Select, Checkbox, Radio, Switch, Slider, Toggle, Calendar, InputOTP, InputGroup, NativeSelect
• Display: Badge, Card, Avatar, Table, Skeleton, Accordion, AspectRatio, Collapsible, Carousel, ScrollArea, Kbd, Empty
• Navigation: Tabs, Breadcrumb, Pagination, Menubar, NavigationMenu
• Overlay: Dialog, Drawer, Sheet, Popover, Tooltip, AlertDialog, ContextMenu, HoverCard
• Feedback: Alert, Progress, Spinner, Toast (Sonner)
• Layout: Resizable panels, ButtonGroup

Compounds

• Layout: AppShell, TabbedContainer, CollapsibleContainer, RecordDetail
• Forms: LoginForm, ContactForm, NewsletterForm
• Cards: PricingCard, StatCard, ProfileCard, FeatureCard
• Navigation: UserMenu, UserMenuCompact, SearchBar, CommandPalette
• Data: DataTable, ImageGallery, ProgressTracker
• Dialogs: ConfirmationDialog, SettingsPanel

🔧 Tech Stack

• Framework: Next.js 16
• UI Library: React 19
• Styling: Tailwind CSS 4
• Component Base: Radix UI
• Documentation: Storybook 10
• Testing: Vitest + Testing Library
• Type Safety: TypeScript 5
• Icons: Lucide React

🌐 Deployment

This project is automatically deployed to Cloudflare Pages on every push to the main branch.

See DEPLOYMENT.md for detailed deployment instructions.

Manual Deployment

# Build Storybook
npm run build-storybook

# The output will be in the `storybook-static` directory

🎯 Using Components from the Registry

Install via shadcn CLI

Configure your project's components.json:

{
  "registries": {
    "@jaybird": "https://jaybird-design-system.pages.dev/r/{name}.json"
  }
}

Then install components:

npx shadcn@latest add @jaybird/app-shell
npx shadcn@latest add @jaybird/pricing-card
npx shadcn@latest add @jaybird/data-table

Local Development

Test components from your local registry:

# Start the dev server
npm run dev

# In another terminal, build the registry
npm run registry:build

# Install from local registry
npx shadcn@latest add http://localhost:3000/r/app-shell.json

🤝 Contributing

1. Create a feature branch: git checkout -b feature/new-component
2. Make your changes and test thoroughly
3. Run tests: npm test
4. Run linting: npm run lint
5. Commit your changes: git commit -m 'Add new component'
6. Push to the branch: git push origin feature/new-component
7. Create a Pull Request

Component Guidelines

• All components must include TypeScript types
• Write Storybook stories for all components
• Include unit tests with Vitest
• Follow accessibility best practices
• Use Tailwind CSS for styling
• Document component props and usage

Adding New Components

1. Create component directory:

   mkdir -p registry/default/your-component

2. Create component file:

   // registry/default/your-component/your-component.tsx
   export function YourComponent() {
     return <div>Your Component</div>
   }

3. Create Storybook story:

   // registry/default/your-component/your-component.stories.tsx
   import type { Meta, StoryObj } from '@storybook/react'
   import { YourComponent } from './your-component'
   
   const meta = {
     title: 'Compounds/YourComponent',
     component: YourComponent,
   } satisfies Meta<typeof YourComponent>
   
   export default meta

4. Add to registry.json (if distributing via registry)

5. Rebuild:

   npm run registry:build

📁 Project Structure

design-system/
├── registry/              # Component source code
│   └── default/
│       ├── ui/           # Primitive components (Elements)
│       ├── app-shell/    # Compound components
│       ├── pricing-card/
│       └── ...
├── .storybook/           # Storybook configuration
├── app/                  # Next.js demo app
├── public/
│   └── r/               # Built registry JSON files
├── .github/
│   └── workflows/       # CI/CD workflows
└── package.json

📄 License

MIT © jayBird US

🔗 Links

• Storybook Documentation
• GitHub Repository
• Issue Tracker
• Deployment Guide

📞 Support

For questions or support, please:

• Create an issue in GitHub
• Contact the design system team
• Check the Storybook documentation

Built with ❤️ by the jayBird team