Project Showcase Website

# Project Showcase Website

Generate a polished, self-contained project showcase website with an interactive architecture diagram, following a specific design system and template. The output matches the visual identity, storytelling structure, and component patterns used across Vivek's portfolio (Dancer Claude, WONYP).

This is NOT a general-purpose webpage builder. It is a **template-first** skill with a fixed design system. The creative work is in the content — the analogy, named principle, architecture mapping, and prose — not in the HTML/CSS.

## Arguments

`<project path, repo URL, or description>` — What project to showcase.

Examples:
- `/project-showcase-website ~/projects/my-ai-tool`
- `/project-showcase-website https://github.com/user/repo`
- `/project-showcase-website` — no args, use current working directory

If no arguments and the working directory has no recognizable project (no source code, no README, no git history), ask the user which project to showcase.

## Reference Websites

This skill bundles two reference implementations in `reference-websites/`. **These are the source of truth** — not the written descriptions in this file. Before generating any page, read both reference index.html files to match the exact CSS, HTML structure, SVG patterns, and prose style.

- `reference-websites/dancer-claude/index.html` — Complex: live canvas demo + project writeup below. 11-node dual-pipeline architecture diagram. Use as reference when the user wants a live demo embedded.
- `reference-websites/wonyp/index.html` — Pure content showcase. 9-node sequential architecture diagram. Use as the **primary template** for most projects.
- `reference-websites/dancer-claude/css/styles.css` — App-portion CSS (for the demo zone).
- `reference-websites/dancer-claude/js/` — ES module architecture showing the app pattern.

---

## Phase 1: Project Discovery

Before asking any questions, read the project to build understanding:

1. **Codebase structure** — file tree, key source files, entry points
2. **README / docs** — if they exist, read them
3. **Git history** — recent commits, what was built, in what order
4. **Any context** the user provides in the invocation

From this, draft internally (do not show the user yet):
- **What the project does** (1-2 sentences)
- **The key components** (3-5 major pieces and what role each plays)
- **What's technically interesting** (what's the non-obvious insight?)
- **Who would care** (what audiences does this serve?)
- **Candidate analogy** (a metaphor that makes the architecture accessible)
- **Candidate named principle** (the core design insight that deserves a title)
- **Candidate tag categorization** (orange tech / blue domain / green audience)
- **Architecture flow** (which components connect to which, in what order)

---

## Phase 2: Context Interview

Ask targeted questions based on gaps in your understanding. This is NOT a fixed checklist — exercise judgment about what you need. Some projects will need 2 questions, some might need 5. **One question at a time.**

### Questions you might ask:

- "I'm thinking of describing the components as [X/Y/Z] — does that metaphor land, or is there a better way to think about them?"
- "The architecture seems to have [describe flow]. Should I show both pipelines, or focus on the runtime flow?"
- "For the tags, I'm thinking [orange: tech1, tech2] [blue: domain1] [green: audience]. Anything missing or wrong?"
- "I'd name the core design insight [proposed name] — the idea that [explanation]. Does that capture it?"
- "What's the GitHub URL for this project?"

### Demo/Video Handling

Ask the user:
> "For the top of the page, would you like:
> A) A live interactive demo embedded above the writeup
> B) A YouTube video embed (provide the video ID)
> C) Content-only — jump straight to the introduction"

**If the user's answer is vague or unclear, print this message to the screen:**
> "Defaulting to Option B (video embed) as response not satisfactory."

Then proceed with a video embed slot and ask for the YouTube video ID. If they don't have one, fall back to option C.

---

## Phase 3: Nuance Check

After the interview, ask one explicit open-ended question:

> "Is there anything unique about this project — a story behind it, a surprising finding, a design decision that's not obvious from the code — that you'd want highlighted on the page?"

This captures the content that makes each page distinctive rather than generic — the "Claude Code Angle" from Dancer Claude, the "Sambar bias" finding from WONYP. Every project has something like this. If the user says "not really," probe once: "What was the hardest part? What surprised you while building it?" Then move on.

