@tekyzinc/gsd-t 2.68.11 → 2.68.13

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.68.13] - 2026-04-05
+
+### Added (element-contract template)
+- **Chart-type-specific mandatory Visual Spec properties** — bar charts must now specify: `bar_width`, `bar_gap`, `bar_group_gap`, `corner_radius`, `label_position`, `label_min_width`, `segment_order`, `orientation`. Circular charts: `outer_diameter`, `inner_diameter`, `segment_order`, `start_angle`, `label_position`, `center_content`. Line/area: `stroke_width`, `point_radius`, `curve_type`, `fill_opacity`. Progress/gauge: `track_width`, `fill_width`, `track_color`. These are the exact properties that distinguish "matches the design" from "looks close."
+
+### Why
+BDS comparison showed bars with wrong width, wrong gap between groups, labels positioned outside instead of inside, wrong segment stacking order. The element contract's Visual Spec was free-form (`{dimension_1}`) — the agent could skip bar_width, segment_order, and label_position entirely. Chart-type-specific mandatory fields close this gap.
+
+## [2.68.12] - 2026-04-05
+
+### Fixed (design-chart-taxonomy template)
+- **Lists section, naming grammar, and formalized extension workflow** now ship in the package source template (previously only existed in local `~/.claude/templates/` copy from v2.67.10 — `update-all` overwrote it). Package template and installed template are now in sync.
+
 ## [2.68.11] - 2026-04-05
 
 ### Changed (widget-contract template)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.68.11",
+  "version": "2.68.13",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 51 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/templates/design-chart-taxonomy.md

@@ -144,6 +144,27 @@ The catastrophic failure mode is: agent sees "bars" in Figma, picks `chart-bar-g
 | `table-zebra`             | Alternating row backgrounds                               |
 | `table-striped-header`    | Only header row has distinct background                   |
 
+**Decision rule: table vs list?**
+- Columns aligned across rows, with a header row labelling columns → **table-\***
+- Each row is self-contained (thumbnail + text stack + meta, no shared column grid) → **list-\*** (see Lists section)
+
+---
+
+## Lists
+
+| Element name                   | Visual distinguisher                                                                              |
+|--------------------------------|---------------------------------------------------------------------------------------------------|
+| `list-simple-vertical`         | Vertical stack of single-line text rows                                                           |
+| `list-icon-vertical`           | Vertical stack of rows; each row has leading icon + text                                          |
+| `list-avatar-vertical`         | Vertical stack of rows; each row has leading avatar + text stack                                  |
+| `list-thumbnail-vertical`      | Vertical stack of rows; each row has leading thumbnail (bounded rect image) + text stack + meta   |
+
+**Decision rule: which list variant?**
+- Leading visual is a circular profile image → `list-avatar-vertical`
+- Leading visual is a glyph → `list-icon-vertical`
+- Leading visual is a bounded-rect image (video thumb, article cover) → `list-thumbnail-vertical`
+- No leading visual → `list-simple-vertical`
+
 ---
 
 ## Controls
@@ -257,11 +278,40 @@ When `gsd-t-design-decompose` runs, for EACH visual element encountered in the d
 
 ---
 
+## Naming grammar
+
+Element names follow a consistent grammar to avoid ad-hoc invention:
+
+```
+{category}-{variant}-{orientation/modifier}
+
+Categories: chart, axis, legend, stat-card, card, table, list, button, input,
+            select, tabs, filter, icon, text, heading, container, stack, grid
+
+Modifiers (common):
+  -single / -multi           — series count
+  -horizontal / -vertical    — orientation
+  -stacked / -grouped        — arrangement
+  -percentage                — values sum to 100%
+  -dense / -comfortable      — density
+  -outline / -filled         — visual weight
+```
+
+When proposing a new entry, match the grammar of its sibling section.
+
 ## Extending the taxonomy
 
 If a new element variant is needed:
 
-1. Add it to the relevant section above with a visual distinguisher
-2. If it's a new chart variant, add a decision rule under the chart type
-3. Bump GSD-T version (minor) and document the addition in CHANGELOG.md
-4. Never delete entries — only add (breaking the closed set is destructive)
+1. **Write a proposal first**: `.gsd-t/contracts/design/taxonomy-proposals/{name}.proposal.md` with:
+   - Section it belongs in (existing or new)
+   - Proposed entry name + visual distinguisher (≤80 chars)
+   - Sibling entries — how the new entry differs from each
+   - Catastrophic-misclassification rationale (what goes wrong if you jam it into an existing entry)
+   - Source (Figma node, screenshot)
+   - Companion entries flagged (if the new entry implies a cluster of siblings)
+2. Add it to the relevant section above with a visual distinguisher
+3. If it creates a new section, place it near structurally similar sections (layout-like near Tables, interactive-like near Controls)
+4. If it's a new chart variant, add a decision rule under the chart type
+5. Bump GSD-T version (minor) and document the addition in CHANGELOG.md
+6. Never delete entries — only add (breaking the closed set is destructive)

package/templates/element-contract.md

@@ -28,6 +28,49 @@ Atomic visual unit. One contract per visual variant (e.g., `chart-bar-stacked-ho
 
 *List every measurable visual property: dimensions, spacing, radii, borders, shadows, opacity. Reference design tokens rather than raw values where possible (`tokens.spacing.4` instead of `16px`).*
 
