What should an AI design system include for agents and model-driven components?

AI design system: which core files and contracts must exist?

Answer. The minimum publishable set is four machine readable artefacts that form the contract an agent reads instead of reverse engineering code.

• Typed tokens in a standard tokens format so runtime and design tools resolve identical values. Use the Design Tokens Format for typed tokens, theming and extension metadata as specified in the Design Tokens Community Group report (Design Tokens Format Module 2025.10) (Design Tokens Community Group / W3C, 2025).
• Canonical component contracts that list inputs, supported runtime states and allowed child blocks. Publish these as machine readable manifests so agents know what props to supply and what children are permitted. The Custom Elements Manifest schema is the established format for component API metadata (webcomponents / Custom Elements Manifest, 2024).
• A design system index that the agent can read instead of inferring style from code. Store canonical docs, example inputs and the rules the model must follow in a ./design-system-index folder so agents reference the same source as engineers. Builder.io recommends an indexed project folder so agents use canonical tokens and docs rather than scattered code (Builder.io docs, 2026).
• An AGENTS.md or agent manifest that defines instruction rules, verification commands and failure handling so agents can run the same checks as developers. Builder.io documents using an AGENTS.md paired with a project index to let agents run verification scripts such as npm run test:verify-ui (Builder.io blog, 2026).

Link these four files to engineering as the contract. When an agent needs to place a result card it reads the contract for that component, reads typed tokens for spacing and colour, and uses AGENTS.md to run the verification command that validates the result.

See our dynamic design systems service for how to hand these artefacts to engineering.

What file structure and naming convention ties tokens, components and agents?

Answer. Use a single source folder with predictable, tool friendly names so agents and build tools can resolve paths without heuristics.

A stable package path and consistent filenames let an agent import tokens and contracts with one path. Builder.io recommends keeping package names stable so agents reference tokens with a single import path such as @acme/ui (Builder.io docs, 2026). Keep token files typed and named so token resolvers can parse their type and theme.

