# 40. Shared Mobile Assets — Icons, Colors, Typography, and Brand Guidelines

meta:
  id: shieldai-unified-restructure-40
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-28, shieldai-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/` — ShieldAI 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/ShieldAI/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 ShieldAI 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 ShieldAI 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."
