Generative UI design system: constrain components, states, and runtime evidence

Generative UI means that an agent influences the interface shown for a particular request or context. It isn't the same as AI-assisted design, where a tool helps a person create a mostly fixed interface, and it's broader than raw code generation. An agent can select a prebuilt component, declare a structured component tree, or generate executable interface code. Those routes grant very different authority.

The design-system job is narrower than the whole generative UI stack. It defines reusable visual decisions and component contracts. It doesn't determine whether a user may view an account, approve a payment, disclose private data, or retry a failed operation. Those decisions need current application policy and runtime facts.

Choose the route per product surface, not for the company as a whole. A support assistant may select fixed status cards, while an analysis workspace may need bounded declarative composition. A prototype sandbox may permit generated code that would be unacceptable in an account or billing surface.

Use the least permissive route that can express the current user task. Moving from fixed selection to declarative composition is a product decision because it changes what must be validated. Open-ended code generation also changes the execution and security boundary.

A component catalog becomes governable when every decision has an owner and every failure has a correction route. Don't collapse those responsibilities into a single generative UI owner column. The model, design system, application, and runtime do different jobs.

When an interface fails, inspect these layers in order. Repair the first layer where the recorded expectation differs from the evidence. A local CSS change can hide a bad catalog mapping, while a prompt edit can hide an authorization defect. Neither corrects the governing decision.

Presence in a component library doesn't amount to admission into a generative catalog. A component can be stable for human-authored screens while still lacking bounded content, machine-readable states, safe action semantics, or a fallback that works without model judgment.

1. Name the catalog, catalog version, component identity, and component version. A declaration must target these identities explicitly.
2. List accepted data with provenance requirements, validation rules, freshness limits, and content bounds. Don't let free text stand in for authoritative runtime facts.
3. Enumerate supported states and legal transitions. Include loading, empty, partial, unavailable, error, interrupted, and recovered states when the task can reach them.
4. Define permitted actions, their consequence classes, and the application authority that approves them. Component visibility doesn't grant permission.
5. Map semantic visual roles rather than raw values. Record modes, focus behavior, user-preference handling, and approved exceptions.
6. Define a deterministic fallback for every rejection class. The fallback must work without asking the model to repair its own invalid output.
7. Name the contract, policy, implementation, evidence, and acceptance owners. One person may hold several roles, but the roles remain distinct.
8. Specify the evidence needed for the component in isolation and in each named consumer. Mark unexecuted cases as unexecuted.

The following record is illustrative and protocol-neutral. It hasn't been executed, validated against a live schema, or accepted for a production consumer.

{
  "recordStatus": "illustrative_unexecuted",
  "catalog": { "id": "workspace-ui", "version": "1.4.0" },
  "component": { "id": "task-summary-card", "version": "2.1.0" },
  "eligibleSurfaces": ["project-workspace"],
  "input": {
    "schema": "TaskSummaryInput@2",
    "provenance": ["application-task-service"],
    "freshness": "checked_by_application",
    "contentBounds": {
      "title": { "min": 1, "max": 90 },
      "summary": { "min": 0, "max": 600 },
      "items": { "min": 0, "max": 12 }
    }
  },
  "states": [
    "loading", "ready", "empty", "partial",
    "stale", "error", "interrupted", "recovered"
  ],
  "actions": [
    {
      "id": "open-task",
      "consequence": "navigation",
      "authorizationSource": "application-policy"
    },
    {
      "id": "mark-complete",
      "consequence": "durable-write",
      "authorizationSource": "task-service",
      "confirmation": "policy-dependent"
    }
  ],
  "forbidden": [
    "agent-supplied-permission-state",
    "unbounded-html",
    "action-success-inferred-from-click"
  ],
  "visualRoles": [
    "background", "foreground", "card", "card-foreground",
    "border", "primary", "primary-foreground", "ring",
    "muted", "muted-foreground", "destructive"
  ],
  "accessibilityObligations": [
    "programmatic-name",
    "keyboard-action-path",
    "visible-focus",
    "status-not-conveyed-by-color-alone",
    "content-reflow-under-supported-zoom"
  ],
  "fallbacks": {
    "unknownComponent": "safe-message",
    "invalidInput": "safe-message",
    "permissionDenied": "permission-notice",
    "missingData": "task-list-link",
    "interruptedStream": "last-validated-snapshot"
  },
  "owners": {
    "contract": "design-system-team",
    "policy": "workspace-product-team",
    "authorization": "task-service-owner",
    "implementation": "frontend-platform",
    "acceptance": "workspace-release-owner"
  },
  "requiredEvidence": [
    "schema-validation-record",
    "isolated-state-results",
    "policy-decision-log",
    "named-consumer-observations",
    "keyboard-and-screen-reader-results",
    "interruption-and-recovery-results"
  ]
}

