Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The public web must show the artifact before explaining the product. Real Sessio

### Public web

- **Header:** Compact and persistent on marketing and reading surfaces. The grouping rule is strict: the left side answers "where can I go" (Wordmark home + at most `Sessions` and `Docs`), the right side keeps exactly one primary action (`Publish`) plus one identity affordance (`Sign in` when signed out; the avatar menu when signed in). Search never appears in the header — it belongs inside the Sessions feed. `Blog` lives in the footer. Theme, `My Sessions`, `Teams`, account, and sign-out live inside the avatar menu, never as parallel header icons. On mobile, every retained action uses a 44px target.
- **Header:** Compact and persistent on marketing and reading surfaces. The grouping rule is strict: the left side answers "where can I go" (Wordmark home + at most `Sessions` and `Docs`), the right side keeps exactly one primary action (`Publish`), one compact Session-language preference, plus one identity affordance (`Sign in` when signed out; the avatar menu when signed in). Search never appears in the header — it belongs inside the Sessions feed. `Blog` lives in the footer. Theme, `My Sessions`, `Teams`, account, and sign-out live inside the avatar menu, never as parallel header icons. On mobile, the Session-language preference moves into the navigation disclosure and every retained action uses a 44px target.
- **Avatar menu:** The avatar opens a popover menu (`Account`, `My Sessions`, `Teams` — or the contextual `Team · {name}` shortcut — a theme toggle, and `Sign out`). It is navigation only; authorization still comes from the server.
- **Homepage:** Featured-first editorial layout for visitors and crawlers. Signed-in visitors who open `/` stay on the real homepage; `/sessions` remains their explicit workspace, and the wordmark never triggers a delayed auth redirect. The hero pairs a concise promise with one real featured Session—never a screenshot of the desktop app. Primary CTA is `Explore Sessions` (linking to `/sessions`); secondary CTA is `Share Yours`. Both are prominent 48px controls without directional-arrow decoration. Search stays compact until the public corpus is large enough to make search-first discovery useful.
- **Homepage feed:** Public Sessions appear immediately after the hero. Use information-rich rows or cards with author, agent, topic/project, Summary excerpt, evidence, and continuation state. Avoid equal-weight feature tiles.
Expand Down Expand Up @@ -62,7 +62,7 @@ Border radius remains restrained: 10px for cards, 8px for inputs, 6px for rows a

### Responsive shell contract

- **Phone (`320–640px`):** Product and marketing headers show the Wordmark, the current account action (`Sign in` or avatar), and one 44px navigation disclosure. `Sessions`, `Docs`, `Publish`, theme, and — signed in — `My Sessions` and `Teams` remain available inside that disclosure; do not compress the complete desktop header into one row.
- **Phone (`320–640px`):** Product and marketing headers show the Wordmark, the current account action (`Sign in` or avatar), and one 44px navigation disclosure. `Sessions`, `Docs`, `Publish`, Session language, theme, and — signed in — `My Sessions` and `Teams` remain available inside that disclosure; do not compress the complete desktop header into one row.
- **Compact (`641–768px`):** The same disclosure remains available so touch targets do not compete for width. Page content may use two columns only when each control still has its intended minimum width.
- **Desktop (`769px+`):** The full persistent navigation is visible. Marketing and Team shells remain capped near 1120px; account forms keep their narrower reading width.
- **Overflow invariant:** At 320, 451, 768, and 1024px, `scrollWidth` must not exceed the viewport. Long Team names, emails, badges, and action labels wrap, truncate, or move below identity instead of widening an ancestor.
Expand Down Expand Up @@ -256,6 +256,7 @@ Semantic colors are tuned for contrast against the void palette — never use Ta
- **Primary continuation action:** one accent `Resume in [agent]` button that opens a clone-style popup (GitHub `Code` button pattern). The popup offers one command per situation — `Spool CLI installed` (`spool resume <sid>`) as the default tab, and `First time — install Spool` (install script + resume) one tab away — each with its own copy action. Never force the curl bootstrap inline on the page. Explain that resuming creates new work and leaves the source unchanged.
- **Stars and published forks:** Public Sessions expose a GitHub-style `Star` control and counts beside Resume. Stars require a signed-in viewer and are removed when the target leaves Public visibility. `Forks` is not a second write path: it counts direct descendants created through `spool resume`, verified by the server with the single-use Resume grant, that were later published and remain Public. A client-declared lineage may support legacy display, but never increments the public fork count; Team and Link-only descendants do not affect it either. These signals do not alter `Top` ranking in the first release.
- **Session titles and Summaries:** the reading surface prefers the summary-derived task title (what the Session accomplished), falling back to the first-prompt-derived label only for legacy Sessions. Titles are stored bilingually (`title` English, `title_zh` Simplified Chinese, ≤96 chars) and new Summary documents carry complete English and Simplified Chinese Markdown bodies. One locale snapshot selects title and Summary together. Each Summary must orient an unfamiliar technical reader with background, motivation, the concrete problem, work performed, validation, and outcome before project-local detail; it must not assume the reader already knows the conversation.
- **Session language:** A reader can switch explicitly between English and Simplified Chinese from the persistent shell. The preference is available signed in or out, persists on the device, and applies atomically to Session titles, Summary bodies, and feed excerpts. It does not imply that product chrome has been fully translated.
- **Token cost:** when recorded usage exists, show the estimated API cost as quiet mono metadata (`$1.87 · 2.4M tokens`) beside publication facts — evidence, not a vanity metric. Costs are computed at publish time from a vendored model-pricing snapshot (LiteLLM-style, refreshed by editing the file); the read path never fetches pricing.
- **Link-only Session:** Same reader, but label it `Link-only` and exclude discovery navigation that implies public listing.
- **Withdrawn:** Keep a stable unavailable page with no leaked title, Summary, author, or content.
Expand Down Expand Up @@ -479,5 +480,6 @@ In dense lists, prefer compact facts over repeated pronouns:
| 2026-07-25 | Feed evidence favors cost and Stars | Session feed rows retain messages, tools, diffstat, and provider evidence, but replace the low-value touched-file count with the immutable token-cost estimate and live Public Star count. File counts remain available in detailed evidence and ranking data. |
| 2026-07-25 | Summaries are bilingual and context-first | A new Summary carries complete English and Simplified Chinese bodies beside bilingual task-outcome titles; locale selects both atomically. Each body first explains the system, motivation, and reader-relevant problem, then implementation, validation, and result. Legacy single-language bodies remain readable. |
| 2026-07-25 | Human guidance is a sparse reading projection | Human prompts can be read without downloading the full raw Session. Provider-aware immutable guidance metadata counts call-side tools and visible reply characters, while prompt/reply records are fetched sparsely and agent prose opens on demand in an accessible modal. |
| 2026-07-25 | Session language is an explicit reader choice | Browser locale remains the first-visit default, but readers can switch English and Simplified Chinese from the persistent shell. The device preference controls bilingual titles, Summaries, and feed excerpts together; it is available signed in or out and does not claim full product-chrome localization. |
| 2026-07-18 | Geist Sans for chrome; Geist Mono for records | The font split distinguishes product interface from authentic Session content, commands, paths, and URLs. |
| 2026-07-18 | Icons follow adjacent-role sizing | Local consistency within a row or toolbar matters more than a rigid global icon whitelist. |
Loading