跳到主要内容

CortexFS DESIGN.md

Visual identity for CortexFS surfaces (docs-site, landing, demos). This file follows the DESIGN.md format (version: alpha): YAML tokens are normative; prose explains how to apply them.

ABI and system architecture are not this document. See architecture.md and spec/.

Overview​

CortexFS should feel like a precision instrument on warm paper — closer to a typeset systems manual and a dark terminal than to a SaaS marketing gradient.

Brand personality:

  • Engineered, not playful. Kernel-adjacent seriousness; short words; no mascot fluff.
  • Warm substrate, cold tools. Paper and limestone neutrals carry long-form reading; coal terminal surfaces carry commands and runtime proof.
  • One mint accent for life. Interaction and status use mint; do not invent a rainbow of brand colors.
  • Type contrast. Serif headlines for gravitas; Inter for UI and body; monospace for paths, commands, and instrumentation.

Audience: Linux and systems engineers, agent runtime authors, people who already live in shells. UI density should favor scannable grids and readable code over illustration-first layouts.

Emotional target: calm confidence — “this ABI is small enough to trust.”

Colors​

The palette is high-contrast ink on warm paper, with a single living accent.

  • Primary (#111312) — Ink: Headlines, body emphasis, primary buttons, focus borders. Maximum permanence on paper.
  • Secondary (#66716C) — Moss slate: Captions, secondary nav, muted lead copy. Never competes with ink.
  • Tertiary (#2A8F73) — Mint: The sole interactive brand accent — eyebrows, links that mean “live,” brand italic accent, success-adjacent signals.
  • Neutral (#F7F5F1) — Paper: Page foundation. Softer than pure white; pairs with limestone lines.
  • Surface (#FFFDFA) / panel (#FFFFFF): Raised reading and card surfaces.
  • Coal (#181B19): Terminal, demo frames, manifest band. On-coal text is warm off-white (#FFFDFA).
  • Line (#DED8CA): Hairline structure; prefer borders over shadows.
  • Amber / Rose / Blue: Semantic only (warning, danger, info) — not brand decoration.
  • Signal (#D8FF66): Terminal highlight and “live rail” accents on coal only.

Dark theme inverts paper and ink while keeping mint, amber, rose, and blue as semantic accents (see docs-site/src/css/custom.css). Agents implementing dark mode should preserve token roles, not invent a second brand.

Typography​

Two narrative voices plus one instrument face:

  • Display / headlines — Georgia (serif): Institutional, editorial, manual- like. Large sizes stay semi-bold (600–700), tight line-height, no tracking tricks.
  • Body / UI — Inter (sans): 14–15px body, comfortable 1.65–1.68 line-height. Heavy weights (750–900) reserved for labels and nav, not body paragraphs.
  • Labels — Inter caps: 12px, weight 900, 0.12em letter-spacing, uppercase for section eyebrows only.
  • Mono — system monospace: Commands, paths, object names (model, agent, tool, session), workbench chrome. Prefer weight 800–950 on coal so code reads as instrumentation, not decoration.

Do not introduce a third display family. Do not use monospace for marketing headlines.

Layout​

Desktop is a fluid grid capped near 1320px content width with generous horizontal rhythm. Hero and band sections use large vertical padding (band ≈ 72px). Gutters between major columns are wide (gutter ≈ 54px).

Spacing scale is 4/8-based: xs 4 → sm 8 → md 16 → lg 24 → xl 32 → 2xl 48 → 3xl 72. Prefer these steps over arbitrary pixel values.

Containment: related content lives in panel cards with md radius and internal padding 18–20px. Feature rails and step grids share the same card language. Avoid full-bleed colored hero washes; the page is paper first.

Mobile collapses multi-column hero and feature rails to a single column; primary actions may shrink from the wide desktop CTA width.

Elevation & Depth​

Depth is tonal and linear, not skeuomorphic:

  • Paper vs panel vs coal layers define hierarchy.
  • Hairline borders (line) separate regions; shadows are rare and soft when present (e.g. demo stage 0 24px 70px translucent black).
  • Prefer border-color hover (ink) and 1–2px lift over heavy drop shadows.
  • Terminal and workbench use inset light edges on coal, not outer glow.

Do not stack multiple competing elevations on one surface.

Shapes​

Shape language is architectural soft-rect:

  • Default containers, code blocks, demo frames, feature cards: 8px (md).
  • Logo marks and tight chips: 6px (sm).
  • Nav pills and flow tags: full pill radius.
  • No mixed “bubble UI” on the same screen as sharp engineering chrome.
  • Brand logo tile sits on white with sm radius; keep mark legible on paper and coal.

Components​

Buttons​

  • Primary: Ink fill, warm on-primary text, md radius, min-height 42px, heavy label weight. Optional diamond prefix (◆) on the home primary CTA only. Hover → pure black fill / white text.
  • Secondary / ghost panel: Panel fill, ink text, line border. Hover strengthens border to ink and lifts 1px. Do not use mint fills for primary conversion actions.

Navbar is frosted paper with a bottom line. Links are muted pills; active/hover uses a faint ink wash. Brand title may collapse CorTeXfs → CTX → mark; keep motion short and ease-out, respect prefers-reduced-motion.

Cards and steps​

Feature cards and developer steps share panel + line + md radius. Hover = ink border + slight lift. Step code regions sit under a hairline with mono type. Amber is allowed for step indices and feature codes, not for large fills.

Terminal / workbench​

Coal frames, mint/signal for prompts and live rails, mono instrumentation. Traffic-light dots (rose / amber / mint) are chrome only. Transcript labels use mint uppercase mono.

Chips and proof row​

Outline chips with soft mono text for object class names. Trust dots may use semantic gradients; they are proof ornaments, not a second palette.

Code blocks​

Line border, md radius, no heavy shadow. Dark theme code sits on coal with lighter border.

Manifest band​

Full coal band, large serif headline, muted on-coal supporting text, single underlined text link — the “closing argument” surface.

Documentation reading and discovery​

The handbook is the task directory: install, operate, extend/evaluate, and understand. Its search filters guide titles, summaries, paths, and keywords; do not imply full-text search. Keep both supported languages complete. Group the sidebar by the same user tasks and expose the handbook from every document. Keep the specification visible as a first-level category.

Long-form documentation uses 16px body text (15px on narrow screens), 1.8 line-height, and paragraphs near 76 characters. Technical tables and code retain horizontal scrolling on narrow screens. Links inside prose are underlined; the active sidebar item has a mint rule in addition to its fill. Use built-in copy controls for executable examples, and ensure installation and session commands match the current canonical guide. Historical recordings must identify retired commands instead of presenting them as current setup.

The handbook uses existing paper/ink/panel tokens and 8px corners, with plain rows grouped by task. Search and filters have visible labels and focus states, 44px minimum targets, a result count, and a recoverable empty state. Native links remain usable before client JavaScript is available.

Do's and Don'ts​

  • Do treat YAML tokens as normative; change CSS only after tokens.
  • Do keep mint as the only brand interaction accent on paper surfaces.
  • Do put commands, paths, and ABI object names in monospace.
  • Do prefer borders and tonal layers over decorative shadows.
  • Do maintain WCAG AA contrast for body text on paper and on coal.
  • Don't introduce purple SaaS gradients, glassmorphism stacks, or neon multi-accent dashboards.
  • Don't use mint or signal as large background fills on paper.
  • Don't set marketing headlines in monospace or body copy in Georgia at small sizes.
  • Don't mix pill-everything with sharp-everything in one component group.
  • Don't put provider logos or API-format branding into the root visual language — CortexFS is vendor-neutral.
  • Don't confuse this file with the ABI: system design lives in architecture.md and spec/.