Visual-system artifacts can supply the catalog with semantic color roles, typography roles, spacing values, layout guidance, light and dark mappings, motifs, and usage constraints. Component contracts then map those inputs to supported structures and states. The consuming application still decides whether a component is permitted, which data is authoritative, and which actions the user may take.

Ambient Sage provides a concrete example of that boundary. Its public kit defines semantic visual roles, Plus Jakarta Sans and JetBrains Mono typography roles, spacing, layout guidance, DESIGN.md, and structured exports. A product team could map those inputs into its own components. The kit doesn't prove that the mapping is correct, that a protocol accepts it, that an action is authorized, or that the composed interface is accessible.

Focus and preference handling need the same separation. A visual source may provide a ring role. A component contract defines when the component exposes focus, and CSS and platform code implement the behavior. The application decides theme policy and persists user choices. Acceptance evidence records whether the complete path worked in the named consumer.

A single status such as generated, done, or successful collapses claims that need different proof. Track the declaration as it crosses each boundary. A later state doesn't retroactively prove that every earlier decision was correct, and a component can render while the task remains incomplete.

1. 1

   Declared

   The catalog and application define the permitted components, versions, states, relationships, and evidence requirements.

2. 2

   Generated

   The agent emits a proposal. Preserve the proposal identity and targeted catalog version without treating it as approved.

3. 3

   Validated

   Deterministic checks confirm schema shape, component identity, versions, content bounds, and allowed relationships.

4. 4

   Policy-approved

   Application policy and authorization permit the proposed data disclosure, component use, and actions for the current context.

5. 5

   Rendered

   The renderer resolves the approved declaration to known implementations or a deterministic fallback.

6. 6

   Interactive

   Required controls are available through supported input and assistive-technology paths under the recorded environment.

7. 7

   Completed

   The authoritative service reports the requested operation's terminal result. A click, optimistic state, or stream ending isn't enough.

8. 8

   Observed

   The product records the relevant interface, runtime, and user outcome evidence for the named consumer and conditions.

9. 9

   Accepted

   The acceptance owner compares observations with expectations, resolves required exceptions, and records pass, revise, or block.

Fallbacks belong to the product contract, not model recovery prose. Each rejection class should produce a known result, preserve useful validated work where safe, and expose a stable retry or alternate path.

A catalog can behave differently across chat, co-creator, and embedded application surfaces. Name the consumer, region, data sources, catalog versions, policies, fallbacks, environments, and acceptance owner. Without that context, a passing component demo can be misapplied to a materially different surface.

record_status: illustrative_unexecuted
consumer:
  id: project-workspace/task-panel
  surface: embedded-application
  adaptive_region: task-panel-body
  stable_regions:
    - application-navigation
    - account-controls
catalogs:
  - id: workspace-ui
    version: 1.4.0
allowed_components:
  - task-summary-card@2.1.0
  - safe-message@1.0.0
  - permission-notice@1.2.0
data_authorities:
  task_state: application-task-service
  authorization: task-service
  user_preferences: application-profile-service
