clear old assets, new ci/cd flow
This commit is contained in:
204
docs/BRAND_GUIDELINES.md
Normal file
204
docs/BRAND_GUIDELINES.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user