npm package: @forcedevelopments/force-ui
Description: A CLI-based component library inspired by shadcn/ui - built by Force Developments
Author: Force Developments
Latest version: 0.1.1

# 🚀 Force UI

A modern, CLI-based component library inspired by shadcn/ui. Built by [Force Developments](https://forcedevelopments.com/).

> **📖 Quick Links:**
> - **Getting Started:** [Setup Guide](./SETUP_GUIDE.md) | [Commands](./COMMANDS.md) | [Getting Started](./GETTING_STARTED.md)
> - **Theming:** [Theme Guide](./THEME_GUIDE.md) | [Dynamic Themes](./DYNAMIC_THEME_IMPLEMENTATION.md)
> - **Publishing:** [📦 Deploy Guide](./DEPLOY.md) | [Publishing](./PUBLISHING.md)

## Philosophy

Force UI follows a **copy-paste** approach rather than traditional npm installation. Components are added directly to your project, giving you complete ownership and control. Modify them freely—they're yours!

## Features

- 🎨 **Beautiful components** built with Tailwind CSS
- 📦 **Copy-paste philosophy** - own your code
- 🔧 **Fully customizable** - modify components as needed
- 💪 **TypeScript first** - complete type safety
- ♿ **Accessible** - ARIA compliant components
- 🎭 **Variants** - multiple styles using class-variance-authority
- 🌙 **Dark mode** - built-in dark mode support
- 🎨 **7 Built-in Themes** - Slate, Orange, Green, Blue, Yellow, Pink, Purple
- 🔌 **Selective Installation** - Add only the components you need
- ⚡ **Dynamic Theme Switching** - Change themes via CLI, React hooks, or per-page
- 🔄 **Per-Page Themes** - Different themes for different pages on the same site

## Quick Start

### Installation

```bash
npm install -g @forcedevelopments/force-ui
```

Or use with npx:

```bash
npx @forcedevelopments/force-ui init
```

### Initialize in Your Project

```bash
cd your-project
force-ui init
```

Choose your preferred theme (Slate, Orange, Green, Blue, Yellow, Pink, Purple) during initialization.

This creates:
- `lib/utils.ts` - Utility functions
- `components/ui/` - Directory for components
- `app/globals.css` - Theme CSS variables (if app directory exists)

### Install Dependencies

```bash
npm install clsx tailwind-merge class-variance-authority
```

### Add Components

```bash
# Add a single component
force-ui add button

# Add multiple components
force-ui add button card input

# Interactive selection
force-ui add
```

### Change Theme

```bash
# List available themes
force-ui theme

# Apply a specific theme
force-ui theme orange
force-ui theme purple
```

### Generate Tailwind Config

```bash
force-ui config
```

## Dynamic Theming

Force UI supports **dynamic theme switching** at runtime! Change themes programmatically, per-page, or via CLI.

### Three Ways to Manage Themes

1. **Global via CLI** (Default theme for entire app)
```bash
force-ui theme purple
```

2. **Dynamic via React** (Programmatic control)
```tsx
import { ThemeProvider, useTheme } from '@/components/theme-provider';

function App() {
  return (
    <ThemeProvider defaultTheme="slate">
      <YourApp />
    </ThemeProvider>
  );
}

function ThemeSwitcher() {
  const { setTheme } = useTheme();
  return <button onClick={() => setTheme('orange')}>Orange Theme</button>;
}
```

3. **Per-Page Themes** (Different themes on different pages)
```tsx
import { PageTheme } from '@/components/theme-provider';

// Home page with slate theme
export default function Home() {
  return (
    <PageTheme theme="slate">
      <HomePage />
    </PageTheme>
  );
}

// Products page with orange theme
export default function Products() {
  return (
    <PageTheme theme="orange">
      <ProductsPage />
    </PageTheme>
  );
}
```

📖 **[Read the complete Theme Guide →](./THEME_GUIDE.md)**

## Usage Example

After adding the button component:

```tsx
import { Button } from '@/components/ui/button';

export default function App() {
  return (
    <div>
      <Button variant="default">Click me</Button>
      <Button variant="destructive">Delete</Button>
      <Button variant="outline" size="sm">Small</Button>
    </div>
  );
}
```

## Available Components

- **Button** - Versatile button with multiple variants
- **Card** - Flexible card layout with header, content, and footer
- **Input** - Styled text input field

More components coming soon!

## Configuration

### Tailwind CSS

Add to your `tailwind.config.js`:

```javascript
module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        ring: "hsl(var(--ring))",
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        secondary: {
          DEFAULT: "hsl(var(--secondary))",
          foreground: "hsl(var(--secondary-foreground))",
        },
        destructive: {
          DEFAULT: "hsl(var(--destructive))",
          foreground: "hsl(var(--destructive-foreground))",
        },
        muted: {
          DEFAULT: "hsl(var(--muted))",
          foreground: "hsl(var(--muted-foreground))",
        },
        accent: {
          DEFAULT: "hsl(var(--accent))",
          foreground: "hsl(var(--accent-foreground))",
        },
        card: {
          DEFAULT: "hsl(var(--card))",
          foreground: "hsl(var(--card-foreground))",
        },
      },
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
    },
  },
  plugins: [],
}
```

### CSS Variables

Add to your `globals.css`:

```css
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;

    --card: 0 0% 100%;
    --card-foreground: 222.2 84% 4.9%;

    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;

    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;

    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;

    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;

    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;

    --border: 214.3 31.8% 91.4%;
    --input: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;

    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;

    --card: 222.2 84% 4.9%;
    --card-foreground: 210 40% 98%;

    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;

    --secondary: 217.2 32.6% 17.5%;
    --secondary-foreground: 210 40% 98%;

    --muted: 217.2 32.6% 17.5%;
    --muted-foreground: 215 20.2% 65.1%;

    --accent: 217.2 32.6% 17.5%;
    --accent-foreground: 210 40% 98%;

    --destructive: 0 62.8% 30.6%;
    --destructive-foreground: 210 40% 98%;

    --border: 217.2 32.6% 17.5%;
    --input: 217.2 32.6% 17.5%;
    --ring: 212.7 26.8% 83.9%;
  }
}

@layer base {
  * {
    @apply border-border;
  }
  body {
    @apply bg-background text-foreground;
  }
}
```

### TypeScript Path Alias

Add to your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}
```

## Component Documentation

### Button

```tsx
import { Button } from '@/components/ui/button';

