lumen-guide

lumen-guide

Multi-tab HTML guide. Two output modes: single-file (everything inlined) or split-file (shell + per-tab fragments + linked CSS/JS).

📄 Rendered example: docs/examples/guide.html

Tier: capability (atomic) — does not invoke other lumen skills. Composites and playbooks may invoke it.

When to invoke

Triggers: write a guide, create a guide, multi-tab doc, architecture doc, create a doc, make a recap, illustrate architecture, comparison matrix, roadmap, explain visually, document with forge.

Pipeline (Frame → Structure → Style → Deliver)

1. Frame — silently infer 3 signals from prompt: reader-action, takeaway, tone. See references/frame-phase.md. No questions; user can request "Frame Trace" if wrong.
2. Structure — pick tab set per content type:

Content	Tabs
Architecture overview	Overview / Components / Flows / Decisions
Migration guide	Why / Before / After / Steps / Rollback
Comparison matrix	Summary / Criteria / Tradeoffs / Recommendation
Project recap	State / Recent / Next / Risks
API reference	Quick start / Endpoints / Auth / Errors / Examples
Roadmap	Now / Next / Later / Maybe

3. Style — pick aesthetic from skills/_shared/aesthetics/ (default editorial.css for guides). Apply component variants from components/components.css. Token system documented in references/tokens.md. Two-track aesthetic detection (branded forge.yml vs exploration) per references/design-phase-two-track.md.

4. Deliver — pick output mode:

   • Single-file (shells/single.html): all CSS/JS inlined in <style> and <script>. Best for share-by-attachment.
   • Split-file (shells/split.html): shell inlines theme-toggle.js + tab-loader.js, links a single css/{SLUG}.css, and lazy-fetches per-tab fragments from tabs/{SLUG}/tab-{ID}.html. Full file layout + placeholder substitution rules in references/phase-3-generate.md — read it before authoring split-file output.

Component library (components/components.css)

Component	Variants
.hero	.hero.left-border, .hero.elevated, .hero.top-border
.section-label	.section-label.dot, .section-label.square, .section-label.triangle
.card	.card.accent, .card.info, .card.warning, .card.critical
.stat-grid	N-column responsive grid of stat tiles
.steps	Numbered step list with connectors
.phases	Horizontal phase ribbon
.kv-strip	Inline key-value pairs
.summary-card	Glance-layer summary with stat-grid
.finding	.finding--high, .finding--medium, .finding--low (severity badge)
.io-strip	Input → Output flow strip
details.disclosure	Native disclosure for deep-layer content
.has-tip	Inline tooltip on hover

Plus base sheets: reset.css, typography.css, layout.css. Tab nav driven by tab-loader.js. Light/dark via theme-toggle.js.

Full token surface in references/tokens.md. Brand-aware loading via references/design-phase-two-track.md.

3-layer information architecture

• Glance ≤5s — hero + stat-grid + section-label headers
• Scan ≤30s — sections + tables + cards + summary-card
• Deep — details.disclosure for full reference content

Tab structure mirrors layers: first tab is glance, middle tabs are scan, last tab(s) are deep reference. Spec in references/output-ux.md.

CSS pattern library (references/css-patterns.md)

Lifted from visual-explainer. Covers:

• KPI card with hero number + trend indicator
• Mermaid zoom controls (+/−/reset/expand buttons + Ctrl/Cmd-scroll + click-pan + click-to-expand)
• Hero-image wrap with base64 data-URI
• Overflow protection (min-width: 0 on grid/flex children, overflow-wrap: break-word)
• Responsive section navigation
• List rendering without display: flex on <li> (absolute-positioned markers instead)

Reach for these patterns when the guide needs them; do not re-invent.

Anti-patterns to avoid

See references/anti-patterns.md. Highlights: never display: flex on <li>, never put marker characters inside flex children, never let grid children overflow.

Quality checks

• Hero present on first tab
• Each tab fits "scan in 30s" rule on first paint
• details.disclosure used for any block >300 words
• .finding uses correct severity class (high/medium/low)
• Tab nav keyboard-accessible (Tab + Enter)
• Mobile: tabs collapse to accordion
• AAA contrast on all var(--text)
• Mermaid diagrams (if any) use the zoom-pan pattern from css-patterns.md

Output

• Single-file mode: one .html written to ~/.agent/lumen/<slug>.html. Open in browser.
• Split-file mode: directory ~/.agent/lumen/<slug>/ with <slug>.html (shell, JS inlined) + css/<slug>.css + tabs/<slug>/tab-<id>.html (one fragment per tab, lazy-fetched). See references/phase-3-generate.md.

PI extension route (v0.1.x)

Not wired through lumen-generate_visual PI tool. A deterministic schema (tab array with markdown-like content + component references) is feasible but not yet implemented. The LLM-authored CC path remains the right fit for guides that need conditional structure and rich free-form text.

Sources

• Roxabi/roxabi-forge/plugins/forge/skills/forge-guide (MIT) — split-file shell architecture, 3-layer information architecture, Frame → Structure → Style → Deliver methodology
• Roxabi/roxabi-forge/plugins/forge/references/base/ (MIT) — components.css + reset.css + typography.css + layout.css + tab-loader.js + theme-toggle.js
• Roxabi/roxabi-forge/plugins/forge/references/ (MIT) — tokens.md, output-ux.md, frame-phase.md, design-phase-two-track.md, anti-patterns.md
• Roxabi/roxabi-forge/plugins/forge/references/shells/ (MIT) — single.html + split.html
• nicobailon/visual-explainer/plugins/visual-explainer/references/css-patterns.md (MIT) — KPI cards, mermaid zoom controls, overflow protection
• skills/_shared/aesthetics/ (this package) — 5 aesthetics shared with diagrams