@vpxa/aikit 0.1.74 → 0.1.76

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

@@ -1,337 +0,0 @@
-# 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.