feat(spec): add responsiveStyles to UI page-component envelope (ADR-0065) (#2214)

ResponsiveStylesSchema/StyleMapSchema model per-breakpoint CSS-property
maps (large/medium/small/xsmall) for the SDUI scoped-styling primitive;
PageComponentSchema gains an optional responsiveStyles field — the
preferred build-independent, collision-free styling channel for
metadata-authored pages (distinct from the layout-oriented responsive
config). 6612 spec tests green; api-surface refreshed.

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

.changeset/spec-responsive-styles.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): add `responsiveStyles` to the UI page-component envelope (ADR-0065)
+
+`ResponsiveStylesSchema` / `StyleMapSchema` model the SDUI scoped-styling
+primitive — per-breakpoint CSS-property maps (`large`/`medium`/`small`/`xsmall`)
+compiled to id-scoped CSS at render. `PageComponentSchema` gains an optional
+`responsiveStyles` field: the preferred, build-independent, collision-free
+styling channel for metadata-authored pages (distinct from the layout-oriented
+`responsive` config). Prefer design-token values.

packages/spec/api-surface.json

@@ -3252,6 +3252,8 @@
     "ReportType (const)",
     "ResponsiveConfig (type)",
     "ResponsiveConfigSchema (const)",
+    "ResponsiveStyles (type)",
+    "ResponsiveStylesSchema (const)",
     "RowColorConfig (type)",
     "RowColorConfigSchema (const)",
     "RowHeight (type)",
@@ -3264,6 +3266,8 @@
     "SharingConfigSchema (const)",
     "Spacing (type)",
     "SpacingSchema (const)",
+    "StyleMap (type)",
+    "StyleMapSchema (const)",
     "SwipeDirection (type)",
     "SwipeDirectionSchema (const)",
     "SwipeGestureConfig (type)",

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

@@ -6,7 +6,7 @@ import { ExpressionInputSchema } from '../shared/expression.zod';
 import { SortItemSchema } from '../shared/enums.zod';
 import { FilterConditionSchema } from '../data/filter.zod';
 import { I18nLabelSchema, AriaPropsSchema } from './i18n.zod';
-import { ResponsiveConfigSchema } from './responsive.zod';
+import { ResponsiveConfigSchema, ResponsiveStylesSchema } from './responsive.zod';
 import {
   UserActionsConfigSchema,
   AppearanceConfigSchema,
@@ -88,6 +88,15 @@ export const PageComponentSchema = lazySchema(() => z.object({
   style: z.record(z.string(), z.string()).optional().describe('Inline styles or utility classes'),
   className: z.string().optional().describe('CSS class names'),
 
+  /**
+   * SDUI scoped responsive styles (ADR-0065). Per-breakpoint CSS-property maps
+   * compiled to id-scoped CSS at render. The preferred styling channel for
+   * metadata-authored pages — build-independent and collision-free, unlike raw
+   * `className`. Prefer design-token values (`var(--space-6)`, `var(--surface)`).
+   */
+  responsiveStyles: ResponsiveStylesSchema.optional()
+    .describe('Per-breakpoint scoped style maps (ADR-0065)'),
+
   /** Visibility Rule */
   visibility: ExpressionInputSchema.optional().describe('Visibility predicate (CEL).'),
 

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

@@ -74,6 +74,40 @@ export const ResponsiveConfigSchema = lazySchema(() => z.object({
 
 export type ResponsiveConfig = z.infer<typeof ResponsiveConfigSchema>;
 
+/**
+ * Style Map Schema (ADR-0065)
+ *
+ * A CSS property → value map (camelCase keys, e.g. `flexDirection`). Values are
+ * arbitrary CSS strings/numbers but authors should prefer design tokens
+ * (`var(--space-6)`, `var(--surface)`) for consistency and AI-safety.
+ */
+export const StyleMapSchema = lazySchema(() =>
+  z.record(z.string(), z.union([z.string(), z.number()]))
+    .describe('CSS property → value map (camelCase keys; design tokens encouraged)'));
+
+export type StyleMap = z.infer<typeof StyleMapSchema>;
+
+/**
+ * Responsive Styles Schema (ADR-0065)
+ *
+ * Per-breakpoint CSS-property maps for the SDUI scoped-styling model. Compiled
+ * to **id-scoped CSS at render** (objectui `SchemaRenderer`) — build-independent,
+ * collision-free, responsive-correct. Desktop-first: `large` is the
+ * unconditional base; `medium`/`small`/`xsmall` are `max-width` overrides.
+ *
+ * Distinct from {@link ResponsiveConfigSchema}, which configures *layout* (grid
+ * columns / visibility / order) on the Tailwind `xs..2xl` axis. This styles a
+ * node's own box; that arranges a node within a grid.
+ */
+export const ResponsiveStylesSchema = lazySchema(() => z.object({
+  large: StyleMapSchema.optional().describe('Unconditional base (desktop-first)'),
+  medium: StyleMapSchema.optional().describe('Applied at ≤ medium breakpoint'),
+  small: StyleMapSchema.optional().describe('Applied at ≤ small breakpoint'),
+  xsmall: StyleMapSchema.optional().describe('Applied at ≤ xsmall breakpoint'),
+}).describe('Per-breakpoint scoped style maps (ADR-0065)'));
+
+export type ResponsiveStyles = z.infer<typeof ResponsiveStylesSchema>;
+
 /**
  * Performance Configuration Schema
  *