# Web

> Primary Web development skill for apps/web — white-floating-card design language, disciplined @felinic/ui usage, deliberate copy, honest empty states, aligned controls, and restrained motion. Never hand-write controls or menus; never leave stray fragments (orphan status labels, misaligned save hints). Compose from @felinic/ui primitives and reuse existing save/feedback patterns from reference pages. Use for any apps/web UI work — new pages, settings/list/detail surfaces, chat components, polish passes — not only legacy page migrations. Read this skill before writing or changing Web frontend code.

- Skill: `felinics/web` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add felinics/web`
- Raw SKILL.md: https://api.skillmd.com/api/skills/felinics/web/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: felinics (https://skillmd.com/u/felinics)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/felinics/web

---


# Web — Page Development & Design Language

## Non-negotiables — read this even if you skim the rest

The ten rules that break a page if you miss them. The rest of this file is the *why* and
the *how*; these are the *must*.

1. **Copy the new, never the legacy — and copy the *contract*, not a page's raw classes.** Open
   a refactored reference page (§ Reference map in `reference.md`) and mirror its *structure*.
   Never pattern-match off a dirty / un-refactored page — and never inherit a reference page's
   stray `font-[NNN]` / `text-[Npx]` / `text-foreground/NN`: some references still carry
   pre-contract token debt (`about` is one — it ships off-scale size, arbitrary weight, and
   hand-mixed alpha in one line), so the token law in `packages/ui/AGENTS.md` outranks any
   single page's classes when they disagree.
2. **A refactor must not regress.** *Before* touching anything, inventory every behavior,
   feature, state, and path the old page has — the new page keeps all of them unless you
   deliberately drop one and say so.
3. **Never hand-write a color — tokens only.** `bg-card` / `text-foreground` / `border-border`,
   etc. Dark mode is purely the result of this, and **nothing lints raw colors in app pages**,
   so one `bg-white` / `#hex` / `text-gray-*` ships visibly broken in dark. For any hover /
   selected / pressed / subtle tint, use the neutral **overlay ladder** (`--ui-hover` /
   `--ui-selected` / `bg-accent`) — never a gray or a `/10` alpha.
4. **Build from the shared shell + primitives.** Centered `max-w-3xl` with gutters;
   `SettingsSection` / `SettingsRow` white cards — one hairline, role-map radius, inset
   dividers, deliberate spacing rhythm, and **no hover-rise** on cards. The full **owner
   vocabulary** — which recurring shapes (row, field, section, tile, banner, loading/empty
   state, delete confirm, page frame…) have an owner component, the decision map, and when a
   shape deliberately stays hand-written — lives in `../ui-owners/SKILL.md`;
   read it before building any of those shapes.
5. **Reuse a component — never hand-write one.** Compose from the real `@felinic/ui` atoms
   (Select / Combobox / Tooltip / icon `Button` / `Empty`) and the existing shared parts; never
   re-skin one, hand-roll an equivalent, or rebuild a control out of raw `<div>`s. **Menus
   included:** dropdown / context / action menus use `DropdownMenu` / `ContextMenu` and their
   `*Item` / `*Separator` / `*Label` slots — never hand-written `<button>` rows, never `<hr>` /
   `border-b` dividers inside a popover. The same rule applies to every other surface: if
   `@felinic/ui` (or an existing app component) already covers it, use it — hand-built markup
   drifts out of the token contract and reads inconsistent page to page. If a layout repeats,
   extract it into one shared component instead of pasting it twice. A genuinely new component
   is a last resort — clear it with the developer *before* building it.
   **The component system is not modelling clay.** `SettingsSection` / `SettingsRow` / the cards
   are not a blank canvas you reshape to taste — each has *one* sanctioned use, and you compose
   *with* them, you do not knead them into a new shape. The tell that you've started treating the
   system as clay: you're putting a hand-rolled `grid` / multi-column layout / freeform `<div>`
   stack **inside** a `SettingsSection` to "arrange things nicer" (a 2-col stat grid jammed into
   the white card is the canonical offence — see `reference.md` dirty→clean). When the shape you
   want isn't one the primitives already give you, that is **not** license to deform a card from
   the inside — it means you've picked the wrong primitive. Stop, find the component whose *one*
   job is that shape (a value-in-a-card is a `SettingsRow`; a label-on-top/number-below readout
   is a **section-level stat tile**, never a grid inside a card), or clear a real new component
   with the developer. Squeezing the clay is always the wrong move, even when it renders fine.
