npm package: @galvyn-io/design
Description: Galvyn Design System — dark-first, monotone with surgical accent color. Tailwind preset + CSS variables + React components.
Author: Yatharth Gupta
Latest version: 0.2.0

# @galvyn-io/design

Dark-first design system with monotone canvas and surgical accent color. Built for internal tools and admin panels.

Works with **Next.js + Tailwind CSS + shadcn/ui** out of the box.

## Quick Start

### 1. Install

```bash
npm install @galvyn-io/design
```

### 2. Import CSS

In your `app/globals.css` (or wherever your global styles live):

```css
/* Import BEFORE Tailwind directives and shadcn styles */
@import "@galvyn-io/design/css";

/* Then your existing Tailwind + shadcn imports */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Optional: set accent hue per-project */
:root {
  --galvyn-accent-hue: 220; /* blue (default) */
  /* Try: 180 (teal), 270 (purple), 340 (pink), 150 (green), 30 (amber) */
}
```

### 3. Add Tailwind Preset

In your `tailwind.config.ts`:

```ts
import type { Config } from 'tailwindcss';
import galvynPreset from '@galvyn-io/design/preset';

export default {
  presets: [galvynPreset],  // ← adds galvyn-* utilities
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    // ... your paths
  ],
  // ... rest of your config (shadcn, etc.)
} satisfies Config;
```

> **Note:** The preset _extends_ your config. It does NOT override shadcn or any existing utilities. All galvyn classes are namespaced with `galvyn-*`.

### 4. Use It

```tsx
// Tailwind classes
<div className="bg-galvyn-bg-000 text-galvyn-text-100">
  <button className="bg-galvyn-accent-400 text-white rounded-galvyn-md">
    Deploy
  </button>
</div>

// Gradient border utility class
<div className="galvyn-border-gradient rounded-galvyn-lg bg-galvyn-surface-100 p-4">
  Card with gradient border
</div>

// React components (optional)
import { Button, Card, Badge } from '@galvyn-io/design/components';

<Card border="strong">
  <Badge variant="success" dot>Healthy</Badge>
  <Button variant="accent">Deploy</Button>
</Card>
```

---

## Architecture

```
@galvyn-io/design
├── /css          → CSS custom properties + utility classes (the core)
├── /preset       → Tailwind preset (extends, never overrides)
├── /components   → React primitives (Button, Card, Badge, etc.)
├── /tokens       → Token constants + helper functions
└── index         → Re-exports tokens, types, helpers
```

### Three import paths, each independent:

| Import | What | Required? |
|--------|------|-----------|
| `@galvyn-io/design/css` | CSS variables + utility classes | **Yes** |
| `@galvyn-io/design/preset` | Tailwind preset | **Yes** (if using Tailwind) |
| `@galvyn-io/design/components` | React components | Optional |

---

## Accent Hue System

The entire accent palette is driven by a single CSS variable:

```css
:root {
  --galvyn-accent-hue: 220;  /* Change this to rotate everything */
}
```

| Hue | Color | Vibe |
|-----|-------|------|
| `220` | Blue | Default / Vercel |
| `180` | Teal | Cloud / infra |
| `270` | Purple | Raycast |
| `340` | Pink | Warm |
| `150` | Green | Growth |
| `30` | Amber | Alert |

You can also set it per-component or per-section:

```tsx
import { galvynAccent } from '@galvyn-io/design';

// Different accent per project
<div style={galvynAccent('teal')}>
  This section uses teal accent
</div>

// Or with a raw hue value
<div style={galvynAccent(300)}>
  Custom hue
</div>
```

---

## shadcn Compatibility

Galvyn is designed to coexist with shadcn/ui:

