---
title: "Documentation components"
url: https://una-lang.org/en/community/design-system/
release: v0.4.0
---

# Documentation components

Every component on this page is written in plain Markdown, so writers and translators never touch HTML. Each one is shown rendered, with its source underneath. Color carries meaning only: blue for notes, green for tips and checks, purple for what matters most, orange for warnings, gold for security and labels, rose for errors.

The strip above is the chapter meta strip. It is rendered from the page's front matter (`time`, `editions`, `prerequisites`, `codes`), never written by hand.

## Text

### Inline code

Backticks make a chip with presence. Its tint follows the code blocks' own colors, so a reader learns one color language: keywords purple, kinds blue, capabilities gold, commands green, file paths dashed with a file icon.

::::demo
A header says `fails OrderError`, a call says `if error pass`, a parameter has the kind `Option[Int]`, an operation needs `@inventory`, you run `una check .`, and the file is `day-to-day/src/orders.una`. Anything else, such as `raw.trim.to_int()`, is a plain chip.
::::

### Error codes

A diagnostic code is detected on its own, in text or in backticks, and links to its page. A backslash before it, `\U3007`, keeps it plain text.

::::demo
Forgetting the clause is U3007, and passing a failure of another kind is `U3008`.
::::

### Specification citations

A `spec/NN §M` reference becomes a citation chip that links to that section. Use it in the Reference part of a chapter, not in running prose.

::::demo
The rules for handling clauses are in spec/06 §3, and refined kinds in spec/03.
::::

### Keys and anchors

Double brackets make a keyboard key; an escaped bracket, `\[`, keeps them plain text. Every heading from level 2 to 4 shows a link anchor on hover; hover the headings on this page. The anchor is hidden from screen readers and out of the tab order, so a heading reads as its text; the table of contents links every section.

::::demo
Press [[/]] or [[Ctrl]] [[K]] to search the docs.
::::

## Callouts

GitHub-style markers on a quote. The title defaults from the marker, in the page's language once that label's translation is approved (in English until then), and can be replaced on the marker line. Use at most one callout per screen; a callout that repeats the paragraph above it should be cut.

::::demo
> [!NOTE]
> `una contract` prints the inferred header of a private function, with the comment `-- inferred`.

> [!TIP] Retry once
> `attempt` works on a capability operation too, so a retry needs no re-raise.

> [!IMPORTANT]
> When a statement can both fail and give an `Option`, `if error` comes first and `if none` second.

> [!WARNING]
> `checked` replaces a proof with a test, so `una.toml` budgets it per module.

> [!SECURITY]
> Lines read from a file are labeled `internal`. Printing a report built from them is a question of information flow, answered by a policy.
::::

## Quotes

### Key idea

One per chapter: the principle the reader should leave with. It moves an existing sentence out of the prose, word for word.

::::demo
> [!KEY]
> Nothing in Una fails at run time without the code saying so.
::::

### Quote with a source

A plain quote. A last paragraph that starts with an em dash names the source.

::::demo
> Make it work, make it right, make it fast.
>
> — A common engineering maxim
::::

## Chapter frame

### What you'll build

Wrap the content under the "What you'll build" heading. The paragraph right before the list becomes its label.

:::::demo
::::build
An order-intake step for a small store. It reports every line, accepted or rejected:

```text
ok      2 x LAMP-01
reject  no product has the SKU CHAIR-09
```

You will learn to:

- declare an error kind whose variants carry what someone needs to fix the problem;
- turn a failure into a value with `attempt`, so one bad line does not stop a batch.
::::
:::::

## Code

### File path and checks

The info string carries the file path, an optional caption, and the checks the block passed. Blocks without a title show their language.

::::demo
```una title="steps/01-quantity/src/quantity.una" caption="the parser" verified="check, run"
parse_quantity(raw: Text) -> Int
  fails QuantityError
=
  let n = raw.trim.to_int()
    if none fail NotANumber(raw)
  n
```
::::

### Output and diagnostics

A `text` block is program output, in a terminal look; test results color `ok` and `passed`. A `text` block that holds a diagnostic is detected and drawn with a rose accent (orange for a warning), its code linked.

::::demo
```text
example orders "a line in stock is accepted" ... ok
example orders "too many units are out of stock" ... ok

2 examples: 2 passed, 0 failed
```

```text
[U3007] Error: `parse_order` can fail with `OrderError`; handle the failure with an `if error` clause
    ╭─[ src/orders.una:56:15 ]
    │
 56 │   let order = parse_order(line)
    │               ────────┬────────
    │                       ╰────────── `parse_order` can fail with `OrderError`
    │
    │ Help: add `if error pass` on its own line
────╯
```
::::

### Wrong and right

