# Build with the toolkit

Use this workflow when an agent builds or changes an application with `@dg/ui`. The user's request sets the scope; this guidance supplies implementation contracts, not permission to publish, deploy, edit unrelated applications or change shared visual defaults.

## Read the sources

Start with the [quick reference](../getting-started/quick-reference.md), then the exact reference of every component, class or token you use. Read the nearest AGENTS.md and the existing source before editing. Component source owns behavior, CSS owns values and Markdown owns the public explanation; when they disagree, reconcile them instead of inventing an API.

The DS publishes generated views of the same sources: `/llms.txt` lists every page, `/ai-context.md` assembles the quick reference and the build guides, `/component-manifest.json` gives exact props and `/tokens.json` gives token roles and values. Each page's Markdown path, such as `/components/button.md`, returns the original file. A deployed version can differ from a local checkout; check `version` before mixing evidence.

## Build

Start a new app from the [boilerplate](../../../../apps/boilerplate/README.md). Follow the quick reference shell and rules, adapt the [collection](recipe-collection.md) or [form](recipe-form.md) recipe where it fits, and implement the applicable states of the [state contract](../getting-started/composition.md#state-contract) with recovery paths. Check long labels and content, not only demo data.

## Ask at the right boundary

Proceed with routine, reversible decisions within the request. Ask before changing a public API, the shared visual language, accessibility behavior or compatibility, and before publishing anything. Present rendered comparisons for significant visual decisions; passing checks is not human approval.

## Verify and hand off

Run the workspace checks, which type-check application code and reject unknown props, and the app build, then follow [accessibility verification](accessibility.md). Explain what changed, why, what was verified and what was not. A change to `@dg/ui` itself follows the [maintenance process](../maintain/evolution.md#maintenance-process) and starts with `pnpm check:toolkit`.

Measuring whether a fresh agent can build from these sources uses the [independent evaluation protocol](../maintain/agent-evaluation.md); running it requires the user's authorization.