Foundation

AI Builders

Strategy

How DOM Studio should be shaped so LLM agents can generate polished apps that remain editable in Studio.

Goal

Make the best path the easiest path

For LLM-built apps

DOM Studio gives AI a compact set of reliable choices: accessible primitives for behaviour, visual components for surfaces, and blocks for complete application patterns.

For human follow-through

The output should be easy to read, easy to change, and when needed, easy to round-trip through Studio as a named tree of components, props, and children.

Principles

What AI should learn from DOM Studio

Prefer composition over invention

LLMs should reach for known primitives, visual surfaces, and blocks before inventing markup. The smaller the vocabulary, the better the generated UI.

Make the examples canonical

Examples are the strongest teaching material. They show the preferred component, prop, token, spacing, and composition style in a form an LLM can copy safely.

Prefer props for behaviour

Props like tone, variant, placement, floatingMode, options, items, and duration are easier for an LLM to choose correctly than handwritten behaviour.

Use semantic tokens

Token utilities such as skin-raised, text-muted-fg, border-border, bg-primary, bg-success, and bg-warning keep generated screens on-theme.

Keep Studio as a second path

When the result should remain editable, an LLM can return a Studio spec with component, props, children, ids, and labels. That is different from ordinary Vue usage.

Make failure checkable

Generated UI should be easy to validate for unknown components, missing required props, overflow, contrast risks, and unsupported class patterns.

LLM docs

What actually helps an AI use DOM Studio

Area	Why it helps
Component names	Use stable names such as DomButton, DomCard, DomCombobox, DomToastStack, and DomJsonListInput.
Prop shapes	Document the common prop names, defaults, allowed values, and event payloads.
Examples	Provide short examples that are complete enough to copy into an app without extra ceremony.
Theme tokens	Tell LLMs which token utilities to use and when to avoid raw colours.
Blocks	Give LLMs complete dashboard, mail, chat, forms, and login patterns to start from.
Studio specs	Only ask for component/props/children specs when the UI should be edited visually later.

Terse context

A small docs file beats a long sales page

What /llms.txt is for

The AI-facing documentation should be short, direct, and practical. It should name the components, explain the house style, and tell an agent which patterns to prefer.

The public docs can sell the vision. The LLM file should behave more like a recipe card.

# DOM Studio LLM notes
- Use DOM Studio primitives before custom markup.
- Use blocks for dashboard, chat, mail, forms, and login screens.
- Use theme tokens, not raw colours.
- Use component props for behaviour.
- Use Studio specs only when the output must remain visually editable.
- Do not recreate dropdown, dialog, combobox, popover, toast, or keyboard logic.

Editable output

Prefer Studio specs for AI-authored UI

Why specs beat raw markup

Specs preserve the intent behind the UI. A card is still a card, a password field is still a password field, and each layer has a stable identity for later editing.

OKComponents can be inspected and reconfigured.
OKBlocks can be composed, duplicated, and normalized.
OKGenerated apps can round-trip through Studio.

{
	"id": "settings-form",
	"label": "Settings form",
	"component": "DomCard",
	"props": {
		"padding": "lg",
		"class": "w-full max-w-2xl"
	},
	"children": [
		{
			"id": "title",
			"label": "Title",
			"component": "h2",
			"props": { "class": "text-2xl font-semibold tracking-tight" },
			"children": [{ "text": "Account settings" }]
		},
		{
			"id": "email",
			"label": "Email input",
			"component": "DomTextInput",
			"props": {
				"label": "Email address",
				"placeholder": "you@example.com"
			}
		}
	]
}

Studio metadata

_edit is for Studio, not the main AI contract

The _edit blocks are mostly for Studio. They tell the inspector which editor to render for a prop.

They can help an AI only in the narrower case where the AI is generating Studio-aware components or specs. For ordinary app generation, examples, props, events, and theme rules matter more.

{
	"id": "email-field",
	"label": "Email field",
	"component": "DomTextInput",
	"props": {
		"label": "Email address",
		"placeholder": "you@example.com"
	}
}

Component folders

Component metadata lives with the component

Discovery convention

Each component can live beside its docs page and examples. A component manager discovers folders and paths, then the inspector reads Vue props and the component's __doc metadata when a view needs labels, docs, or Studio settings.

Set studio.hidden when a helper component should be exported but not offered in Studio.

<script setup>
defineOptions({
	__doc: {
		name: 'Text input',
		tag: '<DomTextInput>',
		description: 'A labelled single-line text field.',
		icon: 'M5 7h14M12 7v10M8 17h8',
		nav: {
			group: 'Forms',
			badge: 'New',
		},
		studio: {
			group: 'Forms',
			icon: 'T',
			hidden: false,
		},
		events: [
			{ name: 'update:modelValue', payload: 'string', description: 'Fired when text changes.' },
		],
	}
});
</script>

Roadmap

What to add next

LLM manifest

Generate a terse machine-readable index from docs, props, events, slots, examples, and block names. Include Studio metadata separately so agents can opt in only when needed.

More app recipes

Add concise recipes for settings, tables, detail pages, checkout, onboarding, empty states, and admin workflows.

Spec validator

Validate Studio specs before rendering: unknown component, illegal child placement, invalid prop option, missing label, and unsafe HTML.

Design critique harness

Run generated screens through checks for overflow, contrast, mobile layout, focus order, and whether the UI uses semantic tokens.

Tiny prompt contract

Keep /llms.txt short and specific so it can be pasted into an agent context without carrying the whole documentation site.

Migration helpers

Add utilities that can convert HTML or Vue snippets into a Studio spec, then normalize classes and replace ad hoc markup with DOM Studio primitives.

Future examples

AI-specific UI patterns

AI chat tools

Chat interfaces where assistant messages can return structured UI, tool results, forms, cards, tables, and follow-up actions.

Voice tools

Voice-first controls for recording, transcription, interruption, status, and generated UI feedback.

Tool result renderers

Patterns for rendering search results, database rows, file previews, streaming jobs, and agent task output.

Server-backed controls

Autocomplete, combobox, command palette, and picker examples where data is fetched as the user types.

Prompt contract

A short instruction block for AI tools

When building with DOM Studio:
1. Prefer existing DOM Studio components and blocks before custom markup.
2. Use DOM Studio theme tokens, not raw colours.
3. Use component props for behaviour; use classes only for layout and spacing.
4. Keep forms native where possible, and rely on DOM Studio for accessibility.
5. Return Studio specs only when the UI should be visually edited later.
6. When returning Studio specs, give every node a stable id and human label.