ui/

React 19, Tailwind v4, shadcn/ui and zustand, rendering state and invoking commands over src/bindings.ts. Domain logic and types live in Rust; nothing here decides.

• src/bindings.ts is generated by crates/app/tests/bindings.rs and never hand-edited; @tauri-apps is imported there and nowhere else (a tools/guard lane).
• A Result-returning command answers through the bindings' runtime as { status: "error" } for a refusal and a transport failure alike; a refusal is read through src/lib/refusal.ts, never off its fields. A refusal that is an ANSWER, not a failure, draws a neutral line naming the control that lifts it and no retry, since asking again answers the same: src/lib/package-read-state.ts judges that for the package page, src/lib/catalog-read-state.ts for every other surface drawing one.
• Every colour, space and radius is a design token; a raw hex, rgb or hsl literal under src/ fails a tools/guard lane. Light, dark and system only, no themes.
• Hue carries one meaning, which harness (--harness-*); status keeps the semantic tokens and item kinds are told apart by icon. --customized marks where a package is changed, on the package page's header and the Customize surfaces; the Library list carries no customization mark, legend or colour.
• Four type steps and no fifth: page title (24 semibold), section title (15 semibold), row label (14 medium), description (13 muted). src/components/page-header.tsx owns the first, src/components/section.tsx the rest. Not mechanically enforced.
• Space groups things and boxes are for objects: a settings or detail surface is Section plus SettingRow, never a stack of cards; a Card is a discrete thing a person acts on as a unit; nesting stops at the card.
• A border means actionable: buttons and inputs carry one, chips and badges are a quiet fill. --muted-foreground is never dimmed further with an opacity suffix.
• Three surface planes back to front, sidebar, page, card; every page draws width and gutters from src/lib/layout.ts, a reading measure or full width for a data-dense table.
• One search box per page that lists things; / focuses the one on screen or goes to the Library from a page with none. Location filtering belongs to the Library's Installed tab; every other page and tab shows every scope.
• A section with nothing in it is not rendered; an empty state appears only when the page would otherwise be blank and its read is done. A failed read shows its error with a retry, kept figures headed as the last kendex could check, never a definite count. Enforced by src/components/account-section.dom.test.tsx.
• One model, stated in src/lib/copy-model.ts and nowhere else: a place is the personal setup or a project, packages are installed into a place, a package names the marketplace it came from and the places it is in, and what a place does with a marketplace is settled on that place's card — never as a control beside the marketplace.
• The guided install, the browse context, registering a project and the questions a write leaves behind are GUIDED-INSTALL.md, templates included.
• Package summaries come from src/lib/package-identity.ts::summaryIndex for observed copies and recordedSummaryIndex for records. useRecordedSummaryIndex takes the page's scope for a missing copy. Other shared selectors are in GUIDED-INSTALL.md § Shared selectors.
• A marketplace is titled by the name its catalogue declares, then by the directory's label for a repository nobody subscribes to, then by the folder or repository it resolves to; a folder says Local folder beside its resolved path. The source alias is a per-place manifest key: it belongs in source details, never in a title, and . never stands as one.
• A page under useCatalog reads the display it returns and resolves no title of its own, passing it to whatever it draws. Its own doc comment says why that hook holds both halves of a Community conversion.
• A card standing for something openable is the open action: the whole card opens it through src/lib/click-asks-to-open.ts, its name keeps a button of its own so the keyboard reaches it, and no Open button stands beside them. Name, then description, then meta in a quieter step.
• A fact a card states stays on screen even where it is also a link: a grid of cards is read by scanning, a count behind hover is a count nobody compares, and a pointer is not the only way in. A secondary action on the thing the card names — bookmark it, remove it — is separately focusable, never activates the card, and appears on hover or focus.
• Standing reads refresh through src/lib/rescan.ts; no reader decides for itself when an install might have happened.
• A row, card or chip that names a thing opens that thing: a package name opens its page, a safety score opens that page's Safety tab at the place whose copy the reading is of, a place opens the place, a marketplace opens the marketplace, a harness chip opens the harness. Secondary actions stay buttons, and no Open button repeats what the container already does — the one exception is a row whose own action is gone, where the button is the only route left and names where it goes. Every such surface takes src/lib/opens-on-activate.ts::opensOnActivate, which puts the open on the pointer and on Enter, names the extra focus stop, and keeps the name a real control; src/lib/click-asks-to-open.ts stays the one predicate under it. The surface takes no widget role: role="button" around real buttons is invalid, and on a row it would replace the row semantics a screen reader navigates by.
• A harness is a harness on screen, never a tool; in a table it is its mark, name on hover and for screen readers.