Skip to content
This repository was archived by the owner on Jun 12, 2026. It is now read-only.
This repository was archived by the owner on Jun 12, 2026. It is now read-only.

πŸ–ΌοΈ Artifact Gallery: Visual showcase of 5-6 real generated artifacts in READMEΒ #14

Description

@ramsani

🎯 Feature: Artifact Gallery in README

Context

The README.md is the first touchpoint for any potential user. Currently it describes what html-explainer does in abstract terms but does not show what the output actually looks like. This is a critical gap: visual-first decisions happen within seconds. A user who cannot see a screenshot or a live example will not install the tool.

A gallery section with real screenshots of generated artifacts β€” showing actual decision decks, diff reviews, architecture diagrams, and recaps β€” converts curious visitors into users by demonstrating real value before they invest any time.

Problem

  • README describes capability in words; without visual proof, users must imagine the output
  • New users cannot evaluate whether the output quality meets their bar without running the tool
  • Artifact patterns are listed by name but not illustrated, making it hard to understand which pattern solves which problem
  • The tool has no standalone proof of value β€” it requires installation to see anything

What This Resolves

  • A Visual Artifact Gallery section in README.md showing 5-6 real artifact screenshots
  • Each gallery item includes: pattern name, artifact type, key visual elements, and the URL to the live example
  • Gallery demonstrates the range of artifact types (decision, review, architecture, workflow, recap, research)
  • Makes the tool output tangible before installation β€” the README becomes the demo

Proposed Approach

Gallery Section (add to README.md after "What Good Output Looks Like"):

Each gallery item shows:

  • Pattern number and name
  • One-line description of what the artifact contains
  • Key structural element (e.g., "Comparison matrix + recommendation")
  • Link to the live example HTML file in the repo

Gallery manifest (examples/gallery-manifest.json):

[
  {
    "pattern": "11-technical-decision-deck",
    "example_path": "examples/before-after-decision.example.html",
    "artifact_type": "decision-deck",
    "summary": "Compare 2-4 options with scores, risks, and recommendations",
    "key_elements": ["comparison matrix", "risk level", "recommendation", "next action"]
  }
]

Acceptance Criteria

  • README.md contains a gallery section with at least 6 rows (one per pattern type)
  • Each gallery row links to a real, verifiable HTML example in the examples/ directory
  • Gallery renders correctly on GitHub.com (light + dark mode compatible)
  • examples/gallery-manifest.json exists and lists all gallery items
  • validate-examples.sh checks that all gallery-referenced examples exist and are valid HTML
  • All gallery-referenced examples pass audit-artifact.py at 90+
  • Screenshot generation script examples/generate-screenshots.sh exists (even if not run in CI yet)

Quality Verification

Verify all gallery examples exist, pass audit at 90+, and README contains the gallery section. Run the validation script to confirm.

Labels

enhancement, documentation, visual-content, gallery

Milestone

v1.1 β€” Collaboration-ready artifacts

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions