303 lines
13 KiB
Markdown
303 lines
13 KiB
Markdown
# 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:**
|
|
```css
|
|
: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
|