@tekyzinc/gsd-t 2.70.10 → 2.70.11

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [2.70.11] - 2026-04-06
+
+### Added (design pipeline — DOM box model inspection + layout arithmetic)
+- **DOM Box Model Inspection** — new mandatory verification step for fixed-height containers. Uses Playwright to evaluate `offsetHeight` vs `scrollHeight` for each child element. Flags elements where `offsetHeight > scrollHeight * 1.5` as INFLATED (symptom: `flex: 1` on a content element inflating its box beyond content size). Added to: `gsd-t-execute` (Step 5.5 inside Design Verification Agent), `gsd-t-quick` (step 8 inside Design Verification Agent), `gsd-t-design-audit` (Step 3.75).
+- **Internal Layout Arithmetic** — widget contract template now requires computed height budgets for fixed-height cards: `card_height - padding - header = body_available`, then `child1 + gap1 + child2 + ... = total_content ≤ body_available`. Forces the agent to write the math before coding — prevents `gap: 12px` when only `gap: 8px` fits.
+- **Flex Centering Anti-Pattern Rule** — `design-to-code.md` Section 8 now explicitly prohibits `flex: 1` on content elements (KPI, labels, text) for centering. Rule: `flex: 1` belongs on containers, `justify-content: center` on the parent. Children keep natural size.
+- **4 new verification checklist items** in `design-to-code.md` and `widget-contract.md`: box model inspection, layout arithmetic, no content flex:1, inflated element detection.
+
+### Why
+BDS horizontal stacked bar cards required 5 user-prompted fix iterations to get spacing right. Root cause: agent used `flex: 1` on `.kpi` to center it vertically, which inflated the element to 144px (content was 40px), displacing the chart section. The property comparison table and SVG overlay both missed this because the *positions* were close enough — the problem was *how space was distributed*, not where elements landed. DOM box model inspection catches the cause (inflated element) not just the symptom (displaced sibling).
+
 ## [2.70.10] - 2026-04-06
 
 ### Added (design pipeline — 2 new capabilities)

package/commands/gsd-t-design-audit.md

@@ -197,9 +197,35 @@ After the per-widget property comparison, run a mechanical SVG-based diff to cat
 
 This step catches spacing rhythm, alignment drift, and proportion issues that pass the per-widget property check but are visually wrong in aggregate.
 
+## Step 3.75: DOM Box Model Inspection (MANDATORY for fixed-height containers)
+
+For each card/widget with a fixed height, inspect the internal space distribution:
+
+1. **Evaluate in browser** (via Playwright) for each card body child:
+   - `offsetHeight` (layout box size), `scrollHeight` (content size), `flex-grow` (computed)
+
+2. **Flag inflated elements**: any element where `offsetHeight > scrollHeight * 1.5`
+   - This means `flex: 1` or `flex-grow: 1` is inflating the element's box beyond its content
+   - Severity: HIGH — "`.kpi` offsetHeight=144px but content only needs 40px — inflated by flex growth"
+
+3. **Verify layout arithmetic**: sum all child `offsetHeight` values + computed gaps. Compare against card body `offsetHeight`:
+   - Sum > body → content overflows (❌ DEVIATION)
+   - Sum < body by >20px with no centering strategy → space is unaccounted (❌ DEVIATION)
+
+4. **Produce box model table** per widget:
+
+```markdown
+### Box Model: {widget-name}
+
+| # | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+|---|---------|-------------|-------------|-----------|---------|
+| 1 | .kpi    | 144px       | 40px        | 1         | ❌ INFLATED |
+| 2 | .chart  | 74px        | 74px        | 0         | ✅ MATCH |
+```
+
 ## Step 4: Summary Report
 