// Variants
<Button variant="default">Default</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon">🎨</Button>
```

### Card

```tsx
import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from '@/components/ui/card';

<Card>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
    <CardDescription>Card description goes here</CardDescription>
  </CardHeader>
  <CardContent>
    <p>Card content</p>
  </CardContent>
  <CardFooter>
    <Button>Action</Button>
  </CardFooter>
</Card>
```

### Input

```tsx
import { Input } from '@/components/ui/input';

<Input type="text" placeholder="Enter text..." />
<Input type="email" placeholder="Email" />
<Input type="password" placeholder="Password" />
```

## Why Force UI?

### vs Traditional Component Libraries
- **Full Control**: Components live in your repo—modify as needed
- **No Bloat**: Only add components you actually use
- **Easy Debugging**: See and edit the source code directly
- **No Version Conflicts**: Components are versioned with your code

### vs shadcn/ui
Force UI is inspired by shadcn/ui but:
- Built and maintained by Force Developments
- May include different components and features
- Focused on our specific design philosophy

## Development

Want to contribute or build your own?

```bash
# Clone the repository
git clone https://github.com/forcedevelopments/force-ui

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Link locally for testing
npm link
```

## Themes

Force UI comes with 7 beautiful pre-built themes:

| Theme | Description | Command |
|-------|-------------|---------|
| **Slate** | Professional gray (default) | `force-ui theme slate` |
| **Orange** | Warm and energetic | `force-ui theme orange` |
| **Green** | Fresh and natural | `force-ui theme green` |
| **Blue** | Calm and trustworthy | `force-ui theme blue` |
| **Yellow** | Bright and cheerful | `force-ui theme yellow` |
| **Pink** | Playful and modern | `force-ui theme pink` |
| **Purple** | Creative and bold | `force-ui theme purple` |

Switch themes anytime with a single command - all your components will automatically adapt!

## Documentation Website

Want to see components in action? Check out our documentation website:

```bash
cd docs
npm install
npm run dev
```

The docs site includes:
- 📚 Complete installation guide
- 🎨 Live component previews
- 💻 Interactive code examples
- 🌈 Theme showcase with live switching
- 📖 Full API documentation

### Deploy the Docs

The documentation website can be deployed to Vercel, Netlify, or any hosting platform. See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed instructions.

## Roadmap

- [x] Multiple color themes
- [x] Theme switching CLI command
- [x] Documentation website
- [ ] More components (Dialog, Dropdown, Tabs, Select, etc.)
- [ ] Component variants and customization
- [ ] Storybook integration
- [ ] Figma design kit
- [ ] Component generator CLI
- [ ] VS Code extension

## Support

- 🌐 Website: [forcedevelopments.com](https://forcedevelopments.com/)
- 🐛 Issues: [GitHub Issues](https://github.com/forcedevelopments/force-ui/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/forcedevelopments/force-ui/discussions)

## License

MIT © Force Developments

---

Built with ❤️ by [Force Developments](https://forcedevelopments.com/)