Skip to content

ADR-0005: Visual Identity and Emblem Logo Integration

Status

Accepted

Context

Following ADR-0004 (Documentation Portal Aesthetics and Design System Overhaul), the Swayrm portal required a recognizable visual identity and emblem across header navigation, browser tabs, and landing presentation.

The project initiator contributed the foundational emblem: a circular composition depicting four hands of diverse hues supporting a transparent glass orb containing an intricate, interconnected network graph with a central core node. The motif symbolizes diverse grassroots participants collaborating horizontally without central authority, safeguarding collective intelligence and collective agency.

However, the initial SVG export from GIMP was 2.3 MB because it embedded an uncompressed 1436×1439 raster image using base64. Direct inclusion in this state would severely degrade static page load performance, increase bandwidth usage, and bloat the repository history.

Decision

  1. Asset Optimization & Multi-Resolution Pipeline (docs/assets/images/):
  2. Vector Wrapper (logo.svg): Replace physical inch dimensions (19.94in) and raw base64 data with a clean SVG container (viewBox="0 0 512 512", responsive 100% scaling) embedding a high-DPI palette-quantized raster. File size reduced from 2.3 MB to ~101 KB (>95% reduction).
  3. Web-Optimized PNG (logo.png): Provide a 512×512 8-bit palette-quantized PNG (~76 KB) for contexts requiring direct raster rendering.
  4. Browser Favicon (favicon.png): Generate a crisp 64×64 PNG (~3.9 KB) preserving node and hand clarity for browser tabs.
  5. MkDocs Theme Integration (mkdocs.yml):
  6. Configure theme.logo: assets/images/logo.svg to establish the emblem in the sticky global header and mobile navigation drawer.
  7. Configure theme.favicon: assets/images/favicon.png for browser bookmark and tab identification.
  8. Hero & Interactive Styling (docs/index.md and docs/stylesheets/extra.css):
  9. Feature the emblem prominently in the landing page hero banner with .swayrm-hero-logo.
  10. Apply circular framing, elevation drop-shadows matching the design system's glow tokens, and smooth hover micro-interactions.
  11. Ensure sharp, glare-free rendering across both default (light) and slate (dark) color schemes.

Consequences

Positive

  • Distinctive Brand Identity: The portal immediately communicates human solidarity and decentralized network topologies to visitors and contributors.
  • Extreme Performance & Efficiency: Reduced page weight by over 2.1 MB while preserving full illustrative fidelity on 4K/Retina displays.
  • Full Browser & Device Support: Header emblem, drawer icon, browser favicon, and hero presentation all work out of the box with zero external runtime dependencies.

Negative / Trade-offs

  • Because the emblem is an illustrative artwork with complex gradients and glass reflections rather than pure flat geometry, the SVG utilizes an optimized embedded raster rather than pure vector Bézier paths. If full vector re-drawing is undertaken in the future (e.g. in Inkscape), it can replace this file seamlessly.