@vpxa/aikit 0.1.57 → 0.1.59

package/scaffold/general/skills/c4-architecture/references/html-design-system.md

@@ -0,0 +1,337 @@
+# HTML/SVG Architecture Diagram Design System
+
+This file is the centralized design system for HTML and SVG architecture diagrams.
+
+It is the single source of truth for visual tokens, component categories, layout rules, and `present` tool composition guidance used by the `c4-architecture` skill and the `present` skill. Update component types, colors, layout rules, and icon slots here only.
+
+## Purpose
+
+- Define a reusable visual language for C4-style architecture diagrams rendered as HTML and inline SVG.
+- Keep category styling extensible through a registry instead of hardcoded component types.
+- Standardize diagram composition for both skill-authored documentation and `present` output.
+
+## Core Design Tokens
+
+### Typography
+
+- Font family: `"JetBrains Mono", monospace`
+- Font source: Google Fonts (`https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;700;800&display=swap`)
+- Component names: `12px`
+- Sublabels: `9px`
+- Annotations: `8px`
+- Tiny labels: `7px`
+- Legend: `10px`
+- Icon area labels: `11px`
+
+### Background
+
+- Page background: `#020617` (`slate-950`)
+- Background pattern: inline SVG grid pattern over the page background
+- Recommended grid line colors:
+  - Major grid: `rgba(148, 163, 184, 0.08)`
+  - Minor grid: `rgba(148, 163, 184, 0.04)`
+
+### Component Box Defaults
+
+- Shape: rounded rectangle
+- Border radius: `rx="6"`
+- Stroke width: `1.5px`
+- Fill: category-specific semi-transparent RGBA fill
+- Stroke: category-specific hex stroke
+- Label stack:
+  - Line 1: C4 label such as `<<Container>>`
+  - Line 2: component name
+  - Line 3: subtype or technology summary
+
+## Category Registry
+
+The registry is hierarchical: categories define shared tokens and C4 intent, while sub-types inherit the category styling and reserve an icon slot for future SVG glyphs.
+
+| Category | Stroke Color | Fill Color | C4 Mapping | Sub-types |
+|---|---|---|---|---|
+| Frontend | `#22d3ee` | `rgba(8, 51, 68, 0.4)` | Container (SPA, web) | SPA, Mobile App, Static Site, Micro-frontend, PWA, Desktop App |
+| Backend | `#34d399` | `rgba(6, 78, 59, 0.4)` | Container (service) | API Service, Worker/Job, BFF, Microservice, Serverless Function, gRPC Service |
+| Data | `#a78bfa` | `rgba(76, 29, 149, 0.4)` | ContainerDb | Relational DB, Document DB, Key-Value Store, Cache, Search Engine, Data Warehouse, Graph DB, Time-Series DB |
+| Infrastructure | `#fbbf24` | `rgba(120, 53, 15, 0.3)` | Deployment_Node | CDN, Load Balancer, DNS, Object Storage, Container Registry, Reverse Proxy, Service Mesh |
+| Messaging | `#fb923c` | `rgba(251, 146, 60, 0.3)` | ContainerQueue | Message Queue, Event Bus, Stream, Pub/Sub, Webhook |
+| Security | `#fb7185` | `rgba(136, 19, 55, 0.4)` | System_Ext / boundary | Auth Provider, API Gateway, WAF, Secret Manager, Certificate Manager, Identity Provider |
+| External | `#94a3b8` | `rgba(30, 41, 59, 0.5)` | System_Ext | Third-party API, SaaS, Legacy System, Partner Service, Payment Provider |
+| Monitoring | `#38bdf8` | `rgba(12, 74, 110, 0.4)` | Container | Logging, Metrics, Tracing, Alerting, APM |
+
+## Sub-type Registry
+
+Each sub-type inherits its category tokens and keeps a placeholder slot for an inline SVG icon.
+
+| Category | Sub-type | C4 Label | Icon Slot |
+|---|---|---|---|
+| Frontend | SPA | `<<Container>>` | `icon-spa` |
+| Frontend | Mobile App | `<<Container>>` | `icon-mobile-app` |
+| Frontend | Static Site | `<<Container>>` | `icon-static-site` |
+| Frontend | Micro-frontend | `<<Container>>` | `icon-micro-frontend` |
+| Frontend | PWA | `<<Container>>` | `icon-pwa` |
+| Frontend | Desktop App | `<<Container>>` | `icon-desktop-app` |
+| Backend | API Service | `<<Container>>` | `icon-api-service` |
+| Backend | Worker/Job | `<<Container>>` | `icon-worker-job` |
+| Backend | BFF | `<<Container>>` | `icon-bff` |
+| Backend | Microservice | `<<Container>>` | `icon-microservice` |
+| Backend | Serverless Function | `<<Container>>` | `icon-serverless-function` |
+| Backend | gRPC Service | `<<Container>>` | `icon-grpc-service` |
+| Data | Relational DB | `<<ContainerDb>>` | `icon-relational-db` |
+| Data | Document DB | `<<ContainerDb>>` | `icon-document-db` |
+| Data | Key-Value Store | `<<ContainerDb>>` | `icon-key-value-store` |
+| Data | Cache | `<<ContainerDb>>` | `icon-cache` |
+| Data | Search Engine | `<<ContainerDb>>` | `icon-search-engine` |
+| Data | Data Warehouse | `<<ContainerDb>>` | `icon-data-warehouse` |
+| Data | Graph DB | `<<ContainerDb>>` | `icon-graph-db` |
+| Data | Time-Series DB | `<<ContainerDb>>` | `icon-time-series-db` |
+| Infrastructure | CDN | `<<Deployment_Node>>` | `icon-cdn` |
+| Infrastructure | Load Balancer | `<<Deployment_Node>>` | `icon-load-balancer` |
+| Infrastructure | DNS | `<<Deployment_Node>>` | `icon-dns` |
+| Infrastructure | Object Storage | `<<Deployment_Node>>` | `icon-object-storage` |
+| Infrastructure | Container Registry | `<<Deployment_Node>>` | `icon-container-registry` |
+| Infrastructure | Reverse Proxy | `<<Deployment_Node>>` | `icon-reverse-proxy` |
+| Infrastructure | Service Mesh | `<<Deployment_Node>>` | `icon-service-mesh` |
+| Messaging | Message Queue | `<<ContainerQueue>>` | `icon-message-queue` |
+| Messaging | Event Bus | `<<ContainerQueue>>` | `icon-event-bus` |
+| Messaging | Stream | `<<ContainerQueue>>` | `icon-stream` |
+| Messaging | Pub/Sub | `<<ContainerQueue>>` | `icon-pub-sub` |
+| Messaging | Webhook | `<<ContainerQueue>>` | `icon-webhook` |
+| Security | Auth Provider | `<<System_Ext>>` | `icon-auth-provider` |
+| Security | API Gateway | `<<System_Ext>>` | `icon-api-gateway` |
+| Security | WAF | `<<System_Ext>>` | `icon-waf` |
+| Security | Secret Manager | `<<System_Ext>>` | `icon-secret-manager` |
+| Security | Certificate Manager | `<<System_Ext>>` | `icon-certificate-manager` |
+| Security | Identity Provider | `<<System_Ext>>` | `icon-identity-provider` |
+| External | Third-party API | `<<System_Ext>>` | `icon-third-party-api` |
+| External | SaaS | `<<System_Ext>>` | `icon-saas` |
+| External | Legacy System | `<<System_Ext>>` | `icon-legacy-system` |
+| External | Partner Service | `<<System_Ext>>` | `icon-partner-service` |
+| External | Payment Provider | `<<System_Ext>>` | `icon-payment-provider` |
+| Monitoring | Logging | `<<Container>>` | `icon-logging` |
+| Monitoring | Metrics | `<<Container>>` | `icon-metrics` |
+| Monitoring | Tracing | `<<Container>>` | `icon-tracing` |
+| Monitoring | Alerting | `<<Container>>` | `icon-alerting` |
+| Monitoring | APM | `<<Container>>` | `icon-apm` |
+
+## Icon Registry
+
+Icons are inline SVG `<symbol>` elements with a 16x16 viewBox, rendered via `<use>` at `(x+W-22, y+4)` inside the component box. They use `currentColor` to inherit the category stroke color.
+
+### Category-Level Icons (active)
+
+Each category has a shared icon defined in `html-template.html` `<defs>`. All sub-types within a category use their category icon by default. Sub-type-specific icons can override these in the future.
+
+| Category | Symbol ID | Shape | Status |
+|---|---|---|---|
+| Frontend | `icon-frontend` | Monitor with stand | **active** |
+| Backend | `icon-backend` | Server rack (3 units) | **active** |
+| Data | `icon-data` | Database cylinder | **active** |
+| Infrastructure | `icon-infrastructure` | Cloud | **active** |
+| Messaging | `icon-messaging` | Envelope | **active** |
+| Security | `icon-security` | Shield with checkmark | **active** |
+| External | `icon-external` | Globe with meridians | **active** |
+| Monitoring | `icon-monitoring` | Line chart with axes | **active** |
+
+Usage pattern:
+```svg
+<use href="#icon-frontend" class="icon-use" x="448" y="154" width="16" height="16"/>
+```
+
+### Sub-type Icons (planned)
+
+When a sub-type icon is added, it overrides the category icon for that specific component. Until implemented, all sub-types use their category icon.
+
+| Sub-type | Icon | Status |
+|---|---|---|
+| SPA | `icon-spa` | planned |
+| Mobile App | `icon-mobile-app` | planned |
+| Static Site | `icon-static-site` | planned |
+| Micro-frontend | `icon-micro-frontend` | planned |
+| PWA | `icon-pwa` | planned |
+| Desktop App | `icon-desktop-app` | planned |
+| API Service | `icon-api-service` | planned |
+| Worker/Job | `icon-worker-job` | planned |
+| BFF | `icon-bff` | planned |
+| Microservice | `icon-microservice` | planned |
+| Serverless Function | `icon-serverless-function` | planned |
+| gRPC Service | `icon-grpc-service` | planned |
+| Relational DB | `icon-relational-db` | planned |
+| Document DB | `icon-document-db` | planned |
+| Key-Value Store | `icon-key-value-store` | planned |
+| Cache | `icon-cache` | planned |
+| Search Engine | `icon-search-engine` | planned |
+| Data Warehouse | `icon-data-warehouse` | planned |
+| Graph DB | `icon-graph-db` | planned |
+| Time-Series DB | `icon-time-series-db` | planned |
+| CDN | `icon-cdn` | planned |
+| Load Balancer | `icon-load-balancer` | planned |
+| DNS | `icon-dns` | planned |
+| Object Storage | `icon-object-storage` | planned |
+| Container Registry | `icon-container-registry` | planned |
+| Reverse Proxy | `icon-reverse-proxy` | planned |
+| Service Mesh | `icon-service-mesh` | planned |
+| Message Queue | `icon-message-queue` | planned |
+| Event Bus | `icon-event-bus` | planned |
+| Stream | `icon-stream` | planned |
+| Pub/Sub | `icon-pub-sub` | planned |
+| Webhook | `icon-webhook` | planned |
+| Auth Provider | `icon-auth-provider` | planned |
+| API Gateway | `icon-api-gateway` | planned |
+| WAF | `icon-waf` | planned |
+| Secret Manager | `icon-secret-manager` | planned |
+| Certificate Manager | `icon-certificate-manager` | planned |
+| Identity Provider | `icon-identity-provider` | planned |
+| Third-party API | `icon-third-party-api` | planned |
+| SaaS | `icon-saas` | planned |
+| Legacy System | `icon-legacy-system` | planned |
+| Partner Service | `icon-partner-service` | planned |
+| Payment Provider | `icon-payment-provider` | planned |
+| Logging | `icon-logging` | planned |
+| Metrics | `icon-metrics` | planned |
+| Tracing | `icon-tracing` | planned |
+| Alerting | `icon-alerting` | planned |
+| APM | `icon-apm` | planned |
+
+## Visual Elements
+
+### Component Box Pattern
+
+Use a rounded component box with semi-transparent fill and category stroke.
+
+```svg
+<g class="node backend">
+  <rect x="280" y="210" width="190" height="60" rx="6" />
+  <text class="c4-tag" x="294" y="226">&lt;&lt;Container&gt;&gt;</text>
+  <text class="node-title" x="294" y="243">API Service</text>
+  <text class="node-subtitle" x="294" y="257">Backend / HTTPS JSON</text>
+</g>
+```
+
+### Arrow Masking Technique
+
+Use an opaque background rectangle below the box content to visually hide arrows beneath components without breaking the component fill style.
+
+```svg
+<g class="node-mask-layer">
+  <rect x="280" y="210" width="190" height="60" rx="6" fill="#020617" />
+  <rect x="280" y="210" width="190" height="60" rx="6"
+        fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5" />
+</g>
+```
+
+### Security Group Boundary
+
+- Purpose: show auth, gateway, WAF, or identity zones
+- Stroke color: rose (`#fb7185`)
+- Pattern: `stroke-dasharray="4,4"`
+- Suggested label: `Security Boundary`
+
+```svg
+<rect x="700" y="140" width="220" height="180" rx="12"
+      fill="transparent" stroke="#fb7185" stroke-width="1.5"
+      stroke-dasharray="4,4" />
+```
+
+### Region Boundary
+
+- Purpose: group a deployment region, platform segment, or domain slice
+- Stroke color: amber (`#fbbf24`)
+- Pattern: `stroke-dasharray="8,4"`
+- Radius: `rx="12"`
+
+```svg
+<rect x="70" y="120" width="600" height="430" rx="12"
+      fill="transparent" stroke="#fbbf24" stroke-width="1.5"
+      stroke-dasharray="8,4" />
+```
+
+### Arrow Marker SVG Definition
+
+```svg
+<defs>
+  <marker id="arrowhead" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto">
+    <path d="M0,0 L8,4 L0,8 Z" fill="#cbd5e1" />
+  </marker>
+</defs>
+```
+
+### Arrow Z-order Rule
+
+Draw arrows early in the SVG so component boxes and masking layers paint over them. This keeps connectors readable in dense diagrams and avoids arrow overlap across component interiors.
+
+## Spacing Rules
+
+- Standard component height: `60px`
+- Minimum vertical gap between stacked components: `40px`
+- Inline connectors should route through gaps rather than through component interiors
+- Keep labels inside the top `28px` of the box and the subtype line inside the lower third
+- Place legends outside boundaries to prevent classification noise inside the diagram area
+
+## Layout Structure
+
+The canonical page composition is:
+
+1. Header: title, pulse dot, subtitle
+2. Main SVG diagram: embedded inside a rounded border card
+3. Summary cards: grid of 3 cards beneath the diagram
+4. Footer metadata: generator, scope, rendering notes, last-updated stamp
+
+## Present Tool Integration
+
+Compose architecture diagrams with the `present` tool by embedding the full HTML/SVG diagram in a markdown block and pairing it with metrics or cards blocks as needed.
+
+### `format: "html"`
+
+Use a `markdown` block with embedded `<div>`, inline SVG, and a `<style>` tag containing the full CSS. The `present` html format renders raw HTML in markdown blocks.
+
+### `format: "browser"`
+
+Use the same composition: a `markdown` block containing the full HTML structure. Summary content can also be added with `cards` and `metrics` blocks alongside the SVG diagram block.
+
+### Example `present` Call Structure
+
+```js
+present({
+  format: "html", // or "browser"
+  title: "System Architecture",
+  content: [
+    {
+      type: "metrics",
+      title: "Overview",
+      value: [
+        { label: "Services", value: "6" },
+        { label: "Data Stores", value: "2" },
+        { label: "External Systems", value: "3" }
+      ]
+    },
+    {
+      type: "markdown",
+      title: "Architecture Diagram",
+      value: "<div class='arch-diagram'>...(inline SVG)...</div><style>...(design system CSS)...</style>"
+    },
+    {
+      type: "cards",
+      title: "Summary",
+      value: [
+        { title: "Frontend", body: "React SPA..." },
+        { title: "Backend", body: "API + async workers..." },
+        { title: "Security", body: "Gateway + IdP..." }
+      ]
+    }
+  ]
+})
+```
+
+This design system is the single source of truth. The `c4-architecture` skill and `present` skill both reference this file. Update component types, colors, or layout rules here only.
+
+## Adding New Categories
+
+1. Add a new row to the Category Registry with the category name, colors, C4 mapping, and initial subtype set.
+2. Add the new sub-types to the Sub-type Registry with a C4 label and icon slot name.
+3. Add icon placeholders to the Icon Registry.
+4. Update [html-template.html](html-template.html) legend content so the new category appears in the rendered template.
+5. Update summary card accent colors in [html-template.html](html-template.html) if the new category needs a dedicated card treatment.
+
+## Template Pairing
+
+See [html-template.html](html-template.html) for the complete self-contained reference implementation of this design system.