# Color Usage Guide - Kodo Design System

**Last Updated**: 2025-01-27  
**Purpose**: Document when and how to use each color in the Kodo design system

## Overview

The Veza application uses the **Kodo Design System** - a cyber/gaming-inspired dark theme palette with neon accents. This guide ensures consistent color usage across the application.

## Color System Architecture

### Primary System: Kodo Design System

The Kodo system is defined in `apps/web/src/index.css` and is the primary color system used throughout the application.

### Secondary System: Veza Fusion Design System

The Veza Fusion system (defined in `apps/web/src/styles/design-system.css`) contains additional colors but is **not the primary system**. Use Kodo colors unless explicitly required by design.

---

## Core Palette

### Background Colors

#### `kodo-void` (Primary Background)
- **RGB**: `11 12 16` / `#0B0C10`
- **Usage**: Main application background, page backgrounds
- **Tailwind**: `bg-kodo-void`
- **When to use**: 
  - Main page backgrounds
  - Root HTML/body background
  - Modal backdrops (with opacity)
- **When NOT to use**: 
  - Cards (use `kodo-graphite` or `kodo-ink`)
  - Elevated surfaces (use `kodo-ink` or `kodo-graphite`)

#### `kodo-ink` (Secondary Background)
- **RGB**: `23 25 35`
- **Usage**: Panels, elevated surfaces, popovers
- **Tailwind**: `bg-kodo-ink`
- **When to use**:
  - Popover backgrounds
  - Elevated panels
  - Secondary containers
- **When NOT to use**:
  - Main backgrounds (use `kodo-void`)
  - Cards (use `kodo-graphite`)

#### `kodo-graphite` (Card Background)
- **RGB**: `31 40 51` / `#1F2833`
- **Usage**: Cards, elevated content containers
- **Tailwind**: `bg-kodo-graphite`
- **When to use**:
  - Card backgrounds
  - Content containers
  - Elevated surfaces that need more contrast
- **When NOT to use**:
  - Main backgrounds (use `kodo-void`)
  - Borders (use `kodo-steel`)

#### `kodo-slate` (Surface Elevated)
- **RGB**: `44 54 67`
- **Usage**: Secondary surfaces, hover states
- **Tailwind**: `bg-kodo-slate`
- **When to use**:
  - Secondary button backgrounds
  - Hover states for dark surfaces
  - Subtle elevation
- **When NOT to use**:
  - Primary backgrounds
  - Borders

#### `kodo-steel` (Borders & Muted)
- **RGB**: `59 69 84`
- **Usage**: Borders, dividers, muted backgrounds
- **Tailwind**: `bg-kodo-steel`, `border-kodo-steel`
- **When to use**:
  - Borders and dividers
  - Muted/disabled backgrounds
  - Input borders
  - Separators
- **When NOT to use**:
  - Text (use `kodo-content-dim` for muted text)
  - Primary backgrounds

---

## Accent Colors

### Primary Accent: Cyan

#### `kodo-cyan` (Primary Accent)
- **RGB**: `102 252 241` / `#66FCF1`
- **Usage**: Primary actions, links, highlights, focus states
- **Tailwind**: `text-kodo-cyan`, `bg-kodo-cyan`, `border-kodo-cyan`
- **When to use**:
  - Primary buttons
  - Links and interactive elements
  - Focus rings and active states
  - Important highlights
  - Icons that need attention
  - Selection indicators
- **When NOT to use**:
  - Body text (too bright)
  - Large background areas (use with opacity: `bg-kodo-cyan/10`)
  - Error states (use `kodo-red`)

#### `kodo-cyan-dim` (Secondary Cyan)
- **RGB**: `69 162 158` / `#45A29E`
- **Usage**: Secondary accents, less prominent highlights
- **Tailwind**: `text-kodo-cyan-dim`, `bg-kodo-cyan-dim`
- **When to use**:
  - Secondary actions
  - Less prominent highlights
  - Gradients with cyan
- **When NOT to use**:
  - Primary actions (use `kodo-cyan`)

### Secondary Accent: Magenta

#### `kodo-magenta` (Secondary Accent)
- **RGB**: `138 126 164` / `#8A7EA4`
- **Usage**: Secondary actions, alternative highlights
- **Tailwind**: `text-kodo-magenta`, `bg-kodo-magenta`
- **When to use**:
  - Secondary buttons
  - Alternative highlights
  - Gradients with cyan
  - Decorative elements
- **When NOT to use**:
  - Primary actions (use `kodo-cyan`)
  - Error states (use `kodo-red`)

### Tertiary Accent: Orange

