fix(spec): say what the dashboard gap author decides, not what the renderer consumes (#15512)

`ui/dashboard`'s `gap` key described its value to app authors in the vocabulary
of a CSS library they never chose and cannot act on. Two independent producer
strings carried that wording, feeding two independent customer-facing surfaces:

  packages/spec/src/ui/dashboard.form.ts  helpText  -> Studio property panel
  packages/spec/src/ui/dashboard.zod.ts   describe  -> content/docs/references/ui/dashboard.mdx

Fixing only the first would have relocated the divergence rather than removed
it: the Studio panel would say what an author decides while the published
reference page still named the library. That is the same producer/consumer
split this card exists to close, one level up.

Both strings now read `Space between widgets, in steps of 0.25rem (4 = 1rem)` --
what the author decides, plus the magnitude, in a CSS unit rather than a
framework scale. The magnitude is stated as measured: the dashboard renderer
sets the grid gap as an inline style computed from this key, so every accepted
value is linear at 0.25rem per step.

No schema change: `gap` stays `z.number().int().min(0).optional()`. `columns` is
untouched on both of its producer lines -- 12 is an author-visible fact about
the grid, not a framework detail.

Generated artifacts regenerated by the repo's own tooling, never by hand:
`gen:docs` for the reference row, `check-i18n-bundles.mjs --write` for the `en`
metadata-forms leaf (a mechanical copy of the form source). Translated locales
are untouched -- regeneration fills gaps and never overwrites a leaf.


Claude-Session: https://claude.ai/code/session_01G4138K1EG7kQ81FNba5Kp4

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/dashboard-gap-author-vocabulary.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/spec": patch
+"@objectstack/platform-objects": patch
+---
+
+fix(spec): the dashboard `gap` field no longer describes itself to app authors in Tailwind vocabulary
+
+`ui/dashboard`'s `gap` key told app authors its value in the vocabulary of a CSS
+library they never chose and cannot act on. **Two** independent producer strings
+carried that wording, and they feed two independent customer-facing surfaces:
+
+- `dashboardForm`'s `helpText` — `Grid gap (Tailwind units)` — rendered verbatim in
+  the Studio property panel, which is spec-driven and feeds this form straight into
+  the generic form renderer.
+- `DashboardSchema.gap`'s `.describe()` — `Grid gap in Tailwind spacing units` —
+  rendered as this field's row in the published reference page
+  `content/docs/references/ui/dashboard.mdx`. The reference corpus renders
+  `.describe()`, never `helpText`.
+
+Both now read **Space between widgets, in steps of 0.25rem (4 = 1rem)**: what the
+author decides, plus the magnitude, stated in a CSS unit instead of a framework's
+scale. The magnitude had to survive the rewrite rather than be dropped with the
+framework name — the number is a spacing step, so `4` means `1rem` and not `4px`,
+and an author who lost that would come away knowing less than before.
+
+The step size is stated as measured rather than inferred: the dashboard renderer
+sets the grid gap as an inline style computed from this key, so every accepted
+value is linear and one step is exactly `0.25rem`. "Tailwind units" was doubly
+wrong — it named an implementation dependency, and it named one the consumer of
+this key does not have.
+
+**No schema change.** `gap` stays `z.number().int().min(0).optional()` and accepts
+exactly what it accepted before; nothing is added to or removed from any public
+surface. `columns` is deliberately untouched on both of its producer lines —
+`12` is an author-visible fact about the grid being laid out, not a framework
+detail — and this is one field's two strings, not a sweep for framework words.
+
+The `en` metadata-forms translation bundle is a mechanical copy of the form source,
+so it is regenerated to match. Translated locales are not touched: regeneration
+fills gaps only and never overwrites an existing leaf.

content/docs/references/ui/dashboard.mdx

@@ -33,7 +33,7 @@ const result = DashboardSchema.parse(data);
 | **header** | `{ showTitle: boolean; showDescription: boolean; actions?: object[] }` | optional | Dashboard header configuration |
 | **widgets** | `{ id: string; title?: string \| Record<string, string>; description?: string \| Record<string, string>; type: Enum<'bar' \| 'horizontal-bar' \| 'column' \| 'line' \| 'area' \| 'pie' \| 'donut' \| …>; … }[]` | ✅ | Widgets to display |
 | **columns** | `integer` | optional | Number of grid columns (default 12) |
-| **gap** | `integer` | optional | Grid gap in Tailwind spacing units |
+| **gap** | `integer` | optional | Space between widgets, in steps of 0.25rem (4 = 1rem) |
 | **refreshInterval** | `number` | optional | Auto-refresh interval in seconds |
 | **dateRange** | `{ field?: string; defaultRange: Enum<'today' \| 'yesterday' \| 'this_week' \| 'last_week' \| 'this_month' \| 'last_month' \| …>; allowCustomRange: boolean }` | optional | Global dashboard date range filter configuration |
 | **globalFilters** | `{ name?: string; field: string; object?: string; label?: string \| Record<string, string>; … }[]` | optional | Global filters that apply to all widgets in the dashboard |

packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts

@@ -932,7 +932,7 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       },
       gap: {
         label: "Gap",
-        helpText: "Grid gap (Tailwind units)"
+        helpText: "Space between widgets, in steps of 0.25rem (4 = 1rem)"
       },
       refreshInterval: {
         label: "Refresh Interval",

packages/spec/src/ui/dashboard.form.ts

@@ -22,7 +22,7 @@ export const dashboardForm = defineForm({
       columns: 3,
       fields: [
         { field: 'columns', type: 'number', colSpan: 1, helpText: 'Grid columns (default 12)' },
-        { field: 'gap', type: 'number', colSpan: 1, helpText: 'Grid gap (Tailwind units)' },
+        { field: 'gap', type: 'number', colSpan: 1, helpText: 'Space between widgets, in steps of 0.25rem (4 = 1rem)' },
         { field: 'refreshInterval', type: 'number', colSpan: 1, helpText: 'Auto-refresh (seconds)' },
         { field: 'header', type: 'composite', colSpan: 3, helpText: 'Dashboard header config (title, subtitle, actions)' },
       ],

packages/spec/src/ui/dashboard.zod.ts

@@ -899,8 +899,8 @@ export const DashboardSchema = lazySchema(() => strictObject({
   /** Grid column count — defaults to 12 for a standard 12-column grid */
   columns: z.number().int().min(1).max(24).optional().describe('Number of grid columns (default 12)'),
 
-  /** Grid gap in Tailwind spacing units (e.g. 4 = 1rem) */
-  gap: z.number().int().min(0).optional().describe('Grid gap in Tailwind spacing units'),
+  /** Space between widgets, in steps of 0.25rem (4 = 1rem) */
+  gap: z.number().int().min(0).optional().describe('Space between widgets, in steps of 0.25rem (4 = 1rem)'),
 
   /** Auto-refresh */
   refreshInterval: z.number().optional().describe('Auto-refresh interval in seconds'),