---
title: "Quick start"
description: "Put a working Soul surface in a page, then choose how the files reach it."
canonical: quickstart.html
navigation-title: "Quick start"
---

<a id="quick-start"></a>

# Quick start

- [How the files arrive](#how-the-files-arrive)
- [Write the surface](#write-the-surface)
- [Classes where no script runs](#classes-where-no-script-runs)
- [Where to continue](#where-to-continue)

Put a working Soul surface in a page, then choose how the files reach it.
The markup is the same with a bundler or with the drop-in. `soul.css`
carries the tokens and the class layer, and the JavaScript registers the
`sds-*` elements.

<a id="how-the-files-arrive"></a>

## How the files arrive

**From the package**

Install the frontend mirror and Lit in a project with a bundler:

```bash
npm install @typo3/soul-frontend lit
```

Import the package entry and the stylesheet from the application's
JavaScript entry:

src/main.js

```javascript
import '@typo3/soul-frontend';
import '@typo3/soul-frontend/dist/soul.css';
```

The package entry leaves Lit external, so the application and the
elements share one reactive-element registry.

**From the drop-in**

Copy `dist/` from the frontend mirror to a public `soul/`
directory, whole. The stylesheet resolves the fonts beside itself. The
script resolves `assets/icons/sprites/` inside it, one file per icon
category. A build that moves the module away from those assets says
where they went with `setIconSprites()`, which takes the directory.
A page that must not fetch carries the glyphs in the script:
`inlineIcons()`.

```html
<script src="/soul/soul-boot.js"></script>
<link rel="stylesheet" href="/soul/soul.css">
<script type="module" src="/soul/soul.js"></script>
```

`soul-boot.js` belongs before the stylesheet where the page has a
mode switch. Leave it out when the page follows the reader's system
setting and offers no switch.

<a id="write-the-surface"></a>

## Write the surface

> [!NOTE]
> `dist/custom-elements.json` in the package says what each element
> takes, compiled from the components themselves. Every tag with its
> attributes, their types, the events it sends, the classes it draws and if
> it takes content. Point an editor or a generator at that file.
> [Components](components/index.md) is the same contract for a reader.
>
> `npx soul-check src/` holds the other half in the project's own tree. A
> class an element draws, written by hand, is a component rebuilt, and the
> check names it with the element to write instead. Put it beside the
> tests. A rule that exists only as prose is one every fresh session finds
> again.

Put `sds-app` on the application root, then address the elements the
surface needs. A complete page adds the shell, the skip link and one of the
bodies in [Page layout](layout.md) around this content:

surface.html

```html
<div class="sds-app">
  <section class="sds-page" aria-labelledby="package-status">
    <h1 id="package-status">Package status</h1>

    <sds-note tone="info" heading="Rendered from Soul">
      <p>The component styles and behaviour come from the same package.</p>
    </sds-note>

    <sds-button href="/docs/">Read the documentation</sds-button>
  </section>
</div>
```

The result is a surface on the canvas, an information note with its labelled
glyph, and a primary press as a real link. The custom elements render light
DOM and emit the same `sds-` classes a server writes.

<a id="classes-where-no-script-runs"></a>

## Classes where no script runs

A server that already knows the answer can write the class layer directly.
It needs `soul.css` and no JavaScript:

```html
<a class="sds-btn sds-btn--primary" href="/docs/">
  Read the documentation
</a>
```

Prefer the element where there is behaviour, state or structure it owns.
Prefer the class where the server has produced final markup and nothing in
the page changes it.

<a id="where-to-continue"></a>

## Where to continue

| Need | Read |
| --- | --- |
| the page shell, bands and responsive frame | [Page layout](layout.md) |
| an element's attributes, properties and events | [Components](components/index.md) |
| headings, lists, tables and prose from a renderer | [Documents](documents.md) |
| the visual rules behind the tokens and components | [Design system](../design-system/index.md) |