Imported from felinics/ui (skills/web/SKILL.md). Install upstream with npx skills add felinics/ui --skill web. Copyright stays with the author.

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:

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 rules — most rows already have a rule elsewhere; the value is being able to name the failure (and so decide whether to fix it now or mark it known).

• Maintainability (can we still change it fast & safely tomorrow):
  • override-plane debt — one result must hold on all four planes at once (packages/ui/AGENTS.md).
  • duplication debt — one arrangement pasted N times; change one = change N, and they drift.
  • source-of-truth debt — one value hand-copied to two homes, kept in sync "by remembering" (a list mirrored in cva and an array with a "keep in sync" comment).
  • discoverability debt — can't find it → rebuild it. grep is blind here (same job, a hundred names, identical-looking CSS), so a missing component map guarantees re-derivation.
• Reliability (will it break when no one is looking):
  • coupling / boundary debt — a cross-module assumption asserted only in a comment, never enforced; survives review, fires at runtime.
  • consistency debt — one job done N ways, so one of them is always the odd/wrong one (the trigger-open philosophy split: Select vs ghost).
• Cleanliness (will it rot the more it is used):
  • extension-contract debt — no sanctioned exit → injection (the red line above).
  • rule debt — a rule written but not mechanized, or whose guard is scoped to the wrong place (the contract scans packages/ui; the debt lives in apps/web).
  • exemplar debt — a dirty page becomes the thing the next author (or agent) copies.

The deepest debt is un-greppable: it lives at runtime / in injected dependency behavior — reka's focus management + pointer-events, portal/teleport leaving the style context, z-index stacking, JS↔CSS measured layout, the Tailwind-v4 translate/transform remap. String search can't find it and review can't see it, because it is synthesized only when the page runs. The defense is always the same: push that complexity down into components / tokens / lint, so neither a human nor an agent ever has to reason about it from inside a page.

Seam-first debugging — find the seam, don't grind the layer

The debt above is mostly un-greppable, so when a visual / interaction bug appears you cannot search your way out — and the wrong instinct is to grind the layer: stack another !important, nudge a z-index, pile on a hover override, tweak a margin until it "looks right." Every grind adds a chrome layer (= more debt) and usually treats a symptom whose cause lives in a seam you are not even editing. Front-end conflicts almost never live inside the layer you are touching; they live in the seam between two layers. So when stuck, debug the seam, not the layer. (This is the diagnostic the override-plane map can't pre-list for you: the map names known seams; this is how you handle a seam nobody wrote down yet.)

1. Stop signal. If your next move is "add one more CSS rule" to fix a look / interaction — stop. That urge is itself the tell that you're grinding a layer.
2. Name the seam. Ask what composes this final result: your classes + the framework's injected data-* / behavior (reka) + the browser's cascade + the current runtime state. The fight is at the seam between two of these — not in the one file you opened.
3. Check ownership. The misbehaving property — where is its home (the ownership table in packages/ui/AGENTS.md)? If you're changing it somewhere it shouldn't be touched, that's the cause; go fix it in its home.
4. Find a solved twin. Has this exact seam already been solved elsewhere? (select-trigger solved the open/hover seam with pointer-events:auto.) Copy the solved one — don't invent a second, conflicting fix (that is how the trigger-open split was born).
5. Fix the contract, not the symptom. Resolve it at the seam's contract (add / unify a variant / slot / one philosophy), never by caking CSS onto the symptom.
6. Circuit breaker. Same bug, second or third "add CSS" attempt still not clean? That is conclusive: the cause is a seam, not a missing rule. Stop adding CSS, return to step 2 — and if the honest fix is a new component / token / a style.css edit, that's a red light (§ Compose, don't style — the extension boundary): stop and ask, don't grind on.

Re-review — two failures a single read of this skill can't prevent

Reading the rules once, up front, is not enough — two failure modes slip past it, and both are fixed by the agent re-reviewing itself, not by adding more rules:

