{"slug":"strategy/market-positioning/BRANDING_GUIDE","title":"Branding Guide — Theme System & Logo Integration","section":"strategy","sectionLabel":"Strategy","status":"unclassified","type":"document","path":"strategy/market-positioning/BRANDING_GUIDE.mdx","bytes":8705,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n\n> **Tier C — Historical.** This document is a point-in-time snapshot preserved for reference. For current architecture, see [CANONICAL_PLATFORM_ARCHITECTURE.md](../architecture/CANONICAL_PLATFORM_ARCHITECTURE.md).\n\n## Overview\n\nYour workbench now includes a comprehensive branding system with 4 distinct brand themes:\n\n1. **Brand Blue** — Primary corporate brand (#4154A3)\n2. **Forest** — Nature-inspired green (#1E4D2B)\n3. **Paper** — Warm neutral brown (#5C4033)\n4. **Mono White** — Minimalist white variant\n\nEach theme includes:\n- Branded logo variants\n- Complete color palettes (light & dark modes)\n- Theme-specific typography and UI styling\n- Persistent user preferences\n\n---\n\n## Theme Architecture\n\n### Color System\n\nEach theme defines 7 core colors:\n\n```typescript\ninterface ThemeColors {\n  background: string;   // Page background\n  foreground: string;   // Text color\n  primary: string;      // Primary brand color\n  secondary?: string;   // Secondary accent\n  muted: string;        // Disabled/secondary text\n  border: string;       // Component borders\n  accent: string;       // Interactive elements\n}\n```\n\n### Brand Configurations\n\n**File:** `packages/domain-shells/utils/branding.ts`\n\nEach theme includes:\n- Logo path (color variant)\n- Logo white (for dark backgrounds)\n- Primary & secondary colors\n- Light mode colors\n- Dark mode colors\n\n---\n\n## Usage\n\n### 1. Apply Theme Globally\n\n```typescript\n\n// Get stored user preference or default\nconst { theme, mode } = getStoredTheme();\n\n// Apply theme to document\napplyTheme('brand-blue', 'light'); // or 'dark'\n```\n\n### 2. Use Theme in Components\n\n```typescript\n\n  const config = getBrandConfig('forest');\n  const colors = getThemeColors('forest', 'light');\n\n  return (\n    <header style={{ backgroundColor: colors.primary }}>\n      <img src={config.logo} alt=\"Logo\" />\n    </header>\n  );\n}\n```\n\n### 3. Theme Switcher Component\n\n```typescript\n\n  return (\n    <div>\n      <ThemeSwitcher />\n    </div>\n  );\n}\n```\n\n---\n\n## Theme Details\n\n### Brand Blue (#4154A3)\n\n**Perfect for:** Corporate, professional, tech companies\n\n- **Logo:** `/logos/brand-blue.svg`\n- **Primary:** #4154A3 (deep blue)\n- **Secondary:** #6B7ACC (lighter blue)\n- **Light Background:** #ffffff\n- **Dark Background:** #111111\n\n### Forest (#1E4D2B)\n\n**Perfect for:** Sustainability, health, environment\n\n- **Logo:** `/logos/forest.svg`\n- **Primary:** #1E4D2B (forest green)\n- **Secondary:** #7BAE7F (sage green)\n- **Light Background:** #ffffff\n- **Dark Background:** #111111\n\n### Paper (#5C4033)\n\n**Perfect for:** Publishing, design, craftsmanship\n\n- **Logo:** `/logos/paper.svg`\n- **Primary:** #5C4033 (warm brown)\n- **Secondary:** #C4956A (tan)\n- **Light Background:** #ffffff\n- **Dark Background:** #111111\n\n### Mono White\n\n**Perfect for:** Minimalist, minimal branding, universal\n\n- **Logo:** `/logos/mono-white.svg`\n- **Primary:** #000000 (black on light) / #ffffff (white on dark)\n- **Light Background:** #ffffff\n- **Dark Background:** #111111\n\n---\n\n## Logo Files\n\nAll logos stored in `/public/logos/`:\n\n```\npublic/logos/\n├── brand-blue.svg    — Brand Blue variant\n├── forest.svg        — Forest green variant\n├── paper.svg         — Paper brown variant\n└── mono-white.svg    — Mono white variant (works on all backgrounds)\n```\n\n**Format:** SVG (scalable, crisp at any size)\n\n**Sizes Used:**\n- Header: 48x48px\n- Sidebar: 12x12px\n- Favicon: 32x32px\n\n---\n\n## Implementing Theme Switcher\n\nAdd to settings panel:\n\n```typescript\n\n  return (\n    <div className=\"space-y-8 p-8\">\n      <section>\n        <h2>Appearance</h2>\n        <ThemeSwitcher />\n      </section>\n    </div>\n  );\n}\n```\n\nThe theme switcher:\n- Shows all 4 theme options\n- Displays logo preview for each\n- Shows active selection with checkmark\n- Persists choice to localStorage\n- Triggers DOM re-renders on change\n\n---\n\n## CSS Variables\n\nThemes automatically generate CSS variables:\n\n```css\n--background: #ffffff;\n--foreground: #000000;\n--primary: #4154A3;\n--secondary: #6B7ACC;\n--muted: #808080;\n--border: #e5e5e5;\n--accent: #4154A3;\n```\n\nUse in Tailwind:\n\n```tsx\n<div className=\"bg-background text-foreground border border-border\">\n  <button className=\"bg-primary text-white hover:bg-accent\">\n    Click me\n  </button>\n</div>\n```\n\n---\n\n## Dark Mode Support\n\nEach theme includes optimized dark mode colors:\n\n```typescript\n// Light mode (default)\napplyTheme('brand-blue', 'light');\n\n// Dark mode\napplyTheme('brand-blue', 'dark');\n```\n\nDark mode adapts:\n- Lighter primary color for contrast\n- Appropriate border colors\n- Readable text contrast\n- Accent colors that work on dark backgrounds\n\n---\n\n## Customization\n\n### Add a New Theme\n\n```typescript\n// In packages/domain-shells/utils/branding.ts\n\n  'my-brand': {\n    name: 'My Brand',\n    logo: '/logos/my-brand.svg',\n    logoWhite: '/logos/my-brand-white.svg',\n    primaryColor: '#YOUR_COLOR',\n    theme: {\n      light: {\n        background: '#ffffff',\n        foreground: '#000000',\n        primary: '#YOUR_COLOR',\n        secondary: '#YOUR_SECONDARY',\n        muted: '#808080',\n        border: '#e5e5e5',\n        accent: '#YOUR_COLOR',\n      },\n      dark: {\n        background: '#111111',\n        foreground: '#ffffff',\n        primary: '#YOUR_LIGHT_COLOR',\n        secondary: '#YOUR_LIGHT_SECONDARY',\n        muted: '#666666',\n        border: '#333333',\n        accent: '#YOUR_LIGHT_ACCENT',\n      },\n    },\n  },\n};\n```\n\nThen add to type:\n\n```typescript\nexport type BrandTheme = 'brand-blue' | 'forest' | 'paper' | 'mono-white' | 'my-brand';\n```\n\n---\n\n## API Reference\n\n### `getBrandConfig(theme: BrandTheme): BrandConfig`\n\nGet complete configuration for a theme.\n\n```typescript\nconst config = getBrandConfig('forest');\nconsole.log(config.primaryColor); // #1E4D2B\n```\n\n### `getThemeColors(theme: BrandTheme, mode: ThemeMode): ThemeColors`\n\nGet color palette for a theme and mode.\n\n```typescript\nconst colors = getThemeColors('forest', 'dark');\nconsole.log(colors.background); // #111111\n```\n\n### `applyTheme(theme: BrandTheme, mode: ThemeMode)`\n\nApply theme to document and persist preference.\n\n```typescript\napplyTheme('forest', 'light');\n// Sets CSS variables on :root\n// Saves to localStorage\n```\n\n### `getStoredTheme(): { theme: BrandTheme; mode: ThemeMode }`\n\nGet user's stored preference or defaults.\n\n```typescript\nconst { theme, mode } = getStoredTheme();\n```\n\n### `generateCSSVariables(theme: BrandTheme, mode: ThemeMode): string`\n\nGenerate CSS variable declaration string.\n\n```typescript\nconst cssVars = generateCSSVariables('forest', 'light');\n// Returns: \"--background: #ffffff; --foreground: #000000; ...\"\n```\n\n---\n\n## Events\n\nListen for theme changes:\n\n```typescript\nwindow.addEventListener('theme-changed', (event: CustomEvent) => {\n  console.log('Theme changed to:', event.detail.theme);\n  // Re-render components that depend on theme\n});\n```\n\n---\n\n## Best Practices\n\n1. **Logo Usage**\n   - Use branded logo in header for identity\n   - Use mono-white for light backgrounds\n   - Use appropriate variant in dark mode\n\n2. **Color Selection**\n   - Ensure sufficient contrast (WCAG AA+)\n   - Test colors in both light and dark modes\n   - Use secondary colors for accents only\n\n3. **Theme Persistence**\n   - Always call `applyTheme()` on app load\n   - Get user preference from `getStoredTheme()`\n   - Listen to `theme-changed` events for updates\n\n4. **Consistency**\n   - Use CSS variables instead of hardcoded colors\n   - Define theme-specific components once\n   - Test across all 4 themes\n\n---\n\n## Files Reference\n\n**Core:**\n- `packages/domain-shells/utils/branding.ts` — Brand configuration\n- `packages/domain-shells/components/theme-switcher.tsx` — Theme UI\n\n**Assets:**\n- `public/logos/brand-blue.svg`\n- `public/logos/forest.svg`\n- `public/logos/paper.svg`\n- `public/logos/mono-white.svg`\n\n**Integration:**\n- `packages/domain-shells/account-success-shell-redesigned.tsx` — Uses branding\n\n---\n\n## Summary\n\nYour workbench now features:\n\n✅ 4 professional brand themes\n✅ Complete light & dark mode support\n✅ Branded logo integration\n✅ Theme-aware CSS variables\n✅ Persistent user preferences\n✅ Theme switcher component\n✅ Full API for theme management\n\nDeploy and customize to match your brand identity.\n"}