Skip to content

Add a headless model and part-set runtime to the design system - #9578

Draft
shawnmcclelland wants to merge 2 commits into
claude/design-system-foundationfrom
claude/design-system-model-parts
Draft

shawnmcclelland wants to merge 2 commits into
claude/design-system-foundationfrom
claude/design-system-model-parts

Conversation

@shawnmcclelland

@shawnmcclelland shawnmcclelland commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #9575 (design-system foundation). Draft for feedback and review before anything builds on it.

What this adds

A frontend pipeline that maps a surface from one rendering to another. It adds no app screens and changes none.

  • Model (@agent-native/design-system/model): a surface is described once as rows with stable dotted ids, labels, state and effects. It holds no layout or styling. validateModel lists every issue, and rowIdSegment turns app data such as an email into a valid id.
  • Runtime (ModelSurface, defineDesignSystem({ parts })): a part set is markup for catalog parts, keyed by part (settings.row). ModelSurface draws a model through the app's part set and falls back to toolkit's own parts. It throws on an unknown part, an unhandled effect or an unfilled slot, so nothing degrades silently.
  • Checks:
    • checkPartSetEquivalence({ model, target }) renders a model through two part sets and compares rows, tree, accessible names and state.
    • applyRowLocators, captureRowStyles and compareRowStyles(source, target) map a rendering that has no row ids onto the model by selector, then compare painted styles row by row.
  • Agent-Native part set: settings nav, groups, rows, sections, notices, reports, buttons and glyphs, on the Base UI parts. It's exercised by its specs only; no screen draws through it yet.

The design-system skill documents the model, parts and checks in references/model.md.

Feedback wanted

  • The row shape (id, part, kind, state, effect, slot, regions, hosts) and the dotted-id rules
  • Throwing on unknown parts, unhandled effects and unfilled slots, versus falling back
  • The two checks' contracts: which fields equivalence compares, and how a source rendering maps onto row ids

Testing

  • design-system: build, unit tests, css:check, typecheck
  • toolkit: typecheck, design-system and settings specs, test:storybook
  • pnpm guards

@shawnmcclelland shawnmcclelland self-assigned this Nov 20, 2026
@shawnmcclelland shawnmcclelland changed the title Draw Settings from a headless model through part sets Add a headless model and part-set runtime to the design system Nov 20, 2026
@shawnmcclelland
shawnmcclelland force-pushed the claude/design-system-model-parts branch from 84b431b to 75a5716 Compare November 20, 2026 21:41
@agent-native/design-system/model describes a surface once as rows with stable dotted ids, validates them, defines the row attributes every part writes, captures rendered rows with names and state read from ARIA, and compares two renders structurally. A source rendering without row ids maps onto the model by selector, so its painted styles compare with a target part set's row by row. The design-system skill documents it in references/model.md.
ModelSurface draws a screen model through the design system's part set, falling back to toolkit's own parts, and throws on an unknown part, an unhandled effect or an unfilled slot. defineDesignSystem takes a parts map. The Agent-Native part set draws settings nav, groups, rows, sections, notices and reports, buttons and glyphs on the Base UI parts. checkPartSetEquivalence checks that a target part set draws a model with the same rows as ours. The eject manifest declares the dependencies the copied parts bring.
@shawnmcclelland
shawnmcclelland force-pushed the claude/design-system-model-parts branch from 75a5716 to 70bc260 Compare November 20, 2026 21:53

This branch has not been deployed

No deployments
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