6. **Earn every word and every block.** Cut copy that doesn't guide; hide blocks that aren't
   actionable; empty *and* loading states must still draw their frame (no layout jump).
   **No stray fragments:** every visible piece must sit in a named region (PageShell
   `#actions`, a row's control column, a dialog footer, a toast) — never a lone status line
   floating where it aligns with nothing. If it can be removed, remove it; if it must stay,
   anchor it and reuse an existing pattern from a reference page.
7. **You are not done until you verify the *rendered* page:** grep for raw colors → flip to
   **dark** → shrink to **narrow + `zh`** → walk **every old interaction** → `mise run lint`.
8. **Draw it before you build it, then audit the nesting.** Sketch the page as an ASCII
   wireframe first — and again when it looks done — and read it like space-complexity: no
   card-in-card, no decorative icon stacked in a card, no nesting layer that isn't earning its
   keep. Fewer boxes, shallower depth.
9. **The root surface answers "is it working," not "configure everything" (the 99/1 rule).**
   The first page a user lands on serves the 99% who came to *glance at state* — it must not
   make them carry the visual weight of inputs, button piles, or history lists that only the 1%
   want. But the 1% are not browsing; they **arrive with a purpose** and will hunt for the
   button — so deep/rare operations (limits, snapshots/history, destructive actions) live behind
   a **named entry point** (a one-line summary row + a button) that opens a focused form showing
   the data *and* the action. Never spill them onto the root, and never bury them in an in-card
   "Advanced" disclosure that mixes diagnostics with real operations (§ 12).
10. **A change is not committed until a human verifies it.** Run lint / grep / type checks
    yourself, but the **rendered** result (visual + interaction) must be checked by a human
    before any `commit` / `amend` / `push` — do not amend or squash unverified work into a
    commit on your own say-so. "It should work" from the agent is not verification; the
    human's eyes on the rendered page is. Follow-up tweaks to an already-committed change
    re-verify before re-amending.

---

This skill is the **page-level** companion to the **atom-level** contract in
`packages/ui/AGENTS.md`. That file governs how a single control looks; this file
governs how you compose controls into a page that reads like the already-refactored
surfaces (Overview, Appearance, Profile, About, Web Search) and never like the
legacy ones.

It exists because the refactor kept slowing down: each page re-derived the same
decisions from scratch and re-made the same mistakes. The point of this skill is to
make that experience reusable — so refactoring "the next page" is a procedure, not
a re-invention.

## Prime directive

> **Copy the new language. Never copy the legacy.** When unsure how something should
> look or behave, open a refactored reference page and mirror it — do not pattern-match
> off an un-refactored page (even one you are mid-refactor on).

Two non-negotiable first steps before you touch a page:

1. **Read `packages/ui/AGENTS.md` in full.** It is the law for tokens, radius, borders,
   color, motion, and the "clean vs dirty" rule. This skill assumes it.
2. **Open one refactored reference + the page you're replacing side by side.** See
   `reference.md` § Reference map for which page to copy for each page shape, and the
   dirty→clean table for diagnosing what to strip.

## A refactor is behavior-preserving — interrogate what it breaks

The Prime directive covers the *look*; this covers the *behavior*. Changing how a page looks
must not silently change what it does. The most common refactor failure is not an ugly page —
it's a page that quietly **lost** an affordance that was buried in the old messy layout. Before
and during a refactor, stop and ask what the refactor could break:

1. **What is the user's path here?** (This is the § 1 copy question, upstream of pixels.) Why
   does the user come to this page, what are they trying to do, how do they get in and out?
   The visual exists to serve that path — so derive the path first, then build to it.
2. **Does each remaining control's *interaction logic* need to change — and if you change it,
   is it still complete?** A control is not just its look. It carries behavior: a select that
   filters, an input that debounces, a toggle that triggers auto-save, a context menu, keyboard
   handling, a drag, a hover-to-reveal action, an empty/loading/error branch. When you swap a
   legacy control for a refactored one, **re-wire every behavior it had** — don't just port the
   markup.
3. **Did the refactor drop functionality?** Inventory everything the old page could *do* — every
   button, menu item, edge action, state, shortcut — and confirm the new page can still do all
   of it, or that you **deliberately** removed it and said why. Never lose a capability by
   accident.
4. **Is there a better path?** A refactor is the moment to question whether the old flow was even
   right: a step that can be removed, a dialog that can be inlined, two redundant controls that
   can merge, a shorter route in/out. Improve the path, don't just repaint it.
5. **A new page is all of the above, from zero.** With no old page to inventory, you must derive
   the path, the required behaviors, and the complete feature set from the requirement itself.
   The risk inverts: not "losing" an old behavior, but **never specifying** one you needed —
   so think the full interaction surface (states, edges, empties, exits) up front.

## Engineering correctness — the dirt the eye can't see

A page can pass every visual rule and still be **wrong**. The most expensive debt isn't an
ugly card — it's behavior that breaks because two modules quietly disagree about a contract.
This is invisible in a screenshot and survives review, so it gets its own pass. Treat it as
part of "clean," not a separate concern.

- **A cross-module assumption must be enforced or eliminated — never just commented.** The
  back-affordance bug is the cautionary tale: `useSyncedQueryParam` switched tabs with
  `router.replace` under a comment claiming "replace won't bury the previous page," while
  `installBackHistory`'s `afterEach` never distinguished replace from push — so replace *did*
  overwrite `previous`, and the back button started reading the bot's raw `bot-<uuid>` slug.
  Both comments looked reasonable; together they were wrong. If module A leans on module B
  behaving a certain way, lock it with a type or a test, or remove the assumption. A comment
  asserting the contract is not enforcement of it.
- **Layout size must never be driven by content.** A `w-fit` sidebar
  (`master-detail-sidebar-layout`) let one too-long back label stretch the whole panel — so a
  bad string became a visibly wider sidebar. Pin widths and let text `truncate` inside a fixed
  box; a locale change, longer data, or an upstream bug must never move the frame.
- **In-page state syncs with `replace`; whatever reads "the previous page" must honor that.**
  Tab/filter swaps are not navigations — they `router.replace`. A history reader that counts
  replace transitions will treat a tab switch as a place to step "back" to.
- **One root cause often wears two faces.** The slug label and the widened sidebar were the
  same bug. When two oddities appear together on the same action, hunt one upstream cause
  before patching each symptom in place.

## The design language in one breath

The refactor is **not** new chrome. It is a switch to a calmer language whose body is
defined by a **single hairline stroke + an inherited white surface**, and whose
interaction is read through **color/fill change in place** — never by lifting, scaling,
shadowing, or bordering something "to make it nicer."

What concretely changed, before → after:

- **Floating white cards.** Content lives in `bg-card` cards with **one** `border-border`
  hairline and the shell radius. The section title sits *above* the card as quiet muted
  text. Use the shared `SettingsSection` / `SettingsRow` primitives — do not hand-roll a card.
- **Unified stroke.** One hairline, `border-border`. Never `border-border/50`,
  `border-*/40`, or a structural border on a control body.
- **Unified radius.** Only the role-map scale (card 14 / menu-shell 12 / control 8 /
  badge·tooltip 6). Never a bare `rounded` or an off-scale `rounded-lg` on a control.
- **Unified color.** Black/white/gray is ~90% of the UI (the skeleton). Charcoal is the
  high-emphasis CTA; blue means "selected"; purple is scarce. `success`/`warning`/
  `destructive` are **rationed signals**, not surface decoration — never tint a whole
  card `bg-success/5`.
- **Unified components.** Use the refactored `@felinic/ui` atoms as-is. Do not re-skin
  them or inject classes that fight their contract (the canonical "weird Select" bug).
- **No hover-rise, ever.** Cards and rows do **not** lift / scale-up / grow a shadow on
  hover or press. Press-scale belongs only to buttons and sidebar rail items — never to a
  large content card (a bot card does not shrink when you press it).

### The shell & spacing rhythm

This is the part that most often gets skipped and is the fastest tell of an un-refactored
page. The refactored pages (Appearance / Profile / About) are **not full-bleed** — they all
sit inside the same shell, and nothing ever touches an edge or another element.

- **The shell.** Content is a centered column inside the right pane, not stretched edge to
  edge: `mx-auto max-w-3xl` caps the width (~768px) and centers it, `px-6` keeps a left/right
  gutter so nothing glues to the pane edge, `pt-10` pushes the title down off the top, `pb-12`
  leaves room at the bottom. A page that runs full-width or starts flush against the top is
  immediately off-language. (About is the one exception: being sparse, it centers its group
  vertically with a slight upward bias instead of top-aligning.)
- **Spacing is a hierarchy of gaps, not free-styled margins.** Each level of structure has
  its own consistent breathing room, and you reuse the same rung instead of inventing values:
  - title → content: `mb-6` (Profile uses `mb-8`)
  - card group → card group: `space-y-8` — the big, generous gap that separates sections
  - section label → its card: `space-y-2.5`
  - row → row inside a card: a `border-b` hairline divider + `py-3`, each row `min-h-[3.75rem]`
  - label → its description: `mt-0.5`
  - inside a padded card block: `p-4`/`p-5` with `space-y-4`
- **Text is never glued — to edges, to the top, or to each other.** Every label has air above
  and below it; the title has air under it; cards have air between them. When something feels
  cramped, the fix is almost always "use the next rung of the spacing hierarchy," not a
  one-off margin.

Concrete shell + primitives (exact recipes + the full spacing ladder live in `reference.md`):

- Page shell: `mx-auto max-w-3xl px-6 pt-10 pb-12`, title `mb-6 px-2 text-lg font-semibold`,
  sections stacked with `space-y-8`.
- Card: `SettingsSection` = `overflow-hidden rounded-[var(--radius-menu-shell)] border border-border bg-card`,
  optional title above as `px-2 text-[13px] font-medium text-muted-foreground`.
- Row: `SettingsRow` = label (`text-sm font-medium`) + description (`text-xs text-muted-foreground`)
  on the left, the control on the right, rows split by `border-b border-border last:border-b-0`.

### Dividers — inset inside a card, full-bleed everywhere else

A divider has two different jobs and two different widths; using the wrong one is a tell.

- **Separating rows *inside* one white card → inset.** The hairline must **not** reach the
  card's left/right edges. This is done by putting the border on a horizontally-margined row
  (the `mx-4` on `SettingsRow`), never on the card itself, and dropping it on the last row
  (`last:border-b-0`). An edge-to-edge line would visually slice the rounded card into stacked
  tiles and break the "this is one continuous surface" reading. **Corollary:** borders go on
  *rows*, never on the invisible wrapper `<div>` you put a `v-if` block in — a wrapper with
  `border-b` that ends up the **last child of the card** doubles its hairline onto the card's own
  bottom stroke (the recurring "fights the stroke" bug). See reference.md § Dividers.
- **Structurally splitting a container → full-bleed.** A Dialog header/footer band, a
  section-heading underline, or a standalone `Separator` between blocks divides the *whole*
  container, so the line spans edge to edge while the content keeps its own inner padding.

The test: is this line separating **items within one surface** (inset) or **splitting the
container itself** (full-bleed)? Answer that before you place a divider.

**A "divider I never drew" is usually a misplaced `#footer`.** If a hairline appears to float
under a single row over an empty strip, you almost certainly put a `SettingsSection #footer`
(Save band) on a *root-page* card — its full-bleed `border-t` plus the lone row's own inset
`border-b` read as a stray line. The line is real chrome in the wrong home: a root page's Save
belongs in `PageShell #actions`, not a card footer (§ 8). Fix the home, not the line.

### Dark mode is not a task — it is the absence of hardcoded color

**Read this twice. This is the single most-skipped requirement, and nothing will catch it for
you.** You do **not** "add dark mode" at the end. Dark mode is the *automatic* result of using
only semantic tokens; it breaks the moment you hardcode one raw color. So there is exactly one
rule, applied from the first line: **never write a raw color — use a semantic token.**

- Raw colors that silently break dark mode: `bg-white`, `bg-black`, `text-white`, `text-black`,
  any `*-gray-*` / `*-zinc-*` / `*-slate-*` / `*-neutral-*`, any `#hex`, any `bg-[#…]` /
  `text-[#…]`, any inline `style="color: …"` / `background: …`. Use `bg-card`, `bg-background`,
  `text-foreground`, `text-muted-foreground`, `border-border`, `bg-accent`, etc. instead.
- **For tints and subtle layering, prefer the neutral overlay ladder — it is the dark-safe way
  to add "color."** When you need a hover / selected / pressed shade, or a faint layer to set
  something apart, reach for the interaction-overlay tokens (`--ui-hover` / `--ui-selected` /
  `--ui-pressed`, the `--overlay-*` rungs, or `bg-accent` which maps into them) — **never** a
  solid fill, a hand-mixed gray, or an alpha hack (`bg-black/5`, `hover:bg-gray-100`). The
  overlays are chroma-0 and composite over whatever surface they sit on, so they are the **same
  token in light and dark** (light = a black wash, dark = a white wash) and identical across
  every color scheme — no `dark:` variant, no per-scheme override, and they cannot break the way
  a baked color does. (Full ladder in `packages/ui/AGENTS.md` § Color → Interaction overlay.)
- **A `dark:` override is a smell, not a fix.** Themed tokens auto-switch with **no** `dark:`
  prefix. If you're reaching for `dark:bg-…` to patch a page, it means you started from a raw
  light color — go back and replace the base color with a token; don't band-aid it per-mode.
- **There is no safety net for app pages.** The UI-contract guard (`mise run lint`) only scans
  `packages/ui` — `apps/web` pages are explicitly out of scope, and there is no ESLint rule for
  hardcoded colors. So a raw color in a page is caught by *nothing*; lint passes, and the page
  ships broken in dark. The discipline below is the only defense — treat it as mandatory.
- **Before you finish, do two things, every time:** (1) grep the page for raw colors
  (`bg-white`, `text-black`, `text-gray-`, `bg-gray-`, `#`, `dark:`, inline `style=`); (2)
  actually **flip the app to dark and look at the rendered page**. The only sanctioned `bg-white`
  is a physical knob (Switch / Slider thumb) over a colored track. Canvas content (charts) can't
  read tokens — reuse the token→concrete-color resolve the reference pages already do, re-run on
  theme change.

### Narrow screens reflow, never overflow

A settings page is a centered `max-w-3xl` column, but the pane is resizable and the desktop
window can be narrow. Multi-column grids collapse with responsive prefixes (`grid-cols-1
sm:grid-cols-2`, stat rows `grid-cols-2 sm:grid-cols-4`); same-row control clusters (search +
button) must not break or clip. Always check the narrowest realistic width, not just the wide
default — and remember Chinese copy is wider, so the narrow + `zh` combination is the real worst
case (see § 1).

**When a component must adapt to a resizable pane, viewport breakpoints are the wrong tool.**
`sm:` / `md:` watch the *window* — but a dockview / master-detail pane changes width while the
window doesn't, so a `sm:` grid won't react when the same component sits in a narrow vs wide
pane. Reach for a **container query** (`@container`) so the component responds to *its own
container's* width, not the viewport. (Page-level `max-w-3xl` columns still use viewport
prefixes; this is only for components that live inside variable-width panes.)

