gh-levnikolaevich-claude-code-skills-full-development-workflow-skills/skills/ln-115-presentation-creator/references/TEMPLATE_ARCHITECTURE.md

x-html-builder Template Architecture

This document describes the structure and content specifications for all HTML templates used by x-html-builder skill.

File Structure

All templates are stored in x-html-builder/references/ following the Template Ownership Principle (each skill owns its templates):

x-html-builder/references/
├── presentation_template.html    # Base HTML5 structure with 6 tab navigation
├── styles.css                     # CSS Variables, responsive design (~500 lines)
├── scripts.js                     # Tab switching, collapsible sections, Mermaid init
├── build-presentation.js          # Node.js build script for inlining
└── tabs/
    ├── tab_overview_template.html          # Landing page
    ├── tab_requirements_template.html      # FRs + ADRs (Non-Functional Requirements are forbidden)
    ├── tab_architecture_template.html      # C4 diagrams
    ├── tab_technical_spec_template.html    # API + Data + Deployment
    ├── tab_roadmap_template.html           # Kanban-style
    └── tab_guides_template.html            # How-to guides

Tab Content Specifications

Tab 1: Overview (Landing Page)

File: tab_overview_template.html

SCOPE:

• INCLUDES: Project name, tagline, business goal, tech stack badges, role-based navigation, quick stats, recent updates
• EXCLUDES: Full requirements → Requirements tab, Detailed diagrams → Architecture tab, Full roadmap → Roadmap tab, API details → Technical Spec tab

Content Elements:

• Header Intro: Project name (h1) + tagline (minimal, no gradient background)
• Project Summary: Business goal in "About This Project" section (h2)
• Role-Based Navigation: 4 cards (Developer/Architect/Product Owner/Stakeholder) - clickable, switches to relevant tab
• Tech Stack Badges: Technology badges with icons and names
• Quick Stats: Project statistics grid (total epics, completed stories, test coverage, uptime SLA)
• Recent Updates: Recent project updates list
• Quick Links: Links to other tabs (Requirements, Architecture, API Reference, Roadmap)

Data Sources:

• requirements.md (project name, business goal)
• architecture.md (tech stack)
• kanban_board.md (stats, recent updates)

Placeholders:

• {{PROJECT_NAME}} - Project name from requirements.md ## Project Name
• {{PROJECT_TAGLINE}} - Short description from requirements.md
• {{BUSINESS_GOAL}} - Business goals section from requirements.md
• {{TECH_STACK_BADGES}} - Generated from architecture.md tech stack
• {{QUICK_STATS}} - Generated from kanban_board.md Epic Story Counters
• {{RECENT_UPDATES}} - Placeholder (currently undefined - TODO: specify data source)

Tab 2: Requirements

File: tab_requirements_template.html

SCOPE:

• INCLUDES: Business goals, FRs (collapsible), ADRs (Strategic/Technical groups), constraints, success criteria
• EXCLUDES: Implementation details → Technical Spec, Diagrams → Architecture, Code → Guides, Non-Functional Requirements (explicitly banned from this tab)

Content Elements:

• Business Goals: Project objectives with key targets (h2 + list)
• Functional Requirements: Collapsible by domain (details/summary tags) - FR-XXX-001 format with Priority (MUST/SHOULD/COULD), Description
• ADRs Section: Grouped by category:
  • Strategic Decisions (h3) - Business/architecture strategy ADRs
  • Technical Decisions (h3) - Technology/implementation ADRs
  • Each ADR in accordion (details/summary) with full content inline:
    • Date | Status | Category (metadata line)
    • Context (h4)
    • Decision (h4)
    • Rationale (h4 + list)
    • Alternatives Considered (h4 + table: Alternative | Pros | Cons | Rejection Reason)
    • Consequences (h4 + Positive/Negative lists)
• Constraints: Technology constraints
• Success Criteria: Measurable project success metrics

Data Sources:

