feat(lint): SDUI styling validator (ADR-0065) (#2225)

xuyushun441-sys · os-zhuang · claude · web-flow · commit f75943a1831a · 2026-06-23T00:11:33.000+08:00
validateResponsiveStyles — a pure (stack) =&gt; Finding[] rule wired into
os validate AND os compile so hand-authored and AI-generated pages are
held to the same bar (ADR-0019). Error: styled node with no id (CSS
can't be scoped -&gt; silently dropped). Warnings: Tailwind-in-className
(dead in metadata), smaller breakpoint with no large base, unknown CSS
property, unknown/typo'd design token. Visual quality (is it ugly) is
explicitly out of scope -&gt; needs render + VLM gate.

Unit tests 9/9 (+ full lint suite 42). Loop-verified on the real
app-showcase styling-gallery page: it is lint-CLEAN, and a mutated
variant is caught on all 4 defects.

Co-authored-by: Jack Zhuang &lt;277994282+os-zhuang@users.noreply.github.com&gt;
Co-authored-by: Claude Opus 4.8 &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/lint-responsive-styles.md b/.changeset/lint-responsive-styles.md
@@ -0,0 +1,15 @@
+---
+"@objectstack/lint": minor
+"@objectstack/cli": patch
+---
+
+feat(lint): SDUI styling validator (ADR-0065)
+
+`validateResponsiveStyles` — a pure `(stack) => Finding[]` rule wired into
+`os validate` and `os compile`, so hand-authored and AI-generated pages are
+held to the same bar (ADR-0019). Catches the deterministic ways a
+`responsiveStyles` block silently fails: a styled node with no `id` (CSS can't
+be scoped → dropped) is an **error**; warnings cover Tailwind-in-`className`
+(silently dead in metadata), a smaller breakpoint with no `large` base, unknown
+CSS properties, and unknown/typo'd design tokens. Quality/visual judgement
+(is it ugly) is out of scope — that needs render + a VLM gate.
diff --git a/packages/cli/src/commands/compile.ts b/packages/cli/src/commands/compile.ts
@@ -10,6 +10,7 @@ import { loadConfig } from '../utils/config.js';
 import { lowerCallables } from '../utils/lower-callables.js';
 import { validateStackExpressions } from '@objectstack/lint';
 import { validateWidgetBindings } from '@objectstack/lint';
+import { validateResponsiveStyles } from '@objectstack/lint';
 import { lintFlowPatterns } from '../utils/lint-flow-patterns.js';
 import { lintAutonumberFormats } from '../utils/lint-autonumber-formats.js';
 import { lintLivenessProperties } from '../utils/lint-liveness-properties.js';
@@ -195,6 +196,37 @@ export default class Compile extends Command {
         }
       }
 
+      // 3c. SDUI scoped-styling correctness (ADR-0065) — a styled node without
+      //     an `id` drops its CSS silently; Tailwind-in-className does nothing
+      //     from metadata. Same bar for hand-authored and AI-generated pages
+      //     (ADR-0019). Errors fail the build; warnings are advisory.
+      if (!flags.json) printStep('Checking SDUI styling (ADR-0065)...');
+      const styleFindings = validateResponsiveStyles(result.data as Record<string, unknown>);
+      const styleErrors = styleFindings.filter((f) => f.severity === 'error');
+      const styleWarnings = styleFindings.filter((f) => f.severity === 'warning');
+      if (styleErrors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({ success: false, error: 'SDUI styling validation failed', issues: styleErrors }));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`SDUI styling check failed (${styleErrors.length} issue${styleErrors.length > 1 ? 's' : ''})`);
+        for (const f of styleErrors.slice(0, 50)) {
+          console.log(`  • ${f.where}: ${f.message}`);
+          console.log(chalk.dim(`      ${f.hint}`));
+          console.log(chalk.dim(`      rule: ${f.rule}  at ${f.path}`));
+        }
+        this.exit(1);
+      }
+      if (styleWarnings.length > 0 && !flags.json) {
+        console.log('');
+        for (const w of styleWarnings) {
+          printWarning(`${w.where}: ${w.message}`);
+          console.log(chalk.dim(`    ${w.hint}`));
+          console.log(chalk.dim(`    rule: ${w.rule}  at ${w.path}`));
+        }
+      }
+
       // 3d. Flow authoring anti-pattern lint (#1874) — advisory warnings for
       //     valid-but-fragile flow metadata (e.g. a record-change trigger using a
       //     date-EQUALITY time condition that only fires on the exact day). Guides
