Skip to content

Deliberation Log: Streamlined Documentation Design & ADR List Indexing

  • Date: October 2026
  • Participants: Project Initiator, AI Collaborator

1. Context & Motivation

Following the introduction of the portal design system in ADR-0004 and visual emblem integration in ADR-0005, the documentation site adopted Material card grids (<div class="grid cards">) to display Architecture Decision Records (ADRs) as graphical tiles on the decision index and landing page navigation.

While visually prominent, user feedback and sparring evaluation highlighted several ergonomic shortcomings: 1. Vertical Footprint & Low Information Density: Each card tile occupied significant vertical and horizontal space, requiring extensive scrolling to survey merely five decisions. 2. Poor Scanability: Architecture Decision Records are primarily consulted by contributors, developers, and civic organizers to quickly verify established precedents and rationale. Large tiles force horizontal eye-jumping and break sequential scanning by ADR number. 3. Scalability Ceiling: As the repository grows towards dozens of ADRs, grid tiles become increasingly cumbersome. 4. Landing Page Utility: The homepage featured generic navigation tiles duplicating top/drawer menu paths instead of surfacing high-signal content directly—specifically the evolving list of architectural decisions.

2. Sparring Dialogue & Design Options

Layout Paradigms Explored

  • Option A: Detailed Multi-Column Table
  • Pros: Strict column alignment for number, title, status, and date.
  • Cons: Requires wide viewport width; on mobile screens, wide tables require horizontal scrolling or awkward column wrapping.
  • Option B: Detailed Cards with Excerpts
  • Pros: Provides multi-line summaries directly on the index.
  • Cons: Retains large vertical footprint; does not solve the scanning bottleneck.
  • Option C: Compact Bullet List with Status Badges (Selected)
  • Pros: High information density, instantly scannable by ADR number and title, perfectly responsive across mobile and desktop, zero horizontal overflow risk, and native to standard Markdown.

Scope of Changes

  • ADR Index (docs/decisions/README.md): Replace <div class="grid cards"> with a clean, sequential list of ADRs with inline status badges (:material-check-circle: Accepted).
  • Homepage (docs/index.md): Remove navigation card tiles under "Navigating the Living Specification". Replace them with clean text links to core spec areas, and introduce an upfront compact listing of Architecture Decision Records directly on the front page.

3. Decision & Next Steps

Consensus was reached to implement the compact list layout across both the homepage and the ADR index page. The change is formalized in ADR-0006.