brand-system-guide

What this skill does

# Brand System Guide

## Soft Intelligence Positioning

Litskills embodies **Soft Intelligence** - a design philosophy that balances AI-powered capability with human-centered warmth. Our brand identity uses pastel colors and smooth gradients to create an approachable, trustworthy experience.

**Core Brand Values**:

- **Approachable**: Pastel colors reduce cognitive load and create welcoming interfaces
- **Intelligent**: AI-specific gradients signal sophisticated technology
- **Trustworthy**: Perceptual uniformity ensures consistency and professionalism
- **Accessible**: WCAG 2.1 AA compliant color contrast for all users

## OKLCH Color Space

We use **OKLCH (Oklab Lightness Chroma Hue)** instead of traditional HSL/RGB for:

1. **Perceptual Uniformity**: Colors with same lightness appear equally bright
2. **Smooth Gradient Interpolation**: Natural gradients without "muddy" middle tones
3. **Wider Color Gamut**: Supports P3 and Rec2020 color spaces
4. **Industry Adoption**: Tailwind CSS v4 and modern browsers natively support OKLCH

**Format**: `L C H` (space-separated, no units)

- **L** (Lightness): 0-1 (0 = black, 1 = white)
- **C** (Chroma): 0-0.4 (saturation intensity)
- **H** (Hue): 0-360 (color angle in degrees)

## Color Palette

### Light Mode Colors

#### Background Colors

| Name             | OKLCH          | Hex       | Usage                |
| ---------------- | -------------- | --------- | -------------------- |
| Warm Cream       | `0.97 0.02 85` | `#FDFBF5` | Main page background |
| Elevated Surface | `0.98 0.01 85` | `#FEFDF9` | Cards, popovers      |

#### Primary Colors

| Name              | OKLCH                  | Hex       | Usage                                |
| ----------------- | ---------------------- | --------- | ------------------------------------ |
| Pastel Periwinkle | `0.8528 0.0731 298.05` | `#D4C5F9` | Primary buttons, links, focus states |
| Soft Blue         | `0.77 0.045 240`       | `#A7BED3` | Secondary buttons, informational     |

**Foreground**: Dark gray `#1F2937` (OKLCH `0.24 0.015 255`)

#### Accent Colors

| Name        | OKLCH          | Hex       | Usage                            |
| ----------- | -------------- | --------- | -------------------------------- |
| Soft Coral  | `0.82 0.08 20` | `#FFB4AB` | Highlights, interactive elements |
| Peach Cream | `0.87 0.09 75` | `#FFD4A3` | Warm highlights, badges          |

#### Semantic Colors

| Name          | OKLCH            | Hex       | Usage                       |
| ------------- | ---------------- | --------- | --------------------------- |
| Soft Red-Pink | `0.70 0.10 15`   | `#E88B8B` | Errors, destructive actions |
| Pastel Green  | `0.78 0.055 150` | `#9BCAA9` | Success, confirmations      |

#### Supporting Colors

| Name        | OKLCH          | Hex       | Usage                               |
| ----------- | -------------- | --------- | ----------------------------------- |
| Muted Warm  | `0.92 0.02 85` | `#ECEADB` | Subtle backgrounds, disabled states |
| Warm Border | `0.85 0.02 85` | `#D9D6C7` | Form borders, separators            |

### Dark Mode Colors

Dark mode uses **enhanced saturation and lightness** for visibility.

#### Primary Colors

| Name                | OKLCH                  | Hex       |
| ------------------- | ---------------------- | --------- |
| Brighter Periwinkle | `0.8528 0.0731 298.05` | `#D8C8FA` |
| Brighter Soft Blue  | `0.7656 0.0515 244.82` | `#98B7D2` |

**Foreground**: Very dark text `#131318` (OKLCH `0.15 0.01 285`)

#### Accent Colors

| Name           | OKLCH                 | Hex       |
| -------------- | --------------------- | --------- |
| Brighter Coral | `0.7932 0.1192 27.56` | `#FF9D91` |
| Brighter Peach | `0.8515 0.119 71.42`  | `#FFC173` |

#### Semantic Colors

| Name            | OKLCH                  | Hex       |
| --------------- | ---------------------- | --------- |
| Softer Red-Pink | `0.6729 0.1203 20.74`  | `#D67676` |
| Brighter Green  | `0.7267 0.0939 152.43` | `#78B88A` |

#### Supporting Colors