- All CSS variables are prefixed `--galvyn-*` (no collision with shadcn's `--` vars)
- The Tailwind preset uses `extend` (never replaces shadcn utilities)
- All Tailwind classes are namespaced: `bg-galvyn-*`, `text-galvyn-*`, etc.
- You can use shadcn components alongside Galvyn components

**Recommended approach:** Use shadcn for complex components (Dialog, Dropdown, etc.) and style them with Galvyn CSS variables for consistent theming.

```tsx
// shadcn Dialog, styled with Galvyn tokens
<Dialog>
  <DialogContent className="bg-galvyn-surface-100 border-galvyn-border-200">
    <DialogTitle className="text-galvyn-text-000">Settings</DialogTitle>
  </DialogContent>
</Dialog>
```

---

## Gradient Borders

The signature effect. Four tiers:

```html
<!-- Subtle (default cards) -->
<div class="galvyn-border-gradient">...</div>

<!-- Medium (focused elements) -->
<div class="galvyn-border-gradient galvyn-border-gradient-medium">...</div>

<!-- Strong (accent-tinted) -->
<div class="galvyn-border-gradient galvyn-border-gradient-strong">...</div>

<!-- Accent (full gradient) -->
<div class="galvyn-border-gradient galvyn-border-gradient-accent">...</div>

<!-- Shimmer (animated, use sparingly) -->
<div class="galvyn-border-gradient galvyn-border-shimmer">...</div>
```

Or with the React helper:

```tsx
import { GradientBorder } from '@galvyn-io/design/components';

<GradientBorder variant="strong" className="p-4 rounded-galvyn-lg">
  Premium content
</GradientBorder>
```

---

## Multi-Project Setup

Each project installs the same package but can customize:

```
galvyn-dashboard/     → --galvyn-accent-hue: 220 (blue)
jarvis-agent/         → --galvyn-accent-hue: 180 (teal)
golf-booking-agent/   → --galvyn-accent-hue: 150 (green)
```

When you update the package:

```bash
# In each project
npm update @galvyn-io/design
```

Or pin to a version in `package.json` and update when ready.

---

## Components

All components use CSS variables — they automatically respond to theme and accent changes.

### Button

```tsx
import { Button } from '@galvyn-io/design/components';

<Button variant="default" size="md">Default</Button>
<Button variant="accent">Deploy</Button>
<Button variant="danger" size="sm">Delete</Button>
<Button variant="ghost" loading>Loading...</Button>
```

### Badge

```tsx
import { Badge } from '@galvyn-io/design/components';

<Badge variant="success" dot>Healthy</Badge>
<Badge variant="error">3 errors</Badge>
<Badge variant="accent">New</Badge>
```

### Card

```tsx
import { Card } from '@galvyn-io/design/components';

<Card border="subtle" padding="md">Default card</Card>
<Card border="strong" padding="lg" hover>Clickable card</Card>
```

### Input

```tsx
import { Input } from '@galvyn-io/design/components';

<Input label="Project" placeholder="my-project" hint="Lowercase only" />
<Input label="Endpoint" mono placeholder="https://..." />
<Input label="Region" error="Invalid region" />
```

### StatusDot, Kbd

```tsx
import { StatusDot, Kbd } from '@galvyn-io/design/components';

<StatusDot status="online" label="API Gateway" />
<Kbd>⌘</Kbd><Kbd>K</Kbd>
```

---

## Development

```bash
git clone https://github.com/galvyn-io/galvyn-design.git
cd galvyn-design
npm install
npm run build    # builds to dist/
npm run dev      # watch mode
```

### Publishing

```bash
npm run release  # builds + publishes to npm
```

---

## Token Reference

### Color Tokens

| Token | Dark | Light | Usage |
|-------|------|-------|-------|
| `--galvyn-bg-000` | `#09090b` | `#ffffff` | Page background |
| `--galvyn-bg-100` | `#0c0c0e` | `#fafafa` | App background |
| `--galvyn-surface-100` | `#141416` | `#ffffff` | Card/panel bg |
| `--galvyn-surface-hover` | `#2a2a2d` | `#ededf0` | Hover state |
| `--galvyn-text-100` | `#fafafa` | `#18181b` | Primary text |
| `--galvyn-text-200` | `#a1a1aa` | `#52525b` | Secondary text |
| `--galvyn-text-300` | `#71717a` | `#71717a` | Tertiary text |
| `--galvyn-accent-400` | hsl-based | hsl-based | Primary accent |

### Spacing (4px grid)

`space-1` = 4px, `space-2` = 8px, `space-3` = 12px, `space-4` = 16px, `space-6` = 24px, `space-8` = 32px

### Radii

`sm` = 4px, `md` = 6px, `lg` = 8px, `xl` = 12px, `2xl` = 16px

---

## License

MIT