---

## Phase 4: Generate

With all context gathered, generate the complete `index.html`. See the sections below for the exact template, design system, architecture diagram rules, and writing style guide.

---

## Template Structure

Every generated page follows this exact HTML skeleton. Read the reference `index.html` files for the precise CSS and component patterns.

```
index.html
├── <head>
│   ├── Google Fonts preconnect (DM Sans 400/700)
│   ├── Inline <style> block (full design system CSS — copy from reference)
│   └── Meta tags (viewport, charset, title)
├── <body>
│   ├── SECTION 1: Hero
│   │   ├── h1 (project title)
│   │   ├── p.tagline (one-sentence subtitle — tech stack + what it does)
│   │   └── .hero-tags-wrap (3-tier tags: orange tech / blue domain / green audience)
│   │
│   ├── SECTION 2: Video (conditional — omit if no video)
│   │   └── .video-wrap with iframe + file:// thumbnail fallback
│   │
│   ├── SECTION 3: Introduction (2-4 paragraphs)
│   │   └── Accessible analogy + system overview + why each component matters
│   │
│   ├── SECTION 4: Architecture (interactive SVG)
│   │   ├── .arch-legend (color-coded component personas)
│   │   ├── .arch-canvas > svg (nodes, paths, animated particles)
│   │   ├── .arch-detail (click-to-reveal detail bar)
│   │   └── .section-text (architecture prose, 2-4 paragraphs)
│   │
│   ├── SECTION 5: Design Philosophy (2-4 paragraphs)
│   │   └── Named principle + why this architecture, not alternatives
│   │
│   ├── SECTION 6: Project-Specific Insight (1-2 subsections)
│   │   └── Meta-commentary, failure analysis, Claude Code angle, cross-project ref
│   │
│   ├── SECTION 7: Results/Proof (optional — omit if no metrics)
│   │   └── Metrics, slideshow, demo video, or evaluation
│   │
│   └── SECTION 8: GitHub Footer
│       └── SVG GitHub icon + "View on GitHub" link
│
└── <script>
    ├── selectStep() — architecture diagram click interaction
    ├── stepData object — per-node emoji, name, description
    ├── Video embed fallback (file:// protocol detection)
    └── Slideshow logic (if results section has images)
```

