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 and Tailwind CSS.

🤖 For AI Agents & Detailed Integration: Please refer to the 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

pnpm add @ginia/ui

2. Configure Tailwind Preset

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

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:

@import "@ginia/ui/styles";

4. Basic Usage

// 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

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

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:

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

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

🚢 Publishing

# 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