• ./design-system-index/README.md
• ./design-system-index/components/*.md
• ./packages/@acme/ui/tokens/{light.json,dark.json,aliases.json}
• ./packages/@acme/ui/components/{button,card}/custom-elements.json
• ./manifests/mcp/*.mcp.json
• ./agents/AGENTS.md
• ./verification/run-verify.sh or npm scripts (npm run test:verify-ui)

Use typed token filenames that follow the Design Tokens Format so resolvers can parse types, colour spaces and extension metadata (Design Tokens Community Group / W3C, 2025). Store component API metadata as custom-elements.json files in each component folder so tools can pick them up automatically (webcomponents / Custom Elements Manifest, 2024). This layout makes automated verification and runtime assembly predictable.

How should component contracts be authored so agents can consume and render them?

Answer. Publish a machine readable contract for every component that includes props, accepted data schemas, supported runtime states, allowed children and provenance outputs.

Author contracts using the Custom Elements Manifest schema for props, attributes, events and slots, then extend that schema with model metadata fields for runtime states such as loading, streaming, uncertain and failed. Include example JSON inputs and minimal visual examples so an agent fills verified inputs rather than inventing layout.

• Props and types. Use explicit types and nullability so an agent can type check inputs before rendering.
• Accepted data schemas. Reference JSON Schema or a lightweight schema for each data prop to avoid malformed data at runtime.
• Runtime states. Add fields such as state: [loading, streaming, uncertain, failed, accepted] and supply the expected UI fragment for each state.
• Allowed children. List permitted child components and their contracts so composition is safe.
• Provenance outputs. Define which fields the component returns for audit logs, such as sourceIds and confidence scores.

Place minimal visual test fixtures alongside the contract. For example include a one screen Story with a loading, streaming and uncertain example so the agent can run a headless interaction test against those fixtures. When you need component UI patterns for model outputs see our AI product design service.

How do verification metadata and agent manifests create a verification loop agents can run?

Answer. Put verification commands and rules in AGENTS.md and the design index so agents run the same checks as developers and cannot hallucinate layout or tokens.

The verification loop is simple. An agent assembles a UI from canonical tokens and component contracts, runs the verification script for the project and then either accepts the UI or emits diagnostics that the agent must fix or surface. Builder.io documents this loop and gives an example command such as npm run test:verify-ui that runs TypeScript, ESLint agent config, Stylelint and headless Storybook interaction tests (Builder.io blog, 2026). The same command must be available to an agent and CI so behaviour matches between human and machine checks.

Place the verification command and rule list in AGENTS.md with examples of acceptable and unacceptable outputs. Builder.io recommends the same so agents run project specific checks rather than assuming global rules (Builder.io docs, 2026). Store diagnostics schemas so an agent can parse errors and retry with corrected inputs.

Which standards and formats should we adopt now?

Answer. Adopt three standards so agents and humans share the same grammar: Design Tokens Format, Custom Elements Manifest and an AGENTS.md plus a design-system-index folder.

These standards let tools parse tokens, read component contracts and run verification without bespoke adapters. The Design Tokens Format became a community report in 2025 (Design Tokens Community Group / W3C, 2025). The Custom Elements Manifest schema is established for component metadata with schemaVersion 2.1.0 in the repo (webcomponents / Custom Elements Manifest, 2024). Builder.io published practical guidance for AGENTS.md and a design index in 2026 that maps to verification scripts and rule files (Builder.io blog and docs, 2026). Model driven UI research also supports publishing explicit models and metadata so adaptive interfaces remain explainable and safe (Silvia Abrahão et al., 2021). Use these three together.

How do we migrate a legacy design system to an AI-ready layout without stopping product work?

Answer. Run a four stage migration that keeps the product shipping and introduces AI readiness incrementally.

• Audit and map current tokens and components to the target typed token format and record gaps. Use the Design Tokens Format as the target token model so you know which values need conversion (Design Tokens Community Group / W3C, 2025).
• Publish a parallel package such as @acme/ui-v2 that contains typed tokens and initial component manifests. Keep the original package stable so existing imports do not break. Builder.io recommends stable package names so agents can resolve a single import path (Builder.io docs, 2026).
• Add AGENTS.md and a design-system-index that references the new package. Put the verify script in the new package and wire CI to run it on pull requests so every change is checked by the agent command.
• Gradually replace components on touched screens. For each replacement run the verification command, record pass/fail and track remaining legacy screens on a visible board. This follows the pragmatic rollout advice in our design system guide where adoption starts on new screens then replaces old components as they are touched.

Hook the verification script to pull requests so agents and CI run the same tests. Our design system guide explains how to keep a system alive while rolling changes and our dynamic design systems page explains the artefacts engineers need to assemble model driven interfaces.

Owner checklist: what must be in place before an agent can render and verify UIs?

Answer. A compact checklist owners can sign off so agents have everything needed to render and verify UIs.

• Typed tokens published in the Design Tokens Format and reachable at a stable package path, for example @acme/ui/tokens. (Design Tokens Community Group / W3C, 2025)
• Component contracts exported as custom-elements.json plus per component model metadata, runtime states and example JSON inputs. (webcomponents / Custom Elements Manifest, 2024)
• A design-system-index folder with canonical component docs, minimal visual examples and allowed composition rules. (Builder.io docs, 2026)
• An AGENTS.md with instruction rules, a verify script example and diagnostics format. The verify script should be runnable locally and in CI. (Builder.io blog, 2026)
• CI hooks that run the verification script on pull requests so changes are checked before merging.
• A migration plan and tracking board for legacy screens and components, with owners assigned to each task. See How to build a design system, implement it and keep it alive for templates.
• A rollout milestone that starts adoption on new screens and gradually replaces legacy components as those screens are touched.

Assign each checklist item a single owner from design ops or engineering and a corresponding ticket in your tracker so the verification loop is repeatable and auditable. If you need artefacts and templates we provide handoff packages for engineers in our dynamic design systems and pattern work in AI product design.