=================================================================== --- a/DESIGN.md +++ b/DESIGN.md @@ -1,38 +1,67 @@ # Visual Design Contract -Chat is a quiet, full-canvas conversation workbench. AgentKit owns the -conversation primitives; the template owns the surrounding navigation and -workspace chrome. +`AGENTS.md` is the canonical statement of the blank-canvas rule — check +`app/routes/_index.tsx` and `app/global.css`, preserve any real UI/brand +already there, and only treat the canvas as blank when those files still show +the starter's placeholder. This file does not restate that rule; it records +**this app's** visual direction. The fields below are the source of truth for +that direction: once filled in, read and preserve them on every build; while +they are still empty, the first substantial UI pass fills them in. -## Product mode +## Non-negotiable: impress by default -- Mode: `operate` -- Audience and cadence: frequent users managing many ongoing agent threads. -- Primary workflow: begin, resume, pin, and organize conversations without - leaving the chat canvas. +When this app is still a blank canvas, every app generated from this template +must look **spectacular on first load**, even when the build prompt gives no +design direction. "Looks like a clean, intentional product" is the floor, not +the goal. When no direction is supplied, you still commit to one — do not +default to safe gray SaaS: -## Visual direction +- Commit to one concrete visual world (see the `frontend-design` skill and its + `references/visual-direction.md`). Do not ship the neutral placeholder theme. +- Choose a product-fitting accent family and set it in the `app/global.css` + tokens for **both** light and dark. Never leave the 0%-saturation default as + the shipped palette. +- Establish a clear type hierarchy, a consistent spacing rhythm, and one + signature detail (a considered empty state, a distinctive header, a crafted + primary action) that makes the surface feel designed for its domain. +- Get focus, hover, empty, loading, and dark-mode states right — that polish is + the difference between an AI demo and a product. -- Direction name: Quiet conversation library -- Palette family: neutral ink and semantic surfaces; active rows use the - existing sidebar accent rather than a separate branded color. -- Type treatment: dense sans-serif labels with regular-weight conversation - titles and restrained section labels. -- Composition: a persistent conversation library beside a generous chat - canvas. New chat is the primary rail action, followed by Pinned and Recents. - Account, workspace, settings, and sign-out controls disclose from one footer - row instead of competing in the rail. -- Shape language: borderless lists, soft selected rows, quiet corners, and - compact icon controls. -- Anti-references: icon-only navigation as the default state, floating chips, - duplicated settings links, timestamps competing with thread titles, and - placeholder destinations that the app does not implement. +Pick a direction and execute it fully; never average toward generic SaaS. Once +a direction is established and recorded below, preserve and extend it rather +than starting over unless otherwise directed to. +## Fill in before building the first surface + +Once the fields below are filled in, they describe this app's established +visual direction — read and preserve them on every subsequent build; do not +re-derive a new direction. The first UI pass must fill these fields in as +part of that build, not leave them as an empty template. + +- Product mode: `operate` | `read` | `persuade` | `experience` +- Audience and cadence: +- Visual world (name + the feeling it creates): +- Palette family + neutral undertone: +- Type treatment: +- Composition: +- Shape language: +- Anti-references (defaults this app must not drift toward): + +## Agent-Native is structural, not visual + +This shell already meets the Agent-Native contract: data in SQL, actions as the +single source of truth, application state for navigation/selection, and +real-time sync. **Chat and the agent rail are opt-in, not default.** Build the +product UI first. Add an `AgentSidebar`, a full-page chat route, or +`sendToAgentChat` handoffs only when the user asks for agent interaction — and +when you do, follow `agent-native-toolkit` and `frontend-design` → Agent +Surface And Page Boundaries so the surfaces are wired correctly. + ## Guardrails -- Preserve the scaffold's semantic tokens and shared component seams. -- Keep domain pages distinct from full-page chat and use the AgentSidebar for - contextual AI. -- Compare sibling apps before reusing their palette or composition. -- Keep pinning, rename, archive, and routing wired to the shared chat thread - model; the sidebar is a presentation layer, not a second history store. +- Keep semantic token names and shared component seams intact; express the + direction through token _values_, type, spacing, and composition — not by + forking the design system. +- Density comes from data, not prose. Subtract explanatory chrome; never + subtract the visual craft that makes the app impressive. +- Compare against real products in the chosen mode, not against the starter.