# HTML Artifact Generator — Full Instructions

## Purpose

Generate single-file HTML artifacts for human-consumed outputs. This skill implements the Output Format Protocol (Design Principle #8): agent self-use = markdown; human consumption = HTML when content warrants it.

## 🚨 P0 Constraint: Chat Non-Degradation

**Every HTML artifact MUST be accompanied by a complete inline markdown summary in chat.** The chat response stands alone — the HTML is a supplement for richer exploration, never the only answer.

```
✅ CORRECT:
[Complete markdown analysis/answer in chat]
"Interactive version with full details: path/to/artifact.html"

❌ WRONG:
"I've generated the analysis. See: path/to/artifact.html"
```

## When to Generate HTML (Escalation Triggers)

Generate an HTML artifact when ANY of these are true:
1. Output > 100 lines of structured content
2. Multi-dimensional comparison (3+ columns × 5+ rows with data relationships)
3. Data requires spatial layout (architecture diagram, flow, dependency graph)
4. Reader will want to manipulate it (filter, sort, tab-switch, toggle details)
5. Synthesizes data from multiple sources into one unified view
6. Output will be shared externally (to colleague, in email, in presentation)
7. Information has visual hierarchy (traffic lights, RAG status, severity colors)

**When NOT to generate HTML:**
- Simple Q&A or explanations (stay markdown)
- Agent-consumed files (MEMORY.md, DDD docs, DailyActivity)
- Slack output (use mrkdwn + Block Kit)
- Content under 100 lines without spatial needs
- When the user is in a rapid back-and-forth conversation (don't slow down the flow)

## Level Selection

Pick the LOWEST level that serves the content:

| Level | Type | When | Template |
|-------|------|------|----------|
| **L1** | Static Doc | Formatted report, comparison table, spec review | `report.html` |
| **L2** | Visual | Charts, SVG diagrams, grids, color-coded status | `visual.html` |
| **L3** | Interactive | Filter, sort, tab-switch, toggle, drill-down | `interactive.html` |
| **L4** | Tool | Purpose-built mini-app (rare — usually frontend-design skill) | Custom |

**Default is L1.** Escalate only with clear justification.

## Template System

### Base Design System (mandatory for ALL levels)

Read the base CSS from `templates/base.css` and include it inline in every HTML file:

```bash
cat templates/base.css
```

### Template Selection

| Use Case | Template | Level |
|----------|----------|-------|
| Pipeline REPORT | `templates/report.html` | L1-L2 |
| Code Review findings | `templates/code-review.html` | L2 |
| Evaluation scorecard | `templates/scorecard.html` | L2 |
| Comparison / analysis | `templates/comparison.html` | L2-L3 |
| Generic (custom) | Use base.css + write structure | L1-L4 |

### How to Use Templates

1. Read the relevant template file
2. Replace `{{PLACEHOLDER}}` markers with actual content
3. Include `base.css` inline in `<style>` block
4. Write the final HTML file to the appropriate location:
   - Pipeline artifacts: `Projects/<project>/.artifacts/`
   - Reports: `Knowledge/Reports/YYYY-MM-DD-<topic>.html`
   - Ad-hoc artifacts: `Attachments/YYYY-MM-DD-<topic>.html`

## HTML Generation Rules

### Single-File Discipline (Non-Negotiable)

- ONE `.html` file. Everything inline.
- `<style>` block with all CSS (from base.css + template-specific)
- `<script>` block with all JS (L3+ only)
- NO external CDN links (no Google Fonts, no Tailwind CDN, no D3 CDN)
- NO images as external URLs (use inline SVG or data: URIs)
- The file IS the artifact — email-able, share-able, archive-able

### Design Constraints

**Typography:**
```css
font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; /* code */
```

**Colors (use CSS variables from base.css):**
- `--color-bg`: #FAFAFA (background)
- `--color-surface`: #FFFFFF (cards)
- `--color-text`: #1A1A1A (body text)
- `--color-accent`: #2563EB (primary blue)
- `--color-success`: #16A34A (green / on track)
- `--color-warning`: #D97706 (amber / at risk)
- `--color-danger`: #DC2626 (red / off track)
- `--color-muted`: #6B7280 (secondary text)
- `--color-border`: #E5E7EB (dividers)

**NEVER:**
- Linear gradients on backgrounds
- Glassmorphism / frosted glass effects
- Icon libraries (Font Awesome, Material Icons, Lucide)
- Loading spinners or skeleton screens
- "Generated by AI" or "Powered by SwarmAI" footers
- Animations longer than 200ms
- Dark theme as default (use `prefers-color-scheme` media query if needed)
- `!important` overrides
- Inline styles on individual elements (use classes)

**ALWAYS:**
- Responsive layout (works on 320px to 2560px)
- `clamp()` for typography sizing
- CSS Grid or Flexbox for layout (never float)
- `@media print` rules (hide nav, full-width tables)
- Semantic HTML elements (`<table>`, `<nav>`, `<main>`, `<section>`, `<article>`)
- `lang` attribute on `<html>` matching content language
- `<meta charset="UTF-8">` + `<meta name="viewport" ...>`
- Accessible: sufficient color contrast (WCAG AA), focus states, aria-labels on interactive elements

### Export Contract (L3+ Mandatory)

For Level 3 and 4, include an export mechanism:

```html
<button id="export-btn" class="export-button" onclick="exportData()">
  Copy as Markdown
</button>

<script>
function exportData() {
  // Build markdown/JSON from current state
  const data = buildExport();
  navigator.clipboard.writeText(data).then(() => {
    const btn = document.getElementById('export-btn');
    btn.textContent = 'Copied!';
    btn.classList.add('copied');
    setTimeout(() => {
      btn.textContent = 'Copy as Markdown';
      btn.classList.remove('copied');
    }, 2000);
  });
}

function buildExport() {
  // Template-specific: collect current state → markdown/JSON string
  // Example: gather filtered/sorted table rows → markdown table
  return '| Column | Data |\n|--------|------|\n...';
}
</script>
```

## Output Locations

| Context | Path | Example |
|---------|------|---------|
| Pipeline artifact | `Projects/<project>/.artifacts/REPORT.html` | Pipeline delivery report |
| Knowledge report | `Knowledge/Reports/YYYY-MM-DD-<topic>.html` | Monthly analysis |
| Ad-hoc artifact | `Attachments/YYYY-MM-DD-<topic>.html` | One-off comparison |
| CMHK reports | `Knowledge/Reports/` (already handled by cmhk-* skills) | Weekly/Monthly |

## Chat Integration Pattern

After generating an HTML artifact, the chat response MUST follow this pattern:

```
[Section 1: Complete markdown answer — the user can decide/act from this alone]

[Section 2: One-line reference to the HTML artifact]
---
Full interactive report: `Knowledge/Reports/2026-05-14-analysis.html`
```

The Section 1 markdown must be **decision-complete** — a busy executive reading only the chat should have enough to act. The HTML is for those who want to explore further.

## Reference

- Design doc: `Knowledge/Designs/2026-05-14-output-format-protocol-design.md`
- TECH.md: `Projects/SwarmAI/TECH.md` → "Output Format Protocol" section
- Inspiration: html-it (robonuggets), frontend-slides (zarazhangrui)