#### `kodo-orange` (Tertiary Accent)
- **RGB**: `230 184 156` / `#E6B89C`
- **Usage**: Warm accents, special highlights
- **Tailwind**: `text-kodo-orange`, `bg-kodo-orange`
- **When to use**:
  - Special highlights
  - Warm accent elements
  - Decorative purposes
- **When NOT to use**:
  - Primary or secondary actions
  - Error states

---

## Semantic Colors

### Success

#### `kodo-lime` (Success)
- **RGB**: `54 229 209`
- **Usage**: Success states, positive feedback
- **Tailwind**: `text-kodo-lime`, `bg-kodo-lime`
- **When to use**:
  - Success messages
  - Positive indicators
  - Completed states
  - Success badges
- **When NOT to use**:
  - Primary actions (use `kodo-cyan`)
  - Error states

### Warning

#### `kodo-gold` (Warning)
- **RGB**: `234 179 8`
- **Usage**: Warning states, caution indicators
- **Tailwind**: `text-kodo-gold`, `bg-kodo-gold`
- **When to use**:
  - Warning messages
  - Caution indicators
  - Rate limit warnings
  - Attention-grabbing elements
- **When NOT to use**:
  - Error states (use `kodo-red`)
  - Success states

### Error

#### `kodo-red` (Error/Destructive)
- **RGB**: `230 57 70` / `#E63946`
- **Usage**: Errors, destructive actions, critical alerts
- **Tailwind**: `text-kodo-red`, `bg-kodo-red`, `border-kodo-red`
- **When to use**:
  - Error messages
  - Destructive actions (delete, remove)
  - Critical alerts
  - Validation errors
  - Failed states
- **When NOT to use**:
  - Primary actions
  - Success states
  - Warning states (use `kodo-gold`)

---

## Text Colors

### Primary Text

#### `kodo-text-main` (Primary Text)
- **RGB**: `243 243 224` / `#F3F3E0`
- **Usage**: Primary body text, headings
- **Tailwind**: `text-kodo-text-main` (usually default)
- **When to use**:
  - Body text
  - Headings
  - Primary content
  - Labels
- **When NOT to use**:
  - Muted/secondary text (use `kodo-content-dim`)

#### `kodo-content-highlight` (Highlighted Text)
- **RGB**: `255 255 255` / `#FFFFFF`
- **Usage**: Important text, emphasized content
- **Tailwind**: `text-kodo-content-highlight`
- **When to use**:
  - Important headings
  - Emphasized content
  - High-contrast text needs
- **When NOT to use**:
  - Body text (use `kodo-text-main`)

#### `kodo-content-dim` (Muted Text)
- **RGB**: `156 163 175` / Gray-400
- **Usage**: Secondary text, hints, metadata
- **Tailwind**: `text-kodo-content-dim`, `text-kodo-secondary`
- **When to use**:
  - Secondary/helper text
  - Metadata (timestamps, counts)
  - Placeholder text
  - Disabled text
  - Hints and descriptions
- **When NOT to use**:
  - Primary content (use `kodo-text-main`)
  - Important information

---

## Opacity Variants

All colors support opacity modifiers in Tailwind:

- `bg-kodo-cyan/10` - 10% opacity (subtle backgrounds)
- `bg-kodo-cyan/20` - 20% opacity (light backgrounds)
- `bg-kodo-cyan/30` - 30% opacity (medium backgrounds)
- `border-kodo-cyan/40` - 40% opacity (borders)
- `text-kodo-cyan/50` - 50% opacity (muted text)

**Common Patterns**:
- `bg-kodo-cyan/10` - Subtle highlight backgrounds
- `bg-kodo-cyan/20` - Light highlight backgrounds
- `border-kodo-cyan/30` - Subtle borders
- `border-kodo-cyan/40` - Medium borders

---

## Usage Guidelines

### 80/20 Rule

- **80% Neutral**: Use background colors (`kodo-void`, `kodo-ink`, `kodo-graphite`, `kodo-steel`) and text colors (`kodo-text-main`, `kodo-content-dim`) for most of the UI
- **20% Color**: Use accent colors (`kodo-cyan`, `kodo-magenta`, `kodo-lime`, `kodo-gold`, `kodo-red`) sparingly for:
  - Interactive elements
  - Important highlights
  - Status indicators
  - Calls to action

### Color Hierarchy

1. **Primary**: `kodo-cyan` - Most important interactive elements
2. **Secondary**: `kodo-magenta` - Secondary actions, alternative highlights
3. **Semantic**: `kodo-lime` (success), `kodo-gold` (warning), `kodo-red` (error)
4. **Neutral**: Background and text colors for structure

### Do's and Don'ts