Pane width is only one of three "bigger" axes; the page must also hold up under **browser zoom**
and a **larger root/OS font**. The defence is the same discipline: lay out with the spacing
ladder and flex/grid gaps (never a margin tuned to one string), size inline-with-text icons in
`em` so they grow with the text while standalone control icons keep the `size-*` rem ladder, cap
width with `max-w-*` + centre so a wide screen never stretches a line, and let any line that can
outgrow its box `truncate`. Full rules + the verify pass (zoom 50→200%, narrow + `zh`, ultra-wide)
live in `reference.md` § Scaling & zoom.

### Scroll ownership

Know who owns the scroll before you add `overflow-*` anywhere. The desktop shell **locks body
overflow**, so a page that needs to scroll must own its own scroll container (the dev wall does
this with `h-dvh overflow-y-auto`); a settings page instead scrolls inside the section's
existing scroll area. The failure modes are symmetric: a page that forgets to own its scroll is
un-scrollable inside the desktop shell, and a page that adds a stray `overflow-*` creates a
*nested* scroll container (a scrollbar inside a scrollbar) or a surprise horizontal scrollbar.
When a transform nudges content sideways (the list↔detail swap pushes panes ±24px), clip it
with `overflow-x-clip` — not `overflow-x-hidden`, which would turn the element into a vertical
scroll container and steal scrolling from the ancestor. Don't introduce a new scroll container
unless you mean to.

