docs(adr): ADR-0065 SDUI styling model — scoped style-objects over arbitrary Tailwind (#2210)

Records the decision that metadata-authored SDUI styling is a scoped
style-object with model-owned responsive breakpoints (token-constrained
values), compiled to per-component id-scoped CSS at render time — NOT
arbitrary Tailwind class strings. Mirrors Builder.io's proven model.

Adds a runnable proof under examples/app-showcase: a reference compiler
(style-object + breakpoints -> id-scoped CSS) + a showcase authoring
shape + a test asserting the four properties the decision rests on
(id-scoping, generated @media, arbitrary-value passthrough,
token resolution). 5/5 green.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

docs/adr/0065-sdui-styling-model.md

@@ -0,0 +1,184 @@
+# ADR-0065: SDUI styling model — scoped style-objects over arbitrary Tailwind classes
+
+**Status**: Proposed (2026-06-22)
+**Deciders**: ObjectStack Protocol Architects
+**Builds on**: [ADR-0026](./0026-client-ui-plugin-distribution.md) (client UI distribution), [ADR-0016](./0016-studio-package-authoring-and-publish.md) (package authoring/publish), [ADR-0049](./0049-no-unenforced-security-properties.md) (spec must not promise what the runtime can't deliver)
+**Consumers**: `@objectstack/spec` (UI component envelope), the objectui renderers (`@object-ui/components`), cloud SDUI page authoring, the AI metadata-authoring agents.
+**Surfaced by**: a Cloud Pricing page (`com.objectstack.cloud` `page/pricing`) that rendered with blank plan headings, then — on investigation — turned out to "work" only by coincidence.
+
+---
+
+## TL;DR
+
+The SDUI styling story to date is **arbitrary Tailwind class strings carried in
+page metadata and passed through to the DOM** (`element:text`/`page:card` etc.
+forward `schema.className`). Investigation shows this is **structurally unsound**
+for a platform where pages are authored *separately from* — and *by parties who
+cannot rebuild* — the renderer, and where the author is increasingly an **AI**.
+
+Three independent failure axes, any one of which is disqualifying, all bite at once:
+
+1. **Compilation.** Tailwind is JIT-compiled at *build* time, scanning *source*.
+   The renderer (objectui Console) is a shipped, frozen artifact whose CSS scans
+   only objectui's own `src` (`objectui: apps/console/src/index.css:12-19`),
+   **never** the page metadata. There is **no safelist**. So a class in metadata
+   produces CSS *only if it coincidentally also appears in objectui source*.
+   (The Pricing page renders today purely because all 16 of its classes happen
+   to be common ones objectui already uses — luck, not a contract. Any
+   arbitrary-value class — `text-[27px]`, `bg-[#1a2b3c]`, `grid-cols-7` — is
+   silently dead.)
+
+2. **Two-build cascade + responsive inversion.** Because the customer's metadata
+   project builds independently from the renderer, you inherently get **two
+   Tailwind stylesheets**. Tailwind utilities have equal specificity, so priority
+   falls to source order — which is undefined across two builds. CSS cascade
+   `@layer` fixes the flat case but **outranks media-query/source-order**, so a
+   higher layer's *unconditional* (mobile-base) utility silently defeats a lower
+   layer's `md:` utility *at all breakpoints* — responsive intent inverts.
+   Per-element this is structural: every rendered element carries the renderer's
+   own classes **and** the author's className, straddling two layers.
+
+3. **AI authorship.** The author is often a cheap model. Arbitrary Tailwind is a
+   ~thousands-of-classes + infinite-arbitrary-value + variant + cascade surface —
+   a maximal footgun. Correctness must be *designed in*, not hoped for. (In the
+   session that surfaced this, a frontier model authoring the page made four
+   distinct mistakes: overclaimed the capability, tripped a latent renderer bug,
+   "verified" with a methodologically false-positive screenshot, and picked
+   classes that worked only by luck.)
+
+**Decision.** SDUI styling is expressed as a **scoped style-object with
+model-owned responsive breakpoints**, whose *values* are constrained to design
+tokens — **not** arbitrary Tailwind classes. Styles compile to **per-component,
+id-scoped CSS at render time** (build-independent, collision-free). Arbitrary
+`className` is demoted to a **gated escape hatch** that only a runtime
+single-engine path may honour. This mirrors the proven model of **Builder.io**,
+the most battle-tested "author content separately, render in arbitrary hosts"
+platform.
+
+---
+
+## Context
+
+### What we have
+
+UI components carry a loose `className` passthrough. The objectui renderers apply
+it directly — e.g. `objectui: packages/components/src/renderers/basic/elements.tsx:87`
+(`cn(VARIANT_CLASS, ALIGN_CLASS, schema?.className)`). The spec does **not** even
+formally model a styling field (`packages/spec/src/ui/component.zod.ts` defines
+per-component `properties` + `children`, no `style`). So styling today is "write
+Tailwind into metadata and hope the renderer's CSS bundle happens to contain it."
+
+### Why "just compile at build time" doesn't rescue it
+
+- **Folding the page files into the renderer's Tailwind `@source`** works *only*
+  for pages that are static source *inside the renderer's own build*. The
+  Console is a shipped dev tool; the customer's metadata project is a **separate
+  build the platform never sees**. A single shared build is impossible.
+- **A safelist / `@source inline(...)`** yields a *bounded* palette, not the
+  arbitrary power that motivated raw className in the first place.
+- **A shared Tailwind preset** (lock version + share `@theme`/breakpoints +
+  emit into a reserved `@layer`) makes two independent builds *coexist*, but
+  cannot remove the responsive-inversion tail (§Decision-2 above): build-time
+  approaches structurally cannot.
+- **Runtime single-engine JIT** (one engine over the composed DOM) *is* correct,
+  but pays a permanent runtime cost (client engine / server compile+cache) and
+  is the *only* build-time-free way to keep arbitrary classes correct.
+
+The honest constraint: **"two independent builds + arbitrary Tailwind + correct
+responsive + zero runtime cost" — pick three.**
+
+### Precedent: Builder.io
+
+Builder.io solves exactly this shape (visual content authored separately,
+rendered into arbitrary host stacks) and **does not bet on Tailwind classes**:
+
+- Styles are CSS **objects**, per breakpoint —
+  `Builder.io SDK: packages/sdks/src/types/builder-block.ts:42`
+  (`responsiveStyles?: { large?, medium?, small?, xsmall?: Partial<CSSStyleDeclaration> }`).
+- Responsive is an **explicit breakpoint map in the data model** (desktop-first:
+  `large` is base, smaller sizes override via `@media (max-width: …)` —
+  `Builder.io SDK: packages/sdks/src/constants/device-sizes.ts:34`), **not**
+  `md:` utility variants the author writes.
+- At render, each block's styles compile to **id-scoped CSS** —
+  `Builder.io SDK: packages/sdks/src/helpers/css.ts` (`createCssClass` emits
+  `.${block.id} { … }`, wrapping smaller breakpoints in `@media`) injected via
+  an inlined `<style>` (`…/components/block/components/block-styles.lite.tsx`).
+- `className` exists only as an **optional passthrough** for hosts that already
+  ship Tailwind — carrying the exact "only works if the host compiled it" caveat.
+
+This dissolves all three failure axes: nothing to scan at build (styles are
+data → CSS at render), nothing to collide (id-scoped, no shared utility layer),
+and responsive is clean generated `@media` owned by the model.
+
+---
+
+## Decision
+
+1. **Styling primitive = scoped style-object.** The UI component envelope gains
+   an optional `style` (base) and `responsiveStyles` (`large`/`medium`/`small`/
+   `xsmall` CSS-property maps). The renderer compiles these to **per-component,
+   id-scoped CSS** at render time. No author-written class strings are required
+   for styling.
+
+2. **Responsive is model-owned.** Breakpoints are expressed as the
+   `responsiveStyles` map (or higher-level responsive props on components like
+   `columns`), generated into proper `@media` rules. Authors **never write
+   breakpoint variant classes** (`md:` …). This deletes the entire
+   layer-vs-media-query failure class.
+
+3. **Values are token-constrained.** Style-object values resolve against a
+   curated design-token palette (spacing/color/radius/typography as
+   CSS variables). This is what Builder.io *lacks* (and is criticised for —
+   inconsistent output); we add it for visual consistency **and** to make the
+   surface enumerable/validatable for AI authors.
+
+4. **Arbitrary `className` is a gated escape hatch, not the interface.** It may
+   be honoured **only** on a runtime single-engine path, and (in cloud) gated to
+   an advanced/paid tier behind a render+review check. It is never what the AI
+   reaches for by default.
+
+5. **Authoring is verified in-loop.** Because styles are now structured data, the
+   authoring tool validates them against the spec schema (reject + self-correct),
+   and the publish path may add a headless render + VLM "looks right?" gate.
+   Correctness by construction + verification, not author virtue.
+
+This ADR is the **mechanism** (open, in framework + objectui); per-tier policy
+and the VLM gate are **cloud** concerns (open-core boundary, cf. ADR-0026).
+
+---
+
+## Consequences
+
+- **Positive.** Styling becomes **build-independent** (data → CSS at render →
+  arbitrary *values* always work), **collision-free** (id-scoped, no two-build
+  cascade war, no `@layer` gymnastics, no safelist), **responsive-correct**
+  (model breakpoints → generated `@media`), and **AI-safe** (structured,
+  schema-validated, token-bounded data instead of a class-string DSL).
+- **Negative / cost.** A render-time CSS-gen step (cheap: object→string, *not* a
+  Tailwind engine). Per-component `<style>`/scoped rules instead of shared
+  utility reuse (slightly larger, uncached-across-blocks CSS — acceptable, and
+  cacheable by content hash). Token constraint must be designed (the palette is
+  now a platform artifact). Existing className-styled pages (e.g. the Pricing
+  page) migrate to the new primitive.
+- **Follow-up.** (a) Add `style`/`responsiveStyles` to `@objectstack/spec` UI
+  envelope. (b) A reference compiler (`style-object + breakpoints → id-scoped
+  CSS`) as the open mechanism. (c) objectui renderer consumes it. (d) Define the
+  token palette. (e) Migrate cloud's built-in `*.page.ts` off raw className.
+  (f) cloud: tier policy + render/VLM gate for the className escape hatch.
+- **Validation.** A showcase under `examples/app-showcase` exercises the
+  primitive and a unit test asserts the four properties the decision rests on:
+  **id-scoping**, **generated `@media` for breakpoints**, **arbitrary values
+  pass through verbatim** (build-independence), and **token-var resolution**.
+
+---
+
+## Non-goals
+
+- **Not** a general-purpose CSS-in-JS framework, animation system, or a Tailwind
+  replacement for hand-written app code. This governs **metadata-authored SDUI**
+  surfaces only.
+- **Not** banning Tailwind inside objectui's own hand-built renderer components
+  (those are scanned source — they compile fine).
+- **Not** mandating the runtime single-engine path now. Runtime JIT is the
+  *only* way to keep the arbitrary-className escape hatch correct, but adopting
+  it is a separate, cost-gated decision (and unnecessary for the token primitive).

examples/app-showcase/test/sdui-styling.test.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+
+import {
+  compileBlockStyles,
+  compilePageStyles,
+  BREAKPOINTS,
+} from './sdui-styling/compile-block-styles.js';
+import { pricingShowcase } from './sdui-styling/pricing-showcase.js';
+
+/**
+ * Verifies the SDUI styling model (ADR-0065) actually delivers the four
+ * properties the decision rests on. In the "demonstrated AND verified" spirit
+ * of the showcase: a model that merely *declares* a styling shape but compiles
+ * to colliding / build-dependent / responsive-inverting CSS would slip past a
+ * shape-only assertion — but not these.
+ */
+describe('SDUI styling model — scoped style-objects (ADR-0065)', () => {
+  // (1) id-scoping: every rule targets `.{id}` — never a global/unscoped
+  // selector. This is what makes two independently-built stylesheets unable to
+  // collide, and removes the whole two-build cascade war.
+  it('scopes every rule to the component id (no global selectors)', () => {
+    const css = compileBlockStyles('plan_solo', {
+      large: { padding: '24px' },
+      small: { padding: '12px' },
+    });
+    expect(css).toContain('.plan_solo {');
+    expect(css).toContain('@media (max-width: 640px) { .plan_solo {');
+    // No bare/global declaration leaks outside an id scope.
+    expect(css).not.toMatch(/(^|\n)\s*padding:/); // padding only ever inside `.plan_solo { … }`
+
+    // Two different blocks → disjoint selectors → cannot collide.
+    const a = compileBlockStyles('block_a', { large: { color: 'red' } });
+    const b = compileBlockStyles('block_b', { large: { color: 'blue' } });
+    expect(a).toContain('.block_a {');
+    expect(b).toContain('.block_b {');
+    expect(a).not.toContain('block_b');
+  });
+
+  // (2) responsive = generated @media owned by the model (desktop-first,
+  // max-width), NOT author-written `md:` classes. Deletes the
+  // layer-vs-media-query inversion class.
+  it('emits proper @media rules for breakpoints (no variant classes)', () => {
+    const css = compileBlockStyles('plan_solo', {
+      large: { padding: '24px' },
+      medium: { padding: '20px' },
+      small: { padding: '12px' },
+      xsmall: { padding: '8px' },
+    });
+    expect(css).toContain(`@media (max-width: ${BREAKPOINTS.medium}px)`);
+    expect(css).toContain(`@media (max-width: ${BREAKPOINTS.small}px)`);
+    expect(css).toContain(`@media (max-width: ${BREAKPOINTS.xsmall}px)`);
+    // The base (`large`) is unconditional — not wrapped in a media query.
+    expect(css.split('\n')[0]).toBe('.plan_solo { padding: 24px; }');
+    // Author never writes a breakpoint variant class.
+    expect(css).not.toContain('md:');
+    expect(css).not.toContain('sm:');
+  });
+
+  // (3) build-independence: arbitrary values pass through verbatim. This is the
+  // property arbitrary Tailwind classes CANNOT guarantee (JIT scans source at
+  // build; metadata is never scanned).
+  it('passes arbitrary values through verbatim (zero build step)', () => {
+    const css = compileBlockStyles('odd', {
+      large: { fontSize: '13px', color: '#1a2b3c', gridTemplateColumns: 'repeat(3, 1fr)' },
+    });
+    expect(css).toContain('font-size: 13px;');
+    expect(css).toContain('color: #1a2b3c;');
+    // camelCase → kebab-case, value untouched.
+    expect(css).toContain('grid-template-columns: repeat(3, 1fr);');
+  });
+
+  // (4) token resolution: values may be design tokens → consistency + an
+  // enumerable, AI-safe surface. Tokens pass through as `var(--…)`.
+  it('passes design-token values through as CSS variables', () => {
+    const css = compilePageStyles(pricingShowcase);
+    expect(css).toContain('.plan_solo {');
+    expect(css).toContain('padding: var(--space-6);');
+    expect(css).toContain('border-radius: var(--radius-lg);');
+    // Showcase responsive shrink applied via the model, scoped.
+    expect(css).toContain('@media (max-width: 640px) { .plan_solo {');
+    expect(css).toContain('.plan_price {');
+    expect(css).toContain('font-size: 44px;'); // arbitrary value alongside tokens
+  });
+
+  // Guard mirrors Builder.io: no id → no CSS (never an unscoped global rule).
+  it('emits nothing for a block with no id', () => {
+    expect(compileBlockStyles('', { large: { padding: '24px' } })).toBe('');
+  });
+});

examples/app-showcase/test/sdui-styling/compile-block-styles.ts

@@ -0,0 +1,81 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Reference compiler for the SDUI styling model (ADR-0065).
+ *
+ * Turns a per-component, breakpoint-keyed style-object into **id-scoped CSS**,
+ * the way Builder.io's SDK does (`createCssClass` →
+ * `Builder.io SDK: packages/sdks/src/helpers/css.ts`). This is the open
+ * *mechanism* prototype: pure `data → CSS string`, no Tailwind, no build-time
+ * class scanning. It exists here as the thing the showcase test verifies; the
+ * production home is `@objectstack/spec`/objectui (ADR-0065 follow-up).
+ *
+ * Desktop-first, matching Builder.io
+ * (`packages/sdks/src/constants/device-sizes.ts:34`, `@media (max-width: …)`):
+ * `large` is the unconditional base; `medium`/`small`/`xsmall` are max-width
+ * overrides. Responsive is owned by the *model*, never by author-written
+ * `md:`-style variant classes — which is what deletes the layer-vs-media-query
+ * inversion class entirely (ADR-0065 §Decision-2).
+ */
+
+export type StyleMap = Record<string, string>;
+
+export interface ResponsiveStyles {
+  /** Unconditional base (desktop-first). */
+  large?: StyleMap;
+  medium?: StyleMap;
+  small?: StyleMap;
+  xsmall?: StyleMap;
+}
+
+/** max-width breakpoints (px). Mirrors Builder.io's default device sizes. */
+export const BREAKPOINTS: Record<'medium' | 'small' | 'xsmall', number> = {
+  medium: 991,
+  small: 640,
+  xsmall: 479,
+};
+
+const camelToKebab = (k: string): string =>
+  k.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+
+/** A style-map → `prop: value;` declarations. Values pass through **verbatim** —
+ * that verbatim passthrough is the whole point: arbitrary values (`13px`,
+ * `#1a2b3c`) and design tokens (`var(--space-6)`) work with zero build step. */
+const mapToDeclarations = (m: StyleMap): string =>
+  Object.entries(m)
+    .map(([k, v]) => `${camelToKebab(k)}: ${v};`)
+    .join(' ');
+
+/**
+ * Compile one component's responsive style-object to id-scoped CSS.
+ * Returns '' for a missing id (no global, unscoped rule is ever emitted —
+ * that scoping is what makes two independently-built stylesheets unable to
+ * collide; ADR-0065 §Decision-1/2).
+ */
+export function compileBlockStyles(id: string, styles: ResponsiveStyles): string {
+  if (!id) return '';
+  const rules: string[] = [];
+  if (styles.large) {
+    rules.push(`.${id} { ${mapToDeclarations(styles.large)} }`);
+  }
+  for (const size of ['medium', 'small', 'xsmall'] as const) {
+    const s = styles[size];
+    if (s) {
+      rules.push(
+        `@media (max-width: ${BREAKPOINTS[size]}px) { .${id} { ${mapToDeclarations(s)} } }`,
+      );
+    }
+  }
+  return rules.join('\n');
+}
+
+/** Compile a whole page's blocks, concatenating their scoped CSS. */
+export function compilePageStyles(
+  blocks: Array<{ id: string; responsiveStyles?: ResponsiveStyles }>,
+): string {
+  return blocks
+    .filter((b) => b.responsiveStyles)
+    .map((b) => compileBlockStyles(b.id, b.responsiveStyles as ResponsiveStyles))
+    .filter(Boolean)
+    .join('\n');
+}