boc/docs/design/foundations/BRAND_PALETTE.md

# BRAND PALETTE

**Token-Specifikation för Landvex Brand Colors**

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | DRAFT — Awaiting brand color definition |
| **Scope** | Landvex Enterprise Platform |
| **Authority** | DESIGN_SPECIFICATION (nivå 5) |

---

## 1. PRINCIPLES

**MUST NOT:** Use brand colors for status (success/warning/danger/info).
**MUST NOT:** Use brand colors in data visualization or map layers.
**MUST:** Use brand colors for identity only: logo, headers, primary actions, focus states.

Brand = identity. Semantic = meaning. **MUST NOT** mix.

---

## 2. TOKEN ARCHITECTURE

### 2.1 Semantic Brand Tokens

| Token | Purpose | Usage |
|-------|---------|-------|
| `brand-primary` | Primary brand color | Logo, primary buttons, key headers |
| `brand-secondary` | Secondary brand color | Accents, highlights, hover states |
| `brand-tertiary` | Tertiary brand color | Subtle accents, backgrounds |

### 2.2 Scale Tokens (12-step)

| Token | Purpose |
|-------|---------|
| `brand-50` | Lightest tint — backgrounds, hover states |
| `brand-100` | Very light — subtle backgrounds |
| `brand-200` | Light — disabled states |
| `brand-300` | Light-medium — borders |
| `brand-400` | Medium — secondary elements |
| `brand-500` | Base — primary usage |
| `brand-600` | Medium-dark — hover states |
| `brand-700` | Dark — active states |
| `brand-800` | Very dark — text on light backgrounds |
| `brand-900` | Darkest — high contrast text |
| `brand-950` | Deepest — special emphasis |

---

## 3. USAGE RULES

### 3.1 Where Brand Colors Are Used

| Context | Token | Example |
|---------|-------|---------|
| Logo | `brand-500` | Landvex logo mark |
| Primary Button | `brand-500` | Default state |
| Primary Button Hover | `brand-600` | Hover state |
| Primary Button Active | `brand-700` | Active state |
| Focus Ring | `brand-500` | Input, Button, Select focus |
| Link | `brand-500` | Text links |
| Link Hover | `brand-600` | Link hover |
| Header Accent | `brand-500` | Page title accent |
| Loading Spinner | `brand-500` | Brand-colored spinner |
| Progress Bar | `brand-500` | Brand-colored progress |

### 3.2 Where Brand Colors Are NOT Used

| Context | Why | Alternative |
|---------|-----|-------------|
| Success states | Brand ≠ meaning | `semantic-green-500` |
| Warning states | Brand ≠ meaning | `semantic-yellow-500` |
| Danger states | Brand ≠ meaning | `semantic-red-500` |
| Info states | Brand ≠ meaning | `semantic-blue-500` |
| Data visualization | Brand ≠ data | Categorical color palette |
| Map layers | Brand ≠ geography | Map layer palette |
| Error text | Brand ≠ error | `semantic-red-500` |
| Validation | Brand ≠ validation | `semantic-green/red-500` |

---

## 4. DARK MODE STRATEGY

| Token | Light Mode | Dark Mode |
|-------|-----------|-----------|
| `brand-primary` | `brand-500` | `brand-400` |
| `brand-secondary` | `brand-600` | `brand-300` |
| `brand-tertiary` | `brand-100` | `brand-800` |

**Rule:** Brand colors shift lighter in dark mode to maintain contrast.

---

## 5. CONTRAST REQUIREMENTS

| Usage | Minimum Contrast | Notes |
|-------|-----------------|-------|
| Text on brand background | 4.5:1 (WCAG AA) | `brand-500` text on white, or white on `brand-500` |
| Large text on brand | 3:1 (WCAG AA Large) | Headers, 18px+ or 14px+ bold |
| Focus indicators | 3:1 | Focus ring vs surrounding |
| Disabled brand | No requirement | Disabled state exempt |

---

## 6. PLACEHOLDER VALUES

**AWAITING BRAND COLOR DEFINITION FROM ERIK/LANDVEX TEAM**

| Token | Hex (Placeholder) | Status |
|-------|-------------------|--------|
| `brand-50` | — | ⏳ Awaiting |
| `brand-100` | — | ⏳ Awaiting |
| `brand-200` | — | ⏳ Awaiting |
| `brand-300` | — | ⏳ Awaiting |
| `brand-400` | — | ⏳ Awaiting |
| `brand-500` | — | ⏳ Awaiting |
| `brand-600` | — | ⏳ Awaiting |
| `brand-700` | — | ⏳ Awaiting |
| `brand-800` | — | ⏳ Awaiting |
| `brand-900` | — | ⏳ Awaiting |
| `brand-950` | — | ⏳ Awaiting |

---

## 7. TOKEN DEPENDENCIES FROM COMPONENTS

Components that reference brand tokens:

| Component | Token | Usage |
|-----------|-------|-------|
| Button (Primary) | `brand-500` | Background |
| Button (Primary Hover) | `brand-600` | Background |
| Button (Primary Active) | `brand-700` | Background |
| Input (Focus) | `brand-500` | Border |
| Select (Focus) | `brand-500` | Border |
| Select (Selected Option) | `brand-50` | Background |
| Link | `brand-500` | Text color |
| Link (Hover) | `brand-600` | Text color |
| Loading | `brand-500` | Spinner color |
| Progress | `brand-500` | Bar color |

---

## 8. GOVERNANCE

### 8.1 Adding Brand Colors

**MUST NOT** add new brand colors without Architecture Review.

**MUST** follow 12-step scale.

**MUST** update all components that reference brand tokens.

### 8.2 Changing Brand Colors

**MUST** assess impact on all components.

**MUST** update visual regression tests.

**MUST** communicate change to all teams.

---

## ÄNDRINGSHISTORIA

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial brand palette token specification |

---

## STATUS

**DRAFT — Awaiting brand color definition**

- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)