**Every page-level scroll container that holds a centered `max-w-3xl` column must reserve the
scrollbar gutter — `[scrollbar-gutter:stable]`.** The shell centers content with `mx-auto`, so
its left/right margins are computed from the pane's *available* width. When a classic
(space-consuming) scrollbar appears, it eats that width and the whole centered column — title,
card edges, everything — shifts sideways. The tell is real and confusing: two sibling tabs look
"only similar," because a long tab scrolls (narrower pane) while a short one doesn't (wider
pane), so the title and card edges land in different spots as you switch between them. A page
that doesn't scroll *today* will the day its content grows — so this is not optional on the
scroller, it's structural. Reserving the gutter keeps the available width constant whether or
not the scrollbar is visible, so every page that shares (or mirrors) the scroller stays aligned.
There are only a handful of these page-level scrollers (the settings section's `router-view`
pane; any master-detail surface that runs its *own* inner scroll pane, e.g. the bot-detail tab
pane) — put the rule on the scroll container itself, never on each page, so all pages it hosts
inherit it for free. Bounded inner scrollers (a tool-call detail body, a dropdown list, a log
pane) are left-aligned and don't need it.

## Component discipline

**Reuse first; build new only with sign-off.** The default is always to *find and reuse* an
existing component, then to *compose* existing atoms — never to hand-write a control out of raw
markup. The most expensive page is the one where the agent quietly re-built from zero what
already existed. Three rules, in order:

