137 lines
6.8 KiB
Markdown
137 lines
6.8 KiB
Markdown
# 40. Shared Mobile Assets — Icons, Colors, Typography, and Brand Guidelines
|
|
|
|
meta:
|
|
id: kordant-unified-restructure-40
|
|
feature: kordant-unified-restructure
|
|
priority: P1
|
|
depends_on: [kordant-unified-restructure-28, kordant-unified-restructure-34]
|
|
tags: [design, assets, branding, mobile, web]
|
|
|
|
objective:
|
|
- Create a centralized design token system and asset library that all three platforms (web, iOS, Android) reference. Document brand guidelines and generate platform-specific asset exports from a single source of truth.
|
|
|
|
deliverables:
|
|
- `design-tokens/` directory at project root:
|
|
- `colors.json` — All color tokens in JSON format:
|
|
- Brand: primary, primaryLight, primaryDark, accent, accentLight, accentDark
|
|
- Semantic: success, warning, error, info
|
|
- Backgrounds: bg, bgSecondary, bgTertiary (with light and dark variants)
|
|
- Text: textPrimary, textSecondary, textTertiary
|
|
- Borders: border, borderDark
|
|
- All values as hex codes
|
|
- `typography.json` — Typography scale:
|
|
- Font family: Inter
|
|
- Sizes: caption, body, headline, title, largeTitle with pixel sizes and line heights
|
|
- Weights: regular, medium, semibold, bold
|
|
- `spacing.json` — Spacing scale:
|
|
- xs (4), sm (8), md (16), lg (24), xl (32), xxl (48), xxxl (64)
|
|
- `shadows.json` — Shadow definitions:
|
|
- sm, md, lg, xl with x, y, blur, spread, color
|
|
- `radius.json` — Border radius scale:
|
|
- none, sm, md, lg, xl, full
|
|
- `assets/` directory at project root:
|
|
- `logo/` — Kordant logo in multiple formats:
|
|
- SVG (source of truth)
|
|
- PNG exports at 1x, 2x, 3x, 4x
|
|
- PDF (for iOS vector assets)
|
|
- XML vector drawable (for Android)
|
|
- `icons/` — Icon set in SVG format:
|
|
- All icons used in the app (shield, microphone, phone, home, user, lock, bell, etc.)
|
|
- Organized by category (navigation, services, actions, status)
|
|
- Named consistently across platforms
|
|
- `illustrations/` — Marketing illustrations:
|
|
- Hero illustration, empty state illustrations, onboarding illustrations
|
|
- SVG source + PNG exports
|
|
- `docs/BRAND_GUIDELINES.md` — Brand documentation:
|
|
- Color palette with usage rules
|
|
- Typography guidelines
|
|
- Spacing and layout rules
|
|
- Icon usage guidelines
|
|
- Voice and tone guidelines
|
|
- Do's and don'ts with visual examples
|
|
- Generation scripts:
|
|
- `scripts/generate-assets.sh` — Converts SVGs to platform-specific formats
|
|
- `scripts/generate-tokens.sh` — Generates platform code from JSON tokens:
|
|
- `web/src/theme/tokens.ts` from `colors.json`
|
|
- `iOS/Kordant/Theme/GeneratedTokens.swift` from JSON
|
|
- `android/app/src/main/res/values/generated_tokens.xml` from JSON
|
|
|
|
steps:
|
|
1. Create `design-tokens/` directory with JSON files.
|
|
2. Define all tokens in JSON with comments/documentation:
|
|
```json
|
|
{
|
|
"colors": {
|
|
"brand": {
|
|
"primary": { "light": "#4F46E5", "dark": "#818CF8" },
|
|
"primaryDark": { "light": "#4338CA", "dark": "#A5B4FC" },
|
|
...
|
|
}
|
|
}
|
|
}
|
|
```
|
|
3. Create `assets/logo/`:
|
|
- Design or export Kordant logo as SVG
|
|
- Generate PNGs at 64px, 128px, 256px, 512px, 1024px
|
|
- Generate iOS app icon set (all required sizes)
|
|
- Generate Android mipmap densities (mdpi to xxxhdpi)
|
|
- Generate favicon sizes for web
|
|
4. Create `assets/icons/`:
|
|
- Source all icons as 24x24px SVGs with consistent stroke width (1.5px or 2px)
|
|
- Name them consistently: `icon-shield.svg`, `icon-microphone.svg`, etc.
|
|
- Generate PNG exports at 1x, 2x, 3x
|
|
5. Create `assets/illustrations/`:
|
|
- Empty state illustrations (no data, no alerts, etc.)
|
|
- Onboarding illustrations
|
|
- Export as SVG + PNG (2x)
|
|
6. Write `docs/BRAND_GUIDELINES.md`:
|
|
- Introduction to Kordant brand identity
|
|
- Color section: primary palette, semantic colors, accessibility requirements (WCAG AA)
|
|
- Typography section: Inter font, scale, usage rules
|
|
- Spacing section: 8px base grid, scale usage
|
|
- Icon section: style (outlined, 1.5px stroke), sizing rules
|
|
- Voice and tone: security-focused, empowering, clear, trustworthy
|
|
- Examples of correct and incorrect usage
|
|
7. Create generation scripts:
|
|
- `scripts/generate-assets.sh`: use `inkscape` or `rsvg-convert` for SVG→PNG, `svg2android` for vector drawables
|
|
- `scripts/generate-tokens.sh`: use a Node.js script or Python script to read JSON and output platform-specific code
|
|
- Web: generate `tokens.ts` with exported const objects
|
|
- iOS: generate `GeneratedTokens.swift` with `struct Tokens { struct Colors { static let brandPrimary = Color(...) } }`
|
|
- Android: generate `generated_tokens.xml` with color resources and dimen resources
|
|
8. Run generation scripts and verify outputs in each platform directory.
|
|
9. Update all platform code to import from generated tokens instead of hardcoded values.
|
|
10. Add CI check that fails if tokens are modified without regenerating platform code.
|
|
|
|
steps:
|
|
- Visual: All generated assets render correctly on each platform
|
|
- Visual: Generated tokens match hand-coded values exactly
|
|
- Documentation: Brand guidelines are comprehensive and include examples
|
|
- Integration: CI script detects token drift
|
|
|
|
acceptance_criteria:
|
|
- [ ] `design-tokens/` contains complete JSON definitions for colors, typography, spacing, shadows, radius
|
|
- [ ] `assets/` contains logo, icons, and illustrations in all required formats
|
|
- [ ] Brand guidelines document is complete with do's and don'ts
|
|
- [ ] Generation scripts successfully produce platform-specific code from JSON tokens
|
|
- [ ] Web app imports colors from generated `tokens.ts`
|
|
- [ ] iOS app imports colors from generated `GeneratedTokens.swift`
|
|
- [ ] Android app imports colors from generated `generated_tokens.xml`
|
|
- [ ] All platforms use the exact same hex values for corresponding tokens
|
|
- [ ] CI detects when tokens are modified without running generation scripts
|
|
|
|
validation:
|
|
- Run `scripts/generate-tokens.sh` and verify output files are created
|
|
- Compare a color value across all three platforms and confirm they match
|
|
- Open generated assets in each platform and verify they render correctly
|
|
- Review brand guidelines document for completeness
|
|
- Test CI script by modifying a token without regenerating
|
|
|
|
notes:
|
|
- The design tokens are the contract between design and engineering. Keep them authoritative and well-documented.
|
|
- Consider using a design token management tool like Style Dictionary, Token Studio, or Tokens Studio for Figma for more advanced workflows.
|
|
- The generation scripts should be run automatically in CI when `design-tokens/` changes.
|
|
- For the logo, ensure it works at small sizes (favicon, app icon) and large sizes (hero, splash).
|
|
- Icons should be designed on a 24x24px grid with 1.5px or 2px stroke for consistency with Material Design and SF Symbols.
|
|
- Illustrations should be simple, on-brand, and optimized for web/mobile performance.
|
|
- The brand voice should be: "We protect you. We're smart about it. We explain things clearly."
|