npm - @tekyzinc/gsd-t - Versions diffs - 2.58.10 → 2.59.10 - Mend

@tekyzinc/gsd-t 2.58.10 → 2.59.10

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 (8) hide show

package/CHANGELOG.md +13 -0
package/commands/gsd-t-design-decompose.md +29 -6
package/commands/gsd-t-execute.md +27 -0
package/commands/gsd-t-quick.md +7 -1
package/package.json +1 -1
package/templates/design-chart-taxonomy.md +265 -0
package/templates/element-contract.md +26 -0
package/templates/widget-contract.md +21 -6

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,19 @@
 All notable changes to GSD-T are documented here. Updated with each release.
+## [2.59.10] - 2026-04-05
+### Added
+- **Chart & Atom Taxonomy** — `templates/design-chart-taxonomy.md` — closed enumeration of ~70 valid element names across charts, axes, legends, cards, tables, controls, atoms (icons/badges/chips/dividers), typography, and layout primitives. Fixes catastrophic failure mode where agents invented element names and picked wrong chart variants (e.g., `chart-bar-grouped-vertical` when design was `chart-bar-stacked-horizontal-percentage`). `gsd-t-design-decompose` now REQUIRES element names to come from this closed set.
+- **Visual distinguisher decision rules** per chart category (stacked vs grouped vs percentage, pie vs donut vs gauge, line vs area, categorical vs histogram) to prevent near-match pattern-matching.
+- **Atoms taxonomy** — icons, badges, chips, dividers, avatars, status-dots, spinners, tooltips, breadcrumbs, pagination, tags — the most-forgotten element tier.
+### Changed
+- **Element template**: `Test Fixture` section is now MANDATORY with the EXACT labels/values/percentages extracted from the design source. Placeholder data (Calculator/Planner/Tracker instead of real labels) is FORBIDDEN. Verifier compares labels verbatim.
+- **Widget template**: adds mandatory **Card Chrome Slots** section (title, subtitle, header_right_control, kpi_header, body, body_sidebar, footer, footer_legend) — each must be filled or explicitly marked N/A. Fixes the "missing subtitle, missing per-card filter dropdown, missing KPI-above-chart" defect.
+- **Design Verification Agent** (gsd-t-execute Step 5.25 + gsd-t-quick Step 5.25): adds mandatory **Step 0 — Data-Labels Cross-Check** that runs BEFORE visual comparison. Verifies every label/value/percentage from the Test Fixture appears verbatim in the rendered UI. Wrong data = CRITICAL deviation, no visual polish can redeem it.
+- **gsd-t-design-decompose**: MUST ingest existing flat `design-contract.md` when present (especially the `## Verification Status` section from prior verified builds) as ground truth for Test Fixture data — no re-inventing labels.
 ## [2.58.10] - 2026-04-05
 ### Added

package/commands/gsd-t-design-decompose.md CHANGED Viewed

@@ -15,19 +15,27 @@ If the project is small (single page, ≤10 elements, nothing reusable), use the
 ---
-## Step 0: Detect Inputs
+## Step 0: Detect Inputs + Load Taxonomy
 Run these checks, log results to user inline:
 1. **Figma MCP available?**
    - If yes → log "Figma MCP detected — will extract exact tokens per element"
    - If no → log "Figma MCP unavailable — using visual analysis (reduced precision)"
-2. **Existing flat contract?**
-   - If `.gsd-t/contracts/design-contract.md` exists → this is a retrofit; read it and use it as input alongside the design source
-   - If not → this is a fresh decomposition from the design source directly
+2. **Existing flat contract? — MANDATORY INGESTION if present**
+   - If `.gsd-t/contracts/design-contract.md` exists:
+     - **READ IT COMPLETELY** — it is the authoritative ground truth for data labels, values, and verification assertions from prior runs
+     - Extract: exact category labels, exact data values, exact center values, exact percentages
+     - Use these as **Test Fixture** data in every element contract you write (not placeholder data)
+     - If the flat contract has a `## Verification Status` section with 30+ rows, that is the GROUND TRUTH for what each element must match — port every row into the relevant element contract's Verification Checklist
+   - If not → fresh decomposition from the design source directly
 3. **Design source provided?**
    - Required: Figma URL, image path, or prototype URL in `$ARGUMENTS`
    - If missing → ask user: "Provide the design source (Figma URL, image path, or prototype URL)"
