create-yss-spec 2.1.5 → 2.1.6

package/template/.pi/skills/drawio/references/docs/design-system/themes.md

@@ -1,441 +0,0 @@
-# Themes
-
-The Draw.io Design System provides 7 built-in themes optimized for different use cases. Custom themes can be created using the JSON theme format.
-
----
-
-## Built-in Themes
-
-### Tech Blue (Default)
-
-Modern professional style for technical architecture diagrams.
-
-**Best for**: Software architecture, system design, DevOps, cloud infrastructure
-
-**Characteristics**:
-
-- Blue primary color with green/purple accents
-- Rounded corners (8px)
-- Clean sans-serif typography
-- Light background with colored nodes
-
-```yaml
-meta:
-  theme: tech-blue
-```
-
-| Element        | Color               |
-| -------------- | ------------------- |
-| Primary nodes  | Blue (#2563EB)      |
-| Database nodes | Green (#059669)     |
-| Decision nodes | Amber (#D97706)     |
-| Connectors     | Dark gray (#1E293B) |
-
----
-
-### Academic Color (Recommended for Academic)
-
-Colorful academic style with semantic colors, optimized for digital viewing and color printing.
-
-**Best for**: Research papers, academic publications, presentations, digital documents
-
-**Characteristics**:
-
-- Semantic colorful palette (blue, green, amber, purple)
-- No rounded corners (sharp edges)
-- Serif typography (Times New Roman)
-- High readability with visual distinction
-
-```yaml
-meta:
-  theme: academic-color
-```
-
-| Element  | Fill         | Stroke    |
-| -------- | ------------ | --------- |
-| service  | 💙 `#DBEAFE` | `#2563EB` |
-| database | 💚 `#D1FAE5` | `#059669` |
-| decision | 🟡 `#FEF3C7` | `#D97706` |
-| queue    | 💜 `#EDE9FE` | `#7C3AED` |
-| user     | 🩵 `#E0F2FE` | `#0284C7` |
-
-> **Recommended**: Use this theme for academic diagrams unless grayscale printing is required.
-
----
-
-### Academic (Grayscale)
-
-High-contrast black/white/gray for IEEE-style publications, optimized for grayscale print.
-
-**Best for**: Grayscale printing, strict IEEE format requirements
-
-**Characteristics**:
-
-- Pure black/white/gray palette
-- No rounded corners (sharp edges)
-- Serif typography (Times New Roman)
-- Maximum contrast for readability
-
-```yaml
-meta:
-  theme: academic
-```
-
-| Element    | Color                    |
-| ---------- | ------------------------ |
-| All nodes  | White fill, black stroke |
-| Labels     | Black (#1E1E1E)          |
-| Connectors | Black (#1E1E1E)          |
-
-> **Print-safe**: This theme remains readable when printed in grayscale.
-
----
-
-### Nature
-
-Green-focused palette for lifecycle, sustainability, and environmental diagrams.
-
-**Best for**: Environmental systems, lifecycle diagrams, sustainability reports, biology
-
-**Characteristics**:
-
-- Green/teal primary colors
-- Natural, organic feel
-- Light green tints
-- Rounded corners
-
-```yaml
-meta:
-  theme: nature
-```
-
-| Element        | Color                 |
-| -------------- | --------------------- |
-| Primary nodes  | Green (#059669)       |
-| Database nodes | Lime (#84CC16)        |
-| Decision nodes | Yellow (#CA8A04)      |
-| Background     | White with green tint |
-
----
-
-### Dark Mode
-
-Dark background with light text for presentations and terminal-style diagrams.
-
-**Best for**: Presentations, slides, terminal/console themes, night mode
-
-**Characteristics**:
-
-- Dark slate background (#0F172A)
-- Light text and bright accent colors
-- High contrast for projection
-- Rounded corners
-
-```yaml
-meta:
-  theme: dark
-```
-
-| Element        | Color                |
-| -------------- | -------------------- |
-| Background     | Dark slate (#0F172A) |
-| Primary nodes  | Blue (#60A5FA)       |
-| Database nodes | Emerald (#34D399)    |
-| Text           | Light gray (#F1F5F9) |
-
----
-
-### Architecture Dark
-
-Slate-950 architecture palette with role-based semantic colors, adapted from
-architecture-diagram-generator (MIT, Cocoon AI). Pair with
-`references/docs/architecture-diagrams.md` for the full design language
-(role mapping, boundary conventions, legend rules).
-
-**Best for**: System/software architecture, microservice maps, cloud service diagrams
-
-**Characteristics**:
-
-- Near-black slate background (#020617)
-- Role-coded strokes: cyan frontend, emerald backend, violet database, amber cloud, orange message bus, rose security
-- Dashed amber region boundaries, dashed rose security groups (via module style overrides)
-- Muted slate connectors so role colors stay dominant
-
-```yaml
-meta:
-  theme: arch-dark
-```
-
-| Element                       | Color                    |
-| ----------------------------- | ------------------------ |
-| Background                    | Slate 950 (#020617)      |
-| Frontend (`user`)             | Cyan stroke (#22D3EE)    |
-| Backend (`service`/`process`) | Emerald stroke (#34D399) |
-| Database nodes                | Violet stroke (#A78BFA)  |
-| Cloud nodes                   | Amber stroke (#FBBF24)   |
-| Queue / bus nodes             | Orange stroke (#FB923C)  |
-| Text                          | Light gray (#F1F5F9)     |
-
----
-
-### High Contrast
-
-Maximum contrast for accessibility, screen readers, and print at any size.
-
-**Best for**: Accessibility-focused documents, high-DPI printing, presentations in bright rooms
-
-**Characteristics**:
-
-- Pure black/white with maximum contrast
-- Heavy stroke weights for visibility
-- Large, clear typography
-- No color dependencies
-
-```yaml
-meta:
-  theme: high-contrast
-```
-
-| Element    | Color                                        |
-| ---------- | -------------------------------------------- |
-| All nodes  | White fill (#FFFFFF), black stroke (#000000) |
-| Labels     | Black (#000000)                              |
-| Connectors | Black (#000000), 2px minimum                 |
-
----
-
-## Theme Selection
-
-### In Specification
-
-```yaml
-meta:
-  theme: tech-blue # or: academic, academic-color, nature, dark, arch-dark, high-contrast
-  layout: horizontal
-```
-
-### Theme x Palette Composition
-
-Theme and palette compose orthogonally. Theme keeps typography, spacing, shapes, connector line styles, modules, and canvas; `meta.palette` replaces only semantic/category colors.
-
-```yaml
-meta:
-  theme: academic
-  palette: okabe-ito
-```
-
-No `meta.palette` means the theme renders exactly as before. Built-in palette JSON lives under `assets/palettes/`; metadata, sources, and generated previews are indexed under `references/examples/palettes/`.
-
-To add a palette without changing code, place a schema-valid `<name>.json` in `~/.drawio-skill/palettes/`. A user file overrides a bundled palette of the same name with an info diagnostic. Explicit invalid selections fail instead of falling back.
-
-### Per-Node Override
-
-Individual nodes can override theme defaults:
-
-```yaml
-nodes:
-  - id: critical
-    label: Critical Service
-    style:
-      fillColor: "#FEE2E2" # Override with error color
-      strokeColor: "#DC2626"
-```
-
----
-
-## Custom Themes
-
-Create custom themes by providing a JSON file following the theme schema.
-
-### Minimal Custom Theme
-
-```json
-{
-  "$schema": "./theme.schema.json",
-  "name": "my-theme",
-  "displayName": "My Custom Theme",
-  "description": "Custom theme for my organization",
-  "colors": {
-    "primary": "#6366F1",
-    "primaryLight": "#E0E7FF",
-    "secondary": "#EC4899",
-    "secondaryLight": "#FCE7F3",
-    "accent": "#14B8A6",
-    "accentLight": "#CCFBF1",
-    "background": "#FFFFFF",
-    "surface": "#F8FAFC",
-    "surfaceAlt": "#F1F5F9",
-    "text": "#1E293B",
-    "textMuted": "#64748B",
-    "textInverse": "#FFFFFF",
-    "border": "#E2E8F0",
-    "borderStrong": "#CBD5E1",
-    "success": "#22C55E",
-    "successLight": "#DCFCE7",
-    "warning": "#F59E0B",
-    "warningLight": "#FEF3C7",
-    "error": "#EF4444",
-    "errorLight": "#FEE2E2",
-    "info": "#3B82F6",
-    "infoLight": "#DBEAFE"
-  },
-  "spacing": {
-    "unit": 8,
-    "scale": {
-      "xs": 4,
-      "sm": 8,
-      "md": 16,
-      "lg": 24,
-      "xl": 32,
-      "2xl": 40,
-      "3xl": 48,
-      "4xl": 64,
-      "5xl": 80
-    }
-  },
-  "typography": {
-    "fontFamily": {
-      "primary": "Inter, sans-serif",
-      "monospace": "Fira Code, monospace",
-      "formula": "STIX Two Math, serif"
-    },
-    "fontSize": {
-      "xs": 10,
-      "sm": 11,
-      "md": 13,
-      "lg": 14,
-      "xl": 16,
-      "2xl": 20
-    },
-    "fontWeight": {
-      "normal": 400,
-      "medium": 500,
-      "semibold": 600,
-      "bold": 700
-    }
-  },
-  "borderRadius": {
-    "none": 0,
-    "sm": 4,
-    "md": 8,
-    "lg": 12,
-    "full": 9999
-  },
-  "shadows": {
-    "none": "none",
-    "sm": "0 1px 2px rgba(0,0,0,0.05)",
-    "md": "0 4px 6px rgba(0,0,0,0.07)",
-    "lg": "0 10px 15px rgba(0,0,0,0.1)"
-  },
-  "node": {
-    "default": {
-      "fillColor": "#E0E7FF",
-      "strokeColor": "#6366F1",
-      "strokeWidth": 1.5,
-      "fontColor": "#1E293B",
-      "fontSize": 13,
-      "fontFamily": "Inter, sans-serif",
-      "rounded": 8
-    }
-  },
-  "connector": {
-    "primary": {
-      "strokeColor": "#1E293B",
-      "strokeWidth": 2,
-      "dashed": false,
-      "dashPattern": null,
-      "endArrow": "block",
-      "endFill": true
-    }
-  },
-  "module": {
-    "fillColor": "#F8FAFC",
-    "strokeColor": "#E2E8F0",
-    "strokeWidth": 1,
-    "rounded": 12,
-    "padding": 24,
-    "labelFontSize": 14,
-    "labelFontWeight": 600,
-    "labelFontColor": "#1E293B"
-  },
-  "canvas": {
-    "background": "#FFFFFF",
-    "gridSize": 8,
-    "gridColor": "#E2E8F0"
-  }
-}
-```
-
-### Using Custom Theme
-
-Place the JSON file in `themes/` directory and reference by name:
-
-```yaml
-meta:
-  theme: my-theme # Loads themes/my-theme.json
-```
-
----
-
-## Theme File Structure
-
-```
-skills/drawio/themes/
-├── theme.schema.json      # JSON Schema for validation
-├── tech-blue.json         # Default theme
-├── academic-color.json    # Academic colorful (recommended)
-├── academic.json          # Academic grayscale
-├── nature.json            # Green/environmental theme
-├── dark.json              # Dark mode theme
-└── [custom].json          # User custom themes
-```
-
----
-
-## Validation
-
-Themes are validated against `theme.schema.json`. Required fields:
-
-- `name`: Machine identifier (lowercase, hyphens)
-- `displayName`: Human-readable name
-- `colors`: Color token definitions
-- `spacing`: Spacing system
-- `typography`: Font definitions
-- `borderRadius`: Corner radius tokens
-- `node`: Node styling (at least `default`)
-- `connector`: Connector styling (at least `primary`)
-- `module`: Module/container styling
-- `canvas`: Canvas settings
-
----
-
-## Consumed Tokens
-
-The renderer consumes these theme tokens directly; others are advisory for now:
-
-| Token                                                                                                              | Effect                                                                                                                                                  |
-| ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `colors.*`                                                                                                         | `$token` references in specs and default fallbacks                                                                                                      |
-| `node.<type>.fillColor/strokeColor/strokeWidth/fontColor/fontSize`                                                 | Node styles (`<type>` falls back to `node.default`)                                                                                                     |
-| `node.<type>.rounded` (incl. `default`)                                                                            | Corner radius: `0` emits square `rounded=0`, `>0` overrides the built-in arcSize. Stadium shapes (`terminal`, arcSize>=50) keep their semantic rounding |
-| `typography.fontFamily.primary/cjk/formula`                                                                        | Font fallback layer: `meta.font.<bucket>` > `node.style.fontFamily` > theme bucket > built-in policy (academic-paper CJK falls back to SimSun)          |
-| `connector.<type>.*`                                                                                               | Edge stroke, arrows, dash patterns                                                                                                                      |
-| `module.fillColor/strokeColor/strokeWidth/rounded/labelFontSize/labelFontWeight/labelFontColor/dashed/dashPattern` | Module containers; `rounded: 0` emits square corners                                                                                                    |
-| `module.padding`                                                                                                   | Layout padding inside module containers                                                                                                                 |
-| `canvas.background`, `canvas.gridSize`                                                                             | Page background and layout snapping grid                                                                                                                |
-
-Not yet consumed: `spacing.*`, `borderRadius.*`, `shadows.*`, `typography.fontSize/fontWeight`, `node.*.fontFamily` (use `typography.fontFamily` instead), `canvas.gridColor`.
-
----
-
-## Theme Switching
-
-To switch themes on an existing diagram:
-
-1. Update the `theme` field in specification
-2. Re-render the diagram
-3. All non-overridden styles will update to new theme
-
-> **Note**: Explicitly defined colors in nodes/edges will NOT change when switching themes. Only theme-referenced values (`$primary`, `$text`, etc.) are affected.
->
-> A selected palette is a second color layer: semantic nodes keep the new theme's typography, shapes, and line styles while continuing to use the palette colors.

package/template/.pi/skills/drawio/references/docs/design-system/tokens.md

@@ -1,232 +0,0 @@
-# Design Tokens
-
-Design tokens are the foundational building blocks of the Draw.io Design System. They define consistent values for colors, spacing, typography, and other visual properties.
-
-## Overview
-
-The design token system follows a hierarchical structure:
-
-```
-Global Tokens → Semantic Tokens → Component Tokens
-```
-
-- **Global Tokens**: Raw values (colors, sizes)
-- **Semantic Tokens**: Purpose-based references (primary, text, border)
-- **Component Tokens**: Applied to specific elements (node.fillColor, connector.strokeWidth)
-
----
-
-## Color Tokens
-
-### Core Palette
-
-| Token          | Description      | Tech Blue | Academic  | Nature    | Dark      |
-| -------------- | ---------------- | --------- | --------- | --------- | --------- |
-| `primary`      | Main brand color | `#2563EB` | `#1E1E1E` | `#059669` | `#60A5FA` |
-| `primaryLight` | Light variant    | `#DBEAFE` | `#F5F5F5` | `#D1FAE5` | `#1E3A5F` |
-| `secondary`    | Supporting color | `#059669` | `#4B4B4B` | `#84CC16` | `#34D399` |
-| `accent`       | Highlight color  | `#7C3AED` | `#6B6B6B` | `#0D9488` | `#A78BFA` |
-
-### Semantic Colors
-
-| Token          | Purpose            | Usage              |
-| -------------- | ------------------ | ------------------ |
-| `background`   | Canvas background  | Diagram canvas     |
-| `surface`      | Container fill     | Modules, groups    |
-| `text`         | Primary text       | Node labels        |
-| `textMuted`    | Secondary text     | Edge labels, hints |
-| `border`       | Default borders    | Node strokes       |
-| `borderStrong` | Emphasized borders | Active elements    |
-
-### Status Colors
-
-| Token     | Meaning                    |
-| --------- | -------------------------- |
-| `success` | Positive state, completion |
-| `warning` | Caution, attention needed  |
-| `error`   | Error, failure state       |
-| `info`    | Informational content      |
-
----
-
-## Spacing Tokens
-
-Based on an **8px grid system** for consistent alignment.
-
-### Scale
-
-| Token | Value | Usage                      |
-| ----- | ----- | -------------------------- |
-| `xs`  | 4px   | Minimal gaps, icon padding |
-| `sm`  | 8px   | Tight spacing              |
-| `md`  | 16px  | Standard spacing           |
-| `lg`  | 24px  | Section gaps               |
-| `xl`  | 32px  | **Node minimum margin**    |
-| `2xl` | 40px  | Large gaps                 |
-| `3xl` | 48px  | Spacious layouts           |
-| `4xl` | 64px  | Module padding             |
-| `5xl` | 80px  | Major sections             |
-
-### Application Rules
-
-1. **Node positions**: Must snap to 8px grid
-2. **Node margins**: Minimum 32px between nodes
-3. **Container padding**: 16px or 24px
-4. **Canvas padding**: 32px from edge
-
----
-
-## Typography Tokens
-
-### Font Families
-
-| Token       | Stack                                | Usage               |
-| ----------- | ------------------------------------ | ------------------- |
-| `primary`   | Inter, Roboto, system-ui, sans-serif | Node labels, titles |
-| `cjk`       | Times New Roman, SimSun              | CJK-bearing labels  |
-| `monospace` | JetBrains Mono, Fira Code, Consolas  | Code, technical IDs |
-| `formula`   | Latin Modern, STIX Two Math, serif   | LaTeX formulas      |
-
-The `cjk` stack is a per-glyph fallback list: Latin glyphs and digits resolve from Times New Roman, CJK glyphs fall through to SimSun — the standard thesis convention inside one label. When a theme defines no `cjk` stack, the built-in policy applies `Times New Roman,SimSun` to every CJK-bearing surface in all profiles.
-
-### Font Sizes
-
-| Token | Size | Usage                              |
-| ----- | ---- | ---------------------------------- |
-| `xs`  | 12px | Absolute floor (`FONT_SIZE_FLOOR`) |
-| `sm`  | 14px | Dense replicate labels             |
-| `md`  | 16px | Captions, legends, text nodes      |
-| `lg`  | 18px | Edge labels                        |
-| `xl`  | 20px | **Default node label**             |
-| `2xl` | 22px | Module titles (bold)               |
-
-These map to the converter font ladder (`FONT_LADDER`: module title 22 / node 20 / edge label 18 / text 16, floor 12). Labels without explicit `style.fontSize` get the ladder automatically and their boxes grow to fit; explicit-bounds boxes (replicate flow) shrink each class uniformly, never below the floor.
-
-### Font Weights
-
-| Token      | Value | Usage            |
-| ---------- | ----- | ---------------- |
-| `normal`   | 400   | Body text        |
-| `medium`   | 500   | Slight emphasis  |
-| `semibold` | 600   | Labels, headings |
-| `bold`     | 700   | Strong emphasis  |
-
----
-
-## Border Radius Tokens
-
-| Token  | Value  | Usage                          |
-| ------ | ------ | ------------------------------ |
-| `none` | 0px    | Sharp corners (Academic theme) |
-| `sm`   | 4px    | Subtle rounding                |
-| `md`   | 8px    | **Default node corners**       |
-| `lg`   | 12px   | Modules, containers            |
-| `full` | 9999px | Circles, pills                 |
-
----
-
-## Node Size Presets
-
-Standard node dimensions (width × height):
-
-| Size     | Dimensions   | Usage                |
-| -------- | ------------ | -------------------- |
-| `small`  | 80 × 40 px   | Compact nodes, icons |
-| `medium` | 120 × 60 px  | **Default size**     |
-| `large`  | 160 × 80 px  | Emphasized nodes     |
-| `xl`     | 200 × 100 px | Major components     |
-
-Presets are minimums, not fixed sizes: once a node carries a plain-text label, the box grows (grid-snapped to 8px) so the label fits its font size — labels must never paint outside the shape. Icon-labeled nodes (label renders below the shape), size-coded shapes (operators, tensors, formulas), and math-bearing labels keep the raw preset.
-
----
-
-## Text & Label Styling
-
-These rules apply to standalone text boxes, callouts, captions, legends, and annotation labels — the elements usually hand-placed during `edit`, `replicate`, and academic-overlay work, where there is no automatic styling to fall back on.
-
-### Transparent by default (no white box)
-
-Text and labels use `fillColor=none` and `labelBackgroundColor=none`.
-
-A white fill or white label background paints an opaque rectangle around the text. On a colored or busy figure that box occludes connectors and neighbors, fights the palette, and makes the diagram look pasted together — readers want the text, not its container. draw.io's default `labelBackgroundColor` is already `none`; the failure mode is _adding_ a white one for perceived legibility.
-
-For plain `type: text` nodes this is enforced, not advisory: the converter always emits `fillColor=none;strokeColor=none;labelBackgroundColor=none`, ignores explicit fills on text nodes, and `validateTextNodeStyles` warns about the override. Replication color extraction must never assign the canvas/background color to a text box fill.
-
-If text genuinely needs separation from a noisy background, use a node type that owns a surface:
-
-- First try cheaper fixes: a darker/bolder `fontColor`, a thin text stroke, or moving the label into whitespace.
-- Then use a `formula` node (white surface with border, by design) or an ordinary shape node with a restrained tint or semi-transparent backing (for example `fillColor=#F8FAFC;opacity=70`) — never a hard `#FFFFFF` block behind plain text.
-
-### Vertical CJK labels (one character per line)
-
-Vertical Chinese/Japanese/Korean labels beside vertical arrows are written one character per line with explicit newlines, e.g. `label: "可\n视\n化\n数\n据"`.
-
-- The converter turns label newlines into `<br>` so they survive XML attribute-value normalization (a literal `\n` in an attribute is folded into a space when the file is reopened, which is where random re-wrapping like `能耗指 标计算` comes from).
-- Do **not** use `horizontal=0` for CJK vertical text — it rotates the glyphs 90° instead of stacking them.
-- Size the box to one glyph column: `width ≈ fontSize + 12–16`, `height ≈ chars × fontSize × 1.4 + padding`; the 48px minimum-width floor does not apply to these narrow columns.
-- Never rely on a narrow box plus `whiteSpace=wrap` to fake vertical text — wrap points drift and clip.
-
-### Size to content, not to the container
-
-A text/label box should be just wider than its longest line (plus small horizontal padding), never stretched to match a parent container or a source-image region.
-
-An oversized text box overlaps neighbors and creates a large invisible hit area, so selecting, moving, and transforming the element — and the shapes near it — becomes awkward. A content-fitted box stays an independent, draggable object.
-
-Width estimate when you must set `bounds`/`size` by hand:
-
-- Per-line width ≈ Σ glyph widths, with Latin/ASCII ≈ `0.6 × fontSize` and CJK full-width ≈ `1.05 × fontSize`.
-- `width ≈ ceil(longest line) + 2 × horizontalPadding` (padding ≈ 8–12px), with a sensible minimum (~48px).
-- For multi-line text, size to the longest line; `height ≈ lines × fontSize × 1.4 + 2 × verticalPadding`.
-
-Prefer letting the converter size text automatically (omit `size`/`bounds` for generated text nodes); reserve explicit `bounds` for high-fidelity replication where exact coordinates matter, and still keep the box just wider than the text.
-
----
-
-## Shadow Tokens
-
-For container emphasis (optional, not all themes use shadows):
-
-| Token  | Value                 | Usage             |
-| ------ | --------------------- | ----------------- |
-| `none` | none                  | Flat design       |
-| `sm`   | 0 1px 2px rgba(...)   | Subtle elevation  |
-| `md`   | 0 4px 6px rgba(...)   | Cards, panels     |
-| `lg`   | 0 10px 15px rgba(...) | Floating elements |
-
----
-
-## Usage in Specifications
-
-Reference tokens in YAML specifications using the `$` prefix:
-
-```yaml
-meta:
-  theme: tech-blue
-
-nodes:
-  - id: api
-    label: API Gateway
-    style:
-      fillColor: $primaryLight # Resolves to #DBEAFE
-      strokeColor: $primary # Resolves to #2563EB
-```
-
----
-
-## Token Resolution
-
-When generating draw.io XML, tokens are resolved in this order:
-
-1. **Explicit style** in node/edge definition
-2. **Semantic type** defaults (e.g., database → cylinder shape)
-3. **Theme defaults** (e.g., node.default.fillColor)
-4. **System defaults** (hardcoded fallbacks)
-
-Example resolution:
-
-```
-Node "User DB" with type: database
-→ Check explicit style: none
-→ Check semantic type: database → cylinder shape, theme.node.database colors
-→ Apply: fillColor=#D1FAE5, strokeColor=#059669, shape=cylinder
-```