| Name                | OKLCH            | Hex       | Usage             |
| ------------------- | ---------------- | --------- | ----------------- |
| Very Dark Blue-Gray | `0.15 0.015 255` | `#131318` | Background        |
| Dark Card Surface   | `0.18 0.015 255` | `#1C1C24` | Cards             |
| Dark Gray           | `0.22 0.015 255` | `#272733` | Muted backgrounds |
| Subtle Border       | `0.24 0.015 255` | `#2E2E3D` | Borders           |

## AI Gradient System

The **AI Gradient** is a signature visual element that identifies AI-powered features.

**Gradient Stops**:

1. **Pastel Periwinkle** - `oklch(0.8528 0.0731 298.05)` #D4C5F9 (0%)
2. **Soft Blue** - `oklch(0.791 0.0391 245.87)` #A7BED3 (50%)
3. **Pale Turquoise** - `oklch(0.824 0.0714 207.19)` #8DD3DD (100%)

**Direction**: 135 degrees diagonal (top-left to bottom-right)

### When to Use AI Gradients

**Use For**:

- AI-powered action buttons (e.g., "Generate with AI", "Ask AI Assistant")
- Chat interfaces with AI agents
- AI feature badges and indicators
- Loading states for AI processing
- Premium AI features (Pro/Enterprise tiers)

**Do NOT Use For**:

- Large background areas (>10% viewport)
- Non-AI features (standard CRUD operations, navigation, settings)
- Text or body copy (readability issues)
- Subtle UI elements (borders, dividers, icons)

### Performance Guidelines

**Viewport Coverage Limit**: <10% of visible screen area

- CSS gradients are GPU-intensive on low-end devices
- Use solid `--primary` color if gradient causes performance issues

**Browser Support**:

- Chrome 111+ (March 2023): Full OKLCH support
- Safari 16.4+ (March 2023): Full OKLCH support
- Firefox 113+ (May 2023): Full OKLCH support

## CSS Utility Classes

### `.ai-gradient`

Apply 3-stop AI gradient to backgrounds:

```css
.ai-gradient {
  background: linear-gradient(135deg in oklch, oklch(0.8528 0.0731 298.05) 0%, oklch(0.791 0.0391 245.87) 50%, oklch(0.824 0.0714 207.19) 100%);
}
```

### `.ai-gradient-button`

Complete button styling with AI gradient and hover effects:

```css
.ai-gradient-button {
  background: linear-gradient(135deg in oklch, oklch(0.8528 0.0731 298.05) 0%, oklch(0.791 0.0391 245.87) 50%, oklch(0.824 0.0714 207.19) 100%);
  color: oklch(0.24 0.015 255);
  font-weight: 600;
  transition: opacity 0.2s ease-in-out;
}

.ai-gradient-button:hover {
  opacity: 0.9;
}
```

### `.ai-gradient-border`

Apply gradient to element borders:

```css
.ai-gradient-border {
  border: 2px solid transparent;
  background-origin: border-box;
  background-clip: padding-box, border-box;
  background-image: linear-gradient(white, white), linear-gradient(135deg in oklch, oklch(0.8528 0.0731 298.05), oklch(0.791 0.0391 245.87), oklch(0.824 0.0714 207.19));
}
```

### Dark Mode Variants

```css
.dark .ai-gradient {
  background: linear-gradient(135deg in oklch, oklch(0.82 0.11 296) 0%, oklch(0.74 0.055 240) 50%, oklch(0.83 0.075 210) 100%);
}

.dark .ai-gradient-button {
  color: oklch(0.15 0.01 285);
}
```

## Tailwind CSS Integration

All color tokens are available as Tailwind utilities via CSS custom properties:

```html
<!-- Background Colors -->
<div class="bg-background text-foreground">Page Content</div>
<div class="bg-card text-card-foreground">Card Surface</div>
<div class="bg-muted text-muted-foreground">Muted Section</div>

<!-- Primary Colors (Interactive) -->
<button class="bg-primary text-primary-foreground">Primary Button</button>
<button class="bg-secondary text-secondary-foreground">Secondary Button</button>

<!-- Background Variants (for sections, not buttons) -->
<section class="bg-primary-bg">Pastel Periwinkle Section</section>
<section class="bg-secondary-bg">Soft Blue Section</section>
<section class="bg-accent-bg">Soft Coral Section</section>

<!-- Accent Colors -->
<span class="bg-accent text-accent-foreground">Accent Badge</span>
<span class="bg-accent-warm text-accent-warm-foreground">Warm Badge</span>

<!-- Se