+4. **Load the chart taxonomy (MANDATORY)**
+   - READ `templates/design-chart-taxonomy.md` from the GSD-T package (or `~/.claude/` if installed)
+   - This is the **CLOSED SET** of valid element names. You MUST pick from this list. Inventing new element names is FORBIDDEN without user approval to extend the taxonomy.
+   - Keep the taxonomy in working memory while classifying — every element you identify MUST be matched against it
 ## Step 1: Survey the Design
@@ -45,14 +53,25 @@ Produce an initial flat inventory table:
 **Rule**: distinct visual variants = distinct rows. A horizontal stacked bar and a vertical stacked bar are TWO rows, not one.
-## Step 2: Classify Each Element
+## Step 2: Classify Each Element (taxonomy-enforced)
 For each row in the inventory, assign:
-- **Category** — chart / legend / axis / card / table / control / layout / typography / icon / other
+- **Category** — chart / legend / axis / card / table / control / atom / typography / layout
+- **Element name** — **MUST come from `templates/design-chart-taxonomy.md`** (closed set). If no match found, STOP and ask user to extend the taxonomy with rationale.
 - **Reuse count** — how many times does it appear across the entire design?
 - **Owner layer** — element / widget-internal / page-internal
+### Visual distinguisher decision rules (consult taxonomy)
+Before naming an element, apply the visual distinguisher rules from the taxonomy:
+- **Bar chart?** → is it stacked/grouped, horizontal/vertical, percentage/absolute? These are ALL distinct element contracts.
+- **Circular?** → pie vs donut (hole in center?) vs gauge (partial arc?)
+- **Line?** → single vs multi, stepped vs smooth, with area or without
+**Anti-pattern to avoid**: "it has bars so it's a bar chart" → WRONG. The failure mode is picking `chart-bar-grouped-vertical` when the design is `chart-bar-stacked-horizontal-percentage`. These render completely differently with completely different data bindings.
 **Promotion rule**: an item becomes an **element contract** if:
 - It appears ≥2 times across the design, OR
 - It has non-trivial visual spec (≥5 distinct spec properties), OR
@@ -60,6 +79,10 @@ For each row in the inventory, assign:
 Otherwise, it stays internal to its widget or page (no contract needed).
+### Atoms are NOT optional
+Icons, badges, chips, dividers, avatars, status dots, spinners — every small artifact that appears in the design gets an element contract if it meets the promotion rule. These are the #1 most-missed tier and produce the "feels off" verification result.
 ## Step 3: Identify Widgets
 A **widget** is a reusable composition of elements + data binding that appears as a visual group in the design. Examples: "Revenue Breakdown" (donut + legend + title + filter), "Stat Strip" (4× stat-card-with-delta).

package/commands/gsd-t-execute.md CHANGED Viewed

@@ -632,6 +632,33 @@ each one matches — not assume it does. 'Looks close' is not a verdict.
 'Appears to match' is not a verdict. The only valid verdicts are MATCH
 (with proof) or DEVIATION (with specifics).
+## Step 0: Data-Labels Cross-Check (MANDATORY — run FIRST)
+Before any visual comparison, verify the built UI is rendering the CORRECT
+DATA from the design. This is the most common failure mode: agents use
+placeholder data (Calculator/Planner/Tracker) while the design shows real
+labels (Steps to Stay Covered/Broker Contact). The verifier then compares
+bar-shapes only and declares MATCH — while the content is catastrophically
+wrong.
+1. For EACH element contract under .gsd-t/contracts/design/elements/
+   (or each section of flat .gsd-t/contracts/design-contract.md):
+   a. Read the 'Test Fixture' section — extract every label, value, percentage
+   b. Open the built UI in the browser
+   c. Inspect the rendered element (via DOM or screenshot OCR)
+   d. For EACH label/value/percentage in the Test Fixture:
+      - Does it appear verbatim in the rendered UI?
+      - If NO → immediate ❌ DEVIATION (severity CRITICAL)
+        Log: 'Test Fixture label {X} not found in rendered UI. Found instead: {Y}.'
+      - If YES → ✅ MATCH for that specific label/value
+2. Count: '{N}/{total} labels+values from Test Fixture appear correctly in UI'
+3. If ANY Test Fixture label or value is missing from the rendered UI:
+   The component is rendering WRONG DATA. This is a CRITICAL deviation.
+   No amount of visual polish can redeem wrong data. Mark the element
+   DEVIATION and continue (do not skip the rest — but flag the severity).
 ## Step 1: Get the Design Reference
 Read .gsd-t/contracts/design-contract.md for the source reference.

