@thespielplatz/tsp-tools-theme 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Changelog
+
+Generated from conventional commits by [changelogen](https://github.com/unjs/changelogen)
+(`npm run bump-version`). Releases before `v0.3.0` were reconstructed from history — the
+changelog ADR 005 asks for had never been generated.
+
+Consumers pin a caret range and do not auto-update, so a release only reaches a service when
+that service's own spec says so. This package has no users of its own — every entry below is a
+change to eight apps at once, at the moment each of them chooses to take it.
+
+## v0.3.0 — 2026-09-22
+
+[compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/v0.2.1...main)
+
+### 🚀 Enhancements
+
+- Quiet shell, language toggle and shared footer row ([347776a](https://github.com/inf0matics/tsp-tools-theme/commit/347776a))
+- TspBrandTile — the frame around a service's mark ([62d6f3a](https://github.com/inf0matics/tsp-tools-theme/commit/62d6f3a))
+- Sidebar footer rows, source variants, and the wordmark fix ([ed4be66](https://github.com/inf0matics/tsp-tools-theme/commit/ed4be66))
+- Nav groups and section headers, white nav at rest ([a15a97c](https://github.com/inf0matics/tsp-tools-theme/commit/a15a97c))
+- Icons on the user row and on nav children ([97011c5](https://github.com/inf0matics/tsp-tools-theme/commit/97011c5))
+- TspUserCard — the user page, rebuilt from stash ([4cd1a48](https://github.com/inf0matics/tsp-tools-theme/commit/4cd1a48))
+- Move the language row below the divider ([62cde28](https://github.com/inf0matics/tsp-tools-theme/commit/62cde28))
+- One meta row — theme, github, support, tip jar, version ([b1fe4fe](https://github.com/inf0matics/tsp-tools-theme/commit/b1fe4fe))
+- Preferences row — theme label left, language toggle right ([4f0d4d8](https://github.com/inf0matics/tsp-tools-theme/commit/4f0d4d8))
+- Nav badges, version tag icon, pre-addressed support mail ([c35e734](https://github.com/inf0matics/tsp-tools-theme/commit/c35e734))
+- Truncated nav labels reveal their full text on hover ([17471ab](https://github.com/inf0matics/tsp-tools-theme/commit/17471ab))
+- Page structure — logged-in vs logged-out, and external nav rows ([b777621](https://github.com/inf0matics/tsp-tools-theme/commit/b777621))
+- The sidebar works on mobile — drawer, top bar, burger ([323ce31](https://github.com/inf0matics/tsp-tools-theme/commit/323ce31))
+- Harvest the old mockups; quiet the sidebar scrollbar ([0442ba3](https://github.com/inf0matics/tsp-tools-theme/commit/0442ba3))
+- Landing page reshaped from stash; forms page; drop the prototypes ([a4db2bb](https://github.com/inf0matics/tsp-tools-theme/commit/a4db2bb))
+- MCP settings page, generalised from trips ([1046d24](https://github.com/inf0matics/tsp-tools-theme/commit/1046d24))
+- MCP settings in the scoped demo; card and code sections on /content ([3085716](https://github.com/inf0matics/tsp-tools-theme/commit/3085716))
+- Release surfaces — banner, notes overview, unread badge, modal ([4bbe783](https://github.com/inf0matics/tsp-tools-theme/commit/4bbe783))
+- Widen the app measure to 1152px ([b0e189d](https://github.com/inf0matics/tsp-tools-theme/commit/b0e189d))
+
+### 🩹 Fixes
+
+- Honour an explicit --port in scripts/dev.mjs ([fab8186](https://github.com/inf0matics/tsp-tools-theme/commit/fab8186))
+- Centre the mark again; add checkboxes, radios and a textarea ([4da3df5](https://github.com/inf0matics/tsp-tools-theme/commit/4da3df5))
+- Give the surfaces three rungs, so a card is not the sidebar ([a53ce8e](https://github.com/inf0matics/tsp-tools-theme/commit/a53ce8e))
+- Pin the shell so it cannot scroll away; gate both apps for icons ([a44bb52](https://github.com/inf0matics/tsp-tools-theme/commit/a44bb52))
+- **review:** Close the review findings — two guards did not actually guard ([1d621ed](https://github.com/inf0matics/tsp-tools-theme/commit/1d621ed))
+- Reserve the scrollbar gutter so the content column stops shifting ([01de755](https://github.com/inf0matics/tsp-tools-theme/commit/01de755))
+- TspUserCard no longer caps the page width ([cc11f04](https://github.com/inf0matics/tsp-tools-theme/commit/cc11f04))
+- The MCP settings page no longer caps its own width ([65b4cbd](https://github.com/inf0matics/tsp-tools-theme/commit/65b4cbd))
+
+### 💅 Refactors
+
+- Consolidate duplicated behaviour; docs move into the package ([b34e898](https://github.com/inf0matics/tsp-tools-theme/commit/b34e898))
+
+### 📖 Documentation
+
+- Correct the @nuxt/icon pin notes for 2.5.1 ([43e68b7](https://github.com/inf0matics/tsp-tools-theme/commit/43e68b7))
+- Reconcile README with the shipped theme; share TspToolOf ([4f72351](https://github.com/inf0matics/tsp-tools-theme/commit/4f72351))
+- Generate the API reference, and document 71 undocumented props ([30a77db](https://github.com/inf0matics/tsp-tools-theme/commit/30a77db))
+
+### 🏡 Chore
+
+- Check in the working agreement and dev launch config ([426dba2](https://github.com/inf0matics/tsp-tools-theme/commit/426dba2))
+- Add scripts/dev.mjs so dev servers pick a free port ([996d0ef](https://github.com/inf0matics/tsp-tools-theme/commit/996d0ef))
+- **release:** V0.3.0 ([0a5c793](https://github.com/inf0matics/tsp-tools-theme/commit/0a5c793))
+- **playground:** Nav prototype — sub-items and section headers ([7c8938b](https://github.com/inf0matics/tsp-tools-theme/commit/7c8938b))
+
+### ✅ Tests
+
+- E2e harness covering both consumption modes ([bff7d0a](https://github.com/inf0matics/tsp-tools-theme/commit/bff7d0a))
+
+## v0.2.1 — 2026-07-28
+
+[compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/v0.2.0...v0.2.1)
+
+### 🩹 Fixes
+
+- Cap @nuxt/icon at ~2.3.1 and gate on icon rendering ([9e4d67d](https://github.com/inf0matics/tsp-tools-theme/commit/9e4d67d))
+
+### 🏡 Chore
+
+- **release:** V0.2.1 ([1d0925b](https://github.com/inf0matics/tsp-tools-theme/commit/1d0925b))
+
+## v0.2.0 — 2026-07-28
+
+[compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/v0.1.3...v0.2.0)
+
+### 🚀 Enhancements
+
+- Site shell, container widths, localisable theme toggle ([a16c5ff](https://github.com/inf0matics/tsp-tools-theme/commit/a16c5ff))
+
+### 🏡 Chore
+
+- **release:** V0.2.0 ([0113c4c](https://github.com/inf0matics/tsp-tools-theme/commit/0113c4c))
+
+## v0.1.3 — 2026-07-28
+
+[compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/v0.1.2...v0.1.3)
+
+### 🩹 Fixes
+
+- Keep colour-mode assignment type-safe under color-mode v4 ([4eb970b](https://github.com/inf0matics/tsp-tools-theme/commit/4eb970b))
+
+### 🏡 Chore
+
+- Stop the release script from double-bumping ([14fc551](https://github.com/inf0matics/tsp-tools-theme/commit/14fc551))
+- **release:** V0.1.3 ([aa248ae](https://github.com/inf0matics/tsp-tools-theme/commit/aa248ae))
+
+## v0.1.2 — 2026-07-28
+
+[compare changes](https://github.com/inf0matics/tsp-tools-theme/compare/edd310cbdf8428b32bb3472164d99e0cbaf53d79...v0.1.2)
+
+### 🏡 Chore
+
+- Prepare package for npm publishing ([cde3422](https://github.com/inf0matics/tsp-tools-theme/commit/cde3422))
+- **release:** V0.1.1 — exports ./package.json + CSS-ownership docs ([9629dd0](https://github.com/inf0matics/tsp-tools-theme/commit/9629dd0))
+- **release:** V0.1.2 ([f18e614](https://github.com/inf0matics/tsp-tools-theme/commit/f18e614))

package/README.md

@@ -16,6 +16,16 @@ Two consumption modes:
 
 ---
 
+> **The design system lives here:** [`docs/design-system.md`](docs/design-system.md) — tokens,
+> components, rules and gates, read from `assets/css/theme.css` and `components/`. It is the
+> source of truth for how tsp.tools services look; the planning project's
+> `architecture/design-system.md` is a pointer to it.
+>
+> The **playground is the reference**, never a mockup. `npm run dev`.
+>
+> **Every prop, slot and emit:** [`docs/api.md`](docs/api.md) — generated from the components by
+> `npm run docs:api` and verified in the gate, so it cannot go stale.
+
 ## Install
 
 ```bash
@@ -34,6 +44,30 @@ Peer expectations (provide them in the consuming app):
 > (A deep relative path such as `extends: ['../..']` can fail to pick up the source dirs;
 > the package name always works.)
 
+### Why `@nuxt/icon` is pinned at all
+
+The layer declares `@nuxt/icon` as a **direct dependency** on a tilde range — currently
+`~2.5.1`. The range is deliberate, even though the original regression is fixed.
+
+`@nuxt/icon` 2.4.1 changed its plugin to take `$fetch` from `useRequestFetch()` and then read
+`.native` off it. During SSR that returns Nitro's request-scoped `event.$fetch`, which has no
+`.native` property — so Iconify's fetch was set to `undefined` and **every server-side icon load
+failed**, logging `[Icon] failed to load icon …` per request. The layer capped at `~2.3.1` to
+escape it. 2.5.1 no longer has the bug, so the cap was lifted (2026-09-20).
+
+It stays a **tilde** range rather than a caret: `@nuxt/ui` only requires `^2.3.x`, so any
+re-resolve of the tree can move consumers across minors on its own, and that is precisely how
+the broken version reached apps the first time. A tilde means a future 2.6 has to be chosen,
+and re-gated, by a human.
+
+The pin is in `dependencies` rather than `overrides` on purpose: npm honours `overrides` only
+in the root project, so an `overrides` entry here would not reach consuming apps.
+
+**Any change to this version must be re-gated with `npm run test:icons`**, which boots the built
+playground and fails on a single `failed to load icon` in the server log. Icons resolve at
+runtime, per request — lint, typecheck and the build all stay green with every glyph missing,
+which is exactly why this is easy to miss.
+
 ---
 
 ## Global usage (whole app themed)
@@ -57,16 +91,28 @@ shell components wherever you like:
 <template>
   <div class="flex min-h-svh bg-default text-default">
     <TspSidebar>
-      <template #brand><TspWordmark>trips<span class="text-primary">.</span></TspWordmark></template>
+      <template #brand>
+        <TspBrandTile><img src="/logo.svg" alt="trips"></TspBrandTile>
+        <TspWordmark name="trips" />
+      </template>
       <template #nav>
-        <TspNavItem to="/" icon="i-tabler-car">Fahrten</TspNavItem>
-        <TspNavItem to="/settings" icon="i-tabler-settings">Einstellungen</TspNavItem>
+        <TspNavItem to="/" icon="i-tabler-car" badge="Owner" badge-tone="primary">Fahrten</TspNavItem>
+        <TspNavGroup to="/reports" icon="i-tabler-file-text" label="Berichte">
+          <TspNavSubItem to="/reports/tax" icon="i-tabler-receipt">Steuer</TspNavSubItem>
+        </TspNavGroup>
+        <TspNavSection label="Extern" />
+        <TspNavItem to="/handbook" icon="i-tabler-book">Handbuch</TspNavItem>
       </template>
       <template #footer>
-        <TspSidebarFooter github-link="https://github.com/…" version="v1.2.0">
-          <template #user>…your user link…</template>
-          <template #logout>…your logout…</template>
-        </TspSidebarFooter>
+        <TspSidebarFooter
+          v-model="locale"
+          app-name="trips"
+          user="fil" user-to="/user"
+          settings-to="/settings" logout-href="/auth/logout"
+          :locales="['de', 'en']"
+          github-link="https://github.com/…" version="v1.2.0" version-link="https://github.com/…/releases/tag/v1.2.0"
+          tip-jar tool-of
+        />
       </template>
     </TspSidebar>
     <main class="flex-1 min-w-0 bg-default">
@@ -125,20 +171,26 @@ scope:
 |---|---|---|
 | `primary` (amber) | `#fbad18` | `#fbad18` |
 | `error` (tomato) | `#ff6347` | `#ff6347` |
-| `bg` | `#f8f9fa` | `#212529` |
-| `surface` (`bg-elevated`) | `#ffffff` | `#2b3035` |
+| `bg` (page) | `#f1f3f5` | `#212529` |
+| `bg-muted` (the shell) | `#f8f9fa` | `#2b3035` |
+| `bg-elevated` (raised content) | `#ffffff` | `#31373e` |
 | `border` | `#dee2e6` | `#404041` |
 | `text` | `#212529` | `#f0f0f0` |
 | `on-primary` (`text-inverted`) | `#212529` | `#212529` |
 
-Brand colours (amber, tomato) are the same in both modes; only bg/surface/border/text flip.
+Brand colours (amber, tomato) are the same in both modes; only surfaces, borders and text flip.
+**Three rungs, not two** — the shell uses `bg-muted`, raised content uses `bg-elevated`. See
+[`docs/design-system.md`](docs/design-system.md) for the full ladder and the reason it changed.
 The amber ramp is also available as Tailwind utilities (`*-tsp-amber-{50..950}`).
 
 **Fonts** — Nunito (text + headings) and Space Grotesk (logo), via `@nuxt/fonts`. Use the
 `tsp-wordmark` class (or `<TspWordmark>`) for Space Grotesk; everything else is Nunito.
 
-**Composable** — `useTspColorMode()` → `{ pref, toggle }`, the remembered (cookie) preference
-for the themed area.
+**Composables** (auto-imported) — `useTspColorMode()` → `{ pref, toggle }`, the remembered
+(cookie) preference for the themed area; `useTspNavDrawer()` → `{ isOpen, open, close, toggle }`,
+the mobile drawer's shared state; `useTspCopy()` → `{ copied, copy }`, clipboard plus a moment of
+confirmation, with a fallback for non-secure contexts; `useTspReveal()` → `{ revealed, toggle,
+mask }`, show/hide a secret with a fixed-length placeholder.
 
 **Components** (auto-imported):
 
@@ -146,16 +198,42 @@ for the themed area.
 |---|---|
 | `TspThemeProvider` | Scoped wrapper — marks a sub-area as themed (`.tsp-theme`). |
 | `TspSidebar` | App-shell sidebar frame; slots `#brand` `#nav` `#footer`. |
-| `TspSidebarFooter` | User → Logout → divider → theme toggle → GitHub + version. |
+| `TspSidebarFooter` | User → Settings → Logout → divider → theme + language → meta icons + version → "A tool of tsp.tools". Rows are **props**, not slots. |
 | `TspSiteHeader` | Public/marketing header; slots `#brand` `#nav` `#actions`, prop `sticky`. |
 | `TspSiteFooter` | Public/marketing footer; slots `#brand` `#links` `#actions`. |
 | `TspThemeToggle` | Sun/moon light–dark toggle (uses `useTspColorMode`). |
-| `TspNavItem` | Sidebar nav link (muted → filled-amber when active). |
-| `TspWordmark` | Space Grotesk + amber brand wordmark. |
+| `TspNavItem` | Sidebar nav link — **white at rest, amber text when active**. Optional `badge`. |
+| `TspNavGroup` | A nav item with always-visible sub-items on a hairline spine. |
+| `TspNavSubItem` | A child row — muted, own icon, amber when active. |
+| `TspNavSection` | A rule, optionally labelled (`External`). |
+| `TspNavBadge` | Outline pill on a nav row; tones `primary` \| `neutral`. |
+| `TspNavLabel` | Truncates a label and reveals it in full on hover. Used by the rows above. |
+| `TspBrandTile` | The frame around a service's mark — `sidebar` (24px) or `hero` (64/96px). |
+| `TspUserCard` | Account card for a service's user page; masked id + manage link. |
+| `TspFooterRow` | One sidebar-footer row — `to` / `href` / `button`. |
+| `TspLanguageToggle` | DE/EN segmented control; all strings are props. |
+| `TspVersionBadge` | Version pill with a tag icon; a link only when given `href`. |
+| `TspWordmark` | `<TspWordmark name="trips" />` → white name + amber dot. |
+| `TspTopBar` | Mobile top bar — burger, brand, page title. Pairs with `TspSidebar`. |
+| `TspSectionCard` | Icon + title over content, on the raised surface. |
+| `TspPageTabs` | Area tabs as routes, so the back button works. |
+| `TspCopyField` | Read-only value + copy; `secret` masks it behind a reveal. |
+| `TspCopyButton` | Copy with a tick confirmation. |
+| `TspCodeBlock` | Config to copy; shown and copied values can differ. |
+| `TspBanner` | Dismissible strip; emits `dismiss`, remembering it is the app's job. |
+| `TspReleaseNotes` | Release notes; props mirror the `tsp-release` skill's shape. |
+| `TspToolOf` | "A tool of tsp.tools". Shared by both footers. |
 | `TspContainer` | Centered content column; props `width` (`app` \| `site`) and `padded`. |
 
-App-specific content (branding, nav lists, user identity, GitHub/version values) is injected
-via slots/props — none of it lives in the layer.
+App-specific content (branding, nav lists, user identity, GitHub/version values) is injected via
+props — none of it lives in the layer. **Prefer props over slots** for the footer rows every app
+has: a slot invites each app to restyle its own copy, which is the drift `TspFooterRow` exists to
+stop. `#user` survives only for apps needing more than a name.
+
+**Open source is derived from `github-link`.** Set it and the meta row shows a GitHub icon and the
+version badge links to the release; leave it out and the badge is plain text — **`version-link`
+is then ignored**, because a closed-source project has no release page to point at. There is no
+`variant` prop; a second source of truth could disagree with the first.
 
 ### App shell vs site shell
 
@@ -164,20 +242,21 @@ use `TspSiteHeader` + `TspSiteFooter` with the wide container:
 
 ```vue
 <TspSiteHeader>
-  <template #brand><NuxtLink to="/"><TspWordmark>tsp<span class="text-primary">.</span>tools</TspWordmark></NuxtLink></template>
+  <template #brand><NuxtLink to="/"><TspWordmark name="trips" /></NuxtLink></template>
   <template #nav><a href="#tools">Tools</a></template>
-  <template #actions><TspThemeToggle /></template>
+  <template #actions><TspThemeToggle icon-only /></template>
 </TspSiteHeader>
 
 <TspContainer width="site"><NuxtPage /></TspContainer>
 
 <TspSiteFooter>
-  <template #brand><TspWordmark>tsp<span class="text-primary">.</span>tools</TspWordmark></template>
+  <template #brand><TspWordmark name="trips" /></template>
   <template #links><NuxtLink to="/imprint">Imprint</NuxtLink></template>
 </TspSiteFooter>
 ```
 
-`TspContainer` defaults to `width="app"` (`max-w-4xl`, `px-6 sm:px-10`) — the app/admin measure.
+`TspContainer` defaults to `width="app"` (`max-w-6xl` = 1152px, `px-6 sm:px-10`) — the app/admin
+measure. Cap prose on the paragraph (`max-w-2xl`), not by narrowing the page.
 `width="site"` is `max-w-[1240px]`, `px-6 md:px-10`, the marketing measure. Both add `pt-10 pb-16`
 unless you pass `:padded="false"` (which is what the header/footer frames do internally).
 
@@ -193,8 +272,10 @@ button shows and announces while dark:
 />
 ```
 
-The defaults are English. The default slot receives `{ isDark, label }` if you want different
-markup (an icon-only square button, say) while keeping the mechanism.
+The visible defaults are **`Light` / `Dark`** — one word, because "mode" earns nothing beside a
+sun icon and the label shares a 224px row with the language control. The aria-labels keep the
+full "Switch to light mode". Pass `icon-only` for a compact icon button (the site header and
+tight rows); the default slot still receives `{ isDark, label }` if you want other markup.
 
 ---
 
@@ -246,18 +327,52 @@ They are excluded from the published package (`files` allowlist).
 
 ## Release
 
-The version bump and the git tag are **not** done by an npm script:
+One command (ADR 005):
 
-1. Bump `package.json` `.version`, commit, and push to `main`.
-2. Publish a GitHub Release for that commit — GitHub creates the `vX.Y.Z` tag on publish.
-3. Ship the package:
+```bash
+npm run bump-version
+```
+
+It runs the full gate, then `changelogen --release` writes `CHANGELOG.md`, bumps
+`package.json`, commits and tags `vX.Y.Z`, then pushes the commit and the tag.
+
+**The pushed tag is what publishes.** `.github/workflows/release.yml` re-runs the gate on a
+clean checkout of the tagged commit and publishes to npm with provenance, so the tarball eight
+services install is built from a tagged commit rather than from whatever a laptop had in its
+working tree. It also refuses to publish if the tag and `package.json` disagree.
 
-   ```bash
-   npm run release      # lint, then npm publish
-   ```
+| Command | |
+|---|---|
+| `npm run gate` | everything CI runs — lint, `docs:api:check`, typecheck, icons, E2E |
+| `npm run bump-version` | the release: gate → changelog + version + tag → push |
+| `npm run release` | break-glass — gate then `npm publish` from here, for when Actions is down |
+
+**There is no npm token.** The package uses npm **trusted publishing**: npmjs.com is configured
+to trust this repository and this workflow file, GitHub mints a short-lived OIDC token for the
+run, and npm verifies it. Nothing long-lived is stored in the repo, so there is no secret to
+rotate and none to leak. Two consequences worth knowing:
+
+- `id-token: write` in `release.yml` **is** the authentication. Remove it and the publish has no
+  way to authenticate at all.
+- The workflow upgrades npm before publishing. Node 22 bundles npm 10, which has no OIDC support
+  and would silently look for a token that does not exist; trusted publishing needs npm ≥ 11.5.1
+  and Node ≥ 22.14.0, and the step fails loudly rather than falling back.
+
+Provenance is automatic under trusted publishing — `--provenance` is not passed, and must not be.
+
+**`0.3.0` is a special case: it needs a tag, not a bump.** Its version was already written into
+`package.json` by hand (`0a5c793`) and its changelog entry is written, so two of changelogen's
+three jobs are done. The third — `changelogen --release` — cannot run: it refuses a bump whose
+result equals the current version (`bumpVersion` returns `false`, reported as "Unable to bump
+version based on changes"), and `-r 0.3.0` on a package already at `0.3.0` is exactly that. So
+tag it directly:
+
+```bash
+npm run gate && git tag -a v0.3.0 -m "v0.3.0" && git push --follow-tags
+```
 
-`npm run release` deliberately only lints and publishes. It never bumps the version or tags,
-so it can't drift from the version that was already committed and tagged in steps 1–2.
+From `0.3.1` on, `npm run bump-version` is the path — changelogen picks the next version from the
+commits, so there is nothing to force.
 
 ## License
 

package/assets/css/theme.css

@@ -89,15 +89,39 @@
      modes (the `on-primary` token). */
   --ui-text-inverted: #212529;
 
-  --ui-radius: 0.5rem;
+  /* Brand amber used as TEXT on the current surface (not as a fill). Amber-400
+     is the brand primary and is correct on the dark surfaces; on light it fails
+     text contrast, so the light group steps down to amber-600 — see
+     design-system.md, accessibility note. Fills keep `--ui-primary`. */
+  --tsp-text-brand: var(--color-tsp-amber-400);
+
+  /* Radius base. Nuxt UI derives its whole scale from this:
+       rounded-sm = 1x = 4px · rounded-md = 1.5x = 6px
+       rounded-lg = 2x = 8px · rounded-xl = 3x = 12px
+     0.25rem is what makes `rounded-xl` the 12px card radius that
+     design-system.md and ADR 018 specify, and `rounded-md` the 6px shell-row
+     radius. The previous 0.5rem is why cards rendered 24px (ADR 018 read that
+     as gage drift; it was this token). */
+  --ui-radius: 0.25rem;
 }
 
-/* Dark surfaces (default) — tsp anthracite. */
+/* Dark surfaces (default) — tsp anthracite.
+
+   THREE RUNGS, NOT TWO. `muted` and `elevated` used to be the same #2b3035,
+   which left no surface for a raised card: it either matched the page or
+   matched the sidebar, and it matched the sidebar in stash, gage and trips.
+   The ladder is now
+     bg        page
+     muted     the shell — sidebar, top bar
+     elevated  raised CONTENT — cards, the user card, feature boxes
+     accented  pressed/selected chrome
+   and the shell sits below content rather than beside it, which is also what
+   ADR 018 wanted from a quiet shell. */
 .dark .tsp-theme,
 .dark.tsp-theme {
   --ui-bg: #212529;
   --ui-bg-muted: #2b3035;
-  --ui-bg-elevated: #2b3035;
+  --ui-bg-elevated: #31373e;
   --ui-bg-accented: #404041;
   --ui-bg-inverted: #f0f0f0;
 
@@ -113,11 +137,16 @@
   --ui-text-highlighted: #ffffff;
 }
 
-/* Light surfaces — tsp light theme (design-system.md → Light theme). */
+/* Light surfaces — tsp light theme (design-system.md → Light theme).
+
+   Same three rungs. Light had the same collapse (muted and elevated both
+   #ffffff) and nowhere left to go, because the page was already near-white:
+   the page steps down to #f1f3f5 so the shell can take #f8f9fa and a raised
+   card can be pure white. Raised means lighter here, the inverse of dark. */
 .light .tsp-theme,
 .light.tsp-theme {
-  --ui-bg: #f8f9fa;
-  --ui-bg-muted: #ffffff;
+  --ui-bg: #f1f3f5;
+  --ui-bg-muted: #f8f9fa;
   --ui-bg-elevated: #ffffff;
   --ui-bg-accented: #dee2e6;
   --ui-bg-inverted: #212529;
@@ -132,6 +161,57 @@
   --ui-text-toned: #343a40;
   --ui-text: #212529;
   --ui-text-highlighted: #16191c;
+
+  /* #fbad18 fails contrast as text on these surfaces; #f47920 passes. */
+  --tsp-text-brand: var(--color-tsp-amber-600);
+}
+
+/* Mode-correct brand text (ADR 018: the active nav item is amber TEXT, not an
+   amber fill). Written unlayered and with two classes so it beats Tailwind's
+   `text-muted` / `hover:text-*` utilities without needing `!important`. */
+.tsp-theme .tsp-text-brand {
+  color: var(--tsp-text-brand);
+}
+
+/* Mode-correct brand colour as a BORDER, for the same reason .tsp-text-brand
+   exists for text: #fbad18 is the brand, but the light group steps down to
+   amber-600 so an accent edge holds up on light surfaces too. */
+.tsp-theme .tsp-border-brand {
+  border-left-color: var(--tsp-text-brand);
+}
+
+/* Reserve the scrollbar's width whether or not the page scrolls.
+
+   The content column is centred, so it moves by HALF the scrollbar width the
+   moment a page gets tall enough to overflow: walking from a short page to a
+   long one shifted every heading, card and table sideways. Measured in Chrome
+   at 1400px, the playground put the column at 364px on a short route and at
+   356.5px on a long one.
+
+   Both selectors are the same rule in the two consumption modes: GLOBAL puts
+   the scope class on <html> itself, SCOPED puts it on a provider inside the
+   page. Neither matches a consumer's own public pages, which this layer does
+   not own and must not relayout.
+
+   Browsers with overlay scrollbars (macOS default) are unaffected — there is no
+   width to reserve, so nothing changes for them either way. */
+html.tsp-theme,
+html:has(.tsp-theme) {
+  scrollbar-gutter: stable;
+}
+
+/* Scrollable, but without a visible scrollbar track. The sidebar nav has to
+   scroll when a service has a long nav or a short window, but a permanent
+   track beside 32px rows in a 224px column reads as clutter — and on platforms
+   with overlay scrollbars it appears and disappears as you move the mouse,
+   which is worse. Scrolling itself is untouched: wheel, trackpad, touch and
+   keyboard all still work. */
+.tsp-scroll-quiet {
+  scrollbar-width: none;
+}
+
+.tsp-scroll-quiet::-webkit-scrollbar {
+  display: none;
 }
 
 /* The wordmark uses Space Grotesk; everything else stays Nunito. */

package/components/TspBanner.vue

@@ -0,0 +1,97 @@
+<!--
+  A dismissible strip across the top of the content area. Its first job is the
+  release announcement the tsp-release skill's `showBanner` flag turns on, but
+  nothing here is release-specific: it is a banner.
+
+    <TspBanner icon="i-tabler-sparkles" title="Version 1.3.0">
+      Neue Auswertung im Bericht.
+      <template #action><UButton …>Was ist neu?</UButton></template>
+    </TspBanner>
+
+  Amber TEXT and an amber left edge, not an amber fill: ADR 018 gives the fill
+  to primary buttons alone, and a full-width amber bar would be the loudest
+  thing on the page by a distance.
+
+  Dismissal is the CALLER's to remember. The banner emits `dismiss`; whether
+  that is per release, per user or per session is a question the layer cannot
+  answer, and guessing it wrong means a banner that never comes back or never
+  goes away.
+-->
+<template>
+  <div
+    v-if="!dismissed"
+    data-testid="tsp-banner"
+    role="status"
+    class="flex items-start gap-3 rounded-xl border border-default border-l-2 bg-elevated px-4 py-3"
+    :class="tone === 'brand' ? 'tsp-border-brand' : ''"
+  >
+    <UIcon
+      v-if="icon"
+      :name="icon"
+      class="mt-0.5 shrink-0 text-lg"
+      :class="tone === 'brand' ? 'tsp-text-brand' : 'text-muted'"
+    />
+
+    <div class="min-w-0 flex-1">
+      <p
+        v-if="title"
+        data-testid="tsp-banner-title"
+        class="text-sm font-bold text-highlighted"
+      >
+        {{ title }}
+      </p>
+      <div class="text-sm text-muted">
+        <slot />
+      </div>
+    </div>
+
+    <div class="flex shrink-0 items-center gap-2">
+      <slot name="action" />
+      <button
+        v-if="dismissible"
+        type="button"
+        data-testid="tsp-banner-dismiss"
+        :aria-label="dismissLabel"
+        :title="dismissLabel"
+        class="flex size-8 items-center justify-center rounded-md text-muted hover:text-highlighted hover:bg-default"
+        @click="dismiss"
+      >
+        <UIcon
+          name="i-tabler-x"
+          class="text-lg"
+        />
+      </button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  /** Headline. Without it the banner is only its default slot. */
+  title?: string
+  /** Leading icon, `i-tabler-*`. */
+  icon?: string
+  /** `brand` = amber accent edge, `neutral` = quiet. Neither is a fill. */
+  tone?: 'brand' | 'neutral'
+  /** Show the close button. The app decides whether it STAYS closed. */
+  dismissible?: boolean
+  /** Accessible name for the close button. */
+  dismissLabel?: string
+}>(), {
+  title: undefined,
+  icon: undefined,
+  tone: 'brand',
+  dismissible: true,
+  dismissLabel: 'Dismiss',
+})
+
+const emit = defineEmits<{ dismiss: [] }>()
+
+// Local only, so the banner disappears immediately on click. Whether it STAYS
+// gone is the app's decision, via the event.
+const dismissed = ref(false)
+const dismiss = () => {
+  dismissed.value = true
+  emit('dismiss')
+}
+</script>

package/components/TspBrandTile.vue

@@ -0,0 +1,46 @@
+<!--
+  The frame a service's mark sits in — size, radius and clipping. The artwork
+  goes in the default slot; the layer ships no logo of its own and must not grow
+  one (spec 02).
+
+    <TspBrandTile><img src="/logo.svg" alt="gage"></TspBrandTile>
+    <TspBrandTile size="hero"><img src="/logo.svg" alt="gage"></TspBrandTile>
+
+  Two sizes, deliberately: `sidebar` (24px, for TspSidebar's #brand slot) and
+  `hero` (64px, 96px from sm up, for a landing lockup). Eight services were each
+  writing `size-6 shrink-0 rounded-[22%]` by hand.
+
+  THE FILL BELONGS TO THE ARTWORK, not to this component. Services ship a
+  logo.svg already drawn as amber tile plus dark mark, so the tile paints no
+  background — it sizes, clips and rounds. A service that passes a bare mark and
+  gets no amber is looking at its own bug, not a missing prop. (It also matters
+  in the shell: ADR 018 gives the amber fill to primary buttons alone.)
+
+  The radius is a PERCENTAGE so the corner scales with the size and both tiles
+  read as one shape. There is no `border` prop — the design system dropped the
+  old border-4, and a prop would keep it alive in the one place that outlives
+  the decision.
+
+  No animation here. An animated mark is the service's own component and goes in
+  the slot like any other content; the tile does not know whether what it holds
+  moves, and clips it either way.
+-->
+<template>
+  <div
+    data-testid="tsp-brand-tile"
+    :data-size="size"
+    class="shrink-0 overflow-hidden rounded-[22%]"
+    :class="size === 'hero' ? 'size-16 sm:size-24' : 'size-6'"
+  >
+    <slot />
+  </div>
+</template>
+
+<script setup lang="ts">
+withDefaults(defineProps<{
+  /** `sidebar` = 24px (TspSidebar #brand), `hero` = 64px / 96px from sm up. */
+  size?: 'sidebar' | 'hero'
+}>(), {
+  size: 'sidebar',
+})
+</script>