Toolkit evolution

Exports, documented props, defaults, methods, public CSS classes and overrides form the public API. Keyboard behavior, accessibility semantics and default visual geometry also belong to the contract. Internal markup, --_ variables and DS-only specimens are not application APIs.

All entries in the reference index are supported public APIs. Experimental work remains app-local until it has a concrete shared use, a documented contract and tests. Do not silently mark an existing public component experimental to justify breaking it.

During 0.x development, a minor version may contain a breaking change only when it is explicitly described. Do not infer compatibility from the version number alone. Release records belong in Changes; do not duplicate the current version in navigation configuration or prose. Historical version headings in that record are intentional.

Treat documentation as part of every public design-system change. This applies to new items, renamed or removed items, changed defaults, visual decisions, interaction and accessibility behavior, not only new parameter names. A visual-only change still needs documentation when it changes a shared decision. A structural cleanup preserves values and cascade order.

1. Identify the owner. Component behavior belongs in its Svelte source, literal token values in tokens.css or breakpoints.css, and shared class behavior in CSS. Document the public contract in the matching component, token or foundation reference. App-specific behavior stays in the app's documentation.
2. Update source and reference together. For a component, update purpose, parameters, exact defaults, methods, overrides, notes, complete Usage examples and Accessibility as applicable. For a token, update its role row without duplicating the CSS value. For a class, update the owning Classes table and composition examples. Explain meaningful constraints and unsupported combinations; do not assert behavior without checking the source.
3. Keep the format consistent. Copy the structure of a nearby reference and follow the reference format. A new component needs its own kebab-case page and an index entry. A new token belongs in the existing role grouping unless it represents a genuinely new shared decision. Add a section to the extraction contract only when it meets a real documentation need.
4. Connect the rendered reference. For a new page or export, list it in its section README.md and add the runnable specimen; navigation and related links derive from that list. Check that the catalogue link reaches the exact documentation page or token/class anchor. For renames and removals, preserve existing URL destinations and update imports, links and examples; explain migration when existing consumers must change.
5. Verify the contract. From the repository root, run pnpm check:toolkit, pnpm check, and pnpm --filter ds build. The fast toolkit check runs the Node tests of @dg/ui and the DS, including API coverage, token and class coverage, Markdown format, compilable examples, generated context, consumer types and local destinations. No dev server or browser installation is needed. These tests cannot establish prose accuracy or visual quality: compare references with the source, run affected browser tests and perform the rendered check on affected examples. Source changes also need the relevant behavior tests and consumer checks.
6. Review before completion. Confirm that the public API, reference, previews and consumers agree; no copied reference or undocumented exception has been introduced. Report remaining verification limits explicitly. A passing build does not replace a documentation or accessibility review.

If the requested change affects no public contract, an unchanged reference is acceptable, but state why. Never postpone necessary documentation to an unspecified later task or generate a second truth for agents. The DS generates machine-readable context from the canonical files; updating their source updates the context at the next build. Recipes are documentation examples, not new public package exports.

Use the smallest extension that solves a present need. Prefer native controls and composition to a new component family. Deprecate an API with a documented replacement and a consumer migration; do not remove it in the same compatible release. For a break, list the old usage, the replacement and affected consumers, and record it in Changes.

Run pnpm check:toolkit, pnpm check, pnpm build and pnpm test:ui from the workspace root. The Toolkit workflow repeats the toolkit and DS checks on pushes and pull requests. The fast toolkit command verifies non-browser contracts; Chromium runs every browser suite, and Firefox and WebKit run the toolkit's critical compatibility scenarios. Browser packages are installed with pnpm exec playwright install chromium firefox webkit.

These checks do not enforce GitHub branch protection, publish a package or deploy a site. Repository administrators must enable the Toolkit validation job as a required check if desired. Review rendered changes, manual accessibility evidence and any migration before approving a release. Never regenerate visual baselines solely to hide a failing test.