Percolate UI - Package Distribution Guide

Branch: percolate-package | Main Repository: Percolate-UI

This branch contains the complete packaging and distribution setup for Percolate UI as an npm package. Use this guide to create and distribute the design system as a reusable package.

🎯 Overview

Percolate UI is a comprehensive design system with 68+ React components built on:

• Radix UI primitives for accessibility
• Tailwind CSS for styling
• TypeScript for type safety
• Next.js optimized components

📦 Package Creation

Step 1: Initialize Package Structure

# Create package directory
mkdir percolate-ui-package
cd percolate-ui-package

# Initialize npm package
npm init -y

# Install build tools
npm install -D typescript @types/react @types/react-dom tsup

Step 2: Project Structure

percolate-ui-package/
├── src/
│   ├── components/
│   │   └── ui/              # Copy from /components/ui (68+ components)
│   ├── contexts/            # Copy from /contexts (7 context providers)
│   ├── lib/
│   │   └── utils.ts         # Copy from /lib/utils.ts
│   ├── hooks/               # Copy from /hooks
│   ├── styles/
│   │   └── globals.css      # Extract CSS variables from app/globals.css
│   └── index.ts             # Main export file
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── tailwind.config.js
└── README.md

Step 3: Package Configuration

package.json

{
  "name": "@percolate/ui",
  "version": "1.0.0",
  "description": "Percolate UI Design System - 68+ React components with Tailwind CSS",
  "main": "dist/index.js",
  "module": "dist/index.esm.js",
  "types": "dist/index.d.ts",
  "files": ["dist", "styles", "tailwind.config.js"],
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    },
    "./styles": "./styles/globals.css",
    "./tailwind": "./tailwind.config.js"
  },
  "scripts": {
    "build": "tsup",
    "dev": "tsup --watch",
    "type-check": "tsc --noEmit",
    "prepublishOnly": "npm run build"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/niteshkumar/Percolate-UI.git",
    "directory": "packages/ui"
  },
  "peerDependencies": {
    "react": ">=18.0.0",
    "react-dom": ">=18.0.0",
    "tailwindcss": ">=3.0.0"
  },
  "dependencies": {
    "@radix-ui/react-accordion": "^1.1.2",
    "@radix-ui/react-alert-dialog": "^1.0.5",
    "@radix-ui/react-avatar": "^1.0.4",
    "@radix-ui/react-checkbox": "^1.0.4",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-label": "^2.0.2",
    "@radix-ui/react-popover": "^1.0.7",
    "@radix-ui/react-select": "^2.0.0",
    "@radix-ui/react-separator": "^1.0.3",
    "@radix-ui/react-slot": "^1.0.2",
    "@radix-ui/react-switch": "^1.0.3",
    "@radix-ui/react-tabs": "^1.0.4",
    "@radix-ui/react-toast": "^1.1.5",
    "@radix-ui/react-tooltip": "^1.0.7",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "tailwind-merge": "^2.5.5",
    "lucide-react": "^0.454.0",
    "next-themes": "^0.2.1"
  }
}

tsup.config.ts

import { defineConfig } from 'tsup'

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
  external: ['react', 'react-dom', 'tailwindcss'],
  banner: {
    js: '"use client";',
  },
})

src/index.ts (Main Export)

// Export all UI components (68+ components)
export * from './components/ui'

// Export context providers
export * from './contexts/color-context'
export * from './contexts/design-context'
export * from './contexts/material-context'
export * from './contexts/sidebar-context'
export * from './contexts/shadow-context'
export * from './contexts/semantic-color-context'
export * from './contexts/view-context'

// Export utilities
export * from './lib/utils'

// Export hooks
export * from './hooks'

🚀 Installation Instructions

For Package Consumers

1. Install Package

npm install @percolate/ui
# or
yarn add @percolate/ui
# or
pnpm add @percolate/ui

2. Install Peer Dependencies

npm install react react-dom tailwindcss

3. Tailwind CSS Setup

Update your tailwind.config.js:

const percolatePreset = require('@percolate/ui/tailwind')

module.exports = {
  presets: [percolatePreset],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    // Include Percolate UI components
    './node_modules/@percolate/ui/**/*.{js,ts,jsx,tsx}',
  ],
}

4. CSS Import

Add to your main CSS file (e.g., globals.css or index.css):

@import '@percolate/ui/styles';
@tailwind base;
@tailwind components;
@tailwind utilities;

5. Provider Setup

// app/layout.tsx (Next.js 13+)
import {
  ColorProvider,
  DesignProvider,
  MaterialProvider
} from '@percolate/ui'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <ColorProvider>
          <DesignProvider>
            <MaterialProvider>
              {children}
            </MaterialProvider>
          </DesignProvider>
        </ColorProvider>
      </body>
    </html>
  )
}

💻 Usage Examples

Basic Components

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Input,
  Label
} from '@percolate/ui'

