[mgoldsborough]

The host owns the gutter's value, the same way it owns the colour, font and radius tokens it injects. The kit owns the mechanism, the app decides where content insets and where it bleeds, and the host never pads the app's slot.

Before this change a host could set only --nb-gutter. That pins one value at every width, so it turns off the narrowing that AppFrame does by container query.

Change

• tokens.gutter is now var(--nb-gutter, var(--nb-gutter-auto, var(--nb-gutter-wide, 1.5rem))), and AppFrame's narrow rule sets --nb-gutter-auto: var(--nb-gutter-narrow, 1rem) instead of a literal 1rem. A host can set both values and still get the kit's breakpoint. --nb-gutter still pins one value at every width. When no host var is set, the gutter is unchanged: 1.5rem, and 1rem in a frame 640px wide or narrower.

• @nimblebrain/synapse/ui now exports the defaults as named constants, so a host can test its values against the kit's:

  • GUTTER_DEFAULT ("1.5rem")
  • GUTTER_NARROW_DEFAULT ("1rem")
  • GUTTER_NARROW_BREAKPOINT (640, in px)

  tokens.gutter and the container rule are built from these constants.

• The comment on the gutter token now states who owns what. The AppFrame and tokens docs pages are updated to match.

• Releases as 0.38.0, a minor bump because this is additive. This PR bumps package.json, package-lock.json and the Python __client_version__, and adds the CHANGELOG entry.

Verification

• npm run ci passes: lint, typecheck, build, size budget, and 657 tests.
• The built synapse-ui.iife is byte-identical to the vendored Python asset, so it does not need re-vendoring.
• Tests: the existing literal assertions on the token and the container rule, with the token now expecting the --nb-gutter-wide fallback and the rule var(--nb-gutter-narrow, 1rem), plus a new test that the three constants are exported from the ui entry with those values.

[mgoldsborough]

QA Review: PR #133

Scope: 11 files, +65/−25 · worktree: supplied review worktree (creation and dependency installation skipped as requested) · reviewed: 4f7365d · CI: green
Round: 1
Risk: LOW
Why this exists: Hosts need to customize wide and narrow gutters while preserving AppFrame's responsive breakpoint.

Critical (must fix)

None.

Fix in-PR (apply mechanically — no adjudication essay expected)

None.

Suggestions (optional)

None.

What Looks Good

• ADDITIVE contract change: both host variables have existing-value fallbacks, and --nb-gutter retains precedence at every width.
• Exported constants drive the token and container rule; tests assert their public exports and literal CSS contract, consistent with the documented test-DOM limitations.
• Version metadata, changelog, and component documentation agree. No dependencies, transport contracts, or security boundaries change.
• All prefetched required and additional checks pass. Relied on CI rather than rerunning its suite; no files were written.

Body claims

• ✅ The fallback chain, narrow rule, default values, breakpoint, and three exports match the implementation.
• ✅ The 0.38.0 version updates and described test changes are present.
• ✅ Passing CI covers lint, typecheck, build, size budget, tests, and the byte-for-byte vendored-IIFE freshness gate.
• The supplied check summary does not expose the exact test count; the body's 657-test total was not independently verified.

machine record

{
  "kind": "review",
  "pr": 133,
  "round": 1,
  "reviewed": "4f7365dba0ad174d1a0d39658d23e321e90e3b82",
  "delta_base": null,
  "ci": "green",
  "risk": "LOW",
  "stop_gate": "n/a",
  "verdict": "No findings; eligible for qa-reviewed.",
  "label": "eligible-on-green",
  "findings": []
}