205 lines
6.0 KiB
Markdown
205 lines
6.0 KiB
Markdown
# 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.
|