-After all widgets are audited (property tables + SVG structural diff), produce a summary:
+After all widgets are audited (property tables + SVG structural diff + box model), produce a summary:
 
 ```markdown
 ## Design Audit Summary

package/commands/gsd-t-execute.md

@@ -785,6 +785,49 @@ aggregate visual drift that individual property checks miss.
 This step catches spacing rhythm, alignment drift, and proportion issues
 that pass the property-level check but are visually wrong in aggregate.
 
+## Step 5.5: DOM Box Model Inspection (MANDATORY for fixed-height containers)
+
+The property table catches wrong values. The SVG overlay catches wrong positions.
+This step catches wrong SPACE DISTRIBUTION — elements whose box model is inflated
+by flex growth, pushing siblings out of position even when the visual appears close.
+
+For each card/widget with a fixed height (container_height is not 'auto'):
+
+1. Use Playwright to evaluate in the browser:
+   ```javascript
+   // For each child element of the card body:
+   const children = await page.$$eval('.card-body > *', els =>
+     els.map(el => ({
+       selector: el.className,
+       offsetHeight: el.offsetHeight,
+       scrollHeight: el.scrollHeight,
+       computedFlex: getComputedStyle(el).flex,
+       computedFlexGrow: getComputedStyle(el).flexGrow,
+     }))
+   );
+   ```
+
+2. Flag any element where `offsetHeight > scrollHeight * 1.5`:
+   This means the element's layout box is ≥50% larger than its content.
+   Symptom: element is using `flex: 1` or `flex-grow: 1` and inflating.
+   ❌ DEVIATION (severity HIGH): '{selector} offsetHeight={X}px but
+   content only needs {scrollHeight}px — inflated by flex growth.
+   Fix: remove flex:1 from this element, apply justify-content:center
+   on its parent container instead.'
+
+3. Verify layout arithmetic:
+   - Read the widget contract's Internal Layout Arithmetic section
+   - Sum all child offsetHeights + computed gaps
+   - Compare against the card body's offsetHeight
+   - If sum > body height → ❌ DEVIATION: content overflows
+   - If sum < body height by >20px with no centering strategy → ❌ DEVIATION
+
+4. Produce box model table:
+   | # | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+   |---|---------|-------------|-------------|-----------|---------|
+   | 1 | .kpi    | 144px       | 40px        | 1         | ❌ INFLATED |
+   | 2 | .chart  | 74px        | 74px        | 0         | ✅ MATCH |
+
 ## Step 6: Report Deviations
 
 For each ❌ DEVIATION, write a specific finding:

package/commands/gsd-t-quick.md

@@ -288,7 +288,14 @@ cannot be redeemed by visual polish.
       | # | SVG Element | SVG Position | Built Position | Δ px | Verdict |
    g. Flag unmapped SVG elements as MISSING, unmapped DOM elements as EXTRA
    This catches aggregate visual drift that property-level checks miss.
-8. Write results (property table + SVG diff) to .gsd-t/contracts/design-contract.md
+8. DOM Box Model Inspection (for fixed-height containers):
+   a. For each card body child, evaluate: offsetHeight, scrollHeight, flex-grow
+   b. Flag elements where offsetHeight > scrollHeight * 1.5 as INFLATED
+      (element using flex:1 when it shouldn't — box larger than content)
+   c. Verify layout arithmetic: sum of child heights + gaps = body height
+   d. Produce box model table:
+      | Element | offsetHeight | scrollHeight | flex-grow | Verdict |
+9. Write results (property table + SVG diff + box model) to .gsd-t/contracts/design-contract.md
    under '## Verification Status'
 9. Any ❌ → append to .gsd-t/qa-issues.md with [VISUAL] tag
 10. Report: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND ({count})"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.70.10",
+  "version": "2.70.11",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 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/stacks/design-to-code.md

@@ -281,6 +281,47 @@ MANDATORY:
 
 **GOOD** — Extracting gap as exactly `24px` from the design, then: `display: flex; gap: 1.5rem; /* 24px — design contract: section-gap */`
 
+### Flex Centering Anti-Pattern (MANDATORY)
+
+```
+NEVER use flex: 1 on a content element to center its text/content.
+flex: 1 makes the ELEMENT GROW to fill available space — the content
+centers within an oversized box, but the box itself displaces siblings.
+
+  WRONG — content element grows, inflated box shifts layout:
+    .kpi { flex: 1; display: flex; justify-content: center; }
+
+  RIGHT — parent grows, children keep natural size:
+    .body { flex: 1; display: flex; flex-direction: column;
+            justify-content: center; }
+    .kpi  { /* no flex: 1 — natural height only */ }
+
+  RULE: flex: 1 belongs on CONTAINERS, not on CONTENT elements.
+        To center content vertically, apply justify-content: center
+        on the parent — never flex: 1 on the child.
+```
+
+### Fixed-Height Container Arithmetic (MANDATORY)
+
+```
+When a card or container has a fixed height, BEFORE writing any CSS:
+  1. Compute the total available body height:
+     body_available = card_height - padding_top - padding_bottom
+                      - header_height - header_to_body_gap
+  2. List every child element's height (from the design contract)
+  3. List every gap between children
+  4. SUM them: total_content = child1 + gap1 + child2 + gap2 + ...
+  5. Compare: total_content MUST ≤ body_available
+  6. If total_content < body_available:
+     Document the centering strategy (justify-content: center on parent)
+  7. If total_content > body_available:
+     The design extraction is wrong — go back to Figma
+
+  This arithmetic goes in the widget contract's Internal Layout
+  Arithmetic section. The implementation MUST match the arithmetic.
+  If gap: 12px makes the math exceed body_available, use gap: 8px.
+```
+
 ---
 
 ## 9. Responsive Breakpoint Strategy
@@ -628,4 +669,7 @@ Before marking any design implementation task as complete:
 - [ ] Accessibility: focus indicators, alt text, ARIA where needed, 44px touch targets
 - [ ] No magic numbers — every value is documented or uses a design token
 - [ ] SVG structural overlay comparison completed — geometry diff ≤2px per element
+- [ ] DOM box model inspection passed — no inflated elements (offsetHeight >> scrollHeight)
+- [ ] Layout arithmetic verified — child heights + gaps = body available height (fixed-height cards)
+- [ ] No content element uses `flex: 1` for centering — only parent containers
 - [ ] Verification results logged in design contract Verification Status table

package/templates/widget-contract.md

@@ -95,6 +95,41 @@ This section specifies how elements are sized, spaced, and aligned WITHIN the ca
 - `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).
 
