@dashforge/tw: <Stack gap='md'> silently renders as 0 — token values not accepted (G-27)

[kensaadi]

Symptom

@dashforge/tw <Stack> accepts a gap prop typed as string. At runtime, only NUMERIC values from a fixed set are honored: "0" | "0.5" | "1" | "2" | "3" | "4" | "6" | "8" | "12" | "16" | "24". Passing size tokens (gap="xs", "sm", "md", "lg", "xl") is silently ignored — TS accepts the string, runtime falls back to 0, and no warning is emitted.

Why this is bad

• Consumers coming from MUI (spacing="md") or any design system that speaks size tokens will make this mistake constantly
• Zero signal: TS is happy, no runtime error, no console warning — layout just looks broken
• Cost Blueprint hours to notice: children were rendered flush with no visible reason

Repro

<Stack direction="column" gap="md">
  <Chip>a</Chip>
  <Chip>b</Chip>
</Stack>

Expected: children separated. Actual: rowGap: normal, children flush.

Discovered while

Refactoring the Blueprint Builder V2 shell. Filed in Blueprint's dogfood report as G-27 (severity: medium — silent-fail DX bug).

Workaround applied in Blueprint

Replaced all gap="xs|sm|md|lg|xl" with numeric equivalents ("2", "3", "4", "6", "8").

Acceptance (pick one)

• Option A — strict types: tighten the prop TS union to the exact literal set of numeric values; unknown strings become a compile error
• Option B — accept both scales: map size tokens ("xs" | "sm" | "md" | "lg" | "xl") to numeric equivalents at runtime, keep the numeric scale as-is (backward compat)
• Minimum: dev-mode console.warn when an unknown gap value is passed (works alongside either A or B)
• Consider renaming gap → space to disambiguate from flex gap semantics (documents-only; would be a breaking change requiring a migration note)
• MDX docs page in dashforge-docs-lab lists the accepted values explicitly

Related

• [1.2.0] Component Defaults System — theme.components + slotProps (Option C) #60 Option C: adds a gap axis to theme.components.Stack.defaults — only meaningful once the runtime value set is unambiguous
• Same silent-fail pattern is worth auditing on other size/spacing axes across the catalog

[kensaadi]

Shipped in cc323f6.

Root cause identified: a tailwind-variants inference quirk. Because the gap variant object mixes numeric keys (0, 1, 2, …) with a single string-literal key ('0.5'), VariantProps<typeof stackVariants> widens the resolved type to string | undefined instead of the strict literal union. That's why TS silently accepted gap="md" — the type check ran, it just checked against string.

Fix picked: Option A (strict types) + the dev-warn add-on. Rejected Option B (accept both scales at runtime) because it doubles the API surface, creates a new "which scale wins on theme.defaults?" failure mode, and doesn't solve the underlying widening bug. Rejected the gap → space rename — the flex-container semantics are already unambiguous once TS narrows correctly.

Three-part fix:

1. stack.variants.ts — added an explicit StackGap literal union (0 | 0.5 | 1 | 2 | 3 | 4 | 6 | 8 | 12 | 16 | 24) that bypasses the VariantProps widening, plus a frozen STACK_GAP_VALUES runtime allow-list.
2. stack.types.ts — StackProps.gap and StackVariantProps.gap now widen to StackGap instead of the broken StackVariants['gap']. Consumers get autocomplete on <Stack gap> AND on theme.components.Stack.defaults.gap.
3. Stack.tsx — process.env.NODE_ENV !== 'production' guard runs STACK_GAP_VALUES.includes(gap) on every render and warns once per unknown value (module-level Set<unknown> de-dupe). The warning message names the passed value AND lists the accepted set so consumers have an actionable pointer.

Behavior after fix:

<Stack gap="md" />        // ❌ TS error: 'md' is not assignable to StackGap
<Stack gap={5} />          // ❌ TS error: 5 is not on the numeric scale
<Stack gap={3} />          // ✅
<Stack gap={0.5} />        // ✅
<Stack gap={(x as never)} />  // TS bypass → dev-warn fires at runtime

Tests: 6 new regression cases on Stack.

• Warn fires on gap="md" (unknown string)
• Warn fires on gap={5} (off-scale numeric)
• Warn does NOT fire on gap={0} / {0.5} / {3} / {24}
• Warn does NOT fire when gap is omitted
• Same unknown value across two Stacks warns exactly once (module-level de-dupe)
• No warn in NODE_ENV=production

Regression check: full @dashforge/tw suite — 109 files / 1692 tests pass, 1 skipped, 0 fail (was 1686 before, +6 from the new tests). Zero regression on Stack's pre-existing 52 tests.

Not shipped here (out of scope for this issue):

• Docs page in dashforge-docs-lab listing the accepted gap values — tracked separately as a docs task.
• Rename gap → space — no design payoff, not doing it.
• Adjacent risk audit: the same VariantProps widening likely affects Box's spacing axes (p, px, py, m, mx, my) and any other tv() variant object that mixes numeric literals with a string key like '0.5'. Worth a follow-up sweep but not blocking this Blueprint-facing fix.