Skip to content

ADR-0004: Documentation Portal Aesthetics and Design System Overhaul

Status

Accepted (Amended by ADR-0006)

Context

ADR-0002 established continuous static publishing for Swayrm using Material for MkDocs hosted on GitLab Pages. However, the initial default appearance was purely utilitarian and lacked distinctive visual identity.

As an open civic technology initiative focused on grassroots collective agency, Swayrm's public documentation portal serves as its primary front door to civic organizers, activists, developers, and researchers. The portal must inspire confidence, communicate technological sophistication, and provide intuitive, enjoyable navigation while upholding high information density and accessibility.

Decision

  1. Custom Design System (docs/stylesheets/extra.css):
  2. Establish brand design tokens, including vibrant Indigo primary and Cyan accent colors.
  3. Provide seamless light and dark mode styling with custom surface tokens.
  4. Implement glassmorphism header styling with background blur.
  5. Add interactive micro-interactions: smooth card hover elevations, animated status badge pulse dots, and responsive button treatments.
  6. High-Signal Hero & Landing Presentation (docs/index.md):
  7. Transform the landing page with a hero banner featuring gradient branding typography, clear mission framing, and prominent action buttons.
  8. Add a visual highlights bar highlighting core tenets (Grassroots Sovereignty, One Human Equal Voice, Fluid Swarm Topologies, Deliberation into Action).
  9. Introduce a structured comparative grid contrasting Big Tech, Traditional NGOs/Parties, Web3/DAOs, and Swayrm.
  10. Theme Capabilities Expansion (mkdocs.yml):
  11. Adopt modern typography: Inter for prose and JetBrains Mono for code blocks.
  12. Enable advanced navigation features: sticky tabs (navigation.tabs.sticky), breadcrumbs (navigation.path), instant prefetching, back-to-top button, and search sharing.
  13. Configure rich Markdown extensions: attr_list, md_in_html, and pymdownx.emoji (Twemoji SVG).
  14. Responsive Card Grids:
  15. Replace raw HTML tables and unstyled lists in docs/vision/VISION.md and docs/decisions/README.md with responsive Material card grids (<div class="grid cards" markdown>).

Consequences

Positive

  • Inspiring First Impression: The portal communicates clarity, purpose, and modern quality, encouraging grassroots adoption and contributor onboarding.
  • Enhanced Usability: Sticky navigation, search features, breadcrumbs, and card layouts make exploring the living specification effortless.
  • Cohesive Visual Identity: Consistent styling across all documentation sections, tables, callouts, and ADR indices.
  • Zero Bloat: Retains static compilation without adding JavaScript application frameworks or external runtime dependencies.

Negative / Trade-offs

  • Custom CSS rules in docs/stylesheets/extra.css must be periodically audited against upstream Material for MkDocs updates.