• requirements.md (business goals, FRs, constraints, success criteria)
• adrs/*.md (all ADR files with Category field for grouping)

Note: Do not add Non-Functional Requirements (performance, security, scalability, etc.). If quality topics need coverage, describe them as architecture quality goals in narrative form only—never as NFR-XXX-001 style requirements.

Placeholders:

• None (all content directly from MD files)

Tab 3: Architecture

File: tab_architecture_template.html

SCOPE:

• INCLUDES: C4 diagrams (Context/Container/Component), Deployment, Solution strategy, Quality attributes
• EXCLUDES: ADRs → Requirements, API details → Technical Spec, Code → Guides

Content Elements:

• C4 Diagrams: 4 levels in Mermaid syntax (preserved exactly as in architecture.md):
  • System Context (C4 Level 1)
  • Container Diagram (C4 Level 2)
  • Component Diagram (C4 Level 3)
  • Deployment Diagram
• Solution Strategy: Architecture pattern, API design approach
• Quality Attributes: Scalability, Security, Maintainability approaches

Data Sources:

• architecture.md (all content)

Placeholders:

• None (all content directly from architecture.md)

EXCLUDES:

• Tech stack table → moved to Technical Spec tab
• ADRs → moved to Requirements tab

Tab 4: Technical Specification

File: tab_technical_spec_template.html

SCOPE:

• INCLUDES: Tech stack (detailed table), API endpoints, Authentication, Error codes, ER diagram, Data dictionary, Integrations, Deployment, Testing strategy (Risk-Based)
• EXCLUDES: Requirements → Requirements tab, Architecture diagrams → Architecture tab, How-to guides → Guides tab

Content Elements:

• Technology Stack: Detailed table (Category | Technology | Version | Purpose) - includes Frontend, Backend, Database, Infrastructure, DevOps categories
• API Endpoints: Table grouped by resource (Endpoint | Method | Description | Request | Response)
• Authentication: Auth mechanism description (JWT, OAuth, etc.)
• Error Codes: Standard error codes table (Code | Message | Description)
• Data Model: ER diagram in Mermaid + Data Dictionary table (Entity | Attributes | Description)
• Third-Party Integrations: External services table (Service | Purpose | API Documentation)
• Deployment Infrastructure: Infrastructure description (cloud provider, services)
• Testing Strategy: Risk-Based Testing approach (2-5 E2E, 3-8 Integration, 5-15 Unit tests per Story, total 10-28 max)

Data Sources:

• technical_specification.md (all content)
• architecture.md (tech stack section - moved here)

Placeholders:

• None (all content directly from MD files)

Tab 5: Roadmap

File: tab_roadmap_template.html

SCOPE:

• INCLUDES: Kanban board (3 columns), Epic cards, Progress bars (%), Milestones
• EXCLUDES: Individual stories → Linear, Daily tasks → task tracker, Team assignments, Implementation details → Technical Spec

Content Elements:

• Kanban Board: 3 columns layout (Todo | In Progress | Done)
• Epic Cards: For each Epic from kanban_board.md:
  • Epic number + title (h3)
  • Description (p)
  • Stories count: X/Y completed
  • Target date or Completed date
  • Status badge (status-todo | status-progress | status-done)
  • Progress bar with % width
• Milestones: Quarterly milestones list with status indicators

Data Sources:

• kanban_board.md (Epic Story Counters table - Epic number, title, status, story counts, target dates)
• requirements.md (Epic descriptions)
• architecture.md (Epic technical context)

Placeholders:

• None (all content generated from kanban_board.md)

Epic Status Mapping:

• Todo → kanban-todo column, status-todo badge, 0% progress
• In Progress → kanban-progress column, status-progress badge, calculated % progress
• Done → kanban-done column, status-done badge, 100% progress

Tab 6: Guides

File: tab_guides_template.html

SCOPE:

• INCLUDES: Getting started, How-to guides (task-oriented), Best practices, Troubleshooting, Contributing, External resources
• EXCLUDES: API reference → Technical Spec, Architecture → Architecture tab, Requirements → Requirements tab

Content Elements:

• Getting Started: Prerequisites, Installation steps (code blocks), Verification checklist
• How-To Guides: Task-oriented guides (How to Add Product, How to Test API, etc.) - steps in ordered lists
• Best Practices: Code style, Testing approach, Design patterns
• Troubleshooting: Common issues with solutions (h3 per issue + list)
• Contributing Guidelines: Fork, branch, test, submit PR workflow
• External Resources: Links to framework docs, third-party docs (target="_blank")

Data Sources:

• docs/guides/*.md (all guide files)
• README.md (getting started section)
• technical_specification.md (testing strategy)

Placeholders:

• None (all content directly from guide files)

Build Process

Script: build-presentation.js (Node.js)

Logic:

1. Read presentation_template.html
2. Read all 6 tab files from tabs/ directory
3. Inject tab content into template (replace <!-- TAB_CONTENT_overview --> etc.)
4. Read styles.css and inline into <style> tags
5. Read scripts.js and inline into <script> tags
6. Write ../presentation_final.html (one level up from assets/)

Expected Output:

• Standalone HTML file (~120-150 KB)
• No external dependencies (except Mermaid.js CDN for diagram rendering)
• All CSS and JavaScript inlined

Styling Specifications

File: styles.css (~500 lines)

CSS Variables:

:root {
    --primary-color: #2563eb;
    --background-color: #f8fafc;
    --text-color: #1e293b;
    --border-color: #e2e8f0;
}

Key Components:

• header-intro: Minimal header (no gradient) - name + tagline
• project-summary: Business goal section (h2 + paragraph)
• role-cards: 4 clickable cards with hover effects (subtle, no transform)
• badge: Tech stack badges (inline-block, rounded, neutral colors)
• epic-card: Roadmap Epic cards with status badges and progress bars
• progress-bar: Horizontal bar with % fill (neutral colors, no gradient)
• tabs: Navigation bar with active tab indicator
• kanban-board: 3-column grid layout
• Mermaid diagrams: Responsive container with max-width
• ADR accordion: details/summary styling with expand indicator
• Responsive breakpoints: Mobile (<768px), Tablet (768-1024px), Desktop (>1024px)

Design Principles:

• Minimal, documentation-focused (vs marketing-style)
• Neutral color palette (blues, grays)
• No excessive gradients or transforms
• GitBook/Docusaurus aesthetic
• Progressive disclosure (collapsible sections)
• Information scent (clear navigation labels)

Validation Checklist

Before completing build, verify:

• HTML structure valid (proper heading hierarchy h1 > h2 > h3)
• All 6 tabs present in navigation (overview, requirements, architecture, technical_spec, roadmap, guides)
• SCOPE tags present in each tab (HTML comments in first 3-5 lines)
• All placeholders replaced (no {{PLACEHOLDER}} remaining)
• Mermaid diagrams render correctly (valid syntax, no errors in console)
• Tab switching works (JavaScript loaded, localStorage state persistence)
• Collapsible sections functional (details/summary expand/collapse)
• Responsive design works (mobile/tablet/desktop breakpoints)
• Kanban board renders: 3 columns, Epic cards in correct columns, progress bars display %
• ADR grouping works: Strategic/Technical sections separate, accordion expands/collapses
• Role-based navigation cards clickable (switches to correct tabs)
• File size within expected range (~120-150 KB)
• Tested in browser: Double-click presentation_final.html → opens without errors

Data Source Mapping

Tab	Primary Source	Secondary Sources
Overview	requirements.md	architecture.md, kanban_board.md
Requirements	requirements.md	adrs/*.md
Architecture	architecture.md	-
Technical Spec	technical_specification.md	architecture.md (tech stack)
Roadmap	kanban_board.md	requirements.md, architecture.md
Guides	docs/guides/*.md	README.md, technical_specification.md

Placeholder Reference

Placeholder	Source	Location
{{PROJECT_NAME}}	requirements.md	## Project Name
{{PROJECT_TAGLINE}}	requirements.md	First paragraph or subtitle
{{BUSINESS_GOAL}}	requirements.md	## Business Goals section
{{TECH_STACK_BADGES}}	architecture.md	## Technology Stack section
{{QUICK_STATS}}	kanban_board.md	Epic Story Counters table
{{RECENT_UPDATES}}	TODO: Undefined	Need to specify data source

TODO: Undefined Placeholders

RECENT_UPDATES:

• Current Status: Placeholder exists in tab_overview_template.html but data source not specified
• Recommendation: Either:
  1. Remove placeholder if not needed
  2. Define data source (e.g., git log last 5 commits, or manual section in requirements.md)
  3. Generate from kanban_board.md Epic status changes

---

Version: 1.0.0 Last Updated: 2025-01-31 Related: x-html-builder/SKILL.md