npm - create-yss-spec - Versions diffs - 2.1.5 → 2.1.7 - Mend

create-yss-spec 2.1.5 → 2.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3444) hide show

package/template/.hermes/skills/drawio/references/docs/design-system/specification.md DELETED Viewed

@@ -1,754 +0,0 @@
-# Specification Format
-The Design System uses a YAML-based specification format for defining diagrams. This format supersedes the [legacy A-H format](../ah-format.md) (now deprecated) with structured, type-safe definitions.
----
-## Overview
-The specification format provides:
-- **Theme integration**: Direct theme selection
-- **Workflow profiles**: Academic-paper and engineering-review validation modes
-- **Semantic types**: Auto-shape mapping
-- **Typed connectors**: Visual hierarchy
-- **Grid alignment**: 8px grid compliance
-- **Text fidelity**: Explicit bounds for standalone text/formulas and offsets for edge labels
-- **Schema validation**: Structured validation
----
-## Basic Structure
-```yaml
-meta:
-  profile: default
-  theme: tech-blue
-  source: generated
-  layout: horizontal
-  canvas: auto
-nodes:
-  - id: n1
-    label: Node Label
-    type: service
-edges:
-  - from: n1
-    to: n2
-    type: primary
-modules: # optional
-  - id: m1
-    label: Module Name
-```
----
-## Meta Section
-Diagram-level configuration.
-```yaml
-meta:
-  # Workflow profile
-  profile: default # default | academic-paper | engineering-review
-  # Academic intent (required when profile=academic-paper)
-  figureType: architecture # architecture | roadmap | workflow
-  # How this spec was produced
-  source: generated # generated | replicated | edited
-  # Theme selection (required)
-  theme: tech-blue # tech-blue | academic | academic-color | nature | dark | high-contrast | custom-name
-  # Optional category-color palette layered over the theme
-  palette: okabe-ito
-  # Layout direction
-  layout: horizontal # horizontal | vertical | hierarchical | star | mesh | tiered
-  # Canvas sizing
-  canvas: auto # auto | WIDTHxHEIGHT, e.g. 800x600 or 1200x800
-  # Connector routing
-  routing: orthogonal # orthogonal | rounded
-  # Grid settings (optional, uses theme defaults)
-  grid:
-    size: 8
-    snap: true
-  # Diagram metadata
-  title: "System Architecture"
-  description: "Overview of microservices"
-  legend: "Optional legend summary for paper-facing diagrams"
-  # Optional replicate metadata
-  replication:
-    colorMode: preserve-original # preserve-original | theme-first
-    background: "#FFF7ED"
-    palette:
-      - hex: "#FDBA74"
-        role: warm node fill
-        appliesTo: nodes
-        confidence: high
-      - hex: "#7C2D12"
-        role: connector stroke
-        appliesTo: edges
-        confidence: medium
-    confidenceNotes:
-      - "Arrowheads were anti-aliased in the source; connector color was normalized to the nearest flat brown."
-```
-### Theme Options
-| Theme            | Description                                  |
-| ---------------- | -------------------------------------------- |
-| `tech-blue`      | Modern professional (default)                |
-| `academic`       | IEEE/print optimized                         |
-| `academic-color` | Color paper or research poster               |
-| `nature`         | Green/environmental                          |
-| `dark`           | Dark mode presentations                      |
-| `high-contrast`  | Maximum contrast for accessibility and print |
-### Palette Options
-`meta.palette` is optional and independent from `meta.theme`. It replaces semantic/category colors while preserving theme typography, spacing, shapes, connector line styles, modules, and canvas. Omitting it preserves existing theme output. Content-neutral `text` and `formula` nodes never join palette mapping: they always inherit theme styling and stay out of palette usage.
-Bundled names and safety metadata are indexed in `references/examples/palettes/README.md`. User palettes load from `~/.drawio-skill/palettes/` and may override a bundled name. Explicit unknown, malformed, or invalid palettes are hard errors and list available names.
-```yaml
-meta:
-  theme: academic
-  palette: ieee-bw
-  print: { target: ieee-single }
-```
-`--validate` checks actual rendered palette usage for grayscale separation, boundary contrast, category capacity, academic CVD notices, and print safety. Under `--strict`, a grayscale-unsafe palette with `cn-thesis`, `ieee-single`, or `ieee-double` fails and suggests `ieee-bw` or `tol-high-contrast`.
-### Font Policy
-Use `meta.font` when you need deterministic diagram typography.
-```yaml
-meta:
-  font:
-    primary: Times New Roman
-    cjk: Times New Roman,SimSun
-    formula: Times New Roman
-```
-- Presence of `meta.font` enables force mode automatically.
-- `primary` applies to Latin text, `cjk` applies to CJK text, and `formula` applies to formula surfaces.
-- Comma-separated fallback stacks are supported; `Times New Roman,SimSun` renders Latin glyphs in Times New Roman and CJK glyphs in SimSun inside one label.
-- When present, `meta.font` overrides lower-priority font-family settings on covered text surfaces.
-- When absent, every profile uses `Times New Roman` for Latin/formula text and the `Times New Roman,SimSun` stack for CJK-bearing text; the academic themes carry the same stack in `typography.fontFamily.cjk`.
-- Font sizes follow the converter ladder when `style.fontSize` is absent: module title 22, node 20, edge label 18, text 16, floor 12. Explicit-bounds boxes shrink each class uniformly so labels stay inside their boxes; `meta.print` (`cn-thesis` 440pt/9pt, `ieee-single` 252pt/8pt, `ieee-double` 516pt/8pt, or custom `widthPt`/`minPt`) adds the print-readability warning.
-### Profile Options
-| Profile              | Description                                          |
-| -------------------- | ---------------------------------------------------- |
-| `default`            | Standard diagram workflow                            |
-| `academic-paper`     | Enables paper-facing validation and export checklist |
-| `engineering-review` | Enables stricter routing and readability review      |
-### Canvas Sizing
-Use `meta.canvas` to control the draw.io page size:
-- `auto` or an omitted field preserves content-derived sizing.
-- `WIDTHxHEIGHT` sets an explicit minimum page size, for example `1200x800`.
-- Width and height must be positive integers.
-- The renderer expands beyond the explicit canvas when content exceeds it, so native shapes are not hidden or cropped.
-For reference-image replication, set `meta.canvas` to the source image dimensions when top-left `bounds`, connector waypoints, or panel regions are copied from the reference coordinate system.
-### Academic Figure Type Options
-Use `meta.figureType` whenever `meta.profile = academic-paper`.
-| Figure Type    | Use When                                                                  | Avoid                                                                      |
-| -------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `architecture` | You are explaining modules, tiers, responsibilities, and interactions     | Turning runtime structure into a step-by-step process flow                 |
-| `roadmap`      | You are explaining milestones, study phases, or delivery progression      | Mixing detailed runtime dependencies into a milestone timeline             |
-| `workflow`     | You are explaining ordered execution, branching, loops, or fallback logic | Collapsing system structure and process control into one overloaded figure |
-### Source Options
-| Source       | Description                                            |
-| ------------ | ------------------------------------------------------ |
-| `generated`  | New diagram created from text/spec                     |
-| `replicated` | Structured redraw from an uploaded image or screenshot |
-| `edited`     | Existing diagram/spec that has been revised            |
-### Layout Options
-| Layout         | Description                                                                                                           | Best For                |
-| -------------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| `horizontal`   | Left-to-right flow                                                                                                    | Process flows           |
-| `vertical`     | Top-to-bottom flow                                                                                                    | Hierarchy               |
-| `hierarchical` | Edge-aware layered auto-layout (vendored elkjs) via the CLI when no node has explicit geometry; legacy grid otherwise | Workflows, dependencies |
-| `star`         | Hub-and-spoke ring around a central device                                                                            | Small hub topologies    |
-| `mesh`         | Ring placement with mid waypoints                                                                                     | Full-mesh links         |
-| `tiered`       | North-South network rows from `network.tier`, `network.role`, or node type (external on top, endpoints at the bottom) | Network topologies      |
-`hierarchical` auto-layout fills node bounds and orthogonal edge waypoints; it degrades to the legacy grid with a warning if the vendored engine is unavailable. Any explicit `bounds`/`position` in the spec disables the auto pass (the author owns the geometry).
----
-## Nodes Section
-Define diagram nodes/elements.
-### Basic Node
-```yaml
-nodes:
-  - id: api
-    label: API Gateway
-```
-### Full Node Definition
-```yaml
-nodes:
-  - id: api
-    label: API Gateway
-    type: service # Semantic type for auto-shape
-    module: frontend # Parent module ID
-    size: medium # small | medium | large | xl
-    icon: aws.api-gateway # Cloud provider icon
-    position: # Optional manual position (center point)
-      x: 100
-      y: 200
-    bounds: # Optional explicit bounds (top-left), preferred for high-fidelity text replication
-      x: 64
-      y: 180
-      width: 160
-      height: 48
-    style: # Style overrides
-      fillColor: "#DBEAFE"
-      strokeColor: "#2563EB"
-      align: center
-      verticalAlign: middle
-```
-### Semantic Types
-| Type       | Shape               | Auto-detect Keywords                         |
-| ---------- | ------------------- | -------------------------------------------- |
-| `service`  | Rounded rectangle   | api, service, component                      |
-| `database` | Cylinder            | db, database, sql, storage                   |
-| `decision` | Diamond             | if, decision, condition                      |
-| `terminal` | Stadium             | start, end, begin, finish                    |
-| `queue`    | Parallelogram       | queue, buffer, kafka                         |
-| `user`     | Ellipse             | user, actor, client                          |
-| `document` | Document            | doc, file, report                            |
-| `formula`  | Rectangle           | $$, equation, formula                        |
-| `text`     | Standalone text box | captions, callouts, legends, annotation text |
-| `cloud`    | Cloud               | cloud, internet, external                    |
-| `process`  | Rounded rectangle   | process, transform, pipeline                 |
-> **Note**: Extended types for deep learning (`conv`, `pool`, `attention`, `embed`, `norm`, `gate`, `tensor3d`, etc.) are also supported by the converter.
-> **Text styling**: Standalone `text`, callouts, captions, and legends default to a transparent fill with no label background, and are sized just wider than their content rather than stretched to a container. See `tokens.md` § Text & Label Styling.
-### Position vs Bounds
-Use `position` for ordinary generated nodes where a center point is enough. It means the center of the rendered node, and the converter derives width/height from `size` or the semantic type. Text nodes without an explicit `size` are fitted to their label content so the box stays just wider than the text.
-Use `bounds` for high-fidelity replication. It means exact top-left geometry:
-```yaml
-nodes:
-  - id: title
-    label: "World Model"
-    type: text
-    bounds:
-      x: 24
-      y: 32
-      width: 180
-      height: 36
-    style:
-      fontFamily: "Times New Roman, serif"
-      fontSize: 16
-      italic: true
-      align: left
-      verticalAlign: top
-      spacingLeft: 4
-      spacingTop: 2
-```
-When both fields are present, `bounds` is the fidelity-preserving geometry and should be treated as authoritative.
-### Size Presets
-| Size     | Dimensions   |
-| -------- | ------------ |
-| `small`  | 80 × 40 px   |
-| `medium` | 120 × 60 px  |
-| `large`  | 160 × 80 px  |
-| `xl`     | 200 × 100 px |
----
-## Edges Section
-Define connections between nodes.
-### Basic Edge
-```yaml
-edges:
-  - from: api
-    to: database
-```
-### Full Edge Definition
-```yaml
-edges:
-  - from: api
-    to: database
-    type: data # Connector semantic type
-    label: Query # Edge label
-    labelPosition: center # start | center | end
-    labelOffset: # Optional x/y offset from the edge label anchor
-      x: 0
-      y: -16
-    bidirectional: false # Two-way connection
-    style: # Style overrides
-      strokeColor: "#1E293B"
-      strokeWidth: 2
-      dashed: true
-    waypoints: # Optional manual routing
-      - x: 420
-        y: 180
-```
-### Connector Types
-| Type            | Line        | Arrow    | Usage         |
-| --------------- | ----------- | -------- | ------------- |
-| `primary`       | Solid 2px   | Open (V) | Main flow     |
-| `data`          | Dashed 2px  | Open (V) | Data/async    |
-| `optional`      | Dotted 1px  | Open (V) | Weak relation |
-| `dependency`    | Solid 1px   | Diamond  | Dependencies  |
-| `bidirectional` | Solid 1.5px | None     | Two-way       |
-### Input Adapter Notes
-- Mermaid, CSV, Terraform, Kubernetes, Compose, SQL DDL, OpenAPI, GitHub Actions, and GitLab CI are supported as CLI input formats.
-- They are normalized into this YAML structure before rendering.
-- YAML remains the canonical intermediate representation.
-- Importers that need stable external identity or declared/live comparison first use the versioned [Canonical Graph Projection](../canonical-graph-projection.md), then project into this YAML structure.
-### Edge Label Placement
-`labelPosition` controls where the label anchor sits along the connector. `labelOffset` controls where the label box sits relative to that anchor.
-Use explicit offsets for replicated labels such as `h(t)`, `z(t)`, or `s(t)` that must not overlap the line:
-```yaml
-edges:
-  - from: hidden
-    to: state
-    label: "s(t)"
-    labelPosition: center
-    labelOffset:
-      x: 0
-      y: -18
-```
-Default rule of thumb: horizontal connectors use `y: -12` to `-20` to lift labels above the line; vertical connectors use `x: 12` to `20` to move labels to the side. Flip the sign when the source puts the label on the opposite side.
-### Text Fidelity for Replication
-When redrawing an image, extract text separately from structure:
-- shape labels: keep inside the shape unless the source text floats outside its object;
-- edge labels: record `labelPosition` and `labelOffset` so they do not sit on the connector;
-- standalone text: use `type: text` with explicit `bounds`;
-- formula annotations: use `type: formula` or `type: text` with official math delimiters and explicit `bounds`;
-- style: preserve font family, font size, italic/bold state, alignment, vertical alignment, and spacing when visible.
----
-## Modules Section
-Group nodes into containers/swimlanes.
-```yaml
-modules:
-  - id: frontend
-    label: Frontend Layer
-    color: $primary # Theme color reference
-  - id: backend
-    label: Backend Services
-    color: $secondary
-  - id: data
-    label: Data Layer
-    color: $accent
-```
-### Module Properties
-| Property | Type   | Description         |
-| -------- | ------ | ------------------- |
-| `id`     | string | Unique identifier   |
-| `label`  | string | Display name        |
-| `color`  | string | Fill color or token |
-| `style`  | object | Style overrides     |
----
-## Style Overrides
-Override theme defaults for individual elements.
-### Node Style Override
-```yaml
-nodes:
-  - id: critical
-    label: Critical Service
-    style:
-      fillColor: "#FEE2E2"
-      strokeColor: "#DC2626"
-      strokeWidth: 2
-      fontColor: "#991B1B"
-      fontSize: 14
-      fontWeight: 600
-```
-Text and formula nodes can also use typography and padding-style fields:
-```yaml
-nodes:
-  - id: formula-note
-    label: "$$z(t)=g(h(t))$$"
-    type: formula
-    bounds: { x: 520, y: 96, width: 220, height: 56 }
-    style:
-      fontFamily: "Times New Roman, serif"
-      fontSize: 15
-      italic: true
-      align: center
-      verticalAlign: middle
-      spacingLeft: 6
-      spacingRight: 6
-```
-### Edge Style Override
-```yaml
-edges:
-  - from: a
-    to: b
-    style:
-      strokeColor: "#DC2626"
-      strokeWidth: 3
-      dashed: true
-      dashPattern: "8 4"
-      endArrow: classic
-```
-### Token References
-Use `$` prefix to reference theme tokens:
-```yaml
-style:
-  fillColor: $primaryLight # Theme's primaryLight color
-  strokeColor: $primary # Theme's primary color
-  fontColor: $text # Theme's text color
-```
-When `meta.palette` is present, use 1-based palette tokens for explicit category colors:
-```yaml
-style:
-  fillColor: $palette2-fill
-  strokeColor: $palette2-stroke
-  fontColor: $palette2-text
-```
-`$paletteN` resolves entry N's base color; `$paletteN-fill`, `$paletteN-stroke`, and `$paletteN-text` resolve the materialized entry fields. The token is invalid without `meta.palette`, and an out-of-range entry produces a warning plus theme-primary fallback.
-### Replication Metadata
-Use `meta.replication` to capture source-palette intent without turning the whole file into raw pixel data:
-```yaml
-meta:
-  source: replicated
-  canvas: 1200x800
-  theme: tech-blue
-  replication:
-    colorMode: preserve-original
-    background: "#FFF7ED"
-    palette:
-      - hex: "#FDBA74"
-        role: service fill
-        appliesTo: nodes
-        confidence: high
-      - hex: "#7C2D12"
-        role: connector and text
-        appliesTo: mixed
-        confidence: medium
-    confidenceNotes:
-      - "Footer gradient was simplified into a flat warm background."
-```
-Recommended usage:
-- Write explicit `style.fillColor`, `style.strokeColor`, and `style.fontColor` on nodes/edges/modules when color extraction is high-confidence.
-- Keep low-confidence or non-essential elements on theme tokens so theme changes and accessibility refinements still work.
-- Use `theme-first` only when the user explicitly wants palette normalization.
-- `meta.replication.palette` records colors extracted from the source image; `meta.palette` selects a reusable rendering palette. Replication preserves the extracted source colors unless normalization was explicitly requested.
-- Rebuild the main diagram with native draw.io cells; do not use a full-page embedded reference image as the final result.
----
-## Complete Example
-### Microservices Architecture
-```yaml
-meta:
-  theme: tech-blue
-  layout: horizontal
-  canvas: auto
-  title: E-Commerce Microservices
-modules:
-  - id: gateway
-    label: API Gateway
-  - id: services
-    label: Core Services
-  - id: data
-    label: Data Layer
-nodes:
-  # Gateway Layer
-  - id: api
-    label: API Gateway
-    type: service
-    module: gateway
-    icon: aws.api-gateway
-  # Services Layer
-  - id: orders
-    label: Order Service
-    type: service
-    module: services
-  - id: inventory
-    label: Inventory Service
-    type: service
-    module: services
-  - id: users
-    label: User Service
-    type: service
-    module: services
-  # Data Layer
-  - id: ordersDb
-    label: Orders DB
-    type: database
-    module: data
-    icon: aws.dynamodb
-  - id: inventoryDb
-    label: Inventory DB
-    type: database
-    module: data
-  - id: usersDb
-    label: Users DB
-    type: database
-    module: data
-edges:
-  # API to Services
-  - from: api
-    to: orders
-    type: primary
-  - from: api
-    to: inventory
-    type: primary
-  - from: api
-    to: users
-    type: primary
-  # Services to Databases
-  - from: orders
-    to: ordersDb
-    type: data
-    label: CRUD
-  - from: inventory
-    to: inventoryDb
-    type: data
-    label: CRUD
-  - from: users
-    to: usersDb
-    type: data
-    label: CRUD
-  # Service Dependencies
-  - from: orders
-    to: inventory
-    type: optional
-    label: Check Stock
-```
-### Neural Network (Academic)
-```yaml
-meta:
-  theme: academic
-  figureType: architecture
-  layout: vertical
-  title: CNN Architecture
-nodes:
-  - id: input
-    label: "Input: \\(X \\in \\mathbb{R}^{28 \\times 28}\\)"
-    type: terminal
-  - id: conv1
-    label: "$$\\text{Conv2D}(32, 3\\times3)$$"
-    type: formula
-  - id: pool1
-    label: "$$\\text{MaxPool}(2\\times2)$$"
-    type: formula
-  - id: conv2
-    label: "$$\\text{Conv2D}(64, 3\\times3)$$"
-    type: formula
-  - id: flatten
-    label: Flatten
-    type: process
-  - id: dense
-    label: "$$\\text{Dense}(128, \\text{ReLU})$$"
-    type: formula
-  - id: output
-    label: "Output: \\(\\hat{y} \\in \\mathbb{R}^{10}\\)"
-    type: terminal
-edges:
-  - from: input
-    to: conv1
-    type: primary
-  - from: conv1
-    to: pool1
-    type: primary
-  - from: pool1
-    to: conv2
-    type: primary
-  - from: conv2
-    to: flatten
-    type: primary
-  - from: flatten
-    to: dense
-    type: primary
-  - from: dense
-    to: output
-    type: primary
-```
----
-## Validation
-Specifications are validated against a JSON Schema:
-```bash
-# Validate specification
-npx drawio-skills validate spec.yaml
-```
-Validation checks:
-- Required fields present
-- Valid theme reference
-- Valid palette reference and palette-token range
-- Valid academic `figureType` when provided
-- Unique node/module IDs
-- Edge references exist
-- Style values valid
----
-## Migration from A-H Format
-### A-H Format (Legacy)
-```
-A. 领域：软件架构
-B. 目的：展示微服务架构
-C. 标题：电商系统
-D. 节点：
-   - API Gateway
-   - Order Service
-   - Database
-E. 连接：
-   - API Gateway → Order Service
-   - Order Service → Database
-F. 布局：水平
-G. 视觉：现代风格
-H. 约束：无
-```
-### New Specification Format
-```yaml
-meta:
-  theme: tech-blue
-  layout: horizontal
-  title: 电商系统
-nodes:
-  - id: api
-    label: API Gateway
-    type: service
-  - id: orders
-    label: Order Service
-    type: service
-  - id: db
-    label: Database
-    type: database
-edges:
-  - from: api
-    to: orders
-    type: primary
-  - from: orders
-    to: db
-    type: data
-```
-### Key Differences
-| Aspect        | A-H Format            | New Format          |
-| ------------- | --------------------- | ------------------- |
-| Structure     | Free text             | YAML schema         |
-| Theme         | Section G description | Explicit theme name |
-| Shapes        | Inferred              | Semantic types      |
-| Connectors    | Text description      | Typed connectors    |
-| Validation    | None                  | JSON Schema         |
-| Extensibility | Limited               | Style overrides     |