Skip to content

ADR-0006: Streamlined Decision Indexing and List Navigation

Status

Accepted (Amends ADR-0004)

Context

ADR-0004 established the documentation portal aesthetic, introducing Material card grids (<div class="grid cards">) to display Architecture Decision Records (ADRs) as visual tiles on the ADR index page (docs/decisions/README.md) and living specification navigation cards on the homepage (docs/index.md).

While tiles provided an initial visual lift, they proved sub-optimal for documentation utility: 1. Excessive Vertical Space: Displaying ADRs as individual card tiles severely restricted information density, forcing excessive scrolling even with a modest number of records. 2. Poor Scanability: Technical and civic collaborators require rapid linear scanning of decisions by ID, title, and status. Card grids fragment the natural reading rhythm. 3. Homepage Redundancy: Navigation tiles on the landing page largely duplicated existing top and drawer navigation links rather than exposing high-signal architectural content directly.

Decision

  1. Replace ADR Tiles with Compact List (docs/decisions/README.md):
  2. Remove the <div class="grid cards"> tile structure from the ADR index.
  3. Render ADRs as a clean, compact bullet list featuring sequential ADR ID, full title link, and inline status badges (:material-check-circle:{ style="color: #10b981;" } \Accepted``).
  4. Surface ADRs on Portal Homepage (docs/index.md):
  5. Remove the navigation card tiles under "Navigating the Living Specification" in favor of clean section links.
  6. Add a dedicated "Architecture Decision Records (ADRs)" section directly on the homepage featuring the compact list of accepted decisions, offering visitors immediate insight into foundational choices.
  7. Supersede Card Tile Grid for Decision Records:
  8. Amend ADR-0004 (Section 4) to specify that ADR indices must utilize compact lists rather than card tiles. Card grids remain reserved for high-level conceptual comparisons where multi-attribute encapsulation is beneficial.

Consequences

Positive

  • High Information Density & Usability: Users can rapidly scan all decisions in one compact view without scrolling across large cards.
  • Long-Term Scalability: Linear lists comfortably scale to dozens or hundreds of decision records without layout degradation.
  • Immediate Front-Door Visibility: Key technical and governance decisions are visible directly from the homepage.
  • Device Independence: Flawless rendering on mobile and desktop without awkward card column breaks.

Negative / Trade-offs

  • Less graphical card decoration on the ADR index page, deliberately prioritizing engineering clarity and scanability over marketing flair.