+### Chart-Type-Specific Mandatory Properties
+
+The free-form table above is necessary but not sufficient. For chart elements, the following properties are **MANDATORY** based on chart category — extract exact values from Figma MCP `get_design_context` or measure from the screenshot. Missing any of these is how "looks off" happens.
+
+**Bar charts** (`chart-bar-*`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `bar_width` | Width of each bar (px or % of available space) | `32px` / `60%` |
+| `bar_gap` | Gap between bars within a group (grouped only) | `4px` |
+| `bar_group_gap` | Gap between category groups | `24px` |
+| `corner_radius` | Rounding on bar ends (top for vertical, right for horizontal) | `4px top` / `0` |
+| `label_position` | Where percentage/value labels appear | `inside-center` / `outside-right` / `above` |
+| `label_min_width` | Minimum bar width to show label (hide if smaller) | `40px` |
+| `segment_order` | For stacked: order of series from bottom/left to top/right | `[NM, MT, OK, TX, IL]` |
+| `orientation` | Explicit confirmation of horizontal vs vertical | `vertical` |
+
+**Circular charts** (`chart-donut`, `chart-pie`, `chart-radial-bar`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `outer_diameter` | Total diameter of the chart | `180px` |
+| `inner_diameter` | Hole diameter (donut only, 0 for pie) | `100px` |
+| `segment_order` | Clockwise order of segments from 12 o'clock | `[Steps, Broker, Video, Quick, Plan]` |
+| `start_angle` | Where first segment starts | `12 o'clock (0°)` |
+| `label_position` | Where percentage labels appear | `outside-radial` / `inside-segment` / `none` |
+| `center_content` | What's displayed in the center hole (donut) | `"485" + "Total Interactions"` |
+
+**Line / area charts** (`chart-line-*`, `chart-area-*`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `stroke_width` | Line thickness | `2px` |
+| `point_radius` | Data point dot radius (0 = no dots) | `4px` |
+| `curve_type` | Linear, bezier, step | `linear` |
+| `fill_opacity` | For area charts: opacity of fill below line | `0.3` |
+
+**Progress / gauge** (`chart-progress-ring`, `chart-progress-bar`):
+| Property | Description | Example |
+|----------|-------------|---------|
+| `track_width` | Width of background track | `12px` |
+| `fill_width` | Width of progress fill (same as track or thinner) | `12px` |
+| `track_color` | Background track color | `#e2e8f0` |
+
+**If your element is a chart and you haven't filled the mandatory properties above, STOP. Go back to Figma and extract them.** These properties are the difference between a chart that "looks close" and one that matches.
+
 ## Labels / Text (if applicable)
 
 | Property      | Value                                                              |