# Quick reference

The shortest path to a complete application with `@dg/ui`. Read this page first; each entry links to the reference that owns the details.

## Shell

Compose the shell once, in the root layout. Routes supply sections only.

```svelte
<script>
  import "@dg/ui/styles.css";
  import { page } from "$app/state";
  import { Page, SkipLink, Header, Main, Footer, Analytics } from "@dg/ui";

  /** @type {{ children?: import('svelte').Snippet }} */
  let { children } = $props();
</script>

<Page lang="en">
  <SkipLink />
  <Header app="Example" links={[{ label: "Home", href: "/" }]} path={page.url.pathname} />
  <Main>{@render children?.()}</Main>
  <Footer identity="Example" />
  <Analytics {page} />
</Page>
```

`lang` (`en` or `fr`) translates every built-in label and should match `<html lang>`. `Page` also restores the saved theme before first paint. [`Analytics`](../components/analytics.md) measures visits once the host serves its configuration, and adds the privacy control to `Footer`. The [new application guide](new-app.md) covers packages, configuration, error routes and hosting.

## Compose a route

| Need                              | Use                                                                                                                                                                             |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Page title and metadata           | [`Heading`](../components/heading.md)                                                                                                                                           |
| Framed block of content           | [`Section`](../components/section.md), with [`SectionHead`](../components/section-head.md) for its numbered label; headings inside reading text are plain h2–h6 in `.formatted` |
| Reading text                      | `<article class="formatted constrained-width">` from [typography and prose](../foundations/typography.md)                                                                       |
| Authored serif writing            | `<div class="formatted prose constrained-width">` from [typography and prose](../foundations/typography.md)                                                                     |
| Equal cells                       | [`Grid`](../components/grid.md)                                                                                                                                                 |
| Horizontal collection             | [`Cards`](../components/cards.md) of [`Card`](../components/card.md)                                                                                                            |
| Action, or link as a button       | [`Button`](../components/button.md), with `href` for a link                                                                                                                     |
| Icon-only action                  | [`IconButton`](../components/icon-button.md)                                                                                                                                    |
| Modal panel, drawer or media view | [`Dialog`](../components/dialog.md)                                                                                                                                             |
| Panels within one page            | [`Tabs`](../components/tabs.md)                                                                                                                                                 |
| Quotation                         | [`Quote`](../components/quote.md)                                                                                                                                               |
| Error route                       | [`ErrorPage`](../components/error-page.md)                                                                                                                                      |
| Conversation                      | [Chat integration](../guides/chat.md)                                                                                                                                           |
| Forms                             | Native elements with the [field classes](../foundations/native-forms.md#native-fields-and-feedback)                                                                             |
| Groups, spacing, alignment        | `.stack`, `.row` and their modifiers from [stack and row](../foundations/stack-and-row.md)                                                                                      |
| Complete page patterns            | [Collection](../guides/recipe-collection.md), [form](../guides/recipe-form.md)                                                                                                  |

## Tokens by role

- Text: `--text-prominent` for headings and links, `--text` for body text, `--text-subtle` for supporting text, `--text-muted` for metadata.
- Surfaces and lines: `--background`, `--background-subtle`, `--background-prominent`; `--border`, `--border-subtle`, `--border-prominent`.
- Accent and status: `--accent`, `--accent-subtle`; `--feedback-error`, `--feedback-success`, `--feedback-warning`, `--feedback-info`, always with explicit text.
- Spacing by relationship: `layout` for independent blocks and the frame, `content` for the parts of one block, `control` within a control group (a label and its field, a row of buttons). Prefer component defaults and the stack and row classes; the `--space-1` to `--space-8` scale covers component-specific values.
- Responsive: `@media (--narrow)`, `@media (--medium)` and `@media not (--medium)` in component styles.

The [foundation pages](../foundations/README.md) list every token and its role.

## Rules

1. One `Page`, one `Main` and `SkipLink` first in the root layout; routes add sections, never another `Page` or `Main`.
2. Choose heading levels for document hierarchy, not for size.
3. Read a component's reference before using a prop; never invent props, classes or tokens. `pnpm check` type-checks application code and rejects unknown props and values.
4. A parent owns the spacing between its children; each child owns its inset. Start from component defaults.
5. Use native HTML for ordinary controls and links.
6. Write content and content names in the audience language; `Page`'s `lang` covers the built-in labels.
7. The application owns data, requests, validation and persistence, and implements the applicable states of the [state contract](composition.md#state-contract).
8. Style in the owning component. Its styles override the foundations; never target another component's internal classes or `--_` variables.
9. Add no token for a one-off value; keep it local.
10. Verify with the workspace checks and build, then follow [accessibility verification](../guides/accessibility.md).