Two blocks marked `mistake="wrong"` and `mistake="right"`, side by side inside a pair, stacked on a phone.

:::::demo
::::pair
```una title="before" mistake="wrong"
check_stock(parse_order(line))
```

```una title="after" mistake="right"
let order = parse_order(line)
  if error pass
check_stock(order)
  if error pass
```
::::
:::::

## Walkthrough steps

A numbered list inside `steps`, after a code block. A step that opens with bold code is tied to the line that holds that code: the line gets the step's number, and hovering over the step highlights it.

:::::demo
::::steps
```una
let left = @inventory.on_hand(order.sku)
  if error fail Unavailable
  if none fail UnknownSku(sku: order.sku)
```

Walkthrough:

1. **`if error fail Unavailable`.** The service's failure becomes a failure of this layer.
2. **`if none fail UnknownSku(sku: order.sku)`.** An unknown SKU is the input's fault.
::::
:::::

## Tables

### Reference table

A normal Markdown table: quiet header, row hover, and a horizontal scroll inside the table, never on the page.

::::demo
| Clause | Use it when |
| --- | --- |
| `if error use v` | You can carry on with a sensible value |
| `if error pass` | Your function fails with the *same* kind |
::::

### Decision table

Wrap a "Which to use" table in `decide`: the first paragraph is its title, and each row reads as a choice leading to an answer.

:::::demo
::::decide
**Which to use:**

| You want to… | Use |
| --- | --- |
| Carry on with a default | `if error use` / `if none use` |
| Keep going and collect outcomes | `attempt`, then `when` |
::::
:::::

## Practice

### Common mistake

Each mistake is a card: its bold lead is the title (the number becomes a badge), the rest of that paragraph is what was written, then what una says, then rows that open with an emphasized label such as *Why:* or *Fix:*.

:::::demo
::::mistake
**3. Failing with a variant of another kind (U3009).** Write `if error fail Timeout` in `check_stock`:

```text
[U3009] Error: `Timeout` is a variant of `StoreError`, and this code fails with `OrderError`
```

*Why:* a function has one error kind.

*Fix:* name a variant of your own kind.
::::
:::::

### Exercise, hint and answer

An exercise is a card. A hint sits in `hint`; the answer sits in `answer`, collapsed, with its summary on the marker line. The summary is a real `<summary>`, reachable with [[Tab]] and opened with [[Enter]].

::::::demo
:::::exercise
**Exercise 2: units shipped.** Write `shipped(results)`, the total of the units of the accepted lines.

::::hint
*Hint:* a private function from one `Result` to an `Int`, then `map` and `sum`.
::::

::::answer Answer (*check, test*; `exercises/2/answer`):
```una
pub shipped(results: List[Result[Order, OrderError]]) -> Int = results.map(each: units).sum()
```
::::
:::::
::::::

### Recap

A list inside `recap` becomes a checklist of rules the reader can apply.

:::::demo
::::recap
- A failure is a value of a sum kind you declare.
- `attempt` keeps an outcome as a `Result`, for batches, counts and retries.
::::
:::::

### For agents and Reference

`agents` frames the part written for coding agents; `reference` turns the closing list into a quiet index.

:::::demo
::::agents
Every diagnostic is available as JSON with `una --json check .`.
::::

::::reference
- Diagnostics: U3007, U3008
- Specification: spec/06 §3
::::
:::::

## Tokens

Added on top of the site's tokens (`--bg`, `--fg`, `--muted`, `--line`, `--purple`, `--purple2`, `--gold`, `--green`). Spacing runs 4, 8, 12, 16, 24, 32 pixels; radii are 6 for chips, 10 for blocks and callouts, 14 for cards.

<div class="c-swatches">
<span class="c-swatch" style="--sw:var(--ink-note)"><i></i><span>--ink-note<small>note</small></span></span>
<span class="c-swatch" style="--sw:var(--ink-tip)"><i></i><span>--ink-tip<small>tip, checks, ok</small></span></span>
<span class="c-swatch" style="--sw:var(--ink-important)"><i></i><span>--ink-important<small>important, steps</small></span></span>
<span class="c-swatch" style="--sw:var(--ink-warning)"><i></i><span>--ink-warning<small>warning, why</small></span></span>
<span class="c-swatch" style="--sw:var(--ink-security)"><i></i><span>--ink-security<small>security, labels</small></span></span>
<span class="c-swatch" style="--sw:var(--ink-danger)"><i></i><span>--ink-danger<small>errors</small></span></span>
<span class="c-swatch" style="--sw:var(--chip-bg)"><i></i><span>--chip-bg<small>inline code</small></span></span>
<span class="c-swatch" style="--sw:var(--surface-term)"><i></i><span>--surface-term<small>output</small></span></span>
</div>
