# Kordant Brand Guidelines

> We protect you. We're smart about it. We explain things clearly.

This document defines the Kordant visual identity. All platform code (web, iOS, Android) references the single source of truth in `design-tokens/`.

---

## Color Palette

### Brand Colors

| Token | Hex | Usage |
|---|---|---|
| `primary` | `#4F46E5` | Primary actions, links, active states, logo |
| `primaryLight` | `#818CF8` | Gradients, hover states, secondary emphasis |
| `primaryDark` | `#4338CA` | Pressed states, depth, navigation active |
| `accent` | `#06B6D4` | Secondary CTAs, success states, data viz |
| `accentLight` | `#67E8F9` | Accent highlights, subtle backgrounds |
| `accentDark` | `#0891B2` | Accent hover/pressed states |

### Semantic Colors

| Token | Hex | Usage |
|---|---|---|
| `success` | `#06B6D4` | Completed actions, secure status, on-brand green |
| `warning` | `#F59E0B` | Pending actions, caution states, review needed |
| `error` | `#EF4444` | Failed actions, threats detected, destructive |
| `info` | `#4F46E5` | Neutral information, tooltips, help text |

### Accessibility

All color combinations must meet **WCAG AA** contrast requirements:
- Normal text: 4.5:1 minimum
- Large text (18px+ bold): 3:1 minimum

Use `primary` on white or `primaryLight` on dark backgrounds for links and interactive elements.

---

## Typography

### Font Family

**Inter** — primary typeface across all platforms.

```
Inter, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif
```

### Type Scale

| Name | Size | Line Height | Weight | Usage |
|---|---|---|---|---|
| `caption` | 12px | 16px | 400 | Metadata, labels, fine print |
| `body` | 16px | 24px | 400 | Default body text |
| `bodyLarge` | 18px | 28px | 400 | Emphasized body, quotes |
| `headline` | 20px | 28px | 600 | Card titles, section headers |
| `title` | 24px | 32px | 600 | Page titles |
| `largeTitle` | 32px | 40px | 700 | Hero headlines |
| `display` | 48px | 56px | 700 | Landing page hero |

### Do's and Don'ts

- ✅ Use `semibold` (600) for headings
- ✅ Use `regular` (400) for body text
- ✅ Keep line lengths between 45-75 characters
- ❌ Don't use more than 2 font sizes per screen
- ❌ Don't use all-caps for body text
- ❌ Don't use italic weight — use secondary text color instead

---

## Spacing

Based on a **4px grid**. All spacing values are multiples of 4.

| Token | Value | Usage |
|---|---|---|
| `xs` | 4px | Within components (icon to text) |
| `sm` | 8px | Tight gaps, list items |
| `md` | 16px | Card padding, form fields |
| `lg` | 24px | Between cards, section padding |
| `xl` | 32px | Between sections |
| `xxl` | 48px | Page-level spacing |
| `xxxl` | 64px | Hero sections, full gaps |

### Do's and Don'ts

- ✅ Always use spacing tokens, never arbitrary values
- ✅ Use `md` as default card padding
- ✅ Use `lg` between related content groups
- ❌ Don't mix spacing tokens (e.g., `12px` is not in the scale)
- ❌ Don't use `xxxl` inside cards

---

## Iconography

### Style

- **Outlined** icons with 1.5px or 2px stroke
- 24×24px grid
- Rounded stroke caps and joins
- Consistent corner radius (2px)

### Naming Convention

```
icon-[category]-[name].svg
```

Examples: `icon-nav-home.svg`, `icon-service-shield.svg`, `icon-action-bell.svg`

### Categories

| Category | Prefix | Examples |
|---|---|---|
| Navigation | `nav-` | home, dashboard, settings |
| Services | `service-` | shield, microphone, phone, home, lock |
| Actions | `action-` | bell, search, share, download |
| Status | `status-` | check, alert, warning, error |

### Do's and Don'ts

- ✅ Use consistent stroke width (1.5px or 2px)
- ✅ Design on 24×24px grid with 2px safe zone
- ✅ Export as SVG for web, PNG at 1x/2x/3x for mobile
- ❌ Don't mix filled and outlined styles
- ❌ Don't use colored icons unless semantic (success/error)
- ❌ Don't use icons larger than 48px without design review

---

## Shadows and Elevation

| Token | CSS | Usage |
|---|---|---|
| `sm` | `0 1px 2px 0 rgba(0,0,0,0.05)` | Inputs, chips, inline elements |
| `md` | `0 4px 6px -1px rgba(0,0,0,0.1)` | Cards, default elevation |
| `lg` | `0 10px 15px -3px rgba(0,0,0,0.1)` | Dropdowns, menus |
| `xl` | `0 20px 25px -5px rgba(0,0,0,0.15)` | Modals, dialogs |

---

## Border Radius

| Token | Value | Usage |
|---|---|---|
| `sm` | 4px | Inputs, chips, badges |
| `md` | 8px | Cards, buttons, modals |
| `lg` | 12px | Large cards, panels |
| `xl` | 16px | Hero cards, featured sections |
| `full` | 9999px | Pills, avatars, badges |

---

## Voice and Tone

### Principles

1. **Security-focused** — We make users feel safe, not scared
2. **Empowering** — Clear actions, not jargon
3. **Clear** — Simple language, no ambiguity
4. **Trustworthy** — Accurate information, honest about limitations

### Examples

| Situation | ✅ Do | ❌ Don't |
|---|---|---|
| Threat detected | "We found your email in a breach. Here's what to do." | "CRITICAL: YOUR DATA IS COMPROMISED!" |
| All clear | "Everything looks good. No threats found." | "No issues detected." |
| Subscription | "Protect your family for $9.99/month" | "Purchase enterprise-grade monitoring" |
| Onboarding | "Let's set up your protection in 2 minutes" | "Configure your security parameters" |

---

## Platform-Specific Notes

### Web (SolidStart + Tailwind)
- Colors are CSS custom properties in `app.css`
- Generated tokens at `web/src/theme/tokens.ts`
- Use Tailwind utility classes: `bg-bg`, `text-text-primary`, `rounded-md`

### iOS (SwiftUI)
- Colors in `iOS/Kordant/Theme/Color+Kordant.swift`
- Generated tokens at `iOS/Kordant/Theme/GeneratedTokens.swift`
- Use `Color.brandPrimary`, `Color.textPrimary`

### Android (Jetpack Compose)
- Colors in `android/.../res/values/colors.xml`
- Generated tokens at `android/.../res/values/generated_tokens.xml`
- Use `MaterialTheme.colors.brandPrimary`

---

## Token Workflow

1. **Design** updates `design-tokens/*.json`
2. **Run** `node scripts/generate-tokens.mjs`
3. **Commit** both JSON and generated files together
4. **CI** verifies token drift on every PR

Never edit generated files manually. Always update the JSON source.