## Context

A documentation layer is mostly interface: a header, a sidebar, a table of
contents, code blocks, a search dialog. Something has to draw them, and the
choice of what decides how much a consumer can change without forking.

The layer's whole proposition is that it is extended rather than generated —
`extends: ['@kirchdev/duxt']`, and every file stays overridable. A theme whose
appearance is only reachable through the options its author thought to expose
would contradict that at the first thing a consumer wanted to look different.
Nuxt's layer resolution already gives a consumer file-level override for free, so
the question was what those files should be.

## Decision

The layer owns the source of its components. shadcn-vue is used as the source of
the primitives — its CLI writes a component's code into the repository, and from
that point the file belongs to the layer, not to a dependency. `components.json`
points the CLI at the layer's own alias, so adding a primitive is one command,
and Tailwind supplies the styling underneath.

The palette is CSS custom properties. Components read tokens and hold no colours,
which is what makes a one-line override reach every surface.

## Consequences

A consumer can change any part of the interface, at whatever depth the change
needs: redefine a token, shadow a component by name, or add a primitive of their
own. None of those requires a fork, and none waits on the layer to expose an
option for it.

The cost is maintenance. An upstream fix to a primitive does not arrive with a
dependency bump — it arrives when someone re-runs the CLI for that component. The
layer carries that for the primitives it ships; a consumer who overrides one
carries it from then on. That trade is what the override guidance is built
around, and it is the reason the guidance exists at all.

Vendored files that the CLI cannot reach are the sharp edge of the same trade: a
stylesheet with no registry item behind it can only be upgraded by downloading it
again, so local changes to it are lost silently rather than conflicting loudly.

## Alternatives considered

**A ready-made documentation theme.** Docus is the obvious fit — Nuxt Content's
own theme, and everything a documentation site needs on the first run. It was
rejected for the same reason it is attractive: the site it produces is its
author's, and reshaping it means either an option that exists or a fork. A layer
whose consumers were expected to look different from each other could not accept
that ceiling.

**A component library as a dependency.** Nuxt UI would have supplied the
primitives without the maintenance, and the layer would have tracked its releases
instead of copying its code. Rejected because a dependency's components can only
be changed as far as their props allow, and the layer would then have had to
invent a second override mechanism to cover the rest — with two of them, neither
would be the obvious one to reach for.

**Hand-written components with no upstream at all.** This removes the dependency
question entirely and was rejected on cost: accessible primitives are difficult
in exactly the places that are easy to get wrong, and a dialog or a combobox
written from scratch would be worse than one adapted from a source that already
solved it.