# Cosmic Ink — design reference

Approved: 25 October 2026. Applies to the personal site, Notes, Learn, and Brand.

## Source of truth

- This document records the approved design decisions.
- `src/styles/global.css` implements shared tokens and components. Change shared styles there, not per lesson.
- `/brand/` is the live visual reference, using the same styles as the site.
- `brand/index.html` preserves the original brand exploration. Earlier alternatives are historical, not competing directions.
- Approved reading mockups: [library and course](brand/learning-ui/01-library-and-course-v1.png), [lesson reader](brand/learning-ui/02-lesson-reader-v1.png), [blog article](brand/learning-ui/03-blog-article-v1.png).
- Generated images guide composition, not exact text or CSS measurements. The revised lesson phone view is the typography reference for all mobile reading pages.

## Identity and palette

The site is Joshua Wong. Cosmic Ink is the design system's name.

| Token | Value | Use |
| --- | --- | --- |
| Paper | `#f3f0e9` | Main reading surface |
| Ink | `#171722` | Text and headings |
| Muted | `#565363` | Supporting text |
| Line | `#ccc7c0` | Decorative separators |
| Blue | `#3455db` | Links, focus, current navigation |
| Violet | `#7050ba` | Occasional emphasis |
| Red | `#bc3447` | Small artwork accent |

Keep pages predominantly paper and ink. Use the existing ASCII magician card on the homepage; keep art, grain, stars, and decorative geometry away from paragraphs. Prefer rules and open space to card grids. Control boundaries use a stronger color than decorative separators.

## Typography and spacing

- Self-host the bundled Martian Mono Variable and its license. No remote font calls.
- Use Martian Mono for headings, paragraphs, navigation, and labels. KaTeX's mathematical fonts are the exception for correctly typeset mathematics.
- Body and main navigation: `1.328125rem` (21.25px at the browser's default 16px), on both desktop and phone. Never shrink mobile prose to fit more content.
- Body line height: 1.7. Reading measure: about 60 characters. Use `--reading-measure: 42em`, calibrated to the bundled Martian Mono at normal width (one character advances 0.7em), so line lengths follow text size without relying on `ch` measurements during WebKit zoom. Heading and metadata limits use the same conversion. Headings: weight 600 for page titles, 500 for sections; body 350–400.
- Supporting metadata: 0.875–1rem; secondary navigation: at least 1rem. Code: 1rem, in independently scrollable blocks.
- Code surfaces use `#f9f7f2` so syntax highlighting, including comments, retains readable contrast.
- Phone gutters: 20px. Wider screens use responsive gutters up to 48px. Use a consistent 8px-based spacing rhythm.

## Page patterns

- Shared header: Joshua Wong, About, Work, Notes, Learn, Brand, Search. On phones, a native expandable menu. Main links have 44px minimum targets.
- Home: existing split introduction and magician artwork, followed by work, about, and links into Notes and Learn. Keep source-backed facts; never invent personal achievements or beliefs.
- Learn library: heading, brief introduction, search link, simple rule-separated course rows.
- Course overview: breadcrumbs, description, prerequisites, Start learning link, ordered modules and lesson links. No completion indicators.
- Lesson: breadcrumbs, course position, title, description, text and figures, native expandable solutions, named Previous/Next links. Derive navigation from the course outline.
- Desktop lesson: course sidebar on the left, article center, page contents right. Below 1280px, contents move above the article. Below 1024px, course navigation also moves above the article into a disclosure.
- Notes article: the same article typography, with date and page contents, without a course sidebar.
- Brand: live palette, typography and component examples, followed by the approved mockups. Include it in navigation so it stays easy to inspect.
- Phone: one reading column. Course contents and page contents are separate disclosures. Put Previous/Next links below the article; never cover reading text with fixed controls.

## Content and interaction

- Text stays selectable HTML. Diagrams use SVG or appropriately sized images, with alternative text and captions when useful. Mathematical notation is rendered at build time.
- Long tables, formulas, and code scroll inside labeled, keyboard-accessible regions, never the entire page.
- Use native `<details>` for worked solutions. Markdown inside details must be separated from the tags by blank lines.
- Teaching figures use selectable HTML inside `.teaching-figure`, with an adjacent caption. `.trace-steps` shows time downward; `.parallel-step` and `.state-comparison` compare actors or states; `.tree-branches` shows routing choices. Comparisons and branches stack below 700px. Label the selected branch in words as well as blue; diagram text is at least 1rem. Use the same patterns on the Brand page.
- Reading and navigation work without JavaScript. Search is the only feature requiring browser JavaScript.
- No database, authentication, CMS, chat, reading-progress state, offline downloads, or animations in article content.
- Sample content is visibly labeled. Source documents are not automatically published.

## Accessibility and review

Use semantic headings, a skip link, visible keyboard focus, underlined article links, meaningful image descriptions, and text as well as color for current location. Honor reduced motion. Check normal-text contrast at 4.5:1 and large text at 3:1.

Before accepting a layout change, check Chrome and WebKit at 320px, 390px, 768px, and 1440px widths, keyboard access, 200% text enlargement/reflow, and JavaScript-disabled reading. Compare 50–200% desktop zoom reflow equivalents and capture matching browser screenshots. Viewport resizing and CSS zoom are not substitutes for a final check of the reported browser’s native zoom; use actual native page zoom when available. Do not disable user zoom to fix a layout issue. Inspect formulas, tables, code, diagrams, first/last lesson navigation, and empty search results.

Update this file and the live Brand page when an approved design decision changes. Content additions should reuse the existing layouts without creating new CSS. Hosting is deferred until local acceptance.