UI Taxonomy

CareerVector's shared frontend components live in three lib/ packages, split by audience and quality bar. The split keeps product polish out of admin surfaces (where the cost would be unjustified) and keeps admin-grade shortcuts out of product surfaces (where they would be visible to end users).

The three tiers

Why the bars differ. ui-kit is consumed by literally every surface, so any glitch shows up everywhere — it must be 100%. ui-product is the surface paying customers see — also 100%, but the constraint relaxes on the mobile axis because the product is desktop-first today. admin-ui is internal (operators, QA engineers, AI agents reading the wiki); shipping a "good enough" component there is the right trade because the time we save funds product polish.

Tier 1: ui-kit (general)

• Audience: everyone — product, admin, status, wiki, ops, qa.
• Bar: 100% mint quality. No edge-case shortcuts, full accessibility, both viewports.
• Mobile: yes. Components must work on mobile AND desktop.
• Package: @cv/ui-kit.
• Structure: subdivided into shells/ (composed chrome — HeaderBar) and primitives/ (atomic UI — buttons, dropdowns, icons, modals). primitives/ exists as a reserved slot today (no entries yet).

What lives here today

Import patterns

Direct deep imports — no barrel re-exports:

import HeaderBar from '@cv/ui-kit/shells/HeaderBar.svelte';

The package exports map enforces this:

"exports": {
    ".": "./src/index.ts",
    "./shells/*": "./src/shells/*",
    "./primitives/*": "./src/primitives/*"
}

./src/index.ts is intentionally export {} to keep tree-shaking friendly and avoid the Svelte compiler's "barrel imports drag in everything" footgun. Use the root import only for shared TypeScript types.

Tier 2: ui-product (CV + JobCache shared)

• Audience: CareerVector and JobCache product users.
• Bar: 100% on desktop. Mobile is not a requirement — the products are desktop-first today.
• Package: @cv/ui-product.
• Structure: shells/ only (deep imports same as ui-kit).

What lives here today

The snippet-slot pattern

SubHeaderBar accepts three named Svelte 5 snippet slots, rendered in row order:

<script lang="ts">
    let {
        leadingSlot,
        identitySlot,
        actionsSlot
    }: {
        leadingSlot?: Snippet;
        identitySlot: Snippet;
        actionsSlot?: Snippet;
    } = $props();
</script>

<div class="flex items-center gap-2 mb-4">
    {#if leadingSlot}{@render leadingSlot()}{/if}
    {@render identitySlot()}
    {#if actionsSlot}{@render actionsSlot()}{/if}
</div>

Render order: leading → identity → actions, separated by gap-2, vertically centered, with mb-4 bottom spacing.

Why snippets vs <slot />. Svelte 5's Snippet props are the idiomatic replacement for the legacy slot API. They type-check at the call site, support default values, and let the parent pass props into the rendered content. Named slots via let:-style scoped slots are not the right tool for a fixed, ordered row of named regions — snippet props express the contract directly in TypeScript.

Wrapper invariant: the shell owns the row layout. Consumers never style the wrapping div. Products own their own icon-button visuals so the row can host both CareerVector and JobCache chrome without coupling the shell to either.

Tier 3: admin-ui (wiki, ops, qa)

• Audience: wiki / ops / qa / status surfaces. Developer- and AI-facing (operators, QA engineers, internal investigation flows, AI agents reading the wiki).
• Bar: 80% acceptable. Functional, consistent, but does not need product-grade polish.
• Mobile: yes — operators check ops dashboards from phones.
• Package: @cv/admin-ui.
• Structure: components/, plus the admin-links.ts link-set helper and theme.css.

What lives here today

How to decide which tier a new component belongs to

1. Who uses it?

   • Used by every perspective (product + admin) → ui-kit.
   • Used by CV and JobCache product surfaces only → ui-product.
   • Used by wiki, ops, qa, or status only → admin-ui.

2. What's the cost of dropping a tier?

   • If you'd lose meaningful polish for product users by leaving it in admin-ui, kick it up.
   • If you'd be paying for polish nobody sees by leaving it in ui-kit, demote it.

3. Litmus test: "If it lands somewhere that's not 100% but it touches a user, kick it up." A component an end user sees cannot live below 100%.

4. One-tier rule: if a component is only used by one tier today, don't preemptively place it in ui-kit. Promote later when a second tier actually consumes it.

Workspace consumer pattern

ui/src/lib/components/workspace/ composes ui-product's SubHeaderBar into the live workspace surface. The shell is in ui-product; the snippet contents are CV-specific and live in the consuming app.

The compose site is ui/src/routes/[wsId]/+layout.svelte. Stripped down:

<SubHeaderBar>
    {#snippet leadingSlot()}
        <DownloadDesktopButton />
    {/snippet}
    {#snippet identitySlot()}
        <WorkspaceIdentityEditor
            {workspace}
            {displayName}
            bind:nameElement={nameEl}
            onSave={saveWorkspaceField}
        />
    {/snippet}
    {#snippet actionsSlot()}
        <WorkspaceActionButtons
            {workspace}
            onRequestDelete={() => { ... }}
        />
        <ScrapingPill />
    {/snippet}
</SubHeaderBar>

The read-only mirror layout (ui/src/routes/view/[wsId]/+layout.svelte) uses the same SubHeaderBar with WorkspaceIdentityReadOnly in identitySlot and omits actionsSlot entirely.

The workspace snippet components

The runtime-capabilities bridge

ui/src/lib/runtime-capabilities.ts is the Tauri IPC bridge. It exposes isTauri(), getAppVersion(), getCapabilityReport(), getWorkspaceBindings(), and observeUrl(). In a plain browser tab every function returns null (or false for isTauri) so callers branch without crashing. ScrapingPill consumes this bridge to gate its entire render — when isTauri() returns false the component emits no DOM at all, so the desktop-only feature is invisible on the web.

What goes where (catalog)

Don'ts

• Don't import ui-product from admin-ui. Cross-tier upward import — admin-ui's 80% bar can't pay for product-grade polish, and the dependency direction would force ui-product changes to ripple into every admin surface.
• Don't import admin-ui from ui-product. Different audience. Admin-grade visuals would leak into the CV/JobCache surface that end users see.
• Don't put a component in ui-kit if only one tier uses it. Promote later, when a second tier actually consumes it. Premature promotion taxes everyone with maintenance cost for no consumer benefit.
• Don't ship product code at admin-ui quality. The 80% bar exists because operators tolerate rough edges that end users do not. Ui-product is 100% — port admin shortcuts up only by reworking them to the product bar.
• Don't add a barrel export * to lib/ui-kit/src/index.ts or lib/ui-product/src/index.ts. Deep imports (@cv/ui-kit/shells/HeaderBar.svelte) keep tree-shaking healthy. The root index files stay export {} for shared types only.
• Don't style SubHeaderBar's wrapper from a consumer. The shell owns flex items-center gap-2 mb-4. Products supply only the slot contents.