@tekyzinc/gsd-t 2.68.10 → 2.68.12

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [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)
+- **Alignment column in Card Chrome Slots** — every slot now requires explicit alignment (left/center/right) extracted from Figma. Incorrect legend alignment was the #2 cause of "looks off" results.
+- **Internal Element Layout section (MANDATORY)** — new section replacing the flat layout table. Documents: body_layout (flex-row/column/grid), body_justify, body_align, body_gap, chart_width/height, legend_width, footer_legend_justify, header_to_body_gap, body_to_footer_gap. These are the exact values that control spacing and sizing of elements within a widget card.
+- **Verification checklist expanded** — now checks: chrome alignment, internal layout, inter-element spacing, element sizing, legend alignment, card container values (6 new items).
+
+### Why
+BDS Analytics comparison revealed consistent intra-widget layout errors: legends left-aligned instead of centered, inconsistent spacing between chart and legend, wrong element sizing within cards. The widget contract template had a Layout section but it specified only container-level properties (padding, border, gap) — not how elements were sized, spaced, and aligned WITHIN the card body. These new fields close that gap.
+
 ## [2.68.10] - 2026-04-05
 
 ### Changed (gsd-t-design-decompose)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.68.10",
+  "version": "2.68.12",
   "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/widget-contract.md

@@ -19,18 +19,20 @@ Composition of elements + data binding + layout. Widgets SELECT and POSITION ele
 
 Every widget is a card with consistent chrome. Missing chrome is the #1 cause of "looks off" verification results. Document EVERY slot, even if empty.
 
-| Slot                    | Element Contract (or N/A)                | Content / Behavior                               |
-|-------------------------|------------------------------------------|--------------------------------------------------|
-| `title`                 | heading-h3                               | {exact title text from design}                   |
-| `subtitle`              | text-caption or N/A                      | {exact subtitle text — "Which tools members interact with most."} |
-| `header_right_control`  | select-dropdown, button-ghost, or N/A    | {e.g., "Members ▼" filter dropdown in card header} |
-| `kpi_header`            | stat-card-kpi-large or N/A               | {e.g., "2.4" + "Avg tools per member" shown above chart} |
-| `body`                  | {primary element, e.g., chart-donut}     | {main visual}                                    |
-| `body_sidebar`          | {e.g., legend-vertical-right or N/A}     | {element positioned alongside body}              |
-| `footer`                | {e.g., text-caption or N/A}              | {e.g., "Last updated: ..."}                      |
-| `footer_legend`         | {e.g., legend-horizontal-bottom or N/A}  | {legend below body}                              |
-
-**Rule**: If the design shows it, document it. If the design doesn't show it, write "N/A". Do NOT leave blank.
+| Slot                    | Element Contract (or N/A)                | Content / Behavior                               | Alignment       |
+|-------------------------|------------------------------------------|--------------------------------------------------|-----------------|
+| `title`                 | heading-h3                               | {exact title text from design}                   | {left / center} |
+| `subtitle`              | text-caption or N/A                      | {exact subtitle text — "Which tools members interact with most."} | {left / center} |
+| `header_right_control`  | select-dropdown, button-ghost, or N/A    | {e.g., "Members ▼" filter dropdown in card header} | right           |
+| `kpi_header`            | stat-card-kpi-large or N/A               | {e.g., "2.4" + "Avg tools per member" shown above chart} | {left / center} |
+| `body`                  | {primary element, e.g., chart-donut}     | {main visual}                                    | {center / left} |
+| `body_sidebar`          | {e.g., legend-vertical-right or N/A}     | {element positioned alongside body}              | {left / center} |
+| `footer`                | {e.g., text-caption or N/A}              | {e.g., "Last updated: ..."}                      | {left / center} |
+| `footer_legend`         | {e.g., legend-horizontal-bottom or N/A}  | {legend below body}                              | {center / left} |
+
+**Rules**:
+- If the design shows it, document it. If the design doesn't show it, write "N/A". Do NOT leave blank.
+- The **Alignment** column is MANDATORY. Incorrect alignment (left vs center) is the #2 cause of "looks off" results after missing chrome. Extract alignment from the Figma node — do not default to left.
 
 ## Elements Used (body composition)
 
