Skip to content

feat(design): add advisory conformance check and local Studio - #8313

Draft
BillLeoutsakosvl346 wants to merge 57 commits into
stagingfrom
codex/design-system-rollout
Draft

BillLeoutsakosvl346 wants to merge 57 commits into
stagingfrom
codex/design-system-rollout

Conversation

@BillLeoutsakosvl346

@BillLeoutsakosvl346 BillLeoutsakosvl346 commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add warning-only design conformance to the existing Test and Build workflow, with file/line annotations and a downloadable report. Failed inspection and stale generated infrastructure are errors.
  • Generate committed EMCN contracts from public APIs, source recipes, defaults, slots, forwarding and global CSS. The diff checker, full scanner and local Studio share this implementation and one findings list.
  • Handle declaration files, aliases/barrels, namespace recipes, lexical scopes, finite helpers/props bundles, imported CSS and compiler identity. Unsupported public types and styling flows stay explicitly unchecked.
  • Validate source-local @designAllow / @designProtect metadata; keep longhand permissions specific and reject contradictory shorthand permissions. Central changes remain findings after regeneration.
  • Keep Studio local under tools/design-studio. All discovered visual EMCN exports and every detected Extra are included. Fixtures declare supported axes/states, and captures verify the intended visible surface. Missing fixtures and failures remain visible.
  • Keep landing (including its shared content engine), docs, Monaco presentation, provider brands and block identity palettes excluded. Product imports from excluded landing implementations report a coverage boundary.

Product appearance is unchanged. Reports and browser images remain outside the repository. This draft targets staging and supersedes the closed draft #7827.

Type of Change

  • New tooling and bug fixes

Files by purpose

  • scripts/design-conformance/: generated facts, shared analysis, ownership validation, diff/CI reports and the rule contract.
  • scripts/generate-design-contracts.ts, root commands and audit runner: generation and read-only freshness checks.
  • scripts/design-scan/, scripts/design-studio/: full scan and explicit local catalog/capture refresh.
  • tools/design-studio/: standalone local UI, real fixtures and labeled indicative source-style samples.
  • EMCN TSDoc, agent guidance and script tests: intentional customization, regeneration workflow and regression coverage.

Local workflow

# During editing: staged, unstaged and nonignored new product files
bun run check:design --base origin/staging --working-tree

# When central design sources change; commit the generated artifact
bun run design:generate
bun run check:design-generated

# Review the committed PR diff
bun run check:design --base origin/staging --head HEAD

# Explicit local inventory and visual refresh
bun run design:scan --repo . --working-tree --output /tmp/sim-design-scan
bun run studio:refresh
bun run studio:dev

# Focused browser checks against a running local Studio
SIM_STUDIO_E2E_URL=http://127.0.0.1:3001 \
SIM_STUDIO_E2E_REPORT_PATH=/tmp/sim-studio-e2e/report.json \
bun run test:studio:e2e

Prefer EMCN and global styles where they fit, and explain intentional new treatments in ordinary PR review. Review records never suppress findings or control Studio inclusion. CI checks the diff and infrastructure freshness; full browser captures are explicitly local.

Testing

  • 916 tests in 48 script suites passed, including temporary Git CLI cases for component/API lifecycle, declaration files, recipe/helper/forwarding changes, metadata validation, working-tree edits, immutable isolation, occurrence matching, exclusions and failure handling. Independent CLI probes also checked poisoned working trees and compiler-cache changes.
  • 52 audits, all 26 repository type tasks and lint tasks passed. Generated freshness, design/Studio types, block-registry and docs-manifest checks passed.
  • Two unchanged generator runs produced identical bytes: 392,067 bytes, 568 exports, 22 recipes, 292 tokens and 402 explicit diagnostics. Two unchanged generator runs reproduced the same SHA-256 hash; memory remains about 1 GiB maximum RSS.
  • Same-source scan reconciliation at 637ddec1d6: 2,316 → 2,315 findings, with every occurrence reconciled. Fifteen previously missed component-owned overflow/outline overrides appeared; eight false width warnings and eight landing-content findings were removed. Zero inspection failures; no landing/docs/content-engine findings. The class-map fix preserved all 2,315 occurrences and added two explicit unchecked product object classifications.
  • Committed check against staging completed with fresh infrastructure and zero inspection failures: 28 warnings—22 intentional central definition/ownership changes and six existing font/height overrides newly exposed by generated ownership. These stay visible; this PR does not migrate product styling.
  • Production Turbopack build passed with the workflow's dummy environment. The route manifest has 934 routes and no Studio route.
  • 48/48 fixture browser checks and 7 catalog interaction checks passed on the final revision, including combined options, checkbox interaction, disabled/open state handling and live Extra previews in light/dark at 16px/20px. Two normal unchanged-source Studio refreshes produced identical stable manifests and all 7,852 image hashes, with zero capture or inspection failures; the second run may reuse validated cached captures. Four inappropriate open-state captures were removed because the ChipModal open=false selection now stays closed.
  • All final CI checks passed, including the production app build. Greptile reported 5/5 on 8b7f8413b8; Cubic completed, and all 81 review threads are resolved. Review fixes cover repeated authored occurrences, nested anonymous-layer rule order, effective JSX/object props ordering, ChipModal state labeling, bounded helper-return keys and effective wrapper defaults, statically false class-map entries, React numeric style serialization, and safe generated output paths/descriptors. Exported class-map dispatch follows proven same-file/central consumers, including namespace imports. Bounded CVA configs and flat compound arrays retain source-only change evidence; ambiguous inputs remain unchecked. Central extraction failures fail comparisons on either side and preserve rename origins. A nested-array CLI timeout regression verifies early rejection.

Coverage limits

