Style guide

theme v2 — night terminal

The design system for LetsBuild.cloud. Dark only — a terminal doesn't have a light mode, and neither does this site. Built on the Rosé Pine palette: deep violet-black surfaces with six muted pastel inks, in place of v1's saturated gruvbox primaries. Identity comes from structure: a statusline, an inverted title row, numbered section rules, a tree TOC. Zero JavaScript, one shared stylesheet (/theme.css).

Principles

1. The interface is a terminal application. The chrome is a statusline; the title is a selected row; the index is a dated listing; panels are bordered frames with tab labels. Structure does the theming.
2. Dark, always. One mode, tuned properly, instead of two compromises. color-scheme: dark keeps native controls and scrollbars in-theme.
3. Muted inks on deep ground. Six pastel hues, none saturated, each with a defined job. Body text is never coloured.
4. Prose first. Monospace everywhere, but with generous leading, a real measure, and decoration that stays out of the reading column.
5. Zero external requests, zero JavaScript. System font stacks, CSS-only components, one shared same-origin stylesheet (/theme.css).

Colour

Rosé Pine: three stacked surfaces, three text tones, six hues. Contrast ratios are measured against --color-bg; hues marked ◆ sit below 4.5:1 and are decorative-only — borders, fills, and large glyphs, never body-size text.

Surfaces

Text & interactive

Hues

Usage rules

• Body text is --color-text or --color-subtle. Nothing else colours a paragraph.
• One link colour, sitewide: foam, hovering to rose.
• Each hue keeps one job. If a new element needs colour, it reuses the hue whose job it matches — it does not get a new one.
• Surfaces stack in order: bg → surface → overlay. Never skip a level for contrast tricks.
• Never hard-code a hex in a rule; always go through a token.

Typography

One family — monospace, everywhere. System-installed developer fonts, no downloads, so the site renders in the reader's own terminal font.

--font-mono: "JetBrains Mono", "Fira Code", "Cascadia Code", "SF Mono",
             Menlo, Consolas, "DejaVu Sans Mono", "Liberation Mono", monospace;

Scale

Seven steps from a 16px base. Monospace runs wide, so the scale is tight.

Weight, leading, tracking

Hierarchy is typographic: the h1 is an inverted block, h2s are numbered small-caps with a rule filling the line, h3s carry an iris sidebar, h4s are small-caps labels. Uppercase + --tracking-wide is the signature for anything label-like.

When a caption wants that look but isn't a section, use .label on a paragraph instead of reaching for an h4. Heading levels are the document outline. A repeated card caption padding it out — ten alternating do and don't in the section below — is noise a screen reader has to walk past to find the real structure. Levels also have to descend one at a time: an h2 followed by an h4 leaves a hole in the outline.

Spacing & layout

Spacing scale

Six steps. Pick from the scale; never invent an in-between value.

• --space-1/2 — inside components: label gaps, chip padding.
• --space-3/4 — between elements: paragraphs, card padding, rows.
• --space-5/6 — between ideas: subsections and sections.

Measure

The reading column is --layout-width: 760px — about 76 monospace characters. One column, no sidebars, no grid. Horizontal padding --layout-pad-x: 1.5rem, vertical --layout-pad-y: 2.5rem. Wide content (code, tables) scrolls inside its own container; the page never scrolls sideways.

Components

The full set, all CSS-only. Anything interactive here is styled native HTML — no scripts to load, nothing to hydrate.

Statusline

The site's chrome, top and bottom of every page: solid segments in the vim mould. Foam segment for identity, overlay segments for context, surface fill between. Segments can be links. Every page header carries the same pattern: identity links home, and the current page's filename sits in a surface segment after the fill.

The bar wraps rather than clips. Segments are nowrap, so a bar with more content than room used to hide its tail behind overflow: hidden — the page width stayed correct and the last links were unreachable. Segments now drop to a second row instead.

The nav row

When a bar carries links as well as status, give it a second line. Add .statusline-stack to the bar and wrap each line in .statusline-row; the row draws the surface tone itself, so a stacked bar needs no trailing .fill. Both the header and the footer are built this way — status above, links below.

The second row is the command line. .statusline-nav drops the fill tone, the foam block and the segment chips, leaving a foam : prompt and plain subtle links that go foam and underline on hover. Two rows of solid segments read as equals, and the row naming the page should win. It also drops the segment padding and spaces itself with a gap, so the : lands on the page's left rail — the same column as the ❯ prompt, the h1 block and every line of prose.

The real thing is a <nav> with an aria-label: a page with two of them needs to say which is which, so the header's is Primary and the footer's is Footer. The specimens below are plain divs — a landmark that exists to be looked at is one more thing for a screen reader to walk past.

Segments that don't fit

A link gets its own row before it gets truncated. The footer colophon used to wear a modifier that truncated it to fit alongside the links: at 1280px it showed 308 of its 449 pixels. You can't tell where a link goes when its name is cut off. It now sits on the status row with the links below it, and .seg-note lets it wrap inside its own box instead: prose in a bar of nowrap segments, read in full at 320px.

.seg-shrink is what's left for the case that genuinely can't wrap: a one-token label like a filename. It keeps its natural width until the row is tight, then yields to an ellipsis, and it's hidden outright below 640px where a label truncated to a sliver is only noise. Never put it on a link or anything else focusable.

