Epic: Brand Identity Foundation — Logo System, Color Palette, Design Tokens

[ericsocrat]

Summary

Establish the foundational visual identity for the project: logomark, wordmark, full lockup system, favicon set, brand color palette, typography scale, and exportable design tokens. This is the first thing that must ship — every other branding task depends on the identity system defined here.

Problem Statement

The project currently has no visual identity. There is no logo, no favicon, no consistent color system beyond Tailwind defaults, no defined typography scale, and no design tokens. This makes the project look like a prototype rather than a production health-tech product, undermines trust with users who rely on it for food safety decisions, and prevents consistent visual language across the frontend, documentation, and GitHub presence.

Key Constraint: Name Will Change

The project name will change in the future. The logo system MUST be architected as two independent, composable pieces:

1. Logomark / Icon — permanent, name-independent. This is the primary deliverable.
2. Wordmark — placeholder using the current working name. Designed to be swapped independently without touching the icon.

All lockup variants (horizontal, stacked) must cleanly separate icon from text so regenerating the wordmark later is trivial.

Architectural Decisions

Decision	Choice	Rationale
Logo architecture	Icon + swappable wordmark	Name will change; icon is permanent investment
Color source of truth	CSS custom properties + Tailwind config	Already using Tailwind; tokens feed both CSS and asset creation
Typography	System font stack or Inter/Plus Jakarta Sans	No external font dependency; fast loading; scientific but approachable
Token format	CSS custom properties + JSON export	CSS vars for runtime; JSON for documentation and design tools
Favicon approach	SVG primary with ICO fallback	SVG supports dark mode via prefers-color-scheme media query

Deliverables

Logo System Files

docs/assets/logo/
├── logomark.svg                    # Icon only — full color (PERMANENT)
├── logomark-dark.svg               # Icon — dark mode variant
├── logomark-mono.svg               # Icon — monochrome (single color)
├── logomark-16.png through logomark-512.png  # Icon PNGs at 16, 32, 64, 128, 180, 192, 256, 512
├── wordmark.svg                    # Text only (PLACEHOLDER — will change)
├── lockup-horizontal.svg           # Icon + text side by side
├── lockup-horizontal-dark.svg      # Horizontal — dark mode
├── lockup-stacked.svg              # Icon above text
└── lockup-stacked-dark.svg         # Stacked — dark mode

Favicon Set

frontend/public/
├── favicon.ico                     # Multi-size: 16×16, 32×32, 48×48
├── favicon.svg                     # SVG with prefers-color-scheme dark mode
├── favicon-16x16.png
├── favicon-32x32.png
└── apple-touch-icon.png            # 180×180 with padding for iOS

Design Tokens

• CSS custom properties file defining: brand colors (primary, secondary, accent), scoring band colors (green/yellow/orange/red/dark-red), semantic colors (info/success/warning/error), surface colors (card/elevated/overlay for light+dark), neutral scale (5-step gray), typography scale (display, h1-h4, body, caption, overline, code), spacing scale, border-radius scale, shadow scale, motion/easing curves
• JSON export of the same tokens for documentation and design tool consumption
• Integration with existing tailwind.config.ts — extend (not replace) the Tailwind theme

Brand Guidelines Document

• docs/BRAND_GUIDELINES.md — comprehensive identity documentation covering: brand overview/personality, logo usage rules (clear space, minimum sizes, do's and don'ts), color system (hex/RGB/HSL values, usage rules, accessibility notes), typography scale, iconography style guide, dark mode color mapping, co-branding rules, complete asset inventory

Logo Design Direction

The logomark should subtly combine:

• Trust/safety: Shield, checkmark, or protective shape
• Health/food: Leaf, plant element, plate, or organic curve
• Data/science: Bar chart, score meter, molecular motif, or data visualization element
• European identity: Optional subtle reference to Polish elements (red/white accent, geometric nod)

Must work at all sizes from 16×16 favicon to 512×512 app icon. Must be instantly recognizable, not generic.

Color Palette Specification

Role	Usage	Suggested Range
Primary	Brand color, headers, CTAs	Deep emerald/teal (#0D7377 range)
Secondary	Backgrounds, subtle accents	Clean white/light gray (#F8FAFC range)
Accent	Premium elements, highlights	Warm gold (#D4A844 range)
Score Green	Band 1–20, healthy	#22c55e
Score Yellow	Band 21–40, moderate	#eab308
Score Orange	Band 41–60, elevated	#f97316
Score Red	Band 61–80, high risk	#ef4444
Score Dark Red	Band 81–100, very high	#991b1b
Info	Informational UI	Blue range
Success	Positive confirmations	Green range
Warning	Caution states	Amber range
Error	Error states	Red range

All colors must meet WCAG AA contrast requirements (4.5:1 for text, 3:1 for UI elements). AAA preferred for body text.

Quality Standards

• All SVGs optimized via SVGO — <title> and <desc> for accessibility, viewBox defined, no fixed width/height on root, no inline styles
• All PNGs optimized (TinyPNG/pngquant level), sRGB color space
• Retina-ready: all raster assets crisp on 2x displays
• Icon must be recognizable and legible at 16×16px minimum
• Every variant must be visually consistent (same visual weight, proportions, color values)

Acceptance Criteria

• Logomark SVG works at 16px and 512px without quality loss
• Full color, dark mode, and monochrome variants all exist and are consistent
• Favicon displays correctly in Chrome, Firefox, Safari, Edge
• SVG favicon switches appearance in dark mode via prefers-color-scheme
• Apple touch icon displays correctly on iOS home screen
• Design tokens CSS file loads without errors in the frontend
• Tailwind config extended with brand tokens — existing styles unaffected
• docs/BRAND_GUIDELINES.md covers all 14 sections listed above
• All assets pass SVGO optimization (icons <5KB each)
• Color contrast ratios verified (WCAG AA minimum)
• Wordmark is clearly separable from logomark for future name change

Sub-Issues

Sub-issues will be linked after creation.

Dependencies

• Blocks: Every other issue in this milestone (all assets derive from identity tokens)
• Blocked by: Nothing — this is the foundation

Estimated Effort

High — 2-3 days of focused design + implementation work

---

Part of Milestone: Visual Identity & Branding System