@@ -46,25 +48,52 @@ Every widget is a card with consistent chrome. Missing chrome is the #1 cause of
 ```
 ┌──────────────────────────────────────────────┐
 │ {title}                        [{filter}]    │
+│ {subtitle}                                   │
 ├──────────────────────────────────────────────┤
 │              │                               │
 │   {chart}    │      {legend}                 │
 │              │                               │
+├──────────────────────────────────────────────┤
+│          {footer_legend}                     │
 └──────────────────────────────────────────────┘
 ```
 
+### Card Container
+
 | Property           | Value                                               |
 |--------------------|-----------------------------------------------------|
 | container_width    | {100% of parent / fixed 480px}                      |
 | container_height   | {auto / fixed 320px}                                |
-| padding            | {tokens.spacing.6}                                  |
-| gap                | {tokens.spacing.4}                                  |
-| background         | {tokens.color.surface.card}                         |
-| border             | {1px solid tokens.color.border.subtle}              |
-| border_radius      | {tokens.radius.lg}                                  |
-| shadow             | {tokens.shadow.sm}                                  |
-| chart_area_ratio   | {60% of widget width}                               |
-| legend_area_ratio  | {40% of widget width}                               |
+| padding            | {16px — extract exact value from Figma}             |
+| background         | {#ffffff}                                           |
+| border             | {1px solid #e2e8f0}                                 |
+| border_radius      | {8px}                                               |
+| shadow             | {none / 0 2px 8px rgba(0,0,0,0.1)}                 |
+
+### Internal Element Layout (MANDATORY — the "looks off" killer)
+
+This section specifies how elements are sized, spaced, and aligned WITHIN the card body. Missing or wrong values here produce the "spacing inside widgets" and "legends incorrectly aligned" class of errors.
+
+| Property                    | Value                                                      |
+|-----------------------------|------------------------------------------------------------|
+| header_to_body_gap          | {16px — gap between title/subtitle row and body content}   |
+| body_layout                 | {flex-row / flex-column / grid}                            |
+| body_justify                | {center / flex-start / space-between}                      |
+| body_align                  | {center / flex-start / stretch}                            |
+| body_gap                    | {24px — gap between body element and sidebar element}      |
+| chart_width                 | {180px / 60% of body / auto}                               |
+| chart_height                | {180px / auto}                                             |
+| chart_align_self            | {center / flex-start}                                      |
+| legend_width                | {auto / 40% of body}                                       |
+| legend_align_self           | {center / flex-start}                                      |
+| body_to_footer_gap          | {16px — gap between body and footer/footer_legend}         |
+| footer_legend_justify       | {center / flex-start — EXTRACT FROM FIGMA, do not default} |
+
+**Rules**:
+- Extract EVERY value from the Figma node — do not approximate.
+- `footer_legend_justify` is critical: center-aligned legends look completely different from left-aligned. Check the Figma.
+- `body_layout` + `body_justify` + `body_align` together define whether the chart is centered in its card, left-aligned, or stretched. Get this wrong and every widget "looks off."
+- These values are WIDGET-OWNED — they describe how the widget positions its elements, not the elements' internal specs (which live in element contracts).
 
 ## Data Binding
 
@@ -154,7 +183,12 @@ The widget harness page (`/design-system/{widget-name}`) renders ONE widget inst
 Widget-level verification runs AFTER all referenced elements pass their own verification. Widget verification only checks composition — element internals are out of scope.
 
 - [ ] All referenced elements present and correctly slotted
-- [ ] Layout dimensions (width, height, padding, gap) match design
+- [ ] Card chrome alignment matches design (title left/center, legend center/left, etc.)
+- [ ] Internal element layout matches design (body_layout, body_justify, body_align)
+- [ ] Inter-element spacing matches design (header_to_body_gap, body_gap, body_to_footer_gap)
+- [ ] Element sizing matches design (chart_width, chart_height, legend_width)
+- [ ] Legend alignment matches design (footer_legend_justify: center vs left)
+- [ ] Card container values match design (padding, border, radius, shadow)
 - [ ] Responsive breakpoints adapt as specified
 - [ ] Data binding produces correct element inputs (spot-check with sample data)
 - [ ] Inter-element interactions fire (hover sync, click propagation)