1  # Gnosis — Design Guidelines
 2  
 3  ## Design Context
 4  
 5  ### Users
 6  
 7  Senior software engineers reviewing complex pull requests on their own machine. They are experienced, opinionated, and want depth — not hand-holding. They open Gnosis to *understand* a change, not to skim it. The app should feel like a quiet reading room: a place to settle in and think, not a dashboard to triage.
 8  
 9  The job-to-be-done is **comprehension**: walk me through this PR the way the author understands it, in the right order, with the right context, so I can review it with confidence and not miss anything important.
10  
11  ### Brand Personality
12  
13  Calm, intellectual, considered. Three words: **scholarly, deliberate, lucid.**
14  
15  The name *Gnosis* points at deep, direct understanding — the interface should embody that. Quiet confidence over flash. Editorial pacing over dense chrome. The voice is that of a thoughtful colleague explaining a change over coffee, not a notification-spamming SaaS app.
16  
17  Emotional goals: **focus, trust, intellectual calm.** The reviewer should feel that the tool respects their attention.
18  
19  ### Aesthetic Direction
20  
21  **Reference feel:** Stripe docs and Notion docs for pacing and restraint — *plus* a specific anchor reference the user shared: a PR-walkthrough tool with a serif-titled, monograph-like layout. That reference is the closest existing thing to the target feel and should be treated as the primary visual touchstone. Key qualities to inherit from it:
22  
23  - **Serif display type for slide titles.** A high-quality editorial serif (e.g. a transitional or modern serif — think the kind used in long-form journalism) is the single most important typographic move. It does most of the work of making the app feel like a monograph rather than a SaaS panel. Body and UI stay sans (Inter); code stays mono (JetBrains Mono).
24  - **Numbered, book-like table of contents.** Sections in the sidebar are numbered (`01`, `02`, `03`…), with optional time-to-read estimates and completion checkmarks. No icons, no card backgrounds, no borders — just type on the page.
25  - **Near-zero chrome.** Sidebars have no dividers or fills. The bottom bar is a thin row of low-contrast, mostly text controls. Buttons and badges are small, quiet, and use type rather than color to communicate.
26  - **Color as punctuation.** On any given slide the *only* color present should be (1) the diff red/green, (2) at most one editorial callout, and (3) a single small status badge if needed (e.g. `CRITICAL`, `27d old`). Everything else is ink-on-paper neutrals. If you find yourself adding a third color to a screen, remove something instead.
27  - **Editorial callouts with inline labels.** When highlighting an idea, use a soft tinted block with a **bold inline label** followed by prose on the same line — not a titled card with an icon. It should read like a sidebar in a printed essay.
28  - **Generous reading column.** Slide prose has a comfortable measure (~65–75ch), 1.6+ line-height, real paragraph spacing. Whitespace around the title is luxurious, not efficient.
29  - **Quiet metadata in mono.** Small, low-contrast, monospace for things like file counts, age, branch names, progress strings. It feels like a margin note, not a status indicator.
30  - **Diffs are allowed to be loud.** Because everything around the diff is calm, the diff itself can keep its classic red/green and still feel intentional. Don't try to "tone down" the diff — tone down everything *around* it.
31  
32  Stripe / Notion remain the secondary references for general typographic discipline and pacing. The PR-walkthrough screenshot is the primary one for layout, chrome, and color restraint.
33  
34  **Palette direction:** Warmer, more editorial than the current cool cyan. Think ink-on-paper: a near-black foreground, a paper-toned background (warm off-white in light, deep warm charcoal in dark), and a single restrained accent used sparingly for emphasis and interaction. Move away from the current cyan (oklch ~195) toward something warmer — a muted amber, ochre, or burnt sienna would echo the classical/gnostic association without being theatrical. The accent should appear rarely enough that it actually means something when it does.
35  
36  **Typography:** Lean into the existing stack — Inter for UI, Sora for display, JetBrains Mono for code — but use them with editorial discipline. Strong hierarchy, comfortable line-height for prose (1.6+), tighter for UI. Display type for slide titles and section breaks, not for chrome.
37  
38  **Theme:** Both light and dark are first-class. Light should feel like a printed page; dark should feel like a well-lit study at night, not a black void. Both must be polished and tested — neither is a second-class citizen.
39  
40  **Density:** Generous. Slides are for reading. Resist the urge to cram. Whitespace is content.
41  
42  **Motion:** Subtle and purposeful. Transitions between slides should feel like turning a page, not like a SaaS toast. Always honor `prefers-reduced-motion`.
43  
44  ### Anti-references — what Gnosis must NOT look like
45  
46  - **Generic AI chatbot UI.** No message bubbles, no purple gradients, no "AI sparkle" tropes. Gnosis uses AI but is not *about* AI — it is about the PR.
47  - **Heavy enterprise / Jira.** No dense toolbars, no busy chrome, no bureaucratic affordances.
48  - **Marketing-y / over-designed.** No landing-page gradients, hero illustrations, or decorative flourishes inside the app. Restraint.
49  - **Unmodified shadcn defaults.** Gnosis must have a distinctive identity. The shadcn primitives are a starting point, not the destination — tokens, spacing, and type should be customized enough that the app does not read as a generic starter.
50  
51  ### Accessibility & Inclusion
52  
53  - **WCAG AA contrast** for all text and meaningful UI.
54  - **Full keyboard navigation.** Every action reachable by keyboard. Visible, well-styled focus rings — not the browser default, not invisible.
55  - **Color-blind safe.** Never rely on color alone for diff add/remove, risk levels, or status. Always pair color with shape, icon, prefix character, or text label.
56  - **Respect `prefers-reduced-motion`** for all transitions, even though it wasn't explicitly selected — it's table stakes for an editorial, focus-oriented app.
57  
58  ### Design Principles
59  
60  1. **Comprehension over decoration.** Every visual choice should make the PR easier to understand. If it doesn't, cut it.
61  2. **Editorial, not dashboard.** Pace, hierarchy, and whitespace belong to long-form reading. Treat slides like pages, not panels.
62  3. **Restraint is the accent.** Color, motion, and ornament are scarce on purpose — when they appear, they mean something.
63  4. **Respect the reviewer's attention.** No interruptions, no notification noise, no chrome competing with content. The reviewer is doing serious work.
64  5. **Distinctive but quiet.** Gnosis should be recognizable in a screenshot — but never loud. Identity comes from typography, palette, and pacing, not from flourish.
65  6. **The serif title carries the brand.** A well-chosen editorial serif on slide titles is non-negotiable — it's the single highest-leverage move toward the monograph feel. Every other typographic decision should defer to making that serif feel inevitable.