A truncating segment must carry a title holding the same text. The ellipsis is a CSS effect, so the string stays whole in the accessibility tree and a screen reader reads all of it. The person who loses information is the sighted mouse user, and on a page with no JavaScript title is the only hover affordance there is. cursor: help signals it. title never reaches a keyboard or touch user, though, which is why the rule is to keep the modifier off anything clickable rather than to paper over one with a tooltip.

Prompt

The interactive signature: foam ❯, subtle text, blinking block cursor. Used once per page at most — under the title. The blink respects prefers-reduced-motion.

Title row

Page titles render as a selected row — rose fill, ground-coloured text, hugging its content width. Nothing else on the site is inverted at this scale, which is what makes it the title.

Buttons

• Primary — foam fill, one per view. Hover shifts to rose.
• Default — outlined; border and text turn foam on hover.
• Danger — love outline, filling on hover. Destructive only.
• Ghost — bracketed text action, for inline or tertiary use.

Tags, badges & keycaps

Tags are outlined and quiet; badges are filled and loud — use badges sparingly. Keycaps get an overlay fill with a thick bottom edge.

Tags also work as links. Wrap a row of them in .tag-list (the topic row at the head of a post) or .tag-cloud (the tag index), both flex-wrap containers. A linked chip outlines in rose on hover, following the sitewide link rule. .tag-count puts a gold post count inside the chip — numbers are gold everywhere.

Cards

A surface panel with its label breaking the top border — the CSS equivalent of a ┌─ title ─┐ box. Accent variants recolour the tab and border together.

Reading shelves

The homepage reading block: one card per Goodreads shelf, each tinted by a .shelf-gold, .shelf-foam or .shelf-iris modifier so the three groups read as three groups. This is the one place a hue means which group rather than its usual job. The card title always says the same thing, so nothing rides on colour alone.

.book-glyph is a book drawn in CSS: a coloured spine down the left edge and two rules for the title on the cover, varying by position so a shelf isn't one book repeated. It replaced a hot-linked Goodreads cover that ran up to 750 KB for a 26px slot. It's decoration, so it's aria-hidden — the title and author sit beside it as text. .reading .card-grid aligns to start so a one-book shelf doesn't stretch to the height of a three-book one.

Callouts

Blockquote

Code

One code component, everywhere. The SSG's own tiny tokenizer (highlight.go — rust, go, python, shell, yaml, js; anything else stays plain) renders every block at build time, whether it's fenced in a post or sourced from a static page. They all come out as the same line-numbered pre.code rows: muted gutter, overlay row hover, surface fill, hairline border. An optional title bar names the file and language. Inline code gets the same treatment at 0.9em. Syntax inks, one job per hue: keywords iris; functions and types foam; strings, macros and flags gold; numbers and lifetimes rose; comments subtle italic — never muted, which fails AA at code size.

 1// Render a post through the single template.
 2func render(post Post) string {
 3    html := markdown.ToHTML(post.Body, 0)
 4    return strings.Replace(tmpl, "{{content}}", html, 1)
 5}

Tables

Rows highlight on hover with a surface fill; headers are small-caps labels.

Forms

Inputs sit on the surface colour with strong borders; focus swaps the border to foam and doubles it with a ring. Checks, radios and ranges use accent-color: var(--c-iris) — native controls, themed without extra markup.

Breadcrumbs & pagination

Tabs

The active tab joins the page: bordered on three sides, ground-filled, sitting on top of the rail. CSS only — each tab is a link to its page.

Progress

Segmented fills — terminal block characters, drawn with a repeating gradient.

Tooltip

Pure CSS: content lives in data-tip, shown on hover and on keyboard focus. For glossary-grade asides only — anything important belongs in the prose.

The bubble wraps at min(32ch, 60vw) and is hidden with display, not opacity alone. An invisible box still occupies the scrollable overflow, so a tooltip near the right edge used to widen the whole page on a phone; transition-behavior: allow-discrete keeps the fade regardless.

Disclosure

Post index

The homepage lists posts by date: gold ISO dates, foam titles, subtle one-line descriptions, dashed hairlines between entries. No glyph prefixes — the date column and separators carry the structure.

Footer

The statusline mirrored at the page end, stacked the same way: the colophon on the status row, the way back on the nav row below it. Every footer links home and ↑ top. Where the header nav points at the content — posts, tags, about — the footer nav points at the way out: the feed, this guide, the top of the page.

Motion & accessibility

• Motion budget: one animation. The prompt cursor blink, removed under prefers-reduced-motion. Everything else is a 0.15s colour/border transition; nothing moves position.
• Contrast. Text tones and link colours clear WCAG AA at body size (most clear AAA). Pine and muted are locked to decorative roles — the ◆ flags in the colour tables are the contract.
• Colour is never the only signal. Links underline on hover, focus draws a 2px foam ring, active tabs change weight and border, callouts carry text labels.
• Semantics. One h1, ordered heading levels, native controls (button, details, progress roles), real nav landmarks. Decoration lives in CSS generated content, kept out of the markup.
• Keyboard. Everything interactive is a native focusable element; tooltips open on focus, not just hover.

Voice & tone

The theme frames the words; style.md governs them: concise, approachable, informal but professional. Active voice, no weasel words, no clichés. Short paragraphs, concrete examples, code where code explains better than prose. The design should feel like the writing.

Token reference

The complete set — every value the theme uses, grouped by concern. The live copy is the :root block in /theme.css, the single stylesheet every page on the site (including this one) links. Change a token there and it changes everywhere at once.

Colour

Typography

Spacing & layout

Borders & motion

Do & don't