npm package: @jybrd/design-system
Description: jayBird Design System - Enterprise component library and design system
Author: jayBird US
Latest version: 1.0.118

# 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](https://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:
```bash
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:**

```bash
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:

```css
/* 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:

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

### Usage

```tsx
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:

```json
{
  "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:

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

### Versioning

This project follows [Semantic Versioning](https://semver.org/):
- **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](./CHANGELOG.md) for version history and migration guides.

## 🏗️ Development

### Prerequisites

- Node.js 20+
- npm or pnpm

### Setup

```bash
# 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](./DEPLOYMENT.md) for detailed deployment instructions.

### Manual Deployment

```bash
# 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`:

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

Then install components:

```bash
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:

```bash
# 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:**
   ```bash
   mkdir -p registry/default/your-component
   ```

2. **Create component file:**
   ```typescript
   // registry/default/your-component/your-component.tsx
   export function YourComponent() {
     return <div>Your Component</div>
   }
   ```

3. **Create Storybook story:**
   ```typescript
   // 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:**
   ```bash
   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](https://jaybird-design-system.pages.dev)
- [GitHub Repository](https://github.com/jaybird-us/design-system)
- [Issue Tracker](https://github.com/jaybird-us/design-system/issues)
- [Deployment Guide](./DEPLOYMENT.md)

## 📞 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