export default function LoginForm() {
  return (
    <Card className="w-[400px]">
      <CardHeader>
        <CardTitle>Login</CardTitle>
      </CardHeader>
      <CardContent className="space-y-4">
        <div className="space-y-2">
          <Label htmlFor="email">Email</Label>
          <Input id="email" type="email" placeholder="Enter email" />
        </div>
        <div className="space-y-2">
          <Label htmlFor="password">Password</Label>
          <Input id="password" type="password" placeholder="Enter password" />
        </div>
        <Button className="w-full">Sign In</Button>
      </CardContent>
    </Card>
  )
}

Advanced Features with Contexts

import {
  useColorContext,
  useDesignContext,
  Button,
  Switch
} from '@percolate/ui'

function ThemeControls() {
  const { currentPalette, updatePalette } = useColorContext()
  const { designConfig, updateConfig } = useDesignContext()

  return (
    <div className="space-y-4">
      <div className="flex items-center space-x-2">
        <Switch
          checked={currentPalette === 'dark'}
          onCheckedChange={(checked) =>
            updatePalette(checked ? 'dark' : 'light')
          }
        />
        <Label>Dark Mode</Label>
      </div>

      <Button
        variant={designConfig.rounded ? 'default' : 'outline'}
        onClick={() => updateConfig({ rounded: !designConfig.rounded })}
      >
        Toggle Rounded Corners
      </Button>
    </div>
  )
}

Complete Design System Integration

import {
  RightSidebar,
  StyleGuide,
  ColorProvider,
  DesignProvider,
  MaterialProvider
} from '@percolate/ui'

function DesignSystemApp() {
  return (
    <ColorProvider>
      <DesignProvider>
        <MaterialProvider>
          <div className="flex min-h-screen">
            <main className="flex-1">
              <StyleGuide />
            </main>
            <RightSidebar />
          </div>
        </MaterialProvider>
      </DesignProvider>
    </ColorProvider>
  )
}

📊 Component Inventory

Form Components (15+)

Button, Input, Textarea, Checkbox, Radio Group, Select, Combobox, Date Picker, Form, Switch, Slider, Toggle, Toggle Group, OTP Input, File Upload

Layout Components (12+)

Card, Separator, Aspect Ratio, Container, Grid, Stack, Spacer, Divider, Resizable Panels, Scroll Area, Sheet, Collapsible

Navigation Components (8+)

Navigation Menu, Menubar, Breadcrumb, Pagination, Tabs, Command Menu, Context Menu, Dropdown Menu

Overlay Components (10+)

Dialog, Alert Dialog, Popover, Tooltip, Hover Card, Toast, Sonner, Modal, Drawer, Alert

Data Display (15+)

Table, Badge, Avatar, Progress, Skeleton, Accordion, Calendar, Charts, Code Block, Typography, Icon, Image, Video, Carousel, Gallery

Specialized Components (8+)

Theme Toggle, Color Picker, Style Guide, Export Button, Material Provider, Glass Shader, Grain Control, Shadow Control

🔧 Development Commands

# Build the package
npm run build

# Watch mode for development
npm run dev

# Type checking
npm run type-check

# Clean build artifacts
npm run clean

📦 Publishing

To npm Registry

# Build and publish
npm run build
npm publish --access public

To GitHub Packages

# Add to package.json
"publishConfig": {
  "registry": "https://npm.pkg.github.com"
}

# Publish
npm publish

🎨 Customization

Custom Theme

// Create custom theme configuration
const customTheme = {
  colors: {
    primary: {
      50: '#f0f9ff',
      500: '#3b82f6',
      900: '#1e3a8a',
    }
  },
  borderRadius: {
    lg: '12px',
    md: '8px',
    sm: '4px',
  }
}

// Use with providers
<DesignProvider theme={customTheme}>
  {/* Your app */}
</DesignProvider>

Component Variants

import { Button } from '@percolate/ui'

// Built-in variants
<Button variant="default">Default</Button>
<Button variant="destructive">Delete</Button>
<Button variant="outline">Outline</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Custom sizes
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon</Button>

🚀 Migration from Source

If migrating from the source code:

1. Replace imports:

   // Before
   import { Button } from '@/components/ui/button'
   
   // After
   import { Button } from '@percolate/ui'

2. Update CSS imports:

   /* Before */
   @import './app/globals.css'
   
   /* After */
   @import '@percolate/ui/styles'

3. Update Tailwind config:

   // Before
   module.exports = { ... }
   
   // After
   const percolatePreset = require('@percolate/ui/tailwind')
   module.exports = {
     presets: [percolatePreset],
     // your config
   }

📚 Resources

• Source Code: Main Repository
• Documentation: Component Docs
• Examples: Usage Examples
• Storybook: Component Playground

🤝 Contributing

1. Fork the main repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request to the percolate-package branch

📄 License

MIT License - see LICENSE file for details.

Percolate UI - A comprehensive React design system built for modern applications.