diff --git a/packages/cli/src/commands/validate.ts b/packages/cli/src/commands/validate.ts
@@ -7,6 +7,7 @@ import { ObjectStackDefinitionSchema, normalizeStackInput } from '@objectstack/s
 import { loadConfig } from '../utils/config.js';
 import { validateStackExpressions } from '@objectstack/lint';
 import { validateWidgetBindings } from '@objectstack/lint';
+import { validateResponsiveStyles } from '@objectstack/lint';
 import {
   printHeader,
   printKV,
@@ -133,6 +134,36 @@ export default class Validate extends Command {
         this.exit(1);
       }
 
+      // 3b. SDUI scoped-styling correctness (ADR-0065) — a styled node's
+      //     responsiveStyles must be scopable (needs an `id`), reference real
+      //     CSS properties + design tokens, and carry a `large` base;
+      //     Tailwind-in-className silently does nothing. Same bar for
+      //     hand-authored and AI-generated pages (ADR-0019).
+      if (!flags.json) printStep('Checking SDUI styling (ADR-0065)...');
+      const styleFindings = validateResponsiveStyles(result.data as Record<string, unknown>);
+      const styleErrors = styleFindings.filter((f) => f.severity === 'error');
+      const styleWarnings = styleFindings.filter((f) => f.severity === 'warning');
+
+      if (styleErrors.length > 0) {
+        if (flags.json) {
+          console.log(JSON.stringify({
+            valid: false,
+            errors: styleErrors,
+            warnings: [...widgetWarnings, ...styleWarnings],
+            duration: timer.elapsed(),
+          }, null, 2));
+          this.exit(1);
+        }
+        console.log('');
+        printError(`SDUI styling check failed (${styleErrors.length} issue${styleErrors.length > 1 ? 's' : ''})`);
+        for (const f of styleErrors.slice(0, 50)) {
+          console.log(`  • ${f.where}: ${f.message}`);
+          console.log(chalk.dim(`      ${f.hint}`));
+          console.log(chalk.dim(`      rule: ${f.rule}  at ${f.path}`));
+        }
+        this.exit(1);
+      }
+
       // 4. Collect and display stats
       const stats = collectMetadataStats(config);
 
@@ -141,7 +172,7 @@ export default class Validate extends Command {
           valid: true,
           manifest: config.manifest,
           stats,
-          warnings: [...exprWarnings, ...widgetWarnings],
+          warnings: [...exprWarnings, ...widgetWarnings, ...styleWarnings],
           duration: timer.elapsed(),
         }, null, 2));
         return;