The final refresh includes 759 component/icon/variant entries: 522 captured and 237 Needs fixture (10 base exports and 227 variants). All 2,315 Extra signals have captures: 37 use real source components and 2,278 use explicitly labeled indicative source-style samples. The UI groups these signals into 725 visual treatments and the component entries into 281 sections. Missing fixtures remain visible and keep the overall run incomplete; successful captures do not imply complete coverage.

Source discovery and contract generation are automatic within supported syntax. Intentional customization metadata and fixture props/providers still need human decisions. New values on a supported finite fixture axis are discovered automatically; a new axis requiring different data remains Needs fixture. Captures invalidate conservatively on checkout changes. Exported object classification uses same-file and supplied central consumers; unchanged arbitrary product consumers are not searched by the diff check, so insufficient evidence stays unchecked. Static provenance does not prove runtime selector/theme availability, full CSS cascade or arbitrary JavaScript. Unknown flows remain visible. See scripts/design-conformance/README.md.

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing; regressions proved red before fixes
  • No new warnings introduced (28 retained design warnings explained above)
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

@vercel

vercel Bot commented Sep 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs Ready Ready Preview Sep 26, 2026 8:54pm UTC

Request Review

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@greptile

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@greptile-apps

greptile-apps Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[High risk] Adds design conformance checking and modifies build configuration.

The PR appears safe to merge based on the changes reviewed.

Summary

Adds advisory design-conformance checks and a local Studio. Since the previous review, the PR expands bounded CVA analysis, treats central extraction failures as incomplete comparisons, and resolves namespace styling references. No new actionable issue was established.

Reviews (18) · Last reviewed commit: "docs(design): document finite CVA analys..."

Comment thread scripts/design-scan/inventory.ts Outdated
Comment thread scripts/design-scan/report.ts

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 113 files

Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic

Comment thread scripts/design-conformance/appearance.ts
Comment thread tools/design-studio/app/layout.tsx Outdated
Comment thread scripts/design-conformance/evaluate.ts Outdated
Comment thread scripts/design-conformance/control-associations.ts
Comment thread .agents/skills/emcn-design-review/SKILL.md Outdated
Comment thread scripts/design-conformance/control-simplifications.ts Outdated
Comment thread scripts/design-conformance/control-simplifications.ts Outdated
Comment thread scripts/design-conformance/catalogue.ts Outdated
Comment thread package.json Outdated
Comment thread tools/design-studio/_components/generated-gallery.tsx Outdated
@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@greptile

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 114 files

Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic

Comment thread scripts/design-conformance/model.ts Outdated
Comment thread scripts/design-conformance/artwork.ts
Comment thread scripts/design-conformance/control-associations.ts Outdated
Comment thread scripts/design-conformance/control-review.ts Outdated
Comment thread scripts/design-conformance/cli.ts Outdated
Comment thread scripts/design-conformance/central-recipes.ts Outdated
Comment thread scripts/design-conformance/control-colour-assignments.ts
Comment thread scripts/design-conformance/normalize.ts
Comment thread scripts/design-conformance/control-typography.ts
Comment thread scripts/design-conformance/lint.ts Outdated
@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@greptile

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 114 files

Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic

Comment thread scripts/design-conformance/control-review.ts Outdated
Comment thread scripts/design-conformance/control-colour-assignments.ts
Comment thread scripts/design-conformance/conformance.ts Outdated
Comment thread scripts/design-conformance/control-simplifications.ts Outdated
Comment thread scripts/design-conformance/control-simplifications.ts Outdated
Comment thread scripts/design-conformance/control-typography.ts Outdated
Comment thread scripts/design-conformance/control-imperative.ts Outdated
Comment thread scripts/design-conformance/control-imperative.ts Outdated
Comment thread scripts/design-conformance/control-imperative.ts Outdated
Comment thread scripts/design-conformance/model.ts
@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 118 files

You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Fix all with cubic | Re-trigger cubic

Comment thread scripts/generate-design-contracts.ts Outdated
Comment thread scripts/design-conformance/extract.ts Outdated
@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@greptile

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 119 files

You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Fix all with cubic | Re-trigger cubic

Comment thread scripts/design-conformance/extract.ts Outdated
@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@greptile

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 119 files

Confidence score: 3/5

  • In scripts/design-conformance/extract.ts, array-valued CVA conditions collapse to the same context, so changes such as size: ['small'] to size: ['large'] can evade appearance comparisons; serialize finite literal arrays in the condition context.
Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="scripts/design-conformance/extract.ts">

<violation number="1" location="scripts/design-conformance/extract.ts:1351">
P2: Array-valued CVA compound conditions collapse to the same `'<unchecked>'` context, so changing `size: ['small']` to `size: ['large']` is invisible to appearance comparison. Serialize finite literal arrays in the condition signature or report them as unchecked.</violation>
</file>

You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Fix all with cubic | Re-trigger cubic

Comment thread scripts/design-conformance/extract.ts Outdated
Comment thread scripts/design-conformance/extract.ts Outdated
Comment thread scripts/design-conformance/conformance.ts Outdated
Comment thread scripts/design-conformance/source-summary.ts
@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@greptile

@BillLeoutsakosvl346

Copy link
Copy Markdown
Contributor Author

@cubic-dev-ai review this PR

@cubic-dev-ai

cubic-dev-ai Bot commented Sep 26, 2026

Copy link
Copy Markdown
Contributor

@cubic-dev-ai review this PR

@BillLeoutsakosvl346 I have started the AI code review. It will take a few minutes to complete.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 119 files

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

You've manually re-run cubic several times on this PR. Each manual re-review checks the full PR again and counts toward your usage quota. To preserve your usage limits, we recommend letting cubic automatically review new commits.

Re-trigger cubic

This branch was successfully deployed

1 active deployment
Preview — 8b7f8413 Deployed Sep 26, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant