feat(spec): declare record:details section headerColor as a closed six-token enum (#12616)

* feat(spec): declare record:details section headerColor as a closed six-token enum

The #11661 refusal's recorded reason (template-literal Tailwind read
generating no CSS) was repaired by objectui#6294's literal-class lookup;
maintainer ruling A (2026-08-26) declares the key as z.enum over
exactly the six tokens that lookup ships: muted, muted/50, accent,
primary/10, secondary/10, destructive/10. Declared = enforced — values
outside the enum (including bg-* pass-through spellings) are refused at
authoring time instead of shipping a header that silently does not paint.
Optional, no schema default; the title withhold stands and its pin flips
consciously, as its own comment anticipated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012xGvxcwPRTJfA7RfjXEYA4

* docs(spec): regenerate ui/component reference for the headerColor enum

gen:docs wrote this page; gen:schema produced no tracked-file changes
(authorable-surface.base.json lags by design — baseRev allowance).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012xGvxcwPRTJfA7RfjXEYA4

---------

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

Author: os-zhuang

.changeset/record-details-headercolor-enum-12126.md

@@ -0,0 +1,5 @@
+---
+"@objectstack/spec": minor
+---
+
+Declare `headerColor` on the strict `record:details` section schema as a closed enum (#12126, maintainer ruling A 2026-08-26). The key was deliberately refused by #11661 because the renderer's only read was a template-literal Tailwind class that generated no CSS; objectui#6294 (merged 2026-08-25) replaced that read with a lookup of complete class literals, so the refusal outlived its recorded reason. The vocabulary is exactly the six tokens that lookup ships — `muted` | `muted/50` | `accent` | `primary/10` | `secondary/10` | `destructive/10` — tints only (`CardHeader` sets no foreground, so solids would need a paired `text-*-foreground`). Declared = enforced: `objectstack validate` refuses anything outside the enum at authoring time — including the renderer's `bg-*` pass-through spellings, which render only when the host app's Tailwind build happens to generate the class — instead of shipping a header that silently does not paint. Optional with NO schema default; the `title` withhold from #11661 stands unchanged.

content/docs/references/ui/component.mdx

@@ -753,7 +753,7 @@ Sort field and direction pair
 | :--- | :--- | :--- | :--- |
 | **columns** | `Enum<'1' \| '2' \| '3' \| '4'>` | optional (default: `"2"`) | Number of columns for field layout (1-4) |
 | **layout** | `never` | optional | [REMOVED] `record:details` property `layout` was removed in @objectstack/spec 17.0.0 (#6946, ADR-0087 D2) — its declared `auto` \| `custom` semantics were never implemented: the renderer tests `layout` only against `inline` \| `compact`, two values the schema never permitted, so both legal values took the same branch and the key selected nothing. Delete the key — the body is already chosen by what you author: `sections` renders the explicit groups (the old `custom`), and omitting it falls back to the object's `highlightFields` (the old `auto`). Run `os migrate meta --from 16` to list the mechanical edits for existing sources; apply them by hand. |
-| **sections** | `{ name?: string; label?: string \| Record<string, string>; columns?: integer; fields: string[]; … }[]` | optional | Field groups rendered as the detail body, in order. Object form: `{ name?, label?, columns?, fields, hideEmpty?, collapsible?, showBorder?, defaultCollapsed?, icon?, description? }`. |
+| **sections** | `{ name?: string; label?: string \| Record<string, string>; columns?: integer; fields: string[]; … }[]` | optional | Field groups rendered as the detail body, in order. Object form: `{ name?, label?, columns?, fields, hideEmpty?, collapsible?, showBorder?, defaultCollapsed?, icon?, description?, headerColor? }`. |
 | **fields** | `string[]` | optional | Explicit field list to display (optional, overrides highlightFields) |
 | **hideFields** | `string[]` | optional | Field names to omit from the body — applied to `fields` and to every section's `fields` (used to dedupe fields already shown in `record:highlights` or as the page title) |
 | **inlineEdit** | `boolean` | optional | Allow inline field editing in the detail body (renderer default: on, where the object itself is editable — set `false` to force it off). |
@@ -774,6 +774,7 @@ Sort field and direction pair
 | **defaultCollapsed** | `boolean` | optional | Start a `collapsible: true` section collapsed (renderer default: expanded). Consulted only when `collapsible` is on — a non-collapsible section never reads its collapse state. |
 | **icon** | `string` | optional | Heading icon, as a lucide icon name (kebab-case, e.g. `building-2`). A value that is not an ASCII identifier (emoji, CJK text) renders as literal text beside the heading instead. Shown where the section heading renders: a titled section, or any collapsible section. |
 | **description** | `string` | optional | Sub-heading text rendered under the section heading (plain string — the renderer applies no translation to it, unlike `label`). Renders on a titled or collapsible section; a collapsible section hides it while collapsed. |
+| **headerColor** | `Enum<'muted' \| 'muted/50' \| 'accent' \| 'primary/10' \| 'secondary/10' \| 'destructive/10'>` | optional | Section-header background tint, from the closed six-token vocabulary rendered by objectui's `record:details` header (`muted` \| `muted/50` \| `accent` \| `primary/10` \| `secondary/10` \| `destructive/10`). A value outside the enum is refused at authoring time rather than silently not painting. Omit for an untinted header. |
 
 ### Nested Shape: `RecordDetailsProps.aria`
 

packages/spec/src/ui/component.test.ts

@@ -708,28 +708,68 @@ describe('RecordDetailsProps', () => {
     expect(message).toContain('`defaultCollapse` → `defaultCollapsed`');
   });
 
-  it('still refuses the two keys #11661 deliberately withholds (`title`, `headerColor`)', () => {
-    // Both are honoured by the renderer at the pin, and both stay OUT of the
-    // accept set on purpose: `title` is a second spelling of the heading slot
-    // `label` declares (the `page:card` `body`-vs-`children` shape, which
-    // #5775 converged rather than declared) and is held for a maintainer
-    // ruling; `headerColor` reaches the DOM only as `bg-${...}`, a
-    // template-literal Tailwind class that generates no CSS under the v4
-    // source scan — dead-in-practice, so declaring it would advertise a
-    // capability the renderer does not deliver. A later batch declaring
-    // either must flip this pin consciously.
-    for (const [key, value] of [
-      ['title', 'Company'],
-      ['headerColor', 'muted'],
+  it('still refuses the one key #11661 deliberately withholds (`title`)', () => {
+    // Honoured by the renderer at the pin, and OUT of the accept set on
+    // purpose: `title` is a second spelling of the heading slot `label`
+    // declares (the `page:card` `body`-vs-`children` shape, which #5775
+    // converged rather than declared) and is held for a maintainer ruling.
+    // A later batch declaring it must flip this pin consciously.
+    //
+    // `headerColor` was withheld alongside it until #12126 (maintainer
+    // ruling A, 2026-08-26): its refusal's recorded reason — a
+    // template-literal Tailwind read that generated no CSS — was repaired by
+    // objectui#6294's literal-class lookup, so the pin flipped CONSCIOUSLY,
+    // as this comment always anticipated. The key's new accept/reject
+    // boundary is pinned by the two tests below.
+    const r = RecordDetailsProps.safeParse({
+      sections: [{ label: 'A', fields: ['a'], title: 'Company' }],
+    });
+    expect(r.success).toBe(false);
+    const message = r.success === false
+      ? r.error.issues.map((i) => i.message).join('\n')
+      : '';
+    expect(message).toContain('`title`');
+  });
+
+  it('accepts all six `headerColor` enum tokens verbatim, with no schema default (#12126)', () => {
+    // Ruling A: a closed z.enum over exactly the six tokens objectui#6294's
+    // `plugin-detail/src/headerColor.ts` lookup ships — complete class
+    // literals in a file every consuming app's Tailwind scan covers, so
+    // every enum value is guaranteed present in the compiled stylesheet.
+    // Declared = enforced.
+    for (const token of [
+      'muted', 'muted/50', 'accent', 'primary/10', 'secondary/10', 'destructive/10',
     ] as const) {
+      const section = RecordDetailsProps.parse({
+        sections: [{ label: 'A', fields: ['a'], headerColor: token }],
+      }).sections?.[0] as Record<string, unknown>;
+      expect(section.headerColor).toBe(token);
+    }
+    // No schema default: an omitted key means "no tint" — the renderer's own
+    // fallback, not an authored request (the `maxVisible` principle).
+    const bare = RecordDetailsProps.parse({
+      sections: [{ label: 'A', fields: ['a'] }],
+    }).sections?.[0] as Record<string, unknown>;
+    expect('headerColor' in bare).toBe(false);
+  });
+
+  it('refuses `headerColor` values outside the closed enum, by name (#12126)', () => {
+    // The boundary ruling A draws: everything outside the six tokens — an
+    // arbitrary palette guess (the objectui#6178 silent-no-paint failure
+    // mode), the renderer's `bg-*` pass-through spellings (which render only
+    // if the HOST app's Tailwind build happens to generate the class), and
+    // the solid tokens the tints-only vocabulary deliberately excludes — is
+    // refused at authoring time rather than shipping a header that silently
+    // does not paint.
+    for (const value of ['blue-100', 'bg-muted', 'primary', 'destructive']) {
       const r = RecordDetailsProps.safeParse({
-        sections: [{ label: 'A', fields: ['a'], [key]: value }],
+        sections: [{ label: 'A', fields: ['a'], headerColor: value }],
       });
       expect(r.success).toBe(false);
-      const message = r.success === false
-        ? r.error.issues.map((i) => i.message).join('\n')
-        : '';
-      expect(message).toContain(`\`${key}\``);
+      if (r.success) continue;
+      const issue = r.error.issues[0]!;
+      expect(issue.code).toBe('invalid_value');
+      expect(issue.path).toEqual(['sections', 0, 'headerColor']);
     }
   });
 

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

@@ -902,25 +902,49 @@ export const RecordDetailsProps = strictObject({
      * the `.objectui-sha` pin (`190fbd01`, objectui `plugin-detail/src/
      * renderers/record-details.tsx` + `plugin-detail/src/DetailSection.tsx`).
      *
-     * Two keys the same measurement found are deliberately NOT declared here
-     * (#11661 holds their forks):
+     * One key the same measurement found is deliberately NOT declared here
+     * (#11661 holds its fork):
      * - `title` — the renderer's `s.title ?? s.label` limb is a second
      *   spelling of the heading slot `label` already declares (identical
      *   localization handling, zero producers). Same shape as the `page:card`
      *   `body`-vs-`children` pair, which #5775 CONVERGED rather than declared
      *   — one heading slot, not two de-facto contracts (Prime Directive #12).
      *   Held for the maintainer's declare-vs-converge ruling.
-     * - `headerColor` — the renderer's only read is `bg-${headerColor}`, a
-     *   template-literal Tailwind class: Tailwind v4 scans source text with
-     *   no safelist, so this call site generates NO CSS and an authored value
-     *   works only when some other source file happens to use the same class
-     *   literally. Dead-in-practice at the pin (zero producers); declaring it
-     *   would advertise a capability the renderer does not deliver.
+     *
+     * `headerColor` used to be withheld alongside it (the renderer's only
+     * read was `bg-${headerColor}`, a template-literal Tailwind class that
+     * generates no CSS under the v4 source scan — declaring it would have
+     * advertised a capability the renderer did not deliver). objectui#6294
+     * (merged 2026-08-25) replaced the interpolation with a lookup of
+     * complete class literals in `plugin-detail/src/headerColor.ts`, so the
+     * renderer now delivers the key because the module declares it; the
+     * refusal outlived its recorded reason and #12126 (maintainer ruling A,
+     * 2026-08-26) declares the key below as a closed enum.
      */
     defaultCollapsed: z.boolean().optional().describe('Start a `collapsible: true` section collapsed (renderer default: expanded). Consulted only when `collapsible` is on — a non-collapsible section never reads its collapse state.'),
     icon: z.string().optional().describe('Heading icon, as a lucide icon name (kebab-case, e.g. `building-2`). A value that is not an ASCII identifier (emoji, CJK text) renders as literal text beside the heading instead. Shown where the section heading renders: a titled section, or any collapsible section.'),
     description: z.string().optional().describe('Sub-heading text rendered under the section heading (plain string — the renderer applies no translation to it, unlike `label`). Renders on a titled or collapsible section; a collapsible section hides it while collapsed.'),
-  })).optional().describe('Field groups rendered as the detail body, in order. Object form: `{ name?, label?, columns?, fields, hideEmpty?, collapsible?, showBorder?, defaultCollapsed?, icon?, description? }`.'),
+    /**
+     * Section-header background tint (#12126, maintainer ruling A 2026-08-26:
+     * declare as a CLOSED enum — declared = enforced). The vocabulary is
+     * exactly the six complete class literals objectui's
+     * `plugin-detail/src/headerColor.ts` lookup ships (objectui#6294): those
+     * literals live in a file every consuming app's Tailwind scan covers, so
+     * each enum value is guaranteed to be in the compiled stylesheet. Tints
+     * only, by the renderer module's own reasoning: `CardHeader` sets no
+     * foreground colour, so a solid `bg-primary` would leave the title
+     * unreadable without a paired `text-*-foreground`.
+     *
+     * Anything outside the enum — including the renderer's `bg-*`
+     * pass-through spellings, which render only if the HOST app's Tailwind
+     * build happens to generate the class — is refused at authoring time
+     * rather than shipping a header that silently does not paint (the
+     * objectui#6178 failure mode this key's old refusal existed to prevent).
+     * Optional with NO schema default: an omitted key means "no tint", the
+     * renderer's own fallback.
+     */
+    headerColor: z.enum(['muted', 'muted/50', 'accent', 'primary/10', 'secondary/10', 'destructive/10']).optional().describe('Section-header background tint, from the closed six-token vocabulary rendered by objectui\'s `record:details` header (`muted` | `muted/50` | `accent` | `primary/10` | `secondary/10` | `destructive/10`). A value outside the enum is refused at authoring time rather than silently not painting. Omit for an untinted header.'),
+  })).optional().describe('Field groups rendered as the detail body, in order. Object form: `{ name?, label?, columns?, fields, hideEmpty?, collapsible?, showBorder?, defaultCollapsed?, icon?, description?, headerColor? }`.'),
   fields: z.array(z.string()).optional().describe('Explicit field list to display (optional, overrides highlightFields)'),
   /**
    * Field names to omit from the body, applied to both `fields` and every