• Context decay — you forgot the rules you read. After a long task (many tool calls, a big diff) the skill you read at the start has been diluted out of context, and the code you just wrote can quietly violate it. So before calling a thing done, reload the contract — don't review from memory: re-open the ownership table + the className red line + the five exits (and run § The review ritual below), then walk your own diff against them — did I inject an appearance/interaction class onto a component, hand-write a hover, hand-roll a control? Memory is not the source of truth; the rules file is.
• The loop is the signal — you're patching a wrong direction. When the same problem runs human flags it → you patch → still wrong, two or three rounds deep, stop patching. The loop is conclusive on its own: the cause is not "one more fix," it's a wrong root or a wrong direction, and every patch only stacks complexity (= debt) on a bad base. Even if you eventually make it "work," a thing patched onto a wrong direction is debt, not a solution. Step back and re-review the whole thing, not the last edit: did I understand the requirement right? Am I fixing the root or a symptom (§ Seam-first debugging)? Is the honest move to throw it out and redo it rather than patch again? Is this a red light (§ Compose, don't style)? The bar is "is the direction right," never "can I eventually make it run."

Same spirit as § Seam-first debugging, scaled up: seam-first stops you grinding one layer on a single bug (a spatial move — look at the seam); this stops you grinding one direction across many rounds (a time/round move — look at the whole). Both say: at a threshold, quit local patching and re-review the larger frame.

UX principles — the part that is hard to see

These are judgment rules. They are the difference between "it renders" and "it's good."

1. Interrogate every line of copy

P0 — Label ≠ placeholder (never show the same noun twice). A field label and its placeholder must not be the same string, and must not read as the same bare noun sitting twice in the viewport (e.g. label Password + placeholder Password, or label Email + placeholder Email). The eye sees a stutter, not a hint. Placeholder is an instruction or a soft example, never a second label:

• Prefer a verb lead-in: Enter password, Enter your email, Enter email or username.
• Or a worked example: name@company.com, e.g. acme-bot — never the field's own name alone.
• Same rule for the first step of a multi-step auth flow where there is no label and the placeholder is the only chrome: still write Enter your email, not Email / Username.
• Check all three locales — a language that glues verb+noun (输入密码) can accidentally make the page title and the placeholder identical too; differentiate (e.g. title 输入密码, placeholder 请输入密码, label 密码).

Lived fail (SaaS login, 2026-07): password step shipped label Password + placeholder Password; first step shipped placeholder Email. Fixed to Enter password / Enter your email / Enter email or username. Treat any new form field the same way before you ship.

Before you write any user-facing line, slow down and ask, repeatedly:

• The user already knows the page's icon and its name in the sidebar. So what do they actually not know yet?
• Why did they come to this page? What are they here to do?
• Does this line guide them — point a direction, reduce a decision — or does it just restate the title in more words?
• If I add this sentence, does it mean anything to the user? If I remove it, do they lose anything?

Then audit both directions: what guidance is missing (a user who lands here is lost), and what is redundant (a label that just narrates the obvious). Cut filler; keep direction. A page is not better for having more words on it.

Two repeat offenders that survive the cut above because each line alone looks fine — they only read wrong stacked together:

• Don't repeat the same word down the nesting ladder. A page title, a section title, and a row label are three rungs, and each must add information, not echo the rung above. A page titled Desktop Environment, a section titled Desktop, and a row labelled Desktop says the word three times and informs once. When a section holds a single control whose label already equals the section title, drop the section title — SettingsSection renders titleless — and let the row carry the name.
• Name the user's outcome, not the implementation under it. Copy is about what the user gets, never the stack that delivers it. "Give this bot a screen it can see and control" — not "Enable the VNC desktop; auto-provisions Debian/Ubuntu/Alpine." Terms like VNC, gstreamer, namespace, CDI, provision, or a raw base-image name are implementation trivia the user never asked for; they belong in a diagnostic Details surface at most, never in a headline, a toggle label, or its description. (This is also the no-foreign-product-name rule: the UI speaks the user's language, not the runtime's.)

Copy is trilingual — en, zh, AND ja — and that is a layout constraint, not just a translation chore. Every user-facing string goes through an i18n key with all three locales written (apps/web/src/i18n/locales/{en,zh,ja}.json) — no hardcoded text. The recurring failure is real and embarrassing: agents write en+zh and forget ja, or reference an existing key that was itself added without ja — the Japanese UI then renders the raw key string (bots.memory.lastUpdated) in production. A 2026-07 parity sweep found 14 such keys referenced by freshly-written templates. So the rule has two halves:

• Writing a new key: add it to all three files in the same edit, placeholders ({count}, {agent}) identical across locales. For Japanese, use natural phrasing but keep the product terms Japanese users read in English (Bot, Workspace, Skill, MCP…).
• Referencing an existing key: existence in en does NOT mean it exists in ja — grep the key in all three locale files before using it; if ja is missing, fill it as part of your change. Before finishing, verify every key your diff references resolves in all three locales. The two languages' shapes also constrain layout: Chinese is denser and wider per glyph, English runs longer, Japanese sits between but often longest with particles. A row that fits perfectly in English can wrap or overflow in Chinese (and vice versa), which silently breaks same-row height (§ 4) and narrow-screen reflow. So write and eyeball all locales, and design the layout to survive the longest of the three.

An error message follows a formula: what happened · why · how to fix. "Email needs an @ symbol" beats "Invalid input"; "We couldn't reach the server — check your connection and retry" beats "Something went wrong." Never blame the user ("This field is required", not "You entered nothing"), and never use humor in an error — they're already frustrated.

One concept, one word — terminology consistency is the copy-layer of consistency debt (§ The debt taxonomy). Pick a term and hold it product-wide: Delete (never also Remove / Trash), Settings (never also Preferences / Options), Create (never also Add / New). Synonyms-for- variety read as different features and quietly erode trust. And a button label names the outcome, not "OK / Submit / Yes" — Save changes, Create account, Delete 5 items (show the count).

2. Don't over-prompt (validation and beyond)

A required field that the user merely touched and moved away from should not flash red. On a page that is a single input plus a select, or a two-field sign-in, nagging "you didn't fill this in" is absurd — the user can see the two empty boxes. Validate at the moment it matters (submit), and surface the error usefully then.

Generalize this: the red-required box is just one instance. Restraint applies to all external component signals. Don't make a component shout a state the user did not ask about and does not benefit from.

2b. Focus follows the job — every step lands the caret where the user will type

This is not a layout rule and not "always autofocus the first field." It is a path rule: when the view changes because the user advanced (or went back) in a multi-step flow, put keyboard focus on the field they are about to fill — not on the button they just pressed, and not nowhere. Users expect to type immediately; making them click the field is a tax on a path they already committed to.

Concrete tells (login is the worked example; apply the path, not a page template):

• Advance into a new step whose job is to type something (e.g. identifier → password, "send code" → OTP): after the step mounts, focus() that step's primary input. HTML autofocus only fires on the first document load — it does not re-fire when a v-if / step swap mounts a new field. Use nextTick + programmatic focus() (or a shared helper) on the step transition itself.
• Back / Edit that returns to a prior field (e.g. "Edit" on a readonly email, or "Back" to the identifier step): focus that field again so the user can correct it without an extra click. Same for dialog list→form→list when the form's job is input.
• One caret, one job. Don't leave focus on Continue after it succeeded; don't focus a readonly display field when the next action is typing in a different control; don't steal focus mid-keystroke for ambient re-renders.
• Wrappers: if the control is a composed field (PasswordInput, InputGroup), put a stable id on the real <input> (or resolve it) before calling focus() — focusing the outer shell does nothing useful.
• Don't invent a global "focus manager." Wire focus at the transition site (onContinue, backToIdentifier, dialog open, view-swap enter) where the path is known. A page that has no step change needs no extra focus code beyond a sensible first-load autofocus.

Review check: after every step / drill-in / back path you ship, tab away and re-enter with the keyboard only — can the user type the next thing without clicking?

3. Empty and loading states must hold the frame

Before shipping an empty state, ask: can this page hold the void? If a bare centered "No data" line leaves the page looking broken or unbalanced, that is the wrong answer. Keep the card / list / table frame drawn, and put the message inside it ("No usage data for the selected period"). The structure should survive having no rows. (Anti-example: a page that drops to bare centered muted text. Good: a framed Empty, or a TableEmpty row inside the table that still draws.)

The loading state has the same duty, plus one more: the layout must not jump when data arrives. A skeleton should match the shape of the final content (Profile's skeleton is a card of rows the same size as the real rows), and every block that loads async should reserve its height up front (the reference pages set a min-h on each row "so a cold load doesn't make the block jump"). Never let a section pop in at a different size than its placeholder, and use — for a not-yet-sampled value rather than a faked 0.

"Hold the frame" is for a section that is always present — the page's primary content, a list that's core to why the page exists. A conditional, secondary section does the opposite: one that only exists to manage things when there are things to manage (an Active sessions list, an issue banner) vanishes entirely when empty rather than drawing an empty frame (this is the §9 / §13 "let the block disappear" move, not a contradiction of the rule above). The test: would a first-time user with nothing set up expect this block to be on the page at all? If it only makes sense once populated, hide it while empty; if it's part of the page's skeleton, keep its frame with the message inside.

4. Same-row controls share a height

Anything sitting on one visual line — a search box next to an "Add" button, a select next to an action — must be the same height. A short search field beside a tall button is a real bug we shipped before. Build the search with InputGroup and the action with Button at the matching size, then verify the heights actually line up.

A control-bearing row's height must not swing with its own interaction. The trap: a SettingsRow whose :description flips with the control's value — a mode SegmentedControl whose blurb changes per selection. SettingsRow sets a min-h floor, so a longer variant wraps to a second line and the whole row — control included — visibly jumps taller as the user toggles. That is content-driving-layout (§ Engineering correctness) fired by a click. The fix is almost always the copy, not the layout: keep such a per-value blurb short enough to hold one line so the height is stable — do not over-engineer it (splitting the blurb into its own row, or reserving a fixed two-line height, is usually worse than tightening the words). Scope note: this is about interaction-driven jumps, not every height difference. A genuinely sparse page whose row is simply taller because its static copy runs long is fine — let it grow; don't chase a uniform row height for its own sake.

5. No redundant or fighting controls

Two controls that solve the same job and contradict each other is a defect, not a feature. (Anti-example: a "Time Range" preset select and a "Custom Range" date picker coexisting with no defined relationship — picking one silently fights the other.) Either pick one model, or make their relationship explicit and visible.

6. Motion: never abused, always felt

• Press-scale only where it fits — buttons, sidebar rail items. Never on a large content card.
• Directional list ↔ detail uses useViewSwap + SwapTransition: forward = list slides out left while detail slides in from the right; back = the reverse. One view visibly gives way to the other — no "fade out, then fade in" double-jump.
• The motion duration palette is fixed (see packages/ui/AGENTS.md § Motion). Stay in it.
• The rule: don't overuse motion, but make every user action perceivable. A click that changes nothing visible feels broken even when it worked.
• A button that swaps the whole card's structure is a last resort, not a pattern. An "Add member" button that replaces the member list with a picker form (Cancel/Confirm and all) reflows the entire card on click — the frame the user was just reading vanishes. Prefer an inline control that commits in place — a select trigger in the header that adds on pick, a popover off the row — so the card's layout never changes. Caveat: the design system does not yet have a settled pattern for "inline add to a list", so until it does, treat the button→swap as an anti-pattern to avoid, not a template to copy. (The Bot Access members card moved off this swap to an inline header select; the old sw

Truncated - read the full file at https://github.com/felinics/ui/blob/72e92fe173fb94b43cdea8ec3a934965833e13df/skills/web/SKILL.md.