myco-ui-development-and-visual-identity

name	myco:ui-development-and-visual-identity
description	Procedures for building, maintaining, and extending Myco's React daemon UI: the v7 component-composition system (AccentSurface/Panel primitives, page-wide selection state, master-detail and slideout layouts), the Grove-owned appearance system (6 themes, light/dark/system mode, three-role fonts, density), project-scoped request context, auth-gated attachments, and the Team Host degraded-presentation family for attached (hosted) projects. Use when building or troubleshooting UI components, extending the theme/appearance system, wiring project-scoped data, or presenting attached-project degradation, even if the user doesn't explicitly ask for UI development guidance.
managed_by	myco
user-invocable	true
allowed-tools	Read, Edit, Write, Bash, Grep, Glob

UI Development and Visual Identity System

The daemon UI lives in packages/myco/ui/ (Vite + React + Tailwind, react-router). It is built on the v7 "Tactile Research" design system: a 6-theme appearance model and a small set of composition primitives under packages/myco/ui/src/components/ui/. Build new surfaces by composing those primitives — do not reinvent card chrome, loading gates, or layout shells.

Prerequisites

• A running daemon (the UI reads/writes through its HTTP API).
• Node.js with npm workspaces; the UI is its own workspace under packages/myco/ui.
• Familiarity with packages/myco/ui/src/components/ui/ (primitives) and packages/myco/ui/src/hooks/ (data hooks over usePowerQuery).

Procedure A: Component Composition (v7 primitives)

Every card/panel derives from AccentSurface (components/ui/accent-surface.tsx) — the v7 signature chrome (2px coloured top stripe, surface-container-low bg, outline-variant border, 12px radius). Its accent is sage | ochre | terra | outline. Panel (components/ui/panel.tsx) wraps AccentSurface with a standard eyebrow/title/actions/footer header and a tone (sage | ochre | terra).

Other primitives in components/ui/: Surface, PageContainer, PageHeader, SectionHeader, Eyebrow/IconEyebrow, DefRow, Badge, StatCard/MetricCard, SlideoutDetailPanel, MasterDetailSplit, Pagination, PageLoading, and the status pills (daemon-status-pill, cortex-status-pill, git-identity-pill).

Gate loading/error with PageLoading (components/ui/page-loading.tsx): <PageLoading isLoading={...} error={...}>{children}</PageLoading> renders a spinner, a "Failed to connect to daemon" state, or the children — never hand-roll these three states.

Exemplary compositions (copy these, verify before citing)

• components/grove/DaemonStatusCard.tsx — the minimal card recipe: Panel tone="sage" + IconEyebrow + a <dl> of DefRows + a Badge. Read this first when building any status/summary card.
• pages/MachineDashboard.tsx — page assembly: a PageContainer + PageHeader stacking self-contained cards (Surface level="low", a local Stat sub-component, dl grids). Cards own their own data hook (useDaemon) and their own loading fallback.
• pages/Logs.tsx — page-wide selection state precedent: a single selectedEntry state drives both the row highlight (selectedId passed into the table) and a SlideoutDetailPanel; re-clicking the selected row toggles it closed. It also hydrates initial filter/selection state from URL query params (new URLSearchParams(window.location.search)) for deep links. Follow this shape for any list-plus-detail page: one selection state at the page, passed down as selectedId + onSelect.

New component recipe

1. Compose from AccentSurface/Panel and the existing primitives; match an exemplar above rather than inventing chrome.
2. Read data through a hook in components/ui/hooks/ built on usePowerQuery; gate rendering with PageLoading (or a card-local if (!data) fallback).
3. Use theme tokens (text-on-surface, text-on-surface-variant, bg-surface-*, border-outline-variant, text-sage/text-ochre) — never hard-coded hex.
4. Keep selection/detail state at the page and pass selectedId/onSelect down.

Procedure B: Project-Scoped Data and Selection

Pages that need a project context use the durable selection model in packages/myco/ui/src/hooks/use-project-selection.tsx:

• useProjectSelection() / useActiveProjectSelection() — read the active ProjectSelection | null from context/durable store.
• ProjectSelectionBoundary — sets the selection for its subtree. Its persist prop (default true) controls whether entering the boundary writes the durable last-known project. Pass persist={false} for read-only route params (redirect targets, machine-scoped pages viewing a specific project) so a non-user-facing navigation never clobbers the user's intentional pick.
• GlobalSelectionBoundary — wraps machine-scoped pages; deliberately sends no project context headers so they operate machine-wide.
• requestContextHeadersFromSelection() (lib/selection.ts, called by lib/api.ts on every request) injects x-myco-grove-id / x-myco-project-id from the active selection. This is the sole request-scoping mechanism — never suppress it.
• OperationsScopePill (components/operations/) — the scope affordance for headers of pages where scope is user-selectable.