@@ -156,6 +187,9 @@ export default class Validate extends Command {
       for (const f of widgetWarnings) {
         warnings.push(`${f.where}: ${f.message}`);
       }
+      for (const f of styleWarnings) {
+        warnings.push(`${f.where}: ${f.message}`);
+      }
       if (stats.objects === 0) {
         warnings.push('No objects defined — this stack has no data model');
       }
diff --git a/packages/lint/src/index.ts b/packages/lint/src/index.ts
@@ -25,3 +25,13 @@ export type { WidgetBindingFinding, WidgetBindingSeverity } from './validate-wid
 
 export { validateStackExpressions } from './validate-expressions.js';
 export type { ExprIssue } from './validate-expressions.js';
+
+export {
+  validateResponsiveStyles,
+  STYLE_NODE_MISSING_ID,
+  STYLE_CLASSNAME_TAILWIND,
+  STYLE_RESPONSIVE_NO_BASE,
+  STYLE_UNKNOWN_CSS_PROPERTY,
+  STYLE_UNKNOWN_TOKEN,
+} from './validate-responsive-styles.js';
+export type { StyleFinding, StyleSeverity } from './validate-responsive-styles.js';
diff --git a/packages/lint/src/validate-responsive-styles.test.ts b/packages/lint/src/validate-responsive-styles.test.ts
@@ -0,0 +1,97 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect } from 'vitest';
+import {
+  validateResponsiveStyles,
+  STYLE_NODE_MISSING_ID,
+  STYLE_CLASSNAME_TAILWIND,
+  STYLE_RESPONSIVE_NO_BASE,
+  STYLE_UNKNOWN_CSS_PROPERTY,
+  STYLE_UNKNOWN_TOKEN,
+} from './validate-responsive-styles.js';
+
+/** Wrap component nodes into a minimal stack with one page. */
+const stackWith = (...components: any[]) => ({
+  pages: [{ name: 'pricing', regions: [{ name: 'main', components }] }],
+});
+
+const rules = (findings: ReturnType<typeof validateResponsiveStyles>) => findings.map((f) => f.rule);
+
+describe('validateResponsiveStyles (ADR-0065)', () => {
+  it('passes a clean page styled with responsiveStyles + tokens', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'card', type: 'flex',
+      responsiveStyles: {
+        large: { display: 'flex', flexDirection: 'column', gap: 'var(--space-4)', padding: 'var(--space-6)', backgroundColor: 'var(--surface)', border: '1px solid hsl(var(--primary))' },
+        small: { padding: 'var(--space-4)' },
+      },
+      properties: {
+        children: [
+          { id: 'price', type: 'element:text', responsiveStyles: { large: { fontSize: '40px', color: 'var(--text-strong)' } }, properties: { content: '$29' } },
+        ],
+      },
+    }));
+    expect(findings).toEqual([]);
+  });
+
+  it('errors when a styled node has no id (CSS cannot be scoped)', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      type: 'flex', responsiveStyles: { large: { padding: 'var(--space-4)' } },
+    }));
+    expect(rules(findings)).toContain(STYLE_NODE_MISSING_ID);
+    expect(findings[0].severity).toBe('error');
+  });
+
+  it('warns when a smaller breakpoint has no large base', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'x', type: 'flex', responsiveStyles: { small: { padding: 'var(--space-2)' } },
+    }));
+    expect(rules(findings)).toContain(STYLE_RESPONSIVE_NO_BASE);
+  });
+
+  it('warns on Tailwind-looking className (silently dead in metadata)', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'x', type: 'flex', className: 'flex flex-col gap-4 md:grid-cols-2 bg-primary',
+    }));
+    expect(rules(findings)).toContain(STYLE_CLASSNAME_TAILWIND);
+  });
+
+  it('warns on an unknown CSS property (typo)', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'x', type: 'flex', responsiveStyles: { large: { flexDirektion: 'column' } },
+    }));
+    expect(rules(findings)).toContain(STYLE_UNKNOWN_CSS_PROPERTY);
+  });
+
+  it('warns on an unknown design token (typo)', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'x', type: 'flex', responsiveStyles: { large: { padding: 'var(--spcae-6)' } },
+    }));
+    expect(rules(findings)).toContain(STYLE_UNKNOWN_TOKEN);
+  });
+
+  it('resolves known tokens (incl. hsl(var(--primary))) without complaint', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'x', type: 'flex',
+      responsiveStyles: { large: { color: 'hsl(var(--primary))', boxShadow: '0 0 0 3px hsl(var(--primary) / 0.25), var(--shadow-lg)', borderRadius: 'var(--radius-xl)' } },
+    }));
+    expect(findings).toEqual([]);
+  });
+
+  it('recurses into nested properties.children', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'root', type: 'flex', responsiveStyles: { large: { display: 'flex' } },
+      properties: { children: [
+        { type: 'flex', responsiveStyles: { large: { gap: 'var(--space-2)' } } }, // missing id, nested
+      ] },
+    }));
+    expect(rules(findings)).toContain(STYLE_NODE_MISSING_ID);
+  });
+
+  it('does not flag a plain non-Tailwind className', () => {
+    const findings = validateResponsiveStyles(stackWith({
+      id: 'x', type: 'flex', className: 'my-custom-scope', responsiveStyles: { large: { display: 'flex' } },
+    }));
+    expect(rules(findings)).not.toContain(STYLE_CLASSNAME_TAILWIND);
+  });
+});
diff --git a/packages/lint/src/validate-responsive-styles.ts b/packages/lint/src/validate-responsive-styles.ts
