@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

npm install @galvyn-io/design

2. Import CSS

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

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

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

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

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

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.

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

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

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:

# 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

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

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

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

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

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

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

Development

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

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