Project switcher — components/ProjectSwitcher.tsx is the real switcher. It reads useProjectSelection(), useGroves(), and useProjectsActivity(), sorts projects by recent activity, and navigates via the lib/selection.ts path helpers (projectPath, projectRouteSuffix, selectionFromLast) — it does not read route params directly. Reuse those helpers rather than string-building routes.

Two bug patterns to avoid:

1. Reading route params instead of the durable selection — the page renders the route's project while the durable selection (and therefore the request headers) holds a different one. Fix: read useActiveProjectSelection() and let the boundary wire the selection.
2. A non-user navigation firing persist={true} — a redirect/background route entry overwrites the user's durable project. Fix: persist={false} on any boundary not driven by an explicit user project-pick.

Procedure C: Auth-Gated Attachments

Attachment bytes come from a bearer-gated daemon route (/api/g/:groveId/p/:projectId/attachments/:file). A bare <img src> cannot send the x-myco-auth header, so always use components/ui/attachment-image.tsx:

import { AttachmentImage, useAttachmentObjectUrls } from '../ui/attachment-image';

<AttachmentImage filePath={attachment.file_path} alt="attachment" />
const urls = useAttachmentObjectUrls(attachments.map(a => a.file_path)); // lightbox/raw

AttachmentImage fetches with the token and renders a blob object URL, resolving the (Grove, project) scope from the active selection. Never render <img src={attachment.file_path}> — it silently renders a broken image or an auth-error body as binary garbage.

Procedure D: Appearance and Theme System

Appearance is Grove-owned config (not a local file): the AppearanceProvider (providers/appearance.tsx) reads it via useScopedConfig and applies it with applyAppearance from lib/appearance-apply.ts. Four axes, whose enum values are the single source of truth in packages/myco/src/config/appearance-values.ts:

• theme — sage | moss | terracotta | dusk | plum | slate (6 themes).
• mode — light | dark | system (toggles the .light class on <html>).
• font — default | geist-mono | system | sf-mono | fira-code | jetbrains-mono, each a three-role stack applied as --font-heading / --font-ui / --font-data (the default stack is the three-font system: Newsreader / Inter / JetBrains Mono).
• density — compact | normal | comfy, scaling --density and root font-size.

Each theme is a CSS file in packages/myco/ui/src/themes/ defining custom properties under :root[data-theme="<name>"] (dark) and :root[data-theme="<name>"].light (light) — --primary, --on-primary, --secondary, --tertiary, etc. Shared accents live in themes/_shared-accents.css.

Adding a theme:

1. Create packages/myco/ui/src/themes/<name>.css with both the base and .light blocks (mirror themes/sage.css).
2. Add <name> to APPEARANCE_THEMES in packages/myco/src/config/appearance-values.ts.
3. Import the CSS in packages/myco/ui/src/index.css.
4. Add a public/favicon-<name>.svg — applyAppearance swaps the favicon per theme.

Procedure E: Master-Detail and Slideout Layouts

MasterDetailSplit (components/ui/master-detail-split.tsx) is a responsive shell, not a spacing knob. Real props: master, detail, hasSelection, optional onCloseMobileDetail, railMinWidthPx/railMaxWidthPx, and the masterAriaLabel/detailAriaLabel landmarks. On desktop it renders a fixed-width rail plus a flex detail pane; on mobile it swaps to a single pane with a Back button. The detail pane owns its gutter (p-6) so every consumer renders flush to the divider — leaf pages must not add their own outer padding.

For a list page where the detail is an overlay rather than a side-by-side pane, use SlideoutDetailPanel driven by a page-level selection state — see pages/Logs.tsx (Procedure A).

Procedure F: Team Host Degraded Presentation (attached/hosted projects)

When a project is attached (served by a Team Host), some daemon routes refuse locally-scoped work. There are exactly two refusal flavors, both classified once in packages/myco/ui/src/lib/degrade.ts — never re-derive a check against ApiError.body in a hook or component.

1. Capability degraded (409) → uniform "unavailable" surface. A degrade-stamped route (git status, Canopy, release provenance, backup/embedding mutations, Grove lifecycle) 409s with { error: 'capability_unavailable_hosted', capability, message }. Detect with hostedDegradedInfo(err); render HostedUnavailable (components/ui/hosted-unavailable.tsx), whose variant is panel (replaces a whole section body) or inline (fits inside an existing card/row). The copy comes from hostedUnavailableMessage(info) — never render the server message verbatim.