#### ✅ DO:
- Use `kodo-cyan` for primary actions and links
- Use `kodo-red` for errors and destructive actions
- Use `kodo-lime` for success states
- Use `kodo-gold` for warnings
- Use opacity variants for subtle backgrounds (`bg-kodo-cyan/10`)
- Use `kodo-steel` for borders and dividers
- Use `kodo-content-dim` for secondary/muted text

#### ❌ DON'T:
- Use Tailwind default colors (`text-cyan-500`, `bg-blue-500`, etc.) - use Kodo colors instead
- Use `kodo-cyan` for large background areas (use with opacity)
- Use `kodo-red` for non-error states
- Mix Kodo and Veza Fusion colors in the same component
- Use arbitrary color values (`text-[#ff0000]`) - use design system colors

---

## Tailwind Usage

### Available Utilities

All Kodo colors are available as Tailwind utilities:

**Backgrounds**:
- `bg-kodo-void`, `bg-kodo-ink`, `bg-kodo-graphite`, `bg-kodo-slate`, `bg-kodo-steel`
- `bg-kodo-cyan`, `bg-kodo-cyan-dim`, `bg-kodo-magenta`, `bg-kodo-orange`
- `bg-kodo-lime`, `bg-kodo-gold`, `bg-kodo-red`

**Text**:
- `text-kodo-text-main`, `text-kodo-content-highlight`, `text-kodo-content-dim`
- `text-kodo-cyan`, `text-kodo-cyan-dim`, `text-kodo-magenta`, `text-kodo-orange`
- `text-kodo-lime`, `text-kodo-gold`, `text-kodo-red`

**Borders**:
- `border-kodo-void`, `border-kodo-ink`, `border-kodo-graphite`, `border-kodo-slate`, `border-kodo-steel`
- `border-kodo-cyan`, `border-kodo-cyan-dim`, `border-kodo-magenta`
- `border-kodo-lime`, `border-kodo-gold`, `border-kodo-red`

**With Opacity**:
- `bg-kodo-cyan/10`, `bg-kodo-cyan/20`, `bg-kodo-cyan/30`
- `border-kodo-cyan/40`, `text-kodo-cyan/50`

---

## Examples

### Primary Button
```tsx
<button className="bg-kodo-cyan text-kodo-void hover:bg-kodo-cyan-dim">
  Primary Action
</button>
```

### Card with Border
```tsx
<div className="bg-kodo-graphite border border-kodo-steel rounded-lg p-4">
  Card Content
</div>
```

### Success Message
```tsx
<div className="bg-kodo-lime/10 text-kodo-lime border border-kodo-lime/30 rounded p-3">
  Success message
</div>
```

### Error Alert
```tsx
<div className="bg-kodo-red/10 text-kodo-red border border-kodo-red/30 rounded p-3">
  Error message
</div>
```

### Muted Text
```tsx
<p className="text-kodo-content-dim text-sm">
  Secondary information
</p>
```

### Focus State
```tsx
<input className="border-kodo-steel focus:border-kodo-cyan focus:ring-kodo-cyan" />
```

---

## Migration Notes

### Replacing Tailwind Default Colors

When migrating from Tailwind default colors to Kodo colors:

- `text-cyan-500` → `text-kodo-cyan`
- `bg-blue-500` → `bg-kodo-cyan`
- `text-gray-400` → `text-kodo-content-dim`
- `bg-gray-800` → `bg-kodo-graphite` or `bg-kodo-ink`
- `border-gray-700` → `border-kodo-steel`
- `text-red-500` → `text-kodo-red`
- `bg-green-500` → `bg-kodo-lime`

---

## Light Mode

Light mode colors are defined in `apps/web/src/index.css` and automatically adjust:

- Backgrounds become lighter
- Text becomes darker
- Accent colors adjust for better contrast
- All Kodo color utilities work in both dark and light modes

---

## Theme Variants

The Kodo system supports theme variants via `data-color-theme`:

- `cyber` (default): Cyan/Magenta
- `ocean`: Blue/Teal
- `forest`: Green/Lime
- `sunset`: Orange/Purple

Theme variants adjust accent colors while maintaining the same structure.

---

## References

- **Color Definitions**: `apps/web/src/index.css` (lines 36-90)
- **Design System**: `apps/web/src/styles/design-system.css`
- **Tailwind Config**: `apps/web/tailwind.config.ts`

---

## Questions?

If you're unsure which color to use:
1. Check this guide first
2. Look at similar components in the codebase
3. Follow the 80/20 rule (80% neutral, 20% color)
4. When in doubt, use `kodo-cyan` for primary actions, `kodo-steel` for borders, `kodo-content-dim` for muted text