package/commands/gsd-t-quick.md CHANGED Viewed

@@ -259,7 +259,13 @@ comparison table. You write ZERO feature code.
 FAIL-BY-DEFAULT: Every visual element starts as UNVERIFIED. Prove each matches.
-1. Read .gsd-t/contracts/design-contract.md for design source reference
+STEP 0 (MANDATORY FIRST): Data-labels cross-check.
+For each element contract (or design-contract.md section), read the Test Fixture.
+Verify EVERY label, value, percentage from the fixture appears verbatim in the
+rendered UI. If any is missing → CRITICAL DEVIATION (wrong data). Wrong data
+cannot be redeemed by visual polish.
+1. Read .gsd-t/contracts/design-contract.md (flat) OR .gsd-t/contracts/design/ (hierarchical) for design source reference + Test Fixtures
 2. Get design reference (Figma MCP screenshot, or design images from contract)
 3. Start dev server, open the built frontend in browser (Claude Preview/Chrome MCP/Playwright)
 4. Open the original design reference in a second browser view

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.58.10",
+  "version": "2.59.10",
   "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 ADDED Viewed

@@ -0,0 +1,265 @@
+# Design Chart & Atom Taxonomy (Closed Set)
+When decomposing a design into element contracts, you MUST pick from this enumerated list. DO NOT invent element names. If a design element doesn't fit any of these, STOP and ask the user to extend the taxonomy before proceeding.
+## Why this is a closed set
+The catastrophic failure mode is: agent sees "bars" in Figma, picks `chart-bar-grouped-vertical`, but the design is actually `chart-bar-stacked-horizontal-percentage`. Different element, different contract, different data binding. Closed enumeration with visual distinguishers prevents this.
+---
+## Charts
+### Bar charts
+| Element name                                  | Visual distinguisher                                                                 |
+|------------------------------------------------|--------------------------------------------------------------------------------------|
+| `chart-bar-horizontal-single`                  | One bar per category, horizontal orientation, single series                          |
+| `chart-bar-vertical-single`                    | One bar per category, vertical orientation, single series                            |
+| `chart-bar-grouped-horizontal`                 | Multiple bars per category SIDE-BY-SIDE, horizontal, ≥2 series (legend required)     |
+| `chart-bar-grouped-vertical`                   | Multiple bars per category SIDE-BY-SIDE, vertical, ≥2 series (legend required)       |
+| `chart-bar-stacked-horizontal`                 | Segments STACKED in one bar per category, horizontal, ≥2 series with absolute values |
+| `chart-bar-stacked-vertical`                   | Segments STACKED in one bar per category, vertical, ≥2 series with absolute values   |
+| `chart-bar-stacked-horizontal-percentage`      | SINGLE horizontal bar, 100% width, segments sum to 100% (distribution viz)           |
+| `chart-bar-stacked-vertical-percentage`        | SINGLE vertical bar, 100% height, segments sum to 100%                               |
+| `chart-bar-diverging-horizontal`               | Bars extend left AND right from a center axis (sentiment, pos/neg)                   |
+| `chart-bar-range-horizontal`                   | Floating bars showing min-max range (no origin axis)                                 |
+| `chart-bar-waterfall-vertical`                 | Sequential bars showing cumulative change, pos/neg                                   |
+**Decision rule for bar charts:**
+1. Does the chart show ONE bar with segments that sum to 100%? → `*-stacked-*-percentage`
+2. Does the chart show multiple bars stacked together? → `*-stacked-*` (non-percentage if absolute values shown)
+3. Does the chart show multiple bars side-by-side per category? → `*-grouped-*`
+4. Single-series, one bar per category? → `*-single`
+### Line / area charts
+| Element name                     | Visual distinguisher                                                 |
+|----------------------------------|----------------------------------------------------------------------|
+| `chart-line-single`              | One line, continuous x-axis                                          |
+| `chart-line-multi`               | ≥2 lines, shared x-axis, legend required                             |
+| `chart-area-single`              | Line with filled area below                                          |
+| `chart-area-stacked`             | Multiple filled areas stacked (summed)                               |
+| `chart-area-stacked-percentage`  | Multiple filled areas stacked to 100%                                |
+| `chart-line-step`                | Stepped line (no diagonal connectors)                                |
+| `chart-line-smooth`              | Smoothed/curved line (bezier)                                        |
+### Circular charts
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `chart-pie`               | Full circle, no hole                                      |
+| `chart-donut`             | Circle with center hole, may show center label/value      |
+| `chart-donut-gauge`       | Partial donut (half or quarter circle) as gauge/progress  |
+| `chart-radial-bar`        | Concentric arcs, one per category                         |
+| `chart-polar`             | Radial grid with data plotted by angle                    |
+### Distribution / comparison
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `chart-scatter`           | Points on x/y plane, no connecting lines                  |
+| `chart-bubble`            | Scatter with variable point size (z-axis)                 |
+| `chart-heatmap`           | Grid of cells with color intensity                        |
+| `chart-treemap`           | Nested rectangles sized by value                          |
+| `chart-histogram`         | Bars showing distribution over continuous range           |
+| `chart-boxplot`           | Box + whiskers showing quartiles                          |
+### Inline / mini
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `chart-sparkline-line`    | Tiny inline line chart, no axes                           |
+| `chart-sparkline-bar`     | Tiny inline bar chart, no axes                            |
+| `chart-sparkline-area`    | Tiny inline filled area, no axes                          |
+| `chart-progress-bar`      | Horizontal bar showing % complete                         |
+| `chart-progress-ring`     | Circular ring showing % complete                          |
+### Flow / hierarchy
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `chart-sankey`            | Flow diagram with weighted links                          |
+| `chart-funnel`            | Decreasing bars/trapezoids showing attrition              |
+| `chart-chord`             | Circular chord diagram                                    |
+### Geo
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `chart-choropleth`        | Map with regions colored by value                         |
+| `chart-symbol-map`        | Map with points/symbols at locations                      |
+---
+## Axes (referenced by charts via `extends`)
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `axis-x-categorical`      | Category labels on x-axis                                 |
+| `axis-x-time`             | Time/date labels on x-axis                                |
+| `axis-x-numeric`          | Numeric scale on x-axis                                   |
+| `axis-y-categorical`      | Category labels on y-axis                                 |
+| `axis-y-numeric`          | Numeric scale on y-axis                                   |
+| `axis-y-log`              | Logarithmic y-axis                                        |
+| `axis-y-dual`             | Two y-axes (left + right) with different scales           |
+---
+## Legends
+| Element name               | Visual distinguisher                                      |
+|----------------------------|-----------------------------------------------------------|
+| `legend-horizontal-top`    | Horizontal row above chart                                |
+| `legend-horizontal-bottom` | Horizontal row below chart                                |
+| `legend-vertical-left`     | Vertical column left of chart                             |
+| `legend-vertical-right`    | Vertical column right of chart                            |
+| `legend-inline`            | Labels placed directly on chart (no separate legend area) |
+| `legend-interactive`       | Legend items toggle series visibility on click            |
+---
+## Cards / Containers (widget chrome, but each is itself an element)
+| Element name                    | Visual distinguisher                                                    |
+|---------------------------------|-------------------------------------------------------------------------|
+| `stat-card`                     | Label + large value                                                     |
+| `stat-card-with-delta`          | Label + value + delta indicator (↑↓ + % change)                         |
+| `stat-card-with-sparkline`      | Label + value + inline sparkline                                        |
+| `stat-card-with-icon`           | Label + value + icon tile (colored square/circle with icon)             |
+| `stat-card-kpi-large`           | Large value centered, small label below (used above charts)             |
+| `card-bordered`                 | Generic card with border + padding                                      |
+| `card-elevated`                 | Generic card with shadow                                                |
+---
+## Tables
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `table-dense`             | Tight row height, small padding                           |
+| `table-comfortable`       | Standard row height                                       |
+| `table-zebra`             | Alternating row backgrounds                               |
+| `table-striped-header`    | Only header row has distinct background                   |
+---
+## Controls
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `button-primary`          | Filled, brand color                                       |
+| `button-secondary`        | Outlined or muted fill                                    |
+| `button-ghost`            | No border/fill, text + hover state only                   |
+| `button-icon`             | Icon-only button                                          |
+| `button-fab`              | Floating action button (circular, elevated)               |
+| `input-text`              | Single-line text input                                    |
+| `input-search`            | Text input with leading search icon                       |
+| `input-textarea`          | Multi-line text input                                     |
+| `select-dropdown`         | Native-or-custom select with chevron                      |
+| `select-multi`            | Multi-select (tags/chips)                                 |
+| `checkbox`                | Square binary toggle                                      |
+| `radio`                   | Circular exclusive choice                                 |
+| `toggle`                  | Binary switch                                             |
+| `slider-range`            | Continuous range input                                    |
+| `tabs-underline`          | Tabs with underline indicator                             |
+| `tabs-pill`               | Tabs rendered as pills                                    |
+| `tabs-segmented`          | Connected segmented-control style                         |
+| `filter-pill`             | Removable filter chip                                     |
+| `date-picker`             | Date input with calendar popup                            |
+| `date-range-picker`       | Date range input                                          |
+---
+## Atoms (small visual artifacts — the often-forgotten tier)
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `icon`                    | SVG/icon-font glyph — one contract if all icons share spec, multiple variants if styles differ |
+| `icon-outline`            | Stroke-only icons (if coexisting with filled variants)    |
+| `icon-filled`             | Filled icons (if coexisting with outline variants)        |
+| `logo`                    | Brand logo                                                |
+| `avatar`                  | User profile image/placeholder (circle or rounded-square) |
+| `badge`                   | Small count indicator (typically on avatar or icon)       |
+| `chip`                    | Rounded container with text (filter, tag, status)         |
+| `status-dot`              | Colored circle indicator                                  |
+| `divider-horizontal`      | Horizontal line separator                                 |
+| `divider-vertical`        | Vertical line separator                                   |
+| `spinner`                 | Loading indicator                                         |
+| `skeleton`                | Loading placeholder                                       |
+| `tooltip`                 | Hover-triggered info bubble                               |
+| `breadcrumb`              | Hierarchical nav trail                                    |
+| `pagination`              | Page number navigation                                    |
+| `tag`                     | Non-removable text label (unlike chip)                    |
+---
+## Typography
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `heading-h1`              | Page title                                                |
+| `heading-h2`              | Section title                                             |
+| `heading-h3`              | Sub-section title / widget title                          |
+| `heading-h4`              | Small heading                                             |
+| `text-body`               | Body text                                                 |
+| `text-caption`            | Small caption/metadata                                    |
+| `text-label`              | Form/field label                                          |
+| `text-mono`               | Monospaced (code, data)                                   |
+---
+## Layout primitives
+| Element name              | Visual distinguisher                                      |
+|---------------------------|-----------------------------------------------------------|
+| `container-page`          | Top-level page container with max-width                   |
+| `container-card`          | Card with padding + radius + optional border/shadow       |
+| `stack-horizontal`        | Flex row                                                  |
+| `stack-vertical`          | Flex column                                               |
+| `grid`                    | CSS grid layout primitive                                 |
+| `divider-section`         | Horizontal divider between page sections                  |
+---
+## Using this taxonomy during decomposition
+When `gsd-t-design-decompose` runs, for EACH visual element encountered in the design:
+1. **Identify the category** (chart / legend / axis / card / table / control / atom / typography / layout)
+2. **Pick the EXACT element name from this file** — do not rename, do not abbreviate
+3. **If no match found** → STOP. Report to user: "Element at Figma node {nodeId} does not match any taxonomy entry. Proposed new variant: {name}, because: {rationale}. Should I extend the taxonomy?"
+4. **Never pick a near-match** — "close enough" is exactly how horizontal stacked bar % became grouped vertical bars.
+### Visual distinguishers for ambiguous cases
+**"Is this a stacked bar or a grouped bar?"**
+- Do the bars for a single category TOUCH/STACK or sit SIDE-BY-SIDE?
+  - Touch/stack → `chart-bar-stacked-*`
+  - Side-by-side → `chart-bar-grouped-*`
+**"Is this stacked-absolute or stacked-percentage?"**
+- Do segments fill a FIXED WIDTH/HEIGHT regardless of data?
+  - Yes (all bars are same length) → `*-stacked-*-percentage`
+  - No (bars vary in length by total value) → `*-stacked-*` (non-percentage)
+**"Is this a pie or a donut?"**
+- Is there a hole in the center?
+  - Yes → `chart-donut`
+  - No → `chart-pie`
+**"Is this a bar chart or a histogram?"**
+- Are x-axis values CATEGORIES (distinct labels) or BINS (numeric ranges)?
+  - Categories → `chart-bar-*`
+  - Numeric bins → `chart-histogram`
+---
+## 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)