2. Attached tenancy pending (404/500) → behave-like-local empty. Before an attached project's first forwarded capture registers it host-side, serve-stamped knowledge reads 404 with { error: 'unknown_tenancy' } (and a residual carve can 500 with attached_config_failed). Detect with isAttachedTenancyPending(err, selection) and map the query to its existing empty shape with resolveAttachedEmpty(result, selection, empty) — the same zero-state a brand-new local project renders. Empty means empty: reuse the hook's own zero object/list (see the EMPTY_DATABASE_DETAILS pattern in hooks/use-database-details.ts), never a bespoke "hosted" placeholder.

Exactly-two-knob suppression rule. On the classified refusal, set only two React Query knobs — retry: false and refetchInterval: false — and only for that refusal (keyed off the same detector). Never touch refetchOnWindowFocus / refetchOnMount / retryOnMount: those are the recovery path. Once registration lands, a page reload or re-selection re-mounts the query and it repopulates. Reference implementations:

• hooks/use-git-identity.ts — the 409 pattern: refetchInterval: (q) => hostedDegradedInfo(q.state.error) ? false : POLL... and retry: (n, err) => hostedDegradedInfo(err) ? false : n < 3.
• hooks/use-database-details.ts — the tenancy pattern: the same two knobs keyed on isAttachedTenancyPending, wrapped in resolveAttachedEmpty.

Classifier precision is load-bearing. Real outages must keep real error presentation: a host outage (host_unreachable 503, host_auth_rejected 502), any relay 5xx, a network error that never became an ApiError, any other 404, and every refusal on a non-attached project all classify as false. Do not widen the detectors to "any 409" or "any 404" — that silently hides genuine failures behind a fake empty page.

Membership copy vocabulary (lib/membership-copy.ts; the copy doctrine is recorded as a Myco decision spore — search "UI copy user vocabulary" to retrieve it): map known failure codes to user-outcome sentences that reference the UI's own affordances ("its host card has a Detach control"), not the daemon's CLI-voiced message or raw error codes. Host-facing surfaces carry zero "grove" strings — the only permitted use is the member's own local Grove picker (LOCAL_GROVE_PICKER_LABEL = "Show under"). Proactive suppression that keys on the attached selection directly (not an error response) gets its own plain line — e.g. BACKUPS_HOSTED_LIST_NOTICE, which replaces the localhost-only backups list so it never shows the member's local backups as if they were the team project's.

Provenance for the above (verify against source, not this list): the classifier and shared empty mapper landed in T4a (0cec8e1b); the attached knowledge-read hooks in T4bcd (b1949b43); the Operations/Canopy/provenance HostedUnavailable wiring in T5a–d (3df07097, e30785f6, d9ee7493, e3c59411).

Cross-Cutting Gotchas

Appearance paints from a pre-bootstrap cache

applyCachedAppearance() (lib/appearance-apply.ts) replays the last-applied values from localStorage['myco-appearance'] synchronously in main.tsx before React mounts, so the chosen theme paints on the first frame. When developing themes, browsers cache CSS aggressively — hard refresh (Cmd+Shift+R).

UI workspace install in worktrees

Each git worktree needs its own npm install in packages/myco/ui (and the UI build must run before dogfooding a worktree daemon). Follow the dogfood-worktree skill rather than a bespoke setup script — the worktree's runtime does not travel with git worktree add.

Layout primitives own spacing

MasterDetailSplit's detail pane and Panel's body own their gutters. Leaf pages must not apply conflicting outer margin/padding — it double-pads or breaks the flush-to-divider alignment.

Request context headers are x-myco-*-id

Grove/project scoping rides on x-myco-grove-id / x-myco-project-id, injected by requestContextHeadersFromSelection() in lib/api.ts — not slug headers. A page that bypasses the selection model (or a machine-scoped page that forgets GlobalSelectionBoundary) leaks or omits the wrong scope.

Navigate via react-router, not window.location

Use useNavigate/useLocation/useSearchParams for navigation and URL state so MemoryRouter (tests, embedded contexts) works. Reading window.location.search once for initial deep-link hydration (as pages/Logs.tsx does) is fine; driving navigation off window.location is not.

Attachment routes are auth-gated

Never render attachment images with a bare <img src> — use AttachmentImage (Procedure C). The route requires x-myco-auth, which an <img> can't send.

Durable selection vs route selection

Route params change every navigation; the durable selection persists until the user picks a new project. Machine-scoped pages wrap with GlobalSelectionBoundary (no project headers); a specific-project view that must not overwrite the user's pick uses ProjectSelectionBoundary persist={false}.

UI embed build order is strictly sequential

build:ui must run before codegen, which must run before build:binary (packages/myco/package.json: build:ui && codegen && … && build:binary). The codegen step runs packages/myco/scripts/gen-ui-assets.ts, which reads the Vite-compiled output and generates packages/myco/src/ui-assets.generated.ts — the file that embeds the React bundle into the binary. If codegen runs before the Vite build, it emits a stale/empty asset map and silently ships a binary with no UI. Always run the full npm run build.