composition:
  route: declarative
  executable_code: forbidden
  nested_depth_max: 4
fallback_policy: workspace-genui-fallbacks@1
acceptance_owner: workspace-release-owner
observations: unexecuted

Write expectations before generating test output. Add observations, evidence references, and dispositions only after execution. The example below is deliberately unexecuted. It's a test plan, not proof that the named consumer or components exist.

Retest when the catalog, component, schema, renderer, authorization policy, fallback policy, named consumer, supported browser or platform, or relevant accessibility behavior changes. Evidence from another surface may inform the plan, but it doesn't automatically transfer.

1. 1

   Freeze the expected record

   Identify the exact catalog, component, consumer, policy, data authority, fallback, environment, and evidence requirement involved.

2. 2

   Inspect the original declaration

   Check component IDs, versions, properties, content bounds, relationships, and action requests before looking at the screenshot.

3. 3

   Read validation and policy evidence separately

   A schema pass and a policy approval answer different questions. Find the earliest recorded rejection, omission, or unexpected approval.

4. 4

   Compare renderer input with output

   Confirm which approved declaration reached the renderer and which implementation and fallback versions it resolved.

5. 5

   Trace runtime facts and events

   Check data freshness, authorization, action IDs, terminal service results, interruption, persistence, and recovery.

6. 6

   Compare observed behavior with acceptance criteria

   Use the named environment and user path. Record uncertainty instead of filling a missing evidence field with inference.

7. 7

   Correct the first divergence and retest downstream

   Repair the owning layer, preserve the evidence chain, and rerun every downstream case invalidated by the change.

This method separates common defects. An unknown or underspecified component is a catalog problem. A request outside the contract is an agent-declaration problem, while a valid but prohibited combination is a policy rejection. Incorrect mapping is a renderer defect. Stale data or a lost completion event is a runtime integration failure. A preference without an owner is an unresolved product decision.

Identity Forge can supply upstream visual-system inputs for a governed catalog: semantic light and dark color roles, typography, spacing, layout and motif guidance, DESIGN.md, and structured exports. Those artifacts can reduce visual ambiguity for component authors and coding agents.

The consuming team still owns the component implementation, catalog schema, protocol integration, validation, application policy, authorization, sandbox or execution boundary, runtime data, event handling, persistence, accessibility evaluation, acceptance evidence, and release decision. A complete kit doesn't certify any of those downstream layers.

Choose one high-reuse component in one named product surface. Write its admission record, declare its data and authorization sources, implement every required fallback, and trace one generated declaration through validation, policy, rendering, interaction, completion, observation, and acceptance. Don't expand the catalog until that record contains real observations instead of unexecuted fields.

• What is Generative UI? Building Agent-Powered Interfaces: Describes fixed, declarative, and open-ended generative UI approaches and identifies security, testing, latency, and accessibility as production concerns.
• Generative UI and Outcome-Oriented Design: Defines generative UI as interfaces generated in real time for user needs and argues that designers must define constraints around desired outcomes.
• Generative UI: A rich, custom, visual interactive user experience for any prompt: Documents Google's implementation and evaluation framing for dynamically generated interactive experiences.
• Generative UI: Understanding Agent-Powered Interfaces: Distinguishes generative UI surfaces such as threaded chat, co-creator workspaces, and interfaces embedded in an application.
• What Is GenUI? Generative UI Explained, with Examples: Discusses how an existing design system can constrain model-controlled interface composition.
• A2UI v0.9: The New Standard for Portable, Framework-Agnostic Generative UI: Presents a versioned declarative route in which agents express UI intent against a client application's component catalog and renderer.
• Ambient Sage Design Kit: Publishes Ambient Sage as a free visual kit with semantic colors, typography, spacing, layout guidance, DESIGN.md, and structured implementation artifacts.
• Design system accessibility checklist: test the system, then retest the product: Explains why documented intent and isolated component evidence do not prove accessibility in a composed product consumer.