+### Internal Layout Arithmetic (MANDATORY for fixed-height cards)
+
+When `container_height` is fixed (not `auto`), you MUST compute and document the internal height budget. The math must add up exactly — no approximation.
+
+```
+card_height:           {e.g., 334px}
+card_padding_top:      {e.g., 16px}
+card_padding_bottom:   {e.g., 16px}
+header_height:         {title + subtitle + gap} = {e.g., 48px}
+header_to_body_gap:    {e.g., 16px}
+─────────────────────────────────────────────────
+body_available:        {card_height - padding_top - padding_bottom
+                        - header_height - header_to_body_gap}
+                       = {e.g., 334 - 16 - 16 - 48 - 16 = 238px}
+
+body_breakdown:
+  kpi_height:          {natural content height, e.g., 40px — NOT flex:1}
+  kpi_to_chart_gap:    {e.g., 16px}
+  chart_section:       {bar + gap + labels + gap + legend}
+                       = {e.g., 30 + 8 + 12 + 8 + 16 = 74px}
+  ────────────────────
+  total_body_content:  {40 + 16 + 74 = 130px}
+  remaining_space:     {238 - 130 = 108px}
+
+centering_strategy:    {e.g., body uses flex-column + justify-content: center
+                        to vertically center the content group (KPI + chart)
+                        in the 238px body area. KPI keeps natural height.}
+```
+
+**Rules:**
+- Every row must be an exact pixel value extracted from the Figma design
+- The sum of all body content MUST equal `body_available` OR explicitly document how remaining space is distributed (centering, padding, etc.)
+- **NEVER use `flex: 1` on a content element (KPI, label, text) to center it.** `flex: 1` makes the element grow to fill available space, inflating its box model. Use `flex: 1` + `justify-content: center` on the PARENT container instead. The parent grows; children keep natural size.
+- If the math doesn't add up, the design extraction is incomplete — go back to Figma
+
 ## Data Binding
 
 **Widget input shape:**
@@ -189,6 +224,9 @@ Widget-level verification runs AFTER all referenced elements pass their own veri
 - [ ] 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)
+- [ ] Layout arithmetic adds up: sum of child heights + gaps = body_available (fixed-height cards only)
+- [ ] No content element uses `flex: 1` for centering — only parent containers may use `flex: 1`
+- [ ] DOM box model check: no element's offsetHeight >> its content height (inflated box = wrong flex)
 - [ ] Responsive breakpoints adapt as specified
 - [ ] Data binding produces correct element inputs (spot-check with sample data)
 - [ ] Inter-element interactions fire (hover sync, click propagation)