### Fixed Elements (copy exactly from references)
- Full CSS design system (inline `<style>` block)
- Google Fonts preconnect pattern
- SVG filter definitions (`particleGlow`, `nodeGlow`)
- Arrow marker definitions (color-coded per the palette)
- Detail bar HTML structure and styling
- GitHub footer HTML/CSS/SVG
- `selectStep()` function pattern
- Video embed fallback (file:// protocol detection from WONYP)

### Variable Elements (generated per project)
- Title, tagline, all prose content
- Tag text and categorization
- Architecture node count, names, emojis, colors, positions, paths, descriptions
- Legend entries (component personas + technology names)
- YouTube video ID (or section omitted)
- Results content (or section omitted)
- GitHub URL

---

## Design System Tokens

These are hard constraints. Do not deviate.

### Colors

| Token | Hex | Usage |
|-------|-----|-------|
| Background | `#0f1019` | Body background |
| Text primary | `#e0e0e0` | Headings, body text |
| Text secondary | `#c8c8c8` | Section text paragraphs |
| Text tertiary | `#a0a0a0` | Captions, tagline, metadata |
| Text quaternary | `#8888aa` | Labels, placeholders |
| Border | `#23263a` | Video borders, dividers |
| Border alt | `#2e3140` | Detail bar top border |
| Card background | `#161822` | Detail bar background |
| Orange (AI/LLM) | `#f97316` | AI processing, tech tags, detail bar name |
| Blue (detection) | `#38bdf8` | Analysis/detection, domain tags |
| Green (output) | `#4ade80` | Output/learning, audience tags |
| Purple (ML) | `#bc8cff` | ML/training pipeline |
| Gray (I/O) | `#888888` | Generic input/output nodes |

### Tag Opacity Gradient

Same hue at decreasing opacity — do NOT use different colors for primary/secondary:
```css
.tag-tech-primary   { color: #f97316;   border: 1px solid #f9731640 }
.tag-tech-secondary { color: #f97316b0; border: 1px solid #f9731630 }
.tag-tech-tertiary  { color: #f9731680; border: 1px solid #f9731620 }
.tag-domain-primary { color: #38bdf8;   border: 1px solid #38bdf840 }
.tag-domain-secondary { color: #38bdf8a0; border: 1px solid #38bdf825 }
.tag-audience       { color: #4ade80;   border: 1px solid #4ade8040 }
```

### Typography

Font: **DM Sans** (Google Fonts), weights 400 and 700 only.

| Context | Size | Weight | Line Height | Letter Spacing |
|---------|------|--------|-------------|----------------|
| H1 (hero) | `clamp(36px, 6vw, 64px)` | 700 | 1.15 | +1px |
| H2 (section) | 32px | 700 | — | +0.5px |
| Tagline | 17px | 400 | 1.7 | +0.3px |
| Body text | 17px | 400 | 1.7 | default |
| Tags | 14px | 400 | — | +0.3px |
| Legend | 18px | 700 | — | default |
| Detail name | 15px | 700 | — | default |
| Detail desc | 13px | 400 | 1.55 | default |

### Spacing

| Context | Value |
|---------|-------|
| Section padding | `80px 24px` (desktop), `60px 20px` (mobile ≤640px) |
| Hero top padding | `120px` |
| Section header margin-bottom | `48px` |
| Paragraph margin-bottom | `1.4em` |
| Tag group gap | `12px` |
| Tag row gap | `10px` |
| Prose max-width | `700px` |
| Diagram max-width | `1100px` |
| Video max-width | `960px` |

### Responsive

Single breakpoint at `640px`:
- Section padding: 80px → 60px vertical
- Hero padding: 120px → 80px top
- Section header: 32px → 26px
- Architecture detail bar: flex-row → flex-column
- Slideshow buttons: 44px → 36px

---

## Architecture Diagram Generation

The interactive SVG architecture diagram is the centerpiece. It varies per project but follows strict structural rules.

### SVG Scaffold

**ViewBox:** Always `0 0 980 480`

**Background:** Dot pattern:
```svg
<pattern id="dots" x="0" y="0" width="30" height="30" patternUnits="userSpaceOnUse">
  <circle cx="15" cy="15" r="0.5" fill="#1a1c2a"/>
</pattern>
<rect width="980" height="480" fill="url(#dots)"/>
```

**Filters:**
```svg
<filter id="particleGlow" x="-100%" y="-100%" width="300%" height="300%">
  <feGaussianBlur in="SourceGraphic" stdDeviation="3" result="blur"/>
  <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
</filter>
<filter id="nodeGlow" x="-20%" y="-20%" width="140%" height="140%">
  <feGaussianBlur in="SourceGraphic" stdDeviation="5" result="blur"/>
  <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
</filter>
```

**Arrow markers** — one per color used:
```svg
<marker id="arrowOrange" markerWidth="8" markerHeight="6" refX="7" refY="3" orient="auto">
  <polygon points="0 0, 8 3, 0 6" fill="#f97316"/>
</marker>
```
Repeat for Blue (`#38bdf8`), Green (`#4ade80`), Purple (`#bc8cff`).

### Color Assignment

Map each component to a color by its role:
- **Orange `#f97316`** — AI/LLM/language processing components
- **Blue `#38bdf8`** — Detection, analysis, data processing
- **Green `#4ade80`** — Output, learning, results, computer vision
- **Purple `#bc8cff`** — ML/training pipeline, pattern finding
- **Gray `#888`** — Generic input/output (upload, render, display)

### Node Template

```svg
<g class="node" data-step="N" onclick="selectStep(N)">
  <rect x="X" y="Y" width="W" height="60" rx="12"
        fill="COLOR10" stroke="COLOR" stroke-width="1.5"/>
  <text class="step-num" x="X+10" y="Y+12">N</text>
  <text class="node-emoji" x="CENTER_X" y="Y+24"
        text-anchor="middle" fill="COLOR">EMOJI</text>
  <text class="node-label" x="CENTER_X" y="Y+46"
        text-anchor="middle" fill="COLOR">Label Text</text>
</g>
```

- `COLOR10` = the color at 10% opacity for fill (e.g., `#f9731610`)
- Node width: 115-155px depending on label length
- Node height: always 60px
- Corner radius: always 12px

### Path Template

Connect nodes with Bézier curves:
```svg
<path id="p-N-M" d="M startX,startY C cp1x,cp1y cp2x,cp2y endX,endY"
      fill="none" stroke="COLOR" stroke-width="2" stroke-opacity="0.4"
      marker-end="url(#arrowColor)"/>
```

Use `stroke-dasharray="7,5"` for inference/optional/offline paths. Solid strokes for primary data flow.

### Animated Particles

2 particles per path, staggered start times:
```svg
<circle r="4" fill="COLOR" filter="url(#particleGlow)">
  <animateMotion dur="2s" repeatCount="indefinite" begin="0s">
    <mpath href="#p-N-M"/>
  </animateMotion>
</circle>
<circle r="4" fill="COLOR" filter="url(#particleGlow)">
  <animateMotion dur="2s" repeatCount="indefinite" begin="1s">
    <mpath href="#p-N-M"/>
  </animateMotion>
</circle>
```

Duration: 2-3s per path. Stagger second particle at half the duration.

### Legend

2-4 entries above the diagram:
```html
<div class="arch-legend">
  <div class="legend-item">
    <div class="legend-top">
      <span class="legend-emoji">EMOJI</span>
      <span class="legend-name" style="color:COLOR">Persona Name</span>
    </div>
    <span class="legend-model">Technology Name</span>
  </div>
</div>
```

### Layout Heuristics

- **≤5 nodes:** Single row, left to right, evenly spaced across 980px width
- **6-8 nodes:** Two rows — top row main pipeline, bottom row secondary/offline, OR sequential with turn at right edge
- **>8 nodes:** Two rows with U-turn (like WONYP's 9-step layout)

For dual-pipeline layouts, add a divider:
```svg
<line x1="40" y1="210" x2="940" y2="210" stroke="#23263a" stroke-width="1"/>
<text x="160" y="235" font-size="11" fill="#555" text-anchor="middle"
      font-weight="700" letter-spacing="2">PIPELINE LABEL</text>
```

### Detail Bar and stepData

```html
<div class="arch-detail">
  <div class="d-icon" id="d-icon"></div>
  <div class="d-name" id="d-name">Click any step to see how it works</div>
  <div class="d-desc" id="d-desc"></div>
</div>
```

```javascript
const stepData = {
  1: { icon: "EMOJI", name: "Step Name",
       desc: "2-3 sentence accessible description. What it does and why it matters." },
  // ... one entry per node
};

let selectedStep = null;

function selectStep(n) {
  document.querySelectorAll('.arch-diagram .node rect').forEach(r => {
    r.setAttribute('stroke-width', '1.5');
    r.removeAttribute('filter');
  });
  selectedStep = n;
  const s = stepData[n];
  const node = document.querySelector('.arch-diagram .node[data-step="' + n + '"] rect');
  if (node) {
    node.setAttribute('stroke-width', '3');
    node.setAttribute('filter', 'url(#nodeGlow)');
  }
  document.getElementById('d-icon').textContent = s.icon;
  document.getElementById('d-name').textContent = s.name;
  document.getElementById('d-desc').textContent = s.desc;
}
```

---

## Writing Style Guide

### Tone & Voice

- **Confident, not academic.** Short declarative sentences. No hedging ("might", "could potentially").
- **Specific, not vague.** Name the technologies, cite the numbers, describe the mechanism.
- **Conversational depth.** Reads like a smart person explaining their work — not a paper abstract, not a README.

### Section-by-Section Patterns

**Introduction (Section 3):**
- Open with what the user experiences: "Upload a photo. Three AI models work together to..."
- Introduce the analogy (personification, relatable metaphor)
- Explain why each component matters — "none can do the full job alone"
- 2-4 paragraphs. No bullet lists.

**Architecture prose (Section 4, below the diagram):**
- Start with the high-level: "Two pipelines power the system" or "The pipeline processes each image through N steps"
- Walk through each pipeline in plain language
- End with the bridge — the invariant, the principle, whatever connects the pieces
- 2-4 paragraphs.

**Design Philosophy (Section 5):**
- Open with the core abstraction as a bold claim: "A dance is a language"
- Build the argument for why this abstraction is the right one
- **Name the principle explicitly** — every project should mint at least one named concept
- Close with why alternatives wouldn't work
- 2-4 paragraphs.

**Project-Specific Insight (Section 6):**
- This is where the personality lives
- Can be: meta-commentary on tools used (Claude Code angle), a failure turned into insight (Sambar bias), a cross-project reference, or a "deeper meaning" section
- Should feel like the author's genuine perspective, not generated boilerplate
- 1-2 subsections, each with its own h2 header.

### Specific Rhetorical Patterns

- **Analogy first, technical second** — "Joe at the club" before "bass-weighted first moment of the power spectral density"
- **Personify components** — give them roles (Brain/Eyes/Scissors, Ears/Body/Eyes)
- **Name your principles** — don't just describe a pattern, title it (Anchoring Principle, Angle Invariant)
- **Punchline endings** — close sections with a memorable line, not a trailing summary
- **Em-dashes for insertion** — use `—` to inject technical detail into flowing prose

### What NOT to Write

- "In this section we will discuss..."
- "It is worth noting that..."
- Bullet-point lists in prose sections (the output is a narrative page, not documentation)
- Generic filler — every sentence earns its place
- Hedging language ("might", "could potentially", "it seems that")
- "Lorem ipsum" or placeholder text of any kind

---

## Preview & Iteration

After generating the page:

1. **Save** `index.html` to the project directory (or a user-specified location)
2. **Open in Chrome** using `mcp__claude-in-chrome__tabs_create_mcp` to create a new tab, then `mcp__claude-in-chrome__navigate` to `file://<absolute-path>/index.html`
3. **Take a screenshot** to show the user what it looks like
4. **Ask for feedback:**
   > "Here's your project showcase. What would you like to change?"
   > - Content / writing
   > - Architecture diagram (add/remove/rename nodes)
   > - Tags / categorization
   > - Add a section (results, video, cross-project reference)
   > - Looks good, ship it
5. **Iterate** — make changes, re-preview, repeat until the user is satisfied

Expect 1-3 rounds of iteration. The architecture diagram positioning and the writing tone are the most common adjustment areas.

---

## Rules

1. **Read the reference files before generating.** The bundled `reference-websites/` folder is the source of truth for CSS, HTML structure, SVG patterns, and prose style. Always read both index.html files before writing output.
2. **Custom CSS only.** Do not use Tailwind, Bootstrap, or any CSS framework. The design system is hand-written CSS matching the references.
3. **Self-contained output.** The generated `index.html` must work by opening the file directly in a browser. All CSS inline, all JS inline, only external dependency is Google Fonts CDN.
4. **No placeholder content.** Every piece of text in the output must be real, specific to the project. No "Lorem ipsum", no "[insert description]", no TODO markers.
5. **Interview before generating.** Always run the discovery → interview → nuance check flow before writing HTML. Don't skip to generation even if the user seems impatient.
6. **One question at a time.** During the interview, ask a single question per message. Don't overwhelm with multi-part questions.
7. **Preview in Chrome.** Always show the user what the page looks like before declaring it done.
8. **Responsive is non-negotiable.** Every page must work on mobile (640px breakpoint) and desktop.