Skip to content

.design-context.md

Latest commit

 

History

History
105 lines (85 loc) · 5.24 KB

.design-context.md

File metadata and controls

105 lines (85 loc) · 5.24 KB
Raw

Design Context

This file is the front door for all design decisions across maximal's UI surfaces (Tauri windows and proxy-served HTML pages). It is consulted by the design-* skills (design-frontend, design-onboard, design-critique, design-check, etc.) and by any agent or human building UI for this project.

This file is intentionally short. It exists to (a) lock the non-negotiables, (b) flag the things that keep regressing, and (c) point at the topic file with the detail you need. Always read the linked topic file before acting in its area.

Who maximal is for

A local proxy between developer tooling (Claude Code, Anthropic SDK, OpenAI SDK, opencode, custom scripts) and the GitHub Copilot API. Two access modes converge on the same files and behavior:

  • CLI users — comfortable in the terminal, prefer keyboard, expect machine-readable output. maximal auth, maximal start, maximal debug --json are their primary surface.
  • Menu-bar app users — same audience, different moment. Run maximal as a set-and-forget background utility, with a tray icon and occasional "what's it doing" peeks. The GUI exists for the moments where typing is the wrong tool (first-run auth, occasional usage check, settings tweak).

Neither audience needs the other's affordances; both should feel like the tool was built for them.

Brand in one paragraph

Warm + crafted + considered. Made by a person, not a corporation. Friendly without being playful-cute; confident without being terminal-stark. Restraint over decoration: layout, type, and spacing carry the feeling. Color is one surface, not the only surface. Full detail in docs/design/aesthetic.md.

The five principles (binding)

These override all other guidance when they conflict.

  1. Speak to the person, not the file.
  2. Power lives in depth, not density.
  3. Color is the user's, contrast is ours (warn at sub-AA, never block).
  4. One humanist accent per window.
  5. Reduced motion is a contract, not a hint (literal, not "with reduced intensity").

Full text + the locked decision log in docs/design/principles.md.

Failure modes — check these first

Patterns that keep regressing. If your work-in-progress matches any of these, stop and re-read the linked doc.

  • Page reads as a grid of similar rectangles → cards used as sectioning chrome.
  • Cards inside cards (forbidden).
  • Window has an in-content H1 duplicating the macOS titlebar text.
  • Brand crimson on a button / focus ring / link / active-nav.
  • Inline raw px / rem / #hex in a component or in a design doc (the one allowed exception is failure-modes.md's drift audit, where the conflict is the point).
  • Token edited in only one place (there are three sites — see windows).
  • :focus instead of :focus-visible.
  • Motion not respecting prefers-reduced-motion.
  • More than one Fraunces moment per window.

Full triage list (with known active drift) in docs/design/failure-modes.md. Read this before any non-trivial UI change.

When you're about to…

Do this Read this first
Anything UI — start here docs/design/failure-modes.md
Touch typography (fonts, sizes, weights, leading, casing, emphasis) docs/design/type.md
Touch layout (windows, grid, spacing, surfaces, elevation, radii, z-order) docs/design/layout.md
Build or modify a component (buttons, inputs, form rows, sidebar, cards, focus rings) docs/design/components.md
Add or change a color (brand, accent, link, destructive, status) docs/design/color.md
Add or modify motion docs/design/motion.md
Wire or change a keyboard binding docs/design/keyboard.md
Touch Settings or Dashboard window architecture docs/design/windows.md
Use, add, or change a token docs/design/tokens.md (vocabulary) + shell/src/ui/styles/theme.ts (values)
Change anything that has a checklist (token, component, color role, keybind, new window) docs/design/change-checklists.md

Hard rules carried here so nobody misses them

  • Token values are declared in shell/src/ui/styles/theme.ts only. Design docs reference tokens by name and purpose, never by value. The one allowed exception is docs/design/failure-modes.md's drift audit table — where showing the conflicting values is the point.
  • The Dashboard (shell/ui/dashboard/style.css) redeclares the same tokens independently by architectural necessity. Any token edit must touch both CSS files. See the checklist before editing.
  • Never inline raw px, rem, or #hex in a component file. Add a token first if needed.
  • Cmd-K is reserved. Do not bind it to anything in v1.
  • Card nesting is forbidden. Either collapse the inner to a row or make the outer a typographic section.
  • Edit the topic files, not this one. This file is the slim pointer. Long content lives in docs/design/*.md.