staging-org / ocean-landing-serve / docs/ ui-rules.md

UI rules

The page should read as typeset by a person for this product: one family, deliberate contrast between levels, nothing added for decoration. Exact values live in src/routes/layout.css; this file holds the rules and the reasons.

Typography

Set every piece of text with a type-* utility. Pick by role, not by size:

UtilityRole
type-displayThe single h1 on a page
type-titleSection h2s and closing statements
type-figurePrices and other standalone numbers (tabular figures)
type-leadThe paragraph under the h1
type-headingItem names: steps, plans, FAQ questions, mobile menu links
type-bodyRunning text
type-smallUnits, captions, footer, meta lines
type-navDesktop nav links
type-uiControls that aren't shadcn buttons
type-brandThe wordmark
type-markThe >=> logo mark, sized relative to the wordmark
type-codeLogs, traces and diffs in the demo console
type-asciiASCII art only

When no role fits, add a new @utility type-<role> in layout.css, then use it. bun run check:ui fails on raw text-* sizes, font-* weights, tracking-*, leading-* and font-stretch in app code; src/lib/components/ui (vendored shadcn) is exempt.

The system behind the values, so a new utility fits it:

  • Family: Instrument Sans for all text, JetBrains Mono only for ASCII art and the logo mark. Fonts are wired through --app-sans, --app-display and --app-mono on :root; swap a family there, nowhere else.
  • Width: display sizes run narrowed via --app-display-stretch (88%). Text at reading sizes stays at 100%. Narrowing past ~85% closes the counters.
  • Weight: three steps. 400 for reading, 500 for controls, 560 for anything that names or titles. Narrowed type looks darker, which is why headings sit at 560 rather than 600. The variable font runs 400 to 700.
  • Tracking: tighten as size grows (display -0.022em, title -0.018em, figure -0.015em), hold body at 0, open small UI text slightly (+0.002em). Narrowed display type gets gentler negative tracking than full-width type would.
  • Leading: display 0.98, title 1.05, lead 1.55, body 1.6. Big type sits tight; reading text breathes.
  • Size: display and title scale fluidly with clamp() between a phone and a desktop size; everything else is fixed.
  • Measure: cap reading text in ch (lead 40ch, steps 42ch, answers 62ch). Headings use text-wrap: balance, paragraphs pretty.

Hierarchy

From Refactoring UI, applied after the pull request list grew to a dozen equal-weight facts per row and read as noise (October 2026):

  • One focus per screen, one per row. Decide what the person is here to do and make that the loudest thing; everything else steps back. If two things compete, de-emphasize one rather than emphasizing the other harder.
  • Say each fact once. A group heading, a status word and a progress track that all mean "waiting on you" are one fact said three times. Keep the clearest and cut the rest.
  • Earn every element. Metadata that doesn't change the decision on this screen (branch, linked issue, diff size on a list) lives on the detail page. Cut column headers, counters and hints the layout already explains; labels are a last resort.
  • Emphasis comes from contrast before color. Dark text for what matters, muted-foreground for the rest. Blue is for the one control or action that matters; red only for a real blocker, not for normal work in progress.
  • Space separates; lines are a last resort. Groups get clearly more space around them than inside them. Reach for a border only when spacing can't do the job.
  • Don't fill the screen. Cap content at the width it needs (a form or article at a reading measure). A list of rows runs the full width so its columns line up. A rail stays only if it helps the decision on that screen.

Color

Use the semantic tokens (text-foreground, text-muted-foreground, bg-primary, border-border, bg-muted). The palette is navy ink #13285c, slate #4a5b7c for secondary text, action blue #1d4ed8, and the foam and hairline blues for surfaces and rules. Hierarchy comes from size, weight and the two text colors; keep emphasis inside a heading at the heading's own color and weight.

The palette is the whole palette. Blue and sky shades carry data (the tide chart and language bars), primary marks actions and things that are done, muted-foreground marks waiting, and destructive marks blocked or removing. No other hues: no success green, warning amber, per-agent colors, brand colors or colored icon tiles. They were tried across the app in October 2026 and reverted as too loud (fcd5dc6). When a screen feels flat, add information, not color. bun run check:ui fails on other hues and raw hex in app code.

One exception, by Fenil's call (October 2026): the home-city skyline on profiles (src/lib/components/profile/CityScape.svelte) is in full color. Landmarks wear their real colors (the Golden Gate in International Orange, patina on Liberty), windows glow amber at night and sunsets leave a warm haze. The colors live in its palette, keyed by the paint rows of each drawing; nothing else on the site borrows them.

Layout

  • Sections: border-t on top, py-20, then a 12-column grid with the title in 4 columns and the content in 8.
  • Container: mx-auto max-w-7xl px-4 sm:px-6 lg:px-8.
  • Content is left-aligned, the hero included.
  • Inner pages end on their last section; the footer carries the page's one closing call to action, so no second CTA band above it.
  • Lists of peers use dividers or plain grids. Use numbers only for real sequences, like the five steps of an incident.

App screens

Product screens under src/routes/(app) follow docs/app-screens.md: the steps, the patterns, the component catalog and how to prove a screen works.

Components and icons

shadcn primitives from #lib/components/ui, icons from Phosphor in the regular weight, imported one per file (import GitBranchIcon from 'phosphor-svelte/lib/GitBranchIcon'; the barrel import compiles slowly). Size icons with size-* classes; color comes from currentColor. Reach for another weight only to mark state, the way a draft pull request uses thin. Phosphor replaced Lucide in October 2026 because its rounder, lighter strokes sit better beside Instrument Sans. Import #lib paths with an explicit extension (#lib/components/ui/button/index.js); the subpath alias doesn't resolve bare directories for the typechecker.

Motion

The ASCII ocean is the page's one ambient animation, with one exception the owner asked for: the caisson scale figure (AgentScale.svelte) plays agents arriving when it scrolls into view, then keeps local disks re-cloning and caisson branch tips pulsing. It runs on requestAnimationFrame only while on screen and shows the finished still under reduced motion. Don't add a third without the same ask. Everything else moves only in response to the user (menu, FAQ, hovers), and it moves snappy:

MotionDurationCurve
Hover and focus color150msdefault (ease-snappy)
Something entering or opening200msease-snappy (fast, settles)
Something leaving or closing150msease-exit (accelerates out)

Exits are always shorter than enters. Transition named properties (transition-colors, transition-[color,box-shadow]), never transition-all. bun run check:ui fails on anything over 200ms, ease-in-out, ease-in, ease-linear or transition-all, vendored shadcn files included. A global rule in layout.css collapses every animation and transition under prefers-reduced-motion.

ASCII ocean

  • Sky props (clouds, sun, birds, boat) stay between the bottom of the hero content and the water line, so nothing ever passes behind text. The hero reports that boundary with contentPx.
  • The grid is 8x15px cells, coupled to type-ascii. Change both together.
  • Each row's textLength pins it to the grid, so a different mono font can't break column alignment.
  • The sky follows the visitor's local hour, read after mount so server and client renders agree: the sun arcs left to right from 6:00 to 19:00, then a moon and twinkling stars take over. Clouds carry a background-colored outline so they pass in front of the sun and moon instead of mixing glyphs.
  • The water answers the pointer: moving over it leaves a wake, pressing sends a ring through the depth field and the surface line. Rows count 15/8 of a column so rings stay round. Both are off under reduced motion, like the rest of the scene.
  • Everything stays in the ocean blues; time of day changes what is in the sky, never its color.

Copy

Sentence case, plain verbs, American English. Buttons say what happens ("Get early access", "See how it works"). Each element does one job; cut any line that only restates its heading.