feat: consolidate reviewed Diagram Design 2.6.0 release (#134)
* fix(commands): stop hardcoding the visual-type count Integrates the final reviewed diff from PR #112. * docs(high-level): correct effective width checklist Integrates the final reviewed diff from PR #105. * fix(commands): quote profile argument hint Integrates the final reviewed diff from PR #126. * test(sankey): gate conservation and ribbon geometry Integrates the final reviewed diff from PR #103. * feat(tooling): add doctor diagnostics gate Integrates the final reviewed diff from PR #132. * feat(scripts): lint diagrams as rendered Integrates the final reviewed diff from PR #18. * feat(types): add quantitative polar chart Integrates the final reviewed diff from PR #101. * chore(release): consolidate reviewed changes in 2.6.0 Documents every combined gate and synchronizes Claude, Codex, and Factory metadata for the 39-type release. * fix(doctor): support installed-skill projects --------- Co-authored-by: mysoniw <soniw1@gmail.com> Co-authored-by: thang <76550342+thangldw@users.noreply.github.com> Co-authored-by: YinShaokun <yinshaokun@didiglobal.com> Co-authored-by: 0xDarkMatter <0xDarkMatter@users.noreply.github.com> Co-authored-by: Rupam Pal <rupam.pal@euromonitor.com> Co-authored-by: Yuvraj3905 <yuvraj202001@gmail.com>
This commit is contained in:
Cathryn Lavery
co-authored by
mysoniw
thang
YinShaokun
0xDarkMatter
Rupam Pal
Yuvraj3905
mysoniw
thang
YinShaokun
0xDarkMatter
Rupam Pal
Yuvraj3905
parent
4b573616cb
commit
b827385a17
@@ -0,0 +1,119 @@
|
||||
# Environment doctor
|
||||
|
||||
Load this file when the user asks to run diagnostics, health checks, or first-run troubleshooting, or when they invoke `/diagram-design:doctor` or `/doctor`.
|
||||
|
||||
The goal is a one-shot report that checks local readiness for Diagram Design import/export and command routing, without mutating user files or installing dependencies.
|
||||
|
||||
Resolve the Diagram Design installation from this loaded reference, not from the
|
||||
user's current working directory. A normal project directory is the expected
|
||||
place to invoke the doctor and must not be treated as a repository-path error.
|
||||
|
||||
Use two diagnostic modes:
|
||||
|
||||
- **Installed-skill mode** (default): check the runtime and the resolved skill
|
||||
installation. Do not require maintainer-only repository files.
|
||||
- **Maintainer-checkout mode**: use this only when the resolved installation
|
||||
root contains `CONTRIBUTING.md`, `.github/workflows/ci.yml`, and
|
||||
`scripts/verify-plugin-package.py`. Add the repository integrity checks below.
|
||||
|
||||
## Inputs
|
||||
|
||||
Optional flags:
|
||||
|
||||
- `--strict` — treat warnings as failures in the final summary.
|
||||
- `--json` — print a machine-readable JSON report in addition to human summary.
|
||||
|
||||
If no flags are provided, run in standard mode.
|
||||
|
||||
## Required checks
|
||||
|
||||
Run all checks in this order and report each as `pass`, `warn`, or `fail`.
|
||||
|
||||
1. Python runtime
|
||||
- Resolve `python3` first, then `python`.
|
||||
- Require version >= 3.10.
|
||||
- `fail` if no Python interpreter is found.
|
||||
- `fail` if version is below 3.10.
|
||||
|
||||
2. Playwright availability for PNG export
|
||||
- Check whether Playwright import works in the active Python interpreter (`import playwright`).
|
||||
- Check whether Chromium is installed for Playwright (`playwright install --help` availability is sufficient for command presence; prefer also checking browser cache when practical).
|
||||
- If missing, mark `warn` and print exact setup hint:
|
||||
- `pip install playwright && playwright install chromium`
|
||||
- Never auto-install dependencies.
|
||||
|
||||
3. Expected script presence (maintainer-checkout mode only)
|
||||
- Verify these repository scripts exist:
|
||||
- `scripts/verify-drawio-import.py`
|
||||
- `scripts/verify-mermaid-import.py`
|
||||
- `scripts/verify-motion.py`
|
||||
- `scripts/lint-skin.py`
|
||||
- `scripts/verify-docs-sync.py`
|
||||
- Missing scripts are `fail` in maintainer-checkout mode.
|
||||
- In installed-skill mode, report that maintainer scripts are not applicable;
|
||||
their absence is not a warning or failure.
|
||||
|
||||
4. Plugin wiring surfaces (maintainer-checkout mode only)
|
||||
- Verify Claude command files exist and point to their references:
|
||||
- `commands/export-diagram.md` -> `references/export.md`
|
||||
- `commands/import-drawio.md` -> `references/import-drawio.md`
|
||||
- `commands/import-mermaid.md` -> `references/import-mermaid.md`
|
||||
- `commands/profile.md` -> `references/profiles.md`
|
||||
- `commands/doctor.md` -> `references/doctor.md`
|
||||
- Verify Pi prompt files exist and point to their references:
|
||||
- `prompts/export-diagram.md` -> `references/export.md`
|
||||
- `prompts/import-mermaid.md` -> `references/import-mermaid.md`
|
||||
- `prompts/profile.md` -> `references/profiles.md`
|
||||
- `prompts/doctor.md` -> `references/doctor.md`
|
||||
- Missing files are `fail`.
|
||||
- Mismatched reference routing is `fail`.
|
||||
- In installed-skill mode, report that maintainer command/prompt wiring is not
|
||||
applicable; partial or absent repository routing trees are not failures.
|
||||
|
||||
5. Common path mistakes
|
||||
- Verify `SKILL.md` beneath the resolved installation root. Do not search for it
|
||||
relative to the user's current project and do not instruct users to enter the
|
||||
maintainer repository.
|
||||
- Detect Windows path quoting risk when paths contain spaces and the provided command examples omit quotes.
|
||||
- Detect references to local installed skill paths that do not exist (if command output includes one).
|
||||
- Mark these as `warn` with a precise fix suggestion.
|
||||
- A missing resolved `SKILL.md` should suggest reinstalling or updating Diagram
|
||||
Design, not changing into a repository checkout.
|
||||
|
||||
## Output contract
|
||||
|
||||
Always print:
|
||||
|
||||
1. A compact summary line:
|
||||
- `Doctor summary: <PASS|WARN|FAIL> (<pass_count> pass, <warn_count> warn, <fail_count> fail)`
|
||||
|
||||
2. A checklist with one line per check:
|
||||
- `[PASS] Python 3.11.9 found at ...`
|
||||
- `[WARN] Playwright not installed ...`
|
||||
- `[FAIL] Missing scripts/verify-docs-sync.py`
|
||||
|
||||
3. A `Next actions` section only when warn/fail exists.
|
||||
|
||||
4. If `--json` is present, append JSON object with:
|
||||
- `status`, `counts`, `checks[]` (`name`, `status`, `message`, `fix` optional), `timestamp`.
|
||||
|
||||
## Safety and behavior rules
|
||||
|
||||
- Read-only diagnostics only: do not modify files, do not install packages, do not run destructive git commands.
|
||||
- If any command fails unexpectedly, capture stderr and continue remaining checks.
|
||||
- Never claim a check passed unless verified directly in this run.
|
||||
- Prefer explicit, copy-pastable remediation commands.
|
||||
|
||||
## Example result
|
||||
|
||||
```text
|
||||
Doctor summary: WARN (6 pass, 2 warn, 0 fail)
|
||||
[PASS] Python 3.11.9 found at /usr/bin/python3
|
||||
[WARN] Playwright package not found in active interpreter
|
||||
[PASS] scripts/verify-drawio-import.py present
|
||||
...
|
||||
|
||||
Next actions
|
||||
- Install PNG export dependencies: pip install playwright && playwright install chromium
|
||||
- Re-run: /diagram-design:doctor --strict
|
||||
```
|
||||
@@ -159,7 +159,7 @@ Write the new tokens to `style-guide.md`. Suggest running the `/regenerate-examp
|
||||
|
||||
After onboarding, the user should:
|
||||
|
||||
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 38 types.
|
||||
1. Open `assets/index.html` (gallery) and confirm the new palette feels coherent across all 39 types.
|
||||
2. If any type looks off, they usually need to tune `muted` (often too dark or too light against the new `paper`).
|
||||
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Semantic patterns
|
||||
|
||||
Semantic patterns describe **what a system does**; the 38 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
|
||||
Semantic patterns describe **what a system does**; the 39 visual types describe **how information is arranged**. Choose a pattern first when behavior, state, enforcement, or risk is load-bearing, then use its nearest visual type as the layout grammar. If no pattern matches, choose a visual type directly.
|
||||
|
||||
Use one primary pattern per figure. A second pattern may supply at most one supporting primitive; if both need full treatment, split overview and detail. Labels and outcomes must remain complete in a static frame.
|
||||
|
||||
|
||||
@@ -420,7 +420,7 @@ Before emitting SVG, verify **every** item. If any fails, fix it — don't ship.
|
||||
|
||||
1. Every cluster `node.cx` equals its chevron's `cx` (§2.2 + §2.7). This is what makes the chevron banner a real legend.
|
||||
2. Every chevron `width` is a multiple of 4 and ≥ 120.
|
||||
3. The reserved right strip (28 px) exists **iff** any vertical chevron is declared. If yes, `effective_w = 972`; if no, `effective_w = 1000`.
|
||||
3. The reserved right strip (28 px) exists **iff** any vertical chevron is declared. If yes, `effective_w = 964`; if no, `effective_w = 1000`.
|
||||
4. Exactly **one** `focal` node. If `focal` is unset in inputs, default to the first `kind: node` under chevron "Storage".
|
||||
5. Every edge whose endpoint is the focal node uses `style: primary` (accent stroke + `arrow-accent` marker).
|
||||
6. Every edge originating from a `kind: bar` component uses `style: trigger` (dashed + `arrow-sm`).
|
||||
@@ -430,7 +430,7 @@ Before emitting SVG, verify **every** item. If any fails, fix it — don't ship.
|
||||
10. Each vertical chevron pairs **1:1** with exactly one `bar` or `cross-cutting` component (§5 pairing rule). `len(verticals) == len(bars) + len(crosscuts)`.
|
||||
11. `viewBox_h = max(540, strip_y_bot + 112)` — grow the canvas when multiple crosscuts are declared so the legend still fits.
|
||||
12. Custom component colors (§3.4) apply only to container + icon + name; connectors stay topology-driven. Cap at 2 custom-colored components in addition to the focal.
|
||||
11. The diagram passes SKILL.md §9 (4-px grid; ≤ 2 accent elements; mono only for technical content; hairlines; no shadows; no `rounded-2xl`).
|
||||
13. The diagram passes SKILL.md §9 (4-px grid; ≤ 2 accent elements; mono only for technical content; hairlines; no shadows; no `rounded-2xl`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,136 @@
|
||||
# Polar Chart
|
||||
|
||||
**Best for:** one quantitative series across 4–8 categories whose clockwise order is meaningful.
|
||||
|
||||
## Input contract
|
||||
|
||||
```yaml
|
||||
title: "Request demand by UTC window"
|
||||
unit: "% of daily peak"
|
||||
scale:
|
||||
min: 0
|
||||
max: 100
|
||||
categories:
|
||||
- { label: "00–03", value: 32 }
|
||||
- { label: "03–06", value: 18 }
|
||||
- { label: "06–09", value: 24 }
|
||||
- { label: "09–12", value: 58 }
|
||||
- { label: "12–15", value: 100, focal: true }
|
||||
- { label: "15–18", value: 82 }
|
||||
- { label: "18–21", value: 76 }
|
||||
- { label: "21–24", value: 45 }
|
||||
start_angle: -90
|
||||
clockwise: true
|
||||
source_note: "Illustrative normalized workload profile"
|
||||
```
|
||||
|
||||
Validation rules:
|
||||
|
||||
1. `scale.min` is exactly `0`; truncated radial scales are invalid.
|
||||
2. `scale.max` is finite and greater than `0`.
|
||||
3. Every value is finite and satisfies `0 <= value <= scale.max`.
|
||||
4. Category labels are unique after trimming and category count is 4–8.
|
||||
5. At most one category is focal.
|
||||
6. Categories retain input order; sorting by value would destroy circular meaning.
|
||||
|
||||
Missing values are out of scope for the first version. The agent must stop and ask whether to omit the category or supply a value; it must not coerce missing data to zero.
|
||||
|
||||
## Quantitative encoding
|
||||
|
||||
For category `i` of `N`, value `v`, center `(cx, cy)`, and outer radius `R`:
|
||||
|
||||
```text
|
||||
theta_i = start_angle + clockwise_sign * 2π * i / N
|
||||
radius_i = R * v / scale.max
|
||||
x_i = cx + radius_i * cos(theta_i)
|
||||
y_i = cy + radius_i * sin(theta_i)
|
||||
```
|
||||
|
||||
Angles are expressed in radians for calculation; `start_angle` is supplied in degrees and defaults to `-90`, placing the first category at twelve o'clock. `clockwise_sign` is `+1` for the default clockwise order and `-1` otherwise.
|
||||
|
||||
The value ray is the line segment from `(cx, cy)` to `(x_i, y_i)`. Its visible length is exactly proportional to `v`. Endpoint circles have constant radius and encode no additional quantity. No filled sector may sit behind or beneath a value ray, because its area would compete with the declared radius encoding.
|
||||
|
||||
The element carrying `data-polar-chart` must be the chart's root `<svg>`. Its descendants are limited to `<g>`, `<line>`, `<circle>`, `<rect>`, `<text>`, `<title>`, and `<desc>`; nested SVGs, paths, polygons, external references, images, and every other element are rejected. Duplicate attributes, mismatched markup, URL-valued SVG references, transforms, CSS loading through `@import`/`url()`, and geometry-affecting CSS are forbidden. Chart elements carry neither `class` nor inline `style`; document styles may not use selectors capable of matching the chart, except the canonical root `svg` layout rule. The only external stylesheet allowed is Google Fonts. Every line carries exactly one of `data-polar-spoke`, `data-polar-ray`, or `data-polar-rule` and uses the role's declared stroke width; spoke and ray geometry is verified within `min(0.75 px, 5% of R)`. The five grid circles carry `data-polar-ring`, use `fill="none"`, a 0.8 px stroke, the chart center, and the 20% through 100% radius intervals exactly once. Every endpoint circle carries `data-polar-marker` and uses the declared 4 px radius, or 5 px for the focal category, with a 1.2 px stroke. The optional full-canvas background is the only rectangle and carries `data-polar-background`. This fail-closed allowlist prevents contributors from bypassing the radius-only encoding with an unannotated or falsely annotated filled shape.
|
||||
|
||||
### Zero
|
||||
|
||||
For `v = 0`, `radius_i = 0`. Render no value ray and no endpoint marker. Keep the faint full-radius category spoke, and render the category's numeric label as `0`. A single scale label at the center also marks the shared zero baseline. Do not add a minimum hub, minimum ray length, displaced marker, or other visible magnitude.
|
||||
|
||||
## Layout conventions
|
||||
|
||||
Version 1 supports:
|
||||
|
||||
- one quantitative series;
|
||||
- 4–8 equally spaced categories in a meaningful clockwise order;
|
||||
- a shared linear scale with `min = 0` and `max > 0`;
|
||||
- five circular grid rings at 20%, 40%, 60%, 80%, and 100%;
|
||||
- one optional focal category rendered with the accent token;
|
||||
- minimal light, minimal dark, and full-editorial examples;
|
||||
- horizontal, upright category labels outside the outer ring;
|
||||
- one numeric value label per category.
|
||||
|
||||
Version 1 excludes:
|
||||
|
||||
- DISC, personality, competency, and role-profile wheels whose sectors are qualitative;
|
||||
- arbitrary point placement within sectors;
|
||||
- filled quantitative wedges, gradient bands, or donut hubs;
|
||||
- multiple series, negative values, logarithmic scales, unequal sector angles, and more than eight categories;
|
||||
- animation or interaction.
|
||||
|
||||
Use Radar for multiple entities scored across common criteria, Line for more than eight ordered time buckets, and Bar when circular order adds no meaning.
|
||||
|
||||
## Geometry
|
||||
|
||||
All three examples use `viewBox="0 0 1000 520"`, center `(500, 230)`, and `R = 160`.
|
||||
|
||||
- Grid rings: `r = 32, 64, 96, 128, 160`.
|
||||
- Category spokes: center to `R`, 0.8 px rule stroke, no arrowhead.
|
||||
- Non-focal value rays: 2 px muted stroke; endpoint marker radius 4.
|
||||
- Focal value ray: 2.4 px accent stroke; endpoint marker radius 5.
|
||||
- Ring labels: `0.2 × max` through `1.0 × max` on the first axis only, Geist Mono 8 px; the example therefore shows `20, 40, 60, 80, 100`.
|
||||
- Category labels: at `R + 28`, Geist Sans 11 px semibold, horizontal and upright.
|
||||
- Numeric labels: at `R + 44`, Geist Mono 8 px, including the unit in the chart subtitle rather than repeating it eight times.
|
||||
- Label anchor: `middle` within 15 degrees of vertical, `start` on the right half, and `end` on the left half.
|
||||
- Drawing order: background, rings, spokes, scale labels, non-focal rays, focal ray, endpoint markers, category labels, numeric labels, legend/source note.
|
||||
|
||||
The minimal examples use the full 1000×520 canvas. The full-editorial example places the same chart in the existing editorial frame and adds summary cards without changing chart geometry.
|
||||
|
||||
## Visual treatment
|
||||
|
||||
- One accent category maximum. All other value rays use the muted token.
|
||||
- Circular rings and spokes are structural grid marks, never category colors.
|
||||
- Endpoint markers are constant-size lollipop heads, not bubbles.
|
||||
- Category labels remain horizontal; tangent rotation is intentionally excluded because it lowers scanability and belongs to the rejected qualitative wheel direction.
|
||||
- The chart must remain understandable in grayscale: position and numeric labels carry the data; accent only directs attention.
|
||||
- The SVG accessible description names the peak category, the scale, and the clockwise category order without narrating geometry.
|
||||
|
||||
## Complexity budget
|
||||
|
||||
- 4–8 categories.
|
||||
- Exactly one quantitative series.
|
||||
- At most one focal category.
|
||||
- Five grid rings and one numeric value label per category.
|
||||
- Static output only; split or change type rather than adding interaction or another encoding.
|
||||
|
||||
## When not to use
|
||||
|
||||
- Multiple series → use Radar.
|
||||
- Non-cyclic categories → use Bar.
|
||||
- More than eight ordered time buckets → use Line.
|
||||
- Qualitative profiles, arbitrary sector placement, negative values, or logarithmic scales → choose a truthful non-polar representation.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
- Donut hubs or any non-zero inner baseline.
|
||||
- Filled wedges, sectors, or gradient bands that imply area encodes magnitude.
|
||||
- Tangent or rotated category labels.
|
||||
- Multiple series on the same polar chart.
|
||||
- Truncated scales whose minimum is not zero.
|
||||
- Categories sorted by value instead of retaining their meaningful circular order.
|
||||
- Treating a missing value as zero.
|
||||
|
||||
## Examples
|
||||
|
||||
- `assets/example-polar.html` — minimal light.
|
||||
- `assets/example-polar-dark.html` — minimal dark with the same dataset and geometry.
|
||||
- `assets/example-polar-full.html` — full editorial with three unequal summary cards and unchanged chart geometry.
|
||||
Reference in New Issue
Block a user