Compose with the toolkit

Use Svelte 5 runes for application state and derived values. Components receive ordinary callback props such as onclick, onsend and onselect. DOM callbacks receive their native event; conversation callbacks document when they receive a string. Do not use Svelte 4 event directives or assume a CustomEvent wrapper.

Content goes through children or named snippets. A supplied snippet replaces the corresponding text fallback; Card.title and Button.icon accept either text or a snippet. Only an explicitly bindable prop supports two-way state: currently ChatComposer.value and Tabs.value. A component reference from bind:this is available after mounting and exposes only documented instance methods.

<script>
  import { Button, Card, Section } from "@dg/ui";
  let count = $state(0);
</script>

<Section>
  <Card title="Collection">
    {#snippet header()}<span>Archive</span>{/snippet}
    <p>Explore the collection and its documents.</p>
    {#snippet footer()}<span>{count} selections</span>{/snippet}
  </Card>
  <Button label="Select" icon="+" onclick={() => count++} />
</Section>

Every component forwards native attributes, DOM callbacks, class and style to its root element, except the names it owns itself; each reference's Notes name that root. Do not target a component's private markup with global selectors.

Forwarded attributes use the native types from svelte/elements, not an unrestricted property map. Use string class names, CSS text for style, native callbacks and appropriate aria-* or data-* attributes. A forwarded attribute does not add toolkit behavior: passing a loading attribute cannot implement a request lifecycle. Button and Card change their native root when href is supplied; choose attributes for that root. Header, Footer and Tabs do not render arbitrary children. Heading forwards Section's padding and crosses but owns its children and fixes gap to 0.

Type checks catch misspelled props and invalid values in typed consumers; they do not validate every JavaScript spread, CSS expression, accessible name or semantic combination. Check the actual composition and its state transitions as well.

The quick reference maps each need to its component or class, and its rules apply everywhere. Composition adds these specific constraints:

• Grid and Cards keep jointive tracks: add no gap between their cells and never repair their lines with overlapping borders.
• .formatted already spaces its blocks; do not also wrap its paragraphs in a stack.
• A linked Card is one link: use an article Card when its content includes links or buttons. Never nest ChatComposer's form in another form.
• Keep small screens free of horizontal page overflow: let text wrap, keep control targets and check long labels, empty content and large text.

Implement states only where they apply. A static heading does not need loading, and a disabled action is not the same as a read-only value. Appearance uses the interaction and feedback tokens; semantics remain with the native element, component or application.

Reduced motion, forced colors, narrow layouts and both themes are verification conditions across these states, not additional business states. Use the native field contract and chat lifecycle for complete examples. Test state transitions, not just a static screenshot of each state.

The application owns domain data, routing, requests, sanitization, persistence and app-specific components; the toolkit supplies presentation and the documented interaction behavior. The reference index is the complete public inventory.