npm package: @ginia/ui
Description: Ginia Design System — Unified UI component library for all Ginia hubs
Latest version: 0.1.26

# Ginia Design System (`@ginia/ui`)

> Unified UI component library for all Ginia hubs to accelerate development and guarantee brand consistency.

## 🚀 Overview

The **Ginia Design System** provides a single source of truth for visual consistency, development efficiency, and brand trust across all Ginia hubs. It is built on top of [Radix UI](https://www.radix-ui.com/) and [Tailwind CSS](https://tailwindcss.com/).

🤖 **For AI Agents & Detailed Integration:** Please refer to the [AGENTS.md](./AGENTS.md) file for comprehensive agent context, package exports, conventions, and configuration steps.

## 📖 Documentation

- **Storybook (live)**: <https://ginia-ui.vercel.app>
- **Component index**: <https://ginia-ui.vercel.app/llms.txt>

## 📦 Installation & Setup

### 1. Install the Package

```bash
pnpm add @ginia/ui
```

### 2. Configure Tailwind Preset

In your consumer project's `tailwind.config.ts`:

```typescript
import type { Config } from "tailwindcss";
import giniaPreset from "@ginia/ui/preset";

const config: Config = {
  presets: [giniaPreset],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@ginia/ui/dist/**/*.{js,mjs}", // Crucial for scanning UI classes
  ],
};

export default config;
```

### 3. Import Global Styles

In your `globals.css` or layout root:

```css
@import "@ginia/ui/styles";
```

### 4. Basic Usage

```tsx
// 1. Components & Utilities
import { Button, Card, Input, cn } from "@ginia/ui";

// 2. Icons (from lucide-react)
import { Search, User } from "@ginia/ui/icons";

// 3. Design Tokens
import { colors, fontFamily } from "@ginia/ui/tokens";
```

## 🛠️ Local Development

Prerequisites: **Node.js** ≥ 18 and **pnpm** ≥ 8

```bash
# Install dependencies
pnpm install

# Start Storybook (Development Mode)
pnpm storybook

# Build the library to dist/
pnpm build

# Watch mode (useful when linking to a hub)
pnpm dev

# Type check
pnpm typecheck
```

## 🧩 Adding a Component

We use `shadcn/ui` conventions for base UI primitives:

```bash
npx shadcn@latest add <component-name>
```

For custom or domain components, create them under `src/components/ui/` or `src/components/domain/` following the existing structure (component file, barrel `index.ts`, and `.stories.tsx`).

## 🔗 Local Development with a Hub

To test local changes in a hub project without publishing:

```bash
# 1. In ginia-ui: build in watch mode
pnpm dev

# 2. In your hub project: link the local package
pnpm link ../ginia-ui
```

## 🚢 Publishing

```bash
# Verify and build
pnpm clean && pnpm build && pnpm typecheck && pnpm build-storybook

# Bump the Version
Follow [Semantic Versioning](https://semver.org/):

## Patch release (bug fixes): 0.1.0 → 0.1.1
npm version patch

## Minor release (new features, non-breaking): 0.1.0 → 0.2.0
npm version minor

## Major release (breaking changes): 0.1.0 → 1.0.0
npm version major

# Commit and push
git add .
git commit -m "chore: release v0.2.0"
git push --follow-tags

# Publish
npm publish --access public --otp=<YOUR_OTP_CODE>

# Update the dependency in consumer projects
pnpm update @ginia/ui
```