@dedesfr/prompter 0.8.7 → 0.8.9

package/skills/design-md/examples/DESIGN.md

@@ -0,0 +1,154 @@
+# Design System: Furniture Collections List
+**Project ID:** 13534454087919359824
+
+## 1. Visual Theme & Atmosphere
+
+The Furniture Collections List embodies a **sophisticated, minimalist sanctuary** that marries the pristine simplicity of Scandinavian design with the refined visual language of luxury editorial presentation. The interface feels **spacious and tranquil**, prioritizing breathing room and visual clarity above all else. The design philosophy is gallery-like and photography-first, allowing each furniture piece to command attention as an individual art object.
+
+The overall mood is **airy yet grounded**, creating an aspirational aesthetic that remains approachable and welcoming. The interface feels **utilitarian in its restraint** but elegant in its execution, with every element serving a clear purpose while maintaining visual sophistication. The atmosphere evokes the serene ambiance of a high-end furniture showroom where customers can browse thoughtfully without visual overwhelm.
+
+**Key Characteristics:**
+- Expansive whitespace creating generous breathing room between elements
+- Clean, architectural grid system with structured content blocks
+- Photography-first presentation with minimal UI interference
+- Whisper-soft visual hierarchy that guides without shouting
+- Refined, understated interactive elements
+- Professional yet inviting editorial tone
+
+## 2. Color Palette & Roles
+
+### Primary Foundation
+- **Warm Barely-There Cream** (#FCFAFA) – Primary background color. Creates an almost imperceptible warmth that feels more inviting than pure white, serving as the serene canvas for the entire experience.
+- **Crisp Very Light Gray** (#F5F5F5) – Secondary surface color used for card backgrounds and content areas. Provides subtle visual separation while maintaining the airy, ethereal quality.
+
+### Accent & Interactive
+- **Deep Muted Teal-Navy** (#294056) – The sole vibrant accent in the palette. Used exclusively for primary call-to-action buttons (e.g., "Shop Now", "View all products"), active navigation links, selected filter states, and subtle interaction highlights. This sophisticated anchor color creates visual focus points without disrupting the serene neutral foundation.
+
+### Typography & Text Hierarchy
+- **Charcoal Near-Black** (#2C2C2C) – Primary text color for headlines and product names. Provides strong readable contrast while being softer and more refined than pure black.
+- **Soft Warm Gray** (#6B6B6B) – Secondary text used for body copy, product descriptions, and supporting metadata. Creates clear typographic hierarchy without harsh contrast.
+- **Ultra-Soft Silver Gray** (#E0E0E0) – Tertiary color for borders, dividers, and subtle structural elements. Creates separation so gentle it's almost imperceptible.
+
+### Functional States (Reserved for system feedback)
+- **Success Moss** (#10B981) – Stock availability, confirmation states, positive indicators
+- **Alert Terracotta** (#EF4444) – Low stock warnings, error states, critical alerts
+- **Informational Slate** (#64748B) – Neutral system messages, informational callouts
+
+## 3. Typography Rules
+
+**Primary Font Family:** Manrope  
+**Character:** Modern, geometric sans-serif with gentle humanist warmth. Slightly rounded letterforms that feel contemporary yet approachable.
+
+### Hierarchy & Weights
+- **Display Headlines (H1):** Semi-bold weight (600), generous letter-spacing (0.02em for elegance), 2.75-3.5rem size. Used sparingly for hero sections and major page titles.
+- **Section Headers (H2):** Semi-bold weight (600), subtle letter-spacing (0.01em), 2-2.5rem size. Establishes clear content zones and featured collections.
+- **Subsection Headers (H3):** Medium weight (500), normal letter-spacing, 1.5-1.75rem size. Product names and category labels.
+- **Body Text:** Regular weight (400), relaxed line-height (1.7), 1rem size. Descriptions and supporting content prioritize comfortable readability.
+- **Small Text/Meta:** Regular weight (400), slightly tighter line-height (1.5), 0.875rem size. Prices, availability, and metadata remain legible but visually recessive.
+- **CTA Buttons:** Medium weight (500), subtle letter-spacing (0.01em), 1rem size. Balanced presence without visual aggression.
+
+### Spacing Principles
+- Headers use slightly expanded letter-spacing for refined elegance
+- Body text maintains generous line-height (1.7) for effortless reading
+- Consistent vertical rhythm with 2-3rem between related text blocks
+- Large margins (4-6rem) between major sections to reinforce spaciousness
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** Subtly rounded corners (8px/0.5rem radius) – approachable and modern without appearing playful or childish
+- **Primary CTA:** Deep Muted Teal-Navy (#294056) background with pure white text, comfortable padding (0.875rem vertical, 2rem horizontal)
+- **Hover State:** Subtle darkening to deeper navy, smooth 250ms ease-in-out transition
+- **Focus State:** Soft outer glow in the primary color for keyboard navigation accessibility
+- **Secondary CTA (if needed):** Outlined style with Deep Muted Teal-Navy border, transparent background, hover fills with whisper-soft teal tint
+
+### Cards & Product Containers
+- **Corner Style:** Gently rounded corners (12px/0.75rem radius) creating soft, refined edges
+- **Background:** Alternates between Warm Barely-There Cream and Crisp Very Light Gray based on layering needs
+- **Shadow Strategy:** Flat by default. On hover, whisper-soft diffused shadow appears (`0 2px 8px rgba(0,0,0,0.06)`) creating subtle depth
+- **Border:** Optional hairline border (1px) in Ultra-Soft Silver Gray for delicate definition when shadows aren't present
+- **Internal Padding:** Generous 2-2.5rem creating comfortable breathing room for content
+- **Image Treatment:** Full-bleed at the top of cards, square or 4:3 ratio, seamless edge-to-edge presentation
+
+### Navigation
+- **Style:** Clean horizontal layout with generous spacing (2-3rem) between menu items
+- **Typography:** Medium weight (500), subtle uppercase, expanded letter-spacing (0.06em) for refined sophistication
+- **Default State:** Charcoal Near-Black text
+- **Active/Hover State:** Smooth 200ms color transition to Deep Muted Teal-Navy
+- **Active Indicator:** Thin underline (2px) in Deep Muted Teal-Navy appearing below current section
+- **Mobile:** Converts to elegant hamburger menu with sliding drawer
+
+### Inputs & Forms
+- **Stroke Style:** Refined 1px border in Soft Warm Gray
+- **Background:** Warm Barely-There Cream with transition to Crisp Very Light Gray on focus
+- **Corner Style:** Matching button roundness (8px/0.5rem) for visual consistency
+- **Focus State:** Border color shifts to Deep Muted Teal-Navy with subtle outer glow
+- **Padding:** Comfortable 0.875rem vertical, 1.25rem horizontal for touch-friendly targets
+- **Placeholder Text:** Ultra-Soft Silver Gray, elegant and unobtrusive
+
+### Product Cards (Specific Pattern)
+- **Image Area:** Square (1:1) or landscape (4:3) ratio filling card width completely
+- **Content Stack:** Product name (H3), brief descriptor, material/finish, price
+- **Price Display:** Emphasized with semi-bold weight (600) in Charcoal Near-Black
+- **Hover Behavior:** Gentle lift effect (translateY -4px) combined with enhanced shadow
+- **Spacing:** Consistent 1.5rem internal padding below image
+
+## 5. Layout Principles
+
+### Grid & Structure
+- **Max Content Width:** 1440px for optimal readability and visual balance on large displays
+- **Grid System:** Responsive 12-column grid with fluid gutters (24px mobile, 32px desktop)
+- **Product Grid:** 4 columns on large desktop, 3 on desktop, 2 on tablet, 1 on mobile
+- **Breakpoints:** 
+  - Mobile: <768px
+  - Tablet: 768-1024px  
+  - Desktop: 1024-1440px
+  - Large Desktop: >1440px
+
+### Whitespace Strategy (Critical to the Design)
+- **Base Unit:** 8px for micro-spacing, 16px for component spacing
+- **Vertical Rhythm:** Consistent 2rem (32px) base unit between related elements
+- **Section Margins:** Generous 5-8rem (80-128px) between major sections creating dramatic breathing room
+- **Edge Padding:** 1.5rem (24px) mobile, 3rem (48px) tablet/desktop for comfortable framing
+- **Hero Sections:** Extra-generous top/bottom padding (8-12rem) for impactful presentation
+
+### Alignment & Visual Balance
+- **Text Alignment:** Left-aligned for body and navigation (optimal readability), centered for hero headlines and featured content
+- **Image to Text Ratio:** Heavily weighted toward imagery (70-30 split) reinforcing photography-first philosophy
+- **Asymmetric Balance:** Large hero images offset by compact, refined text blocks
+- **Visual Weight Distribution:** Strategic use of whitespace to draw eyes to hero products and primary CTAs
+- **Reading Flow:** Clear top-to-bottom, left-to-right pattern with intentional focal points
+
+### Responsive Behavior & Touch
+- **Mobile-First Foundation:** Core experience designed and perfected for smallest screens first
+- **Progressive Enhancement:** Additional columns, imagery, and details added gracefully at larger breakpoints
+- **Touch Targets:** Minimum 44x44px for all interactive elements (WCAG AAA compliant)
+- **Image Optimization:** Responsive images with appropriate resolutions for each breakpoint, lazy-loading for performance
+- **Collapsing Strategy:** Navigation collapses to hamburger, grid reduces columns, padding scales proportionally
+
+## 6. Design System Notes for Stitch Generation
+
+When creating new screens for this project using Stitch, reference these specific instructions:
+
+### Language to Use
+- **Atmosphere:** "Sophisticated minimalist sanctuary with gallery-like spaciousness"
+- **Button Shapes:** "Subtly rounded corners" (not "rounded-md" or "8px")
+- **Shadows:** "Whisper-soft diffused shadows on hover" (not "shadow-sm")
+- **Spacing:** "Generous breathing room" and "expansive whitespace"
+
+### Color References
+Always use the descriptive names with hex codes:
+- Primary CTA: "Deep Muted Teal-Navy (#294056)"
+- Backgrounds: "Warm Barely-There Cream (#FCFAFA)" or "Crisp Very Light Gray (#F5F5F5)"
+- Text: "Charcoal Near-Black (#2C2C2C)" or "Soft Warm Gray (#6B6B6B)"
+
+### Component Prompts
+- "Create a product card with gently rounded corners, full-bleed square product image, and whisper-soft shadow on hover"
+- "Design a primary call-to-action button in Deep Muted Teal-Navy (#294056) with subtle rounded corners and comfortable padding"
+- "Add a navigation bar with generous spacing between items, using medium-weight Manrope with subtle uppercase and expanded letter-spacing"
+
+### Incremental Iteration
+When refining existing screens:
+1. Focus on ONE component at a time (e.g., "Update the product grid cards")
+2. Be specific about what to change (e.g., "Increase the internal padding of product cards from 1.5rem to 2rem")
+3. Reference this design system language consistently

package/skills/doc-builder/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: doc-builder
+description: Generate interactive system flowchart documentation pages with Mermaid.js diagrams. Use this skill whenever the user asks to create documentation, document architecture, generate flowcharts, visualize system flows, or create technical diagrams for any scope — a single page, feature, module, or entire project/repo. Also use when the user says things like "create documentation for ...", "document this module", "generate system diagrams", or "visualize the architecture".
+---
+
+# System Flowcharts Generator
+
+Generate interactive, self-contained HTML documentation pages with Mermaid.js flowchart diagrams. The pages follow a Mintlify-inspired design system with a sidebar, top navbar, module cards, and lazy-rendered diagrams.
+
+## When to use
+
+- User asks to document a system, module, feature, or entire repo
+- User wants flowcharts, architecture diagrams, or system visualizations
+- User says "create documentation", "document the flows", "generate diagrams", etc.
+
+## Workflow
+
+### 1. Determine Scope and Output Strategy
+
+Ask the user (or infer from context) what they want documented. Then, after exploring the codebase, **recommend** whether to use a single file or multiple files — but let the user decide.
+
+When making your recommendation, consider:
+- **Number of flows/sections**: A feature with 3 flows fits comfortably in one file. A module with 12+ flows gets unwieldy.
+- **Content density**: If each flow has detailed diagrams and step timelines, even a few flows can make a single page very long.
+- **Navigability**: A single file with sidebar sections is simpler to share and browse. Multiple files are easier to maintain and load faster individually.
+
+Present your recommendation like: "This module has 8 major flows — I'd suggest splitting into separate pages per domain area with an index page, but I can also put it all in one file if you prefer. What do you think?"
+
+For multi-file output, create an `index.html` that links to each module's page. Each module page is fully self-contained (all CSS/JS inline).
+
+### 2. Explore the Codebase
+
+Investigate the target scope to understand:
+- System architecture and module boundaries
+- Data flows and request lifecycles
+- Key processes, workflows, and decision points
+- External integrations and dependencies
+- Error handling paths
+
+### 3. Identify Flowchart Content
+
+For each section/module, identify:
+- **Overview**: What the module does, its key components (rendered as module cards)
+- **Flows**: The major workflows worth diagramming (each becomes a sidebar section with a Mermaid flowchart)
+- **Steps**: Key process steps (rendered as timeline flow steps)
+
+### 4. Generate the HTML
+
+Read the full design system spec from `references/ui-patterns.md` in this skill's directory. Follow it exactly — all design tokens, components, typography, responsive breakpoints, and JavaScript behavior.
+
+Key requirements:
+- Single self-contained HTML file per page (all CSS and JS inline)
+- Google Fonts loaded via `<link>` tag (Inter + Geist Mono)
+- Mermaid.js loaded via CDN
+- Left sidebar navigation with sections for Overview + each flow
+- Lazy Mermaid rendering (diagrams render only when their tab is activated)
+- Tab switching updates breadcrumbs and scrolls to top
+- Scroll animations via IntersectionObserver
+- Mobile responsive (sidebar collapses below 1024px)
+
+### 5. Output Location
+
+Save output to `docs/` directory by default:
+- Single scope: `docs/flowcharts.html` or `docs/<name>-flowcharts.html`
+- Multi-file: `docs/flowcharts/index.html` + `docs/flowcharts/<module>.html`
+
+Ask the user if they want a different location.
+
+---
+
+## Mermaid Diagram Conventions
+
+Use consistent node styling to communicate meaning:
+
+| Color | Meaning | Mermaid Style |
+|-------|---------|---------------|
+| Cyan (`#06B6D4`) | Start/Entry point | `style A fill:#06B6D4,color:#fff` |
+| Green (`#18E299`) | System process | `style B fill:#18E299,color:#0F172A` |
+| Amber (`#F59E0B`) | Approval/Decision requiring human input | `style C fill:#F59E0B,color:#0F172A` |
+| Red (`#EF4444`) | Error/Rejection | `style D fill:#EF4444,color:#fff` |
+| White (`#ffffff`) | Standard process step | (default, no override needed) |
+
+Always include a legend after each diagram explaining the color conventions used.
+
+## Mermaid Tips
+
+- Use `flowchart TD` (top-down) for most flows
+- Use descriptive node labels in quotes: `A["User Submits Form"]`
+- Use edge labels for conditions: `C -->|"Valid"| D`
+- Keep diagrams focused — if a flow has more than ~15 nodes, split into sub-flows
+- Use subgraphs to group related steps: `subgraph "Authentication" ... end`
+
+---
+
+## Index Page (Multi-file Output)
+
+When generating multiple module pages, create an `index.html` that:
+- Uses the same design system (topbar, styling)
+- Shows a grid of module cards (one per module page)
+- Each card links to the module's HTML file
+- Includes a brief project overview at the top
+
+---
+
+## Design System Reference
+
+The complete UI pattern specification is bundled at `references/ui-patterns.md`. Read it before generating any HTML. It contains:
+- All design tokens (colors, spacing, dimensions)
+- Typography specs (Inter + Geist Mono)
+- Component HTML/CSS patterns (topbar, sidebar, flowchart containers, module cards, flow steps, badges, legends)
+- Mermaid.js configuration block
+- JavaScript for tab switching, lazy rendering, scroll animations
+- Responsive breakpoints
+
+Follow the spec precisely — do not improvise styles or deviate from the documented patterns.

package/skills/doc-builder/references/ui-patterns.md

@@ -0,0 +1,394 @@
+# System Flowcharts - UI Pattern Documentation
+
+> Reusable pattern for generating interactive system flowchart documentation pages.
+> Mintlify-inspired Classic Light theme, featuring a left sidebar, top navbar, and Mermaid.js diagrams.
+
+---
+
+## Table of Contents
+
+- [Design Tokens](#design-tokens)
+- [Typography](#typography)
+- [Page Structure](#page-structure)
+- [Components](#components)
+  - [Top Navigation Bar](#top-navigation-bar)
+  - [Left Sidebar](#left-sidebar)
+  - [Main Content Area](#main-content-area)
+  - [Flowchart Container](#flowchart-container)
+  - [Mermaid Diagram](#mermaid-diagram)
+  - [Module Cards Grid](#module-cards-grid)
+  - [Flow Steps (Timeline)](#flow-steps-timeline)
+  - [Badges](#badges)
+  - [Legend](#legend)
+- [Mermaid Configuration](#mermaid-configuration)
+- [JavaScript Behavior](#javascript-behavior)
+- [Responsive Breakpoints](#responsive-breakpoints)
+- [Usage Template](#usage-template)
+
+---
+
+## Design Tokens
+
+### Color Palette
+
+| Token                | Value                          | Usage                    |
+| -------------------- | ------------------------------ | ------------------------ |
+| `--color-primary`    | `#0F172A`                      | Slate 900 - Dark text    |
+| `--color-brand`      | `#18E299`                      | Primary brand green      |
+| `--color-brand-light`| `#d4fae8`                      | Light brand background   |
+| `--color-brand-deep` | `#0fa76e`                      | Deep brand accent text   |
+| `--color-white`      | `#ffffff`                      | Main content background  |
+| `--color-warning`    | `#F59E0B`                      | Amber - Warnings         |
+| `--color-error`      | `#EF4444`                      | Red - Errors/Rejections  |
+| `--color-info`       | `#3B82F6`                      | Blue - Standard Process  |
+| `--color-gray-50`    | `#F9FAFB`                      | Standard light background|
+| `--color-gray-100`   | `#F3F4F6`                      | Subtle hover background  |
+| `--color-gray-500`   | `#6B7280`                      | Secondary text (slate)   |
+| `--color-gray-700`   | `#374151`                      | Primary body text        |
+| `--color-gray-900`   | `#111827`                      | Headings and strong text |
+| `--color-border`     | `#E5E7EB`                      | Standard borders         |
+| `--color-border-medium`| `#D1D5DB`                    | Hover borders            |
+
+### Core Layout Dimensions
+
+| Token                    | Value    | Usage                      |
+| ------------------------ | -------- | -------------------------- |
+| `--sidebar-width`        | `260px`  | Width of left sidebar      |
+| `--header-height`        | `60px`   | Height of top sticky nav   |
+| `--content-max-width`    | `880px`  | Max width of reading pane  |
+
+---
+
+## Typography
+
+### Fonts
+
+| Font             | Weight             | Usage                              |
+| ---------------- | ------------------ | ---------------------------------- |
+| **Inter**        | 400, 500, 600, 700 | Body, headings, main UI elements   |
+| **Geist Mono**   | 400, 500, 600      | Code, tags, badges, step numbers   |
+
+### Google Fonts Import
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Geist+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+```
+
+---
+
+## Page Structure
+
+The layout follows a two-column documentation structure:
+
+```html
+<body>
+  <div class="layout">
+    <header class="topbar">
+      <!-- Logo and Breadcrumbs -->
+    </header>
+
+    <div class="layout-body">
+      <aside class="sidebar">
+        <!-- Sidebar Navigation Links -->
+      </aside>
+
+      <main class="main-content">
+        <div class="content-container">
+          <!-- Page Header (Title, Subtitle, Summary Pills) -->
+          <!-- Flowchart Containers per section -->
+        </div>
+      </main>
+    </div>
+  </div>
+</body>
+```
+
+---
+
+## Components
+
+### Top Navigation Bar
+
+Sticky header with branding and dynamic breadcrumbs.
+
+```html
+<header class="topbar">
+  <div class="topbar-logo">
+    <svg>...</svg> Docs Logo
+  </div>
+  <div class="topbar-breadcrumbs">
+    <!-- Breadcrumb items -->
+    <span class="active" id="breadcrumb-current">Current Section</span>
+  </div>
+</header>
+```
+
+**Key styles:**
+- `position: fixed`, `height: 60px`
+- Background: `rgba(255, 255, 255, 0.85)` with `backdrop-filter: blur(12px)`
+- Border bottom: `1px solid var(--color-border)`
+
+---
+
+### Left Sidebar
+
+Fixed navigation menu replacing traditional horizontal tabs.
+
+```html
+<aside class="sidebar">
+  <div class="sidebar-group">
+    <div class="sidebar-group-title">Category Name</div>
+    <nav class="sidebar-nav">
+      <button class="sidebar-link active" data-tab="overview">
+        <span>Overview</span>
+      </button>
+      <button class="sidebar-link" data-tab="section-1">
+        <span>Section 1</span>
+      </button>
+    </nav>
+  </div>
+</aside>
+```
+
+**Key styles:**
+- Fixed below topbar, width `260px`
+- Background: `var(--color-gray-50)`
+- Links (`.sidebar-link`): Clean layout with `font-size: 0.875rem`
+- Active State: Background `var(--color-brand-light)`, text `var(--color-brand-deep)`
+
+---
+
+### Main Content Area
+
+Responsive container for readability.
+
+```html
+<main class="main-content">
+  <div class="content-container">
+    <div class="page-header">
+      <div class="eyebrow">Category</div>
+      <h1>Main Document Title</h1>
+      <p class="subtitle">Document description</p>
+    </div>
+  </div>
+</main>
+```
+
+**Key styles:**
+- Margin-left matches sidebar width (`260px`)
+- Content max-width constrained to `880px`
+- `padding: 3rem 2rem 5rem` for generous vertical whitespace
+
+---
+
+### Flowchart Container
+
+Wrapper that shows/hides content based on active sidebar link.
+
+```html
+<section class="flowchart-container" id="tab-id">
+  <!-- Content for this section -->
+</section>
+```
+
+**Key styles:**
+- `display: none` by default, `display: block` when `.active`
+- Fast entry animation: `fadeIn 0.4s ease` (opacity + translate)
+
+---
+
+### Mermaid Diagram
+
+Container for Mermaid.js rendered flowcharts.
+
+```html
+<div class="mermaid-container">
+  <h3>Diagram Title</h3>
+  <p class="mermaid-caption">Diagram explanation text.</p>
+  <pre class="mermaid">
+flowchart TD
+    A["Start"] --> B["Process"]
+    B --> C{"Decision"}
+    C -->|Yes| D["Success"]
+    C -->|No| E["Handle Error"]
+  </pre>
+</div>
+```
+
+**Container styles:**
+- Border: `1px solid var(--color-border)`
+- Border radius: `12px`
+- `overflow-x: auto` allows wide diagrams to scroll horizontally inside the container.
+
+---
+
+### Module Cards Grid
+
+Overview cards for system modules/features.
+
+```html
+<div class="modules-grid">
+  <article class="module-card">
+    <h3>Module Name</h3>
+    <p>Short description of the module.</p>
+    <div class="badge-row">
+      <span class="badge badge-module">Label</span>
+    </div>
+  </article>
+</div>
+```
+
+**Key styles:**
+- Grid: `repeat(auto-fill, minmax(320px, 1fr))`
+- Pure white background, subtle `1px solid var(--color-border)` borders
+- Hover effect: elevates shadow and darkens border to `--color-border-medium`
+
+---
+
+### Flow Steps (Timeline)
+
+Vertical timeline with connected step cards.
+
+```html
+<div class="flow-section">
+  <h3>Timeline Title</h3>
+  <div class="flow-grid">
+    <article class="flow-step">
+      <span class="dot"></span>
+      <h4>Step Title</h4>
+      <p>Description</p>
+    </article>
+  </div>
+</div>
+```
+
+**Key styles:**
+- Timeline line: `::before` on `.flow-grid` (2px wide, gray-200)
+- Connection dot: rendered via `.dot` element (16px circle, white center, brand green border)
+- Steps inherit hover-elevation styles from `.module-card`
+
+---
+
+### Badges
+
+Inline status indicators.
+
+```html
+<span class="badge badge-module">MODULE</span>
+<span class="badge badge-status">DEFAULT</span>
+<span class="badge badge-warning">WARNING</span>
+<span class="badge badge-error">ERROR</span>
+```
+
+| Class            | Background             | Text Color          |
+| ---------------- | ---------------------- | ------------------- |
+| `.badge-module`  | `var(--brand-light)`   | `var(--brand-deep)` |
+| `.badge-status`  | `var(--gray-100)`      | `var(--gray-700)`   |
+| `.badge-warning` | `#FEF3C7` (Amber 100)  | `#D97706` (Amber 600)|
+| `.badge-error`   | `#FEE2E2` (Red 100)    | `#DC2626` (Red 600) |
+
+---
+
+### Legend
+
+Contextual legend placed after diagrams.
+
+```html
+<div class="legend">
+  <h3>Legend</h3>
+  <div class="legend-items">
+    <div class="legend-item"><div class="legend-icon is-user"></div><span>User Action</span></div>
+    <div class="legend-item"><div class="legend-icon is-system"></div><span>System Process</span></div>
+  </div>
+</div>
+```
+
+**Icon borders:** 
+- User: Brand Green
+- System: Slate 900
+- Warning: Amber
+- Process: Blue
+
+---
+
+## Mermaid Configuration
+
+The design applies custom light-mode variables directly via the `mermaid.initialize` block to harmonize with the UI:
+
+```javascript
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'base',
+  themeVariables: {
+    darkMode: false,
+    background: '#F9FAFB',
+    mainBkg: '#ffffff',
+    primaryColor: '#111827',
+    primaryTextColor: '#374151',
+    primaryBorderColor: '#18E299',
+    lineColor: '#1f2937',
+    secondaryColor: '#F3F4F6',
+    tertiaryColor: '#E5E7EB',
+    fontFamily: 'Inter, system-ui, sans-serif',
+    fontSize: '13px',
+    edgeLabelBackground: '#ffffff',
+    clusterBkg: '#F9FAFB',
+    clusterBorder: '#E5E7EB'
+  },
+  flowchart: {
+    useMaxWidth: true,
+    htmlLabels: true,
+    curve: 'basis',
+    padding: 24,
+    wrappingWidth: 200
+  }
+});
+```
+
+---
+
+## JavaScript Behavior
+
+### Navigation & Breadcrumbs
+
+Clicking a `.sidebar-link` sets active classes on the link and matching `.flowchart-container`. It also extracts the link text and updates `#breadcrumb-current`, scrolling the user back to the top of the content area.
+
+### Mermaid Lazy Rendering
+
+Diagrams render only when their corresponding section is activated:
+
+```javascript
+const renderTab = async (tabId) => {
+  if (renderedTabs.has(tabId)) return;
+  const container = document.getElementById(tabId);
+  if (!container) return;
+  
+  const diagrams = container.querySelectorAll('.mermaid');
+  if (!diagrams.length) {
+    renderedTabs.add(tabId);
+    return;
+  }
+  
+  if (document.fonts?.ready) await document.fonts.ready;
+  await mermaid.run({ querySelector: `#${tabId} .mermaid` });
+  renderedTabs.add(tabId);
+};
+```
+
+### Scroll Animations
+
+`.animate-on-scroll` elements fade and slide up automatically via `IntersectionObserver`.
+
+---
+
+## Responsive Breakpoints
+
+### Tablets & Mobile (`max-width: 1024px`)
+
+The dual-pane UI gracefully collapses:
+
+| Component        | Change                                        |
+| ---------------- | --------------------------------------------- |
+| Sidebar          | Hidden (`display: none`)                      |
+| Main Content     | `margin-left: 0`, full width, reduced padding |
+| Topbar Logo      | Returns to intrinsic width                    |