1. **Hand-writing a component is forbidden.** A clickable `<div>` that re-implements a Button, a
   bespoke popover list that re-implements a Select, a `<div>`-grid that re-implements a Table —
   all banned. They can't receive the size / token / focus / a11y contract, and they drift. If
   `@felinic/ui` (or an existing app component) has it, use it as-is.
2. **A composition that can repeat must be extracted, not pasted.** Even when every piece is a
   properly reused atom, if the *arrangement* could appear in more than one place (a provider
   row, a card header, an empty tile, a field cluster), lift it into one shared component and
   reuse that. Copy-pasted markup is duplication waiting to drift out of sync — and a reused
   composition dropped into a spot where the same shape recurs is the signal to extract it.
3. **A genuinely new component needs the developer's OK first.** When nothing fits and no
   composition will do, stop and say so — name what's missing and why — get agreement, then
   build it once in the shared layer. Never silently spawn a one-off component mid-page.

**A component is a component — patterns that co-star are not families.** Each component is a
standalone contract with its own identity; two components appearing together in a house
pattern does NOT make one belong to the other. Worked example: the focused-dialog family
(`DialogPanel` / `DialogViewHeader` / `DialogBody`) and `ActionCard` almost always ship
together — a named entry card opening a focused dialog — yet they are ORTHOGONAL: the dialog
anatomy belongs to `Dialog` and opens from any trigger (a toolbar button opens the bot-mcp
Import panel; a shortcut could too), and ActionCard is just one opener that emits a click and
doesn't know what opens. Filing the dialog primitives "under ActionCard" would have invented
a false dependency — a future agent would think "no ActionCard, so I can't use DialogPanel"
and hand-roll a dialog shell, or worse, bolt an ActionCard on just to unlock the dialog. The
general tests, because the NEXT case won't look like this one:

