From fd714cdb02dfe520b9f7ae35489ef78522368117 Mon Sep 17 00:00:00 2001
From: Appa Rao Vadde <9968587+vadde@users.noreply.github.com>
Date: Tue, 3 Nov 2026 10:24:27 -0500
Subject: [PATCH 1/6] feat(docs): implement Year 2500 Design Patterns Living
Documentation Portal
- Create high-performance zero-toolchain compiler 'scripts/build-docs.py' compiling 28 chapters, 38 runnable Python implementations, and 77 diagrams
- Build Year 2500 liquid glass design system with Aero Mica halos, Holo 2050 cyber-HUD, and Matrix Obsidian themes in 'docs/site/style.css'
- Implement 1:1 DSA nested tree navigation with distinct category badge pills, expandable child links, and batch tree controls
- Implement bi-directional collapsible chapter accordions with Focus Mode synchrony, reading controls, and sub-10ms batch expand
- Build Interactive Pattern Decision Matrix & Framework Triage Engine
- Build sub-millisecond Fullscreen Theater Mode diagram workbench
- Integrate Web Audio API directional haptic acoustic engine (HapticAudio)
- Implement 15-Gate Automated Headless Verification Suite ('scripts/test-docs.sh')
- Add canonical DevEx Makefile targets ('make docs-build', 'docs-serve', 'docs-test', 'ci')
- Add GitHub Actions CI ('ci.yml') and continuous deployment workflow ('docs-publish.yml')
- Authoritative PRD 'SPEC-001' and living engineering skill 'design-patterns-docs-portal'
- Sanitize Mermaid syntax edge-cases and align Unicode box-drawing tables
---
.../design-patterns-docs-portal/SKILL.md | 250 ++
.github/workflows/ci.yml | 16 +
.github/workflows/docs-publish.yml | 50 +
.gitignore | 2 +
00 - Foundations/theory.md | 12 +-
01 - Singleton (Creational)/theory.md | 6 +-
02 - Factory Method (Creational)/theory.md | 2 +-
.../theory.md | 4 +-
.../theory.md | 4 +-
Makefile | 82 +
README.md | 20 +-
_internal/instructions.md | 2 +-
docs/site/app.js | 1453 ++++++++++++
docs/site/assets/aero-mica-theme-verified.png | Bin 0 -> 216410 bytes
.../assets/decision-matrix-hud-verified.png | Bin 0 -> 257828 bytes
.../assets/hero-command-deck-verified.png | Bin 0 -> 219094 bytes
.../theater-mode-workbench-verified.png | Bin 0 -> 180473 bytes
docs/site/assets/verification-holo-theme.png | Bin 0 -> 188550 bytes
.../verification-liquid-sidebar-tree.png | Bin 0 -> 247589 bytes
docs/site/index.html | 342 +++
docs/site/style.css | 2044 +++++++++++++++++
scripts/audit_ascii_boxes.py | 356 +++
scripts/audit_collapsible_elements.py | 181 ++
scripts/audit_links_and_anchors.py | 168 ++
scripts/audit_monospace_badging.py | 97 +
scripts/build-docs.py | 698 ++++++
scripts/build-docs.sh | 38 +
scripts/test-docs.sh | 240 ++
...-design-patterns-futuristic-docs-portal.md | 304 +++
29 files changed, 6348 insertions(+), 23 deletions(-)
create mode 100755 .agents/skills/design-patterns-docs-portal/SKILL.md
create mode 100644 .github/workflows/docs-publish.yml
create mode 100755 Makefile
create mode 100755 docs/site/app.js
create mode 100755 docs/site/assets/aero-mica-theme-verified.png
create mode 100755 docs/site/assets/decision-matrix-hud-verified.png
create mode 100755 docs/site/assets/hero-command-deck-verified.png
create mode 100755 docs/site/assets/theater-mode-workbench-verified.png
create mode 100644 docs/site/assets/verification-holo-theme.png
create mode 100644 docs/site/assets/verification-liquid-sidebar-tree.png
create mode 100755 docs/site/index.html
create mode 100755 docs/site/style.css
create mode 100755 scripts/audit_ascii_boxes.py
create mode 100755 scripts/audit_collapsible_elements.py
create mode 100755 scripts/audit_links_and_anchors.py
create mode 100755 scripts/audit_monospace_badging.py
create mode 100755 scripts/build-docs.py
create mode 100755 scripts/build-docs.sh
create mode 100755 scripts/test-docs.sh
create mode 100755 specs/SPEC-001-design-patterns-futuristic-docs-portal.md
diff --git a/.agents/skills/design-patterns-docs-portal/SKILL.md b/.agents/skills/design-patterns-docs-portal/SKILL.md
new file mode 100755
index 0000000..0e18ed7
--- /dev/null
+++ b/.agents/skills/design-patterns-docs-portal/SKILL.md
@@ -0,0 +1,250 @@
+---
+name: design-patterns-docs-portal
+description: >-
+ Authoritative engineering guide and automated testing protocol for the Design Patterns Living Documentation Portal (https://vadde.github.io/DesignPatterns/). Covers Year 2500 cosmic liquid-glass design system, Aero Mica ambient halos, draggable sidebar resizer invariants, commute gadget mobile drawer, zero-truncation titles, touch-overflow containment, 1:1 ScrollSpy sync, Mermaid SVG layout rules, Safari WebKit flex sizing, sub-millisecond Theater mode workbench, KaTeX math typesetting, interactive Pattern Finder & Decision Matrix, Cmd+K fuzzy search, Unicode monospace box-drawing alignment engine, and the 15-gate automated headless audit suite.
+---
+
+# ๐๏ธ Design Patterns Living Documentation Portal Engineering Skill
+
+This skill is the **authoritative engineering protocol and single source of truth** for maintaining, styling, extending, and verifying the `vadde/DesignPatterns` Living Documentation Portal ([https://vadde.github.io/DesignPatterns/](https://vadde.github.io/DesignPatterns/)).
+
+AI coding assistants and engineers must follow this guide whenever adding patterns, modifying CSS styles, rendering architecture diagrams, building interactive widgets, or testing on mobile and desktop viewports.
+
+---
+
+## ๐๏ธ Portal Architecture & File Map
+
+The documentation portal is built with **zero build toolchain dependencies** (pure vanilla HTML5, CSS3, ES2022 JavaScript, and standard CDN libraries):
+
+```
+DesignPatterns/
+โโโ Makefile # Canonical DevEx commands (docs-build, docs-serve, docs-test, etc.)
+โโโ specs/
+โ โโโ SPEC-001-design-patterns-futuristic-docs-portal.md # Ratified PRD & System Architecture Spec
+โโโ docs/site/
+โ โโโ index.html # Hydrated Year 2500 Command Deck Shell
+โ โโโ style.css # Liquid glass tokens, Aero Mica halos, resizer, responsive layout
+โ โโโ app.js # ScrollSpy, resizer, mobile drawer, search modal, lazy renderers
+โโโ scripts/
+โ โโโ build-docs.py # Production catalog compiler (28 chapters, 38 python examples)
+โ โโโ build-docs.sh # Static bundle packaging script (outputs to _site/)
+โ โโโ test-docs.sh # 15-Gate automated headless verification suite
+โ โโโ audit_ascii_boxes.py # Unicode UAX #11 monospace box-drawing linter and formatter
+โ โโโ audit_collapsible_elements.py # Collapsible details & raw HTML block auditor
+โ โโโ audit_links_and_anchors.py # Universal link & local path leak prevention auditor
+โ โโโ audit_monospace_badging.py # Monospace semantic badge and tree auditor
+โโโ .agents/skills/design-patterns-docs-portal/
+โ โโโ SKILL.md # YOU ARE HERE โ Authoritative design & engineering protocol
+โโโ .github/workflows/
+ โโโ ci.yml # Parallel CI verification (Python compile, Ruff, 15-Gate Audit)
+ โโโ docs-publish.yml # CD workflow deploying verified main pushes to GitHub Pages
+```
+
+---
+
+## ๐จ Design System & Multi-Theme Engine
+
+The portal uses a **deep cosmic liquid-glass design system with Aero Mica ambient halos** supporting 4 distinct themes:
+
+### Color Palette Tokens
+
+| Token | CSS Variable | Hex / RGBA Value | Purpose |
+|---|---|---|---|
+| **Canvas Deep Base** | `--bg-deep` | `#050813` | Deep space background canvas |
+| **Card Surface** | `--bg-card` | `rgba(13, 20, 39, 0.65)` | Glassmorphism card background |
+| **Card Border** | `--bg-card-border` | `rgba(255, 255, 255, 0.08)` | Subtle translucent glass card edge |
+| **Hover Border** | `--bg-card-border-glow` | `rgba(0, 242, 254, 0.35)` | Interactive element border focus |
+| **Cyan Accent** | `--accent-cyan` | `#00f2fe` | Primary interactive focus, active items, Creational badges |
+| **Violet Accent** | `--accent-violet` | `#a855f7` | Diagram relational links, Structural badges |
+| **Emerald Accent** | `--accent-emerald` | `#10b981` | Behavioral badges, Foundations status |
+| **Amber Accent** | `--accent-amber` | `#f59e0b` | Architectural badges, caution callouts |
+| **Rose Accent** | `--accent-rose` | `#f43f5e` | Capstone alerts, Anti-patterns |
+| **Primary Text** | `--text-main` | `#f1f5f9` | High-contrast body text and titles |
+| **Muted Text** | `--text-muted` | `#94a3b8` | Subtitles, parameter descriptions |
+| **Dim Text** | `--text-dim` | `#64748b` | Captions, footnotes, table metadata |
+
+### Theme Invariants:
+1. **Liquid Glass (`[data-theme="liquid"]`)**: Default deep cosmic glass with vibrant cyan/violet edge glows.
+2. **Aero Mica (`[data-theme="mica"]`)**:
+ - **High-Contrast Code Blocks**: Code blocks MUST use dark text on bright frosted surface (`background: rgba(255, 255, 255, 0.95); color: #0f172a !important;`). Never leave white-on-white text!
+ - **Frosted Theater Tool Buttons**: Must use high-contrast frosted pills (`background: rgba(255, 255, 255, 0.22); border: 1px solid rgba(255, 255, 255, 0.55); color: #ffffff !important;`) so that `+`, `โ`, `100%`, and `Fit` buttons pop over the dark modal header.
+3. **Obsidian Dark (`[data-theme="matrix"]` or `[data-theme="obsidian"]`)**: Matte pure-black stealth palette with neon emerald accents.
+4. **Cyberpunk Neon (`[data-theme="holo"]` or `[data-theme="cyberpunk"]`)**: High-saturation electric cyan and amber contrast grid.
+
+---
+
+## โ๏ธ Interactive Draggable Sidebar Resizer & Collapsible Rail Standard
+
+The navigation sidebar supports continuous draggable resizing and full collapsible rail distraction-free mode:
+
+### Operational Invariants:
+1. **Collapsible Distraction-Free Reading**:
+ - Closed via `#sidebar-close-btn` inside sidebar or `#sidebar-dock-toggle` in header.
+ - When collapsed, `body.sidebar-collapsed` shifts `.sidebar` by `margin-left: calc(-1 * var(--sidebar-width)); opacity: 0; visibility: hidden;` and hides `.sidebar-resizer`.
+ - Floating reopen tab `#floating-sidebar-toggle` appears on the left edge (`top: calc(var(--topbar-height) + 14px); left: 14px;`).
+ - Global keyboard shortcuts: `โB`, `Ctrl+B`, or `[` (when not focused in inputs) toggle the rail instantly.
+ - State persisted in `localStorage.setItem('dp_sidebar_collapsed', 'true' / 'false')`.
+2. **Bounds Clamping**: Resizing strictly clamped between `MIN_WIDTH = 240px` and `MAX_WIDTH = 560px`.
+3. **Dragging Performance**: During drag, `body.resizing-sidebar` sets `cursor: col-resize !important; user-select: none !important;`.
+4. **Persistence**: Width choice is saved to `localStorage.setItem('dp_sidebar_width', width)`.
+5. **Double-Click Reset**: Double-clicking resets `--sidebar-width` to default `330px`.
+6. **Zero-Truncation Invariant**: Never clip navigation titles with single-line ellipses (`white-space: normal; word-break: break-word`).
+
+---
+
+## ๐ฑ Commute Gadget Mobile Navigation Architecture
+
+1. On viewports $\le 1024\text{px}$, sidebar transitions into an off-canvas slide-out drawer (`width: min(86vw, 360px)`).
+2. **Stacking Context Invariant**: `#mobile-drawer-backdrop` (`z-index: 1100`) must be placed inside `.layout-container` right before `.sidebar` (`z-index: 1200`).
+3. **Sticky Scroll Invariant**: **Never use `overflow-x: hidden` on `html` or `body`**. Always use `overflow-x: clip;` to prevent breaking `position: sticky`.
+4. Wrap all `
` elements in `` with horizontal touch scrolling and explicit min-width (`min-width: 520px`).
+
+---
+
+## ๐ฏ Universal Delegated In-Page Navigation
+
+All in-page anchors (`a[href^="#"]`) use delegated event interception in `app.js`:
+1. Intercepts click and cancels native jump.
+2. Checks if target element or any ancestor is collapsed (`.pattern-chapter.is-collapsed` or closed `
`).
+3. Automatically uncollapses containing chapters, opens ``, and updates toggle buttons.
+4. Forces synchronous layout flush (`targetEl.getBoundingClientRect()`).
+5. Smoothly scrolls with exact 72px cushion:
+ ```javascript
+ const y = targetEl.getBoundingClientRect().top + window.pageYOffset - 72;
+ window.scrollTo({ top: y, behavior: 'smooth' });
+ ```
+6. Applies a temporary flash focus highlight (`flash-focus`) for 1800ms. Zero treasure hunting!
+
+---
+
+## โก Sub-10ms "Expand All" SLA
+
+When opening all 28 chapters simultaneously:
+- **Root-Cause Pitfall**: Synchronous execution of diagram render calls inside accordion `toggle` events freezes the CPU for seconds.
+- **The Protocol**: Guard accordion `toggle` listeners with `STATE.isBatchExpanding`:
+ ```javascript
+ STATE.isBatchExpanding = true;
+ document.querySelectorAll('.pattern-chapter').forEach(c => c.classList.remove('is-collapsed'));
+ document.querySelectorAll('.theory-details, .example-card').forEach(d => { d.open = true; });
+ setTimeout(() => {
+ STATE.isBatchExpanding = false;
+ renderVisibleDiagrams();
+ }, 50);
+ ```
+
+---
+
+## ๐ Mermaid Diagram & Safari WebKit Layout Rules
+
+### 1. Isolated `mermaid.render()` Execution:
+Never rely on uncoordinated `mermaid.run()`. Always use isolated, direct rendering:
+```javascript
+const { svg, bindFunctions } = await window.mermaid.render(renderId, code);
+el.innerHTML = svg;
+if (bindFunctions) bindFunctions(el);
+```
+
+### 2. The Safari WebKit Flex-SVG Sizing Invariant:
+- **Never use `width: auto !important` on `.mermaid svg`** inside flex containers. In WebKit/Safari, an SVG with percentage width and `width: auto` collapses to `0px ร 0px`!
+- **CSS Rule**:
+ ```css
+ .mermaid svg {
+ display: block !important;
+ width: 100% !important;
+ max-width: 100% !important;
+ height: auto !important;
+ max-height: 580px !important;
+ object-fit: contain;
+ margin: 0 auto;
+ }
+ ```
+- **Intrinsic Dimension Injection**:
+ Extract `vbW` and `vbH` from the SVG's `viewBox` and inject explicit W3C attributes:
+ ```javascript
+ svgEl.setAttribute('width', vbW);
+ svgEl.setAttribute('height', vbH);
+ svgEl.style.aspectRatio = `${vbW} / ${vbH}`;
+ ```
+
+### 3. Escaping & Syntax Cleanliness:
+- Escape `<` and `>` in node labels as `<` / `>` or `โค` / `โฅ`.
+- Every diagram MUST have a globally unique `id="mermaid-diagram-{uid}"`.
+
+---
+
+## ๐ Fullscreen Theater Mode Workbench
+
+Implemented using native HTML5 `