package/templates/element-contract.md CHANGED Viewed

@@ -85,6 +85,32 @@ Atomic visual unit. One contract per visual variant (e.g., `chart-bar-stacked-ho
 - {e.g., All series arrays MUST have length === categories.length}
 - {e.g., Values MUST be non-negative for stacked variants}
+## Test Fixture (MANDATORY — extracted from design, NOT placeholder)
+This is the EXACT data from the design source. Verification compares the built component rendered with this fixture against the Figma design. Placeholder data (Lorem, foo/bar, Calculator/Planner) is FORBIDDEN here — the verifier must be able to compare actual labels and values side-by-side.
+```json
+{
+  "__source__": "{Figma node URL or image file + node id}",
+  "__extracted_via__": "{Figma MCP get_design_context | visual analysis}",
+  "__extracted_date__": "{YYYY-MM-DD}",
+  "categories": ["{exact label 1 from design}", "{exact label 2}", "..."],
+  "series": [
+    {
+      "name": "{exact series name from design}",
+      "values": [{exact value 1}, {exact value 2}, ...]
+    }
+  ],
+  "center_value": "{exact value shown in donut center, if applicable}",
+  "center_sublabel": "{exact sublabel, if applicable}",
+  "percentages_shown": [{30}, {21}, {20}, {15}, {14}]
+}
+```
+**Verification rule**: when the component is rendered with THIS fixture, every label, every value, every percentage shown in the built UI MUST match the design. Any substitution is a DEVIATION.
 ## Responsive Behavior
 | Breakpoint | Adaptation                                                    |

package/templates/widget-contract.md CHANGED Viewed

@@ -15,16 +15,31 @@ Composition of elements + data binding + layout. Widgets SELECT and POSITION ele
 {One sentence — what this widget shows and why. E.g., "Displays revenue breakdown by product category with donut chart and accompanying legend-table, used on the dashboard Overview page and the Analytics detail page."}
-## Elements Used
+## Card Chrome Slots (MANDATORY — fill every row or explicitly mark N/A)
+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.
+## Elements Used (body composition)
 | Slot             | Element Contract                        | Rationale                          |
 |------------------|-----------------------------------------|------------------------------------|
-| {chart}          | chart-donut                             | {part-to-whole comparison}         |
-| {legend}         | legend-vertical-right                   | {6+ series, needs vertical space}  |
-| {title}          | heading-h3                              | {widget header}                    |
-| {filter}         | select-dropdown                         | {time-range selector}              |
+| {body element}   | {e.g., chart-donut}                     | {why this element}                 |
+| {sidebar}        | {e.g., legend-vertical-right}           | {why this variant}                 |
-**Rule**: Each slot references an element contract by name. Widget CANNOT override element visual spec. To customize, create a new element variant.
+**Rule**: Each slot references an element contract by name from `design-chart-taxonomy.md`. Widget CANNOT override element visual spec. To customize, create a new element variant.
 ## Layout