- **Independence test:** can A be used, correctly and completely, without B ever existing?
  If yes, A is not B's child — don't name it, file it, or document it as one.
- **Ownership test:** when A and B co-star, who owns the seam? The answer is "a PATTERN in
  this skill" (a documented composition, like the ActionCard → focused-dialog skeletons) —
  never a component absorbed into the other's namespace, props, or docs section.
- **Coupling smells to reject on sight:** a component whose props exist only to serve one
  sibling (`forDialog`, `insideCard`); a component importing a sibling it doesn't render;
  docs/exports that nest one standalone contract under another's heading; a name that bakes
  in the co-star (`ActionCardDialog`) when both halves are independently reusable.

Patterns live in this skill as *compositions of named parts*; components live in the library
as *parts that don't know their co-stars*. Keep those two layers straight and the next
accidental marriage never happens.

Then pick the right component instead of bending the wrong one. See `reference.md` §
Component picker for the full decision table and the icon/badge/tooltip rules. The
recurring failures to avoid:

- **Menus (dropdown / context / overflow / kebab):** `DropdownMenu` or `ContextMenu` as the
  shell; each action is `DropdownMenuItem` / `ContextMenuItem` (or checkbox/radio variants when
  needed); group labels use `*MenuLabel`; splits use `*MenuSeparator` — never a raw `<button>`,
  clickable `<div>`, or `<hr>` / `border-b` / `h-px bg-border` standing in for menu chrome.
  The trigger is `<Button>` / `TextButton` / `DropdownMenuTrigger as-child`, not a bespoke
  clickable span. Submenus use `*MenuSub` + `*MenuSubTrigger` + `*MenuSubContent`. All menu
  surfaces share `lib/menu.ts` (`menuItemClass`, `menuSeparatorClass`) — hand-building rows
  bypasses that contract and is the fastest path to "this menu looks different from every other
  menu."
- **Choosers:** `Select` (pick one value from a menu) · `Combobox` (searchable, single
  *or* `multiple`) · `SegmentedControl` (a mode/filter, no panels) · `Tabs` (switch panels).
  Do not hand-roll a searchable dropdown when `Combobox` exists; do not inject custom
  classes into a `Select` trigger that fight the field-edge contract.
- **Icon buttons:** `<Button variant="ghost" size="icon">` in a toolbar, `variant="outline"`
  standalone. Icons are **lucide components** (`<Plus/>`), never a typed glyph (`"+"`),
  and never free-sized — let the `size-4` control ladder apply. Never `scale-90` a control
  to "fix" its size.
- **Icon position in a text button is semantics, not decoration.** On a compound-action
  button, the icon's placement declares which verb dominates: a *leading* glyph names the
  action's identity ("this is a copy button"), a *trailing* `ExternalLink`/chevron names the
  *outcome/destination* ("pressing this leaves to a page / drills in"). Worked case: the
  device-code "Copy & Open" button with a leading `Copy` glyph read as copy-only and users
  never guessed it opened the browser; moving to a trailing `ExternalLink` fixed the
  expectation without a word of extra copy. Pick the position by asking "what should the
  user expect to *happen*?" — never by symmetry or habit. And **spacing between a Button's
  direct children belongs to the Button** (`gap-2`, `gap-1.5` on `sm`, plus `has-[>svg]`
  padding compensation): hand-adding `ml-*`/`mr-*` on the icon stacks onto that gap and
  visibly unbalances the button (the recurring "icon drifted right" bug).
- **Default to no icon — an icon is a cost, not a freebie.** An icon must earn its place by
  carrying meaning — a brand/provider mark, a status, or a clear action glyph on a button. It is
  never free: a boxed icon drags in a surface (and its shadow), one more color, and a "does this
  glyph even fit our language?" judgment call. So a generic lucide glyph dropped beside a title,
  floated atop a "No X" empty block, or **stacked inside a card** is decoration, not signal — it
  reads as cheap chrome and cheapens the page. Ship none by default; when a spot genuinely seems
  to want one, **clear it with the developer before adding it** rather than sprinkling icons on
  your own judgment.
- **Never reuse a bordered/filled primitive as a leading icon inside a card that already has its
  own border.** `ItemMedia variant="icon"` and any similar tile primitive bake in their own
  `border` — that is correct where they're designed to stand alone, but dropping one inside a card
  that already carries `border-border` stacks TWO strokes on one visual unit, visible at once. This
  is the "chrome layers stacked on a control" violation (§ The one rule — clean vs dirty) hiding
  behind an otherwise-correct instinct ("reuse, don't hand-roll") — it slips past review because the
  primitive is real and contract-listed, not hand-rolled CSS. When you need an icon at a specific
  *footprint* (e.g. matching an adjacent control's size so two rows carry comparable weight), borrow
  only the size (`flex items-center justify-center` at whatever size fits) — never the primitive's
  border/bg. See `reference.md` § Dirty → clean for the full case (`ActionCard`'s icon slot).
- **`BadgeCount`:** `destructive` red dot pinned to an icon corner = alert/unread; `default`
  neutral count rides a tab/filter/segment; a flat list row uses a plain muted numeral, no bubble.
- **`Tooltip`:** always the `@felinic/ui` `Tooltip`. A hand-rolled or legacy tooltip is a bug.
- **An empty state keeps the populated skeleton — it is the same page with no rows yet.** The
  worst empty-state failure is letting "there's no data" rearrange the page into a *different*
  shape. Keep the exact frame the populated state uses (the same `SettingsSection` card, the same
  grid container) and drop the message *inside* it, so entering an empty page vs a full one never
  jolts the layout. The model is the **Plugins tab**: its empty state is the very white card it
  shows when populated — just `py-12` centered title + description + the one guiding action (an
  outline "+ Add" / "Supermarket" button). Two hard rules ride on top:
  - **`border-dashed` is NOT an empty-state look.** Dashed is reserved for the **"+ Add another"
    tile** that sits *beside real items in an already-populated list/grid*, where adding one more
    is the secondary affordance. A completely-empty surface takes the **solid** frame its
    populated form has — the section card, or a solid-`border` framed block for a standalone grid
    — never a dashed box, and never bare floating muted text. (This refines the older "outermost
    Empty earns a dashed border" guidance: it does not — outermost empties are solid-framed.)
  - **No decorative icon.** An `EmptyMedia variant="icon"` glyph tile, or any big lucide glyph
    stacked above the title, is banned: it is both card-in-card and the icon-abuse below. Just
    title + description + action. (An action *button* keeps its own small action glyph — that is
    not a decorative tile.) This page-type attracts icon abuse — a giant glyph crammed in front
    of a list item or empty block — so default to **none** everywhere except a button's own glyph.
- **Destructive actions:** a filled `<Button variant="destructive">`, gated behind a
  confirmation (`ConfirmPopover`, or a dialog for heavier deletes) — never a bare one-click
  delete, never a ghost button with manual red text. Group truly dangerous actions in a danger
  card kept at the bottom of the page. **Confirm covers interruption, not just deletion:** any
  action that ends running work or severs a live connection — Stop a runtime, Terminate a
  session, Disconnect — earns the same confirm step, because "it stops what it was doing" is a
  consequence the user must opt into. Skip the confirm only for cheap, reversible actions.
- **Long lists / big dropdowns virtualize.** A list or chooser that can hold hundreds of rows
  (sessions, models, searchable selects) must virtualize, not render every node — otherwise the
  refactor that "looks fine" with 5 rows jank-scrolls with 500. Reuse the existing virtualized
  patterns instead of a plain `v-for` over an unbounded list.

## Compose, don't style — the extension boundary

**First, the root principle everything below derives from.** A component library and its
design tokens exist for exactly one reason: **callers write no magic values, so the
system's maintainer can change ONE number in ONE place and every caller benefits.** Every
magic string a caller must hand-copy — a `grid-rows-[…]` recipe, a raw hex, an arbitrary
`h-[37px]`, a prop pairing that only works if you remember it — is a defect in the SYSTEM,
not a chore for the caller. It means N call sites now pin that value, the maintainer's
one-place edit no longer reaches them, and each copy is one more chance to mis-copy a
fragment and resurrect a solved bug. This cuts both ways:

- **When USING a component:** if correct usage requires you to hand-write a layout/style
  string or memorize an unenforced pairing, do not dutifully copy it — the component is
  incomplete. (Live example: `DialogPanel` exists because the focused-dialog shell was a
  copy-me class string, `max-h-[80dvh] grid-rows-[auto_minmax(0,1fr)]…` plus a
  remember-to-disable-the-corner-close rule; every consumer had to transcribe it
  perfectly. The fix was never "copy it more carefully" — it was making the recipe BE the
  component, with the pairing enforced by a prop.)
- **When DESIGNING a component:** the acceptance test is "a caller who has never read the
  implementation fills in content — title, icon, fields — and hand-writes zero
  layout/appearance CSS." Knobs are **enumerated props** (`width="2xl" | "3xl"`), never
  free-text class strings: an enum forces the next rung to be added in the library,
  deliberately, instead of invented per page.
- **When you FIND a violation you cannot fix in this task:** say so to the human you are
  working with, explicitly — "this component still requires callers to hand-write X, which
  breaks the one-place-to-change guarantee." That escalation is not noise; it is the most
  fundamental defect class in this codebase, and the human decides whether to stop and fix
  the system or knowingly take the debt. Never silently absorb it into your page.

This is the page-layer half of `packages/ui/AGENTS.md` § *Compose, don't style* (read it for
the ownership table + the four override planes). Component discipline above says *which*
component to use; this says how you are allowed to **add to** one — because the moment you
can't, the only exit left is injecting CSS, and injected CSS is the single largest source of
page debt: it fights the component's `::before` fill / field-edge, breaks dark mode, and
nothing lints it on an app page.

**"I want to add something" has exactly five exits — four need no CSS, the fifth is an upgrade:**

| I want to… | The sanctioned exit |
|---|---|
| add content (icon / badge / suffix) | a **slot** |
| change size / density | the **`size` prop** |
| change meaning (emphasis / danger / selected) | the **`variant` prop** |
| change *outer* layout (width / alignment / outer margin) | a **layout-only className** (see the red line) |
| want a look the component doesn't offer | **upgrade the component** (add a `variant`/slot, or extract a pure-style component) — never inject in place |

**The className red line — the outer box is yours, the body is the component's:**

- **Allowed on a component** (it only positions the outer box): `w-full`, `flex-1`, `grid`,
  `gap-*`, outer margin (`mt-*` / `mx-auto`), `max-w-*`.
- **Forbidden on a component** (it reaches into the body and fights `style.css`): `bg-*`,
  `hover:*`, `active:*`, `border-*`, `shadow-*` / `shadow-none!`, `ring-*`, `h-[Npx]`. If you
  just typed one of these onto a `<Button>` / `<Select>` / `<TextButton>`, stop — pick the
  right `variant`/`size`, or upgrade the component. (Canonical offender: the 6×-pasted "add
  provider" button carrying `bg-background border-border hover:bg-accent shadow-none!` on a
  real `<Button>`.)

**The agent workflow — find, reuse, compose, upgrade; never style:**

1. **Find before you write — and do not trust grep.** Ten near-identical controls can wear a
   hundred names, and they all share similar CSS, so "I didn't match it" does **not** mean it
   doesn't exist — the odds it already exists under another name are high. Check the component
   map / `reference.md` § Component picker before assuming nothing fits. Re-deriving an existing
   component is the #1 debt source.
2. **Priority is an order, not a suggestion:** reuse > compose > upgrade > (never) hand-write style.
3. **Copy only a gold-standard reference, never a dirty page.** few-shot copies what it sees;
   some good-looking pages are already off-contract, so their markup is poison — confirm a page
   is clean before mirroring it.
4. **Red lights — STOP and ask, do not improvise:** you need a *new component*, a *new token*,
   to *edit `style.css`*, or an *a11y / RTL* trade-off. Improvising past any of these means
   hand-writing past the boundary — exactly the move this whole contract exists to prevent.

## The debt taxonomy — name it before you decide to fix it

"Is this debt?" stops being a vibe once the failure has a name. Three axes turn the adjectives
*maintainable / reliable / clean* into a checklist; when unsure whether something is worth
flagging, match it here. This is a diagnostic lens, not new r

…(truncated)