Alex.

$ cat ~/style/field-manual.md

/style

A working reference, not a manifesto: how alexmbugua.me writes, names things, and presents itself.

This is a style page in the IndieWeb sense: part editorial guide, part design reference, part reminder to keep the site recognizably mine. The philosophy lives in Guiding Principles; the raw token matrix lives in /palette.

If something on this site feels consistent, it probably passed through this page.

Writing

The site speaks like a developer thinking out loud at a clean desk: warm, specific, a little unusual but intentional, and useful enough for future Alex to debug from.

Voice

  • Warm, not loud.
  • Precise, not academic.
  • Personal, not diary-only.
  • Curious, not performative.
  • Specific before abstract.
  • Clear before clever.

The site should read like someone thinking clearly, not performing intelligence.

Clarity beats cleverness. Specificity beats abstraction. Shipping beats theorizing.

Titles

  • Use sentence case by default.
  • Keep technical titles specific, searchable, and human.
  • Preserve proper nouns, acronyms, product names, package names, filenames, and commands.
  • Let essays and personal reflections be more poetic when the mood earns it.
  • Do not write clickbait, keyword soup, or inflated academic phrasing.

Formatting

  • Short paragraphs by default.
  • Headings create scan paths; they are not decoration.
  • Use inline code for filenames, commands, CSS classes, symbols, API names, and storage keys.
  • Use fenced code blocks for commands, snippets, logs, and config fragments.
  • Use footnotes for side quests, jokes, provenance, and extra context.
  • Use bullets when they make a thing easier to scan.
  • Keep punctuation calm. Prefer commas, periods, colons, and parentheses over repeated em dashes.

Technical writing

  • Show the bug before the fix when that helps the reader.
  • Name the environment when it matters: OS, browser, package version, font version, service, or deploy target.
  • Name files and commands precisely.
  • Explain the tradeoff, not just the outcome.
  • Include failure states and debugging notes when they will help future Alex.

Good titles

  • Fixing missing Block Element glyphs in 0xProto
  • Building an animated footnote system in Astro
  • Day n' Night [Dusk Till Dawn (hi)]

Less good

  • You won't believe this font bug
  • A comprehensive exploration of modern typographic remediation
  • Some thoughts

This site is not

  • A portfolio trying to impress everyone.
  • A blog optimized for clicks.
  • A content machine.
  • A place for polished perfection at the expense of honest notes.

It is a working space: a place to think, build, revise, and leave useful traces behind.

Breaking the rules

Rules exist to make the site clearer, not stricter. Break them when:

  • Rhythm matters more than strict structure.
  • A poetic title fits the piece better than a searchable one.
  • A tiny fragment makes the thought land.
  • The interface needs to feel alive, not merely correct.
  • A one-off page needs a one-off moment, as long as it still respects the system.

If it reads better and still feels like this site, it is better.

Example

Before

In this article we explore the implementation of a scalable animation system for a modern web interface.

After

I wanted the sidebar to feel alive. Here's how I made it breathe.

Interface system

The rest of this page is the supporting UI specimen sheet: tokens, type, prose elements, controls, cards, and terminal accents. These exist to support the writing: to keep it readable, consistent, and unmistakably part of this site.

Color roles

Use semantic roles first. Base tokens build surfaces, brand tokens carry action, status tokens mean state, and atmosphere tokens keep the cosmic layer from leaking into structural UI.

Base 100

--color-base-100

Primary page background: the warm void or parchment field.

Base 200

--color-base-200

Secondary surfaces, panels, and quiet elevation.

Base 300

--color-base-300

Tertiary surfaces, dividers, borders, and table rules.

Base Content

--color-base-content

Default body text against base surfaces.

Primary

--color-primary

Brand action color and active terminal accents.

Secondary

--color-secondary

Supporting accent for alternate emphasis.

Accent

--color-accent

Phosphor highlight for headings, focus, and identity moments.

Neutral

--color-neutral

Subdued UI fills that should stay out of the way.

Heading

--color-heading

Semantic heading color decoupled from raw status tokens.

Link

--color-link

Semantic interactive text color for prose and utility links.

Muted

--color-muted

Captions, metadata, and low-emphasis explanatory text.

Code BG

--color-code-bg

Inline code surface, slightly lifted from the page base.

Atmosphere Ink

--color-atmosphere-ink

Topography and ambient pattern ink, separate from surfaces.

Guestbook Pattern Ink

--color-guestbook-pattern-ink

Dense guestbook pattern ink tuned quieter than atmosphere ink.

Matrix Rain

--color-matrix-rain

Optional matrix background glyph color.

Info

--color-info

Informational messages and helpful hints.

Success

--color-success

Positive outcomes and confirmations.

Warning

--color-warning

Cautions, command names, and alert states.

Error

--color-error

Errors, destructive actions, and anomaly states.

Type

The site speaks in 0xProto. uni0553 is a rare accent for pixel-era labels, buttons, and console charm. No soft corporate sans voice sneaks into the cockpit.

Primary / 0xProto

The quick brown fox pings localhost at 03:17 and waits for the signal.

Accent / uni0553

BOOT SEQUENCE / FIELD NOTES / STAR MAP

Global selection and body

The global body layer uses 0xProto, --color-base-content, and the ambient topography surface. Browser text selection uses --color-info with --color-info-content.

Drag across this sentence to test the real ::selection style. Visible token preview: selected text.

Headings

Headings should create a usable scan path. Terminal flavor is welcome; broken outline order is not.

H1 Header: main transmission

H2 Header: section waypoint

H3 Header: local construct

H4 Header: compact detail

Prose

The prose layer should be readable before it is clever. Links, lists, quotes, tables, and details carry the same sharp terminal language as the rest of the site.

Inline prose

A regular internal link, an external slashpage link , strong text, emphasis, search result mark, inserted text, 1, and inline-code.

Keyboard

Use Cmd + K for command-palette style shortcuts and Ctrl + Shift + L for theme language.

Lists

  • Use bullets for quick scanning.
  • Keep items parallel when possible.
  • Do not turn every paragraph into a list.

Blockquote

A note can sound personal and still be precise. The lab bench has room for both.

Table

Element Use Site note
code Inline tokens Filenames, classes, commands, APIs
blockquote Quoted or pulled notes Warm warning rail, no ornamental quote marks
kbd Keyboard input Use for shortcuts like Cmd + K
details Side context Use when the page needs optional depth

Details / callout

Open a tiny side quest

Use details for tangents, source notes, tool output, or anything useful that should not interrupt the main scan path.

Code

Code should feel like material from the same terminal as the UI. Inline code is compact; blocks are bordered and scrollable. Markdown-rendered pages get the Shiki data attributes; Astro-authored pages only get those highlight styles when the attributes are written into the markup intentionally.

Inline tokens

Name the exact thing: src/pages/style.astro, --color-accent, theme-flavor, astro:page-load.

Markdown-only highlight hooks

Generated MDX/Shiki output may include data-theme, data-line, data-highlighted-line, and data-highlighted-chars. Do not expect those styles from plain .astro snippets unless those attributes are authored explicitly.

Buttons

Buttons are italic, monospace, sharp-edged controls. Start with .btn, add a color when state or emphasis requires it, then add a personality variant only when the surface deserves extra character.

Color variants

Personality variants

Sizes

Badges and tags

Badges label metadata, state, and tiny taxonomy. Tags can use .link-action when they navigate; badges are better when they just annotate.

Badge variants

default primarysecondaryaccentneutralinfosuccesswarningerror

Badge sizes

xs sm default lg

Forms

Inputs are blunt terminal fields with visible focus rings. The patterned textarea below intentionally imports the guestbook component styles so this page can document that form surface where it is used.

Text inputs

Named input moods

Guestbook textarea surface

Controls

Checkboxes use the icon font. Toggles are square, compact, and tokenized. Every state needs focus visibility and reduced-motion respect.

Checkbox states and sizes

Checkbox colors

Toggle states and sizes

Toggle colors

Cards and frames

Cards are structural surfaces, not decoration. Keep borders sharp, use base surfaces, and reserve heavy character for places where it helps the object feel handled.

Plain panel

Use for small grouped references, metadata, and utility specimens.

Content card surface

Matches the quiet framed cards used by content listings.

Avatar frame

8BIT

Terminal bits

These are the tiny signals that make the site feel alive: command prompts, cursors, ASCII-ish labels, and phosphor accents. Use them like seasoning, not wallpaper.

Prompt line

$ transmit --channel style --mode warm-void

System labels

> signal uplink boot sequence telemetry

Words and motifs

Recurring words should feel like site weather, not a thesaurus trap. Use motifs when they clarify tone or structure.

Preferred motifs

signalorbitconstellationstarlightuplinkterminalphosphortelemetryfield noteslab notesboot sequencetransmissionarchivetiny machines

Use carefully

hackerglitchretroAIproductivitycinematicseamless

Do not ship

  • Corporate filler: fast-paced landscape, leverage, cutting-edge, game-changing.
  • Generic portfolio cliches that could describe anyone.
  • Effects that make content harder to read.
  • One-off colors when a semantic token already exists.
  • Rounded non-circular surfaces unless they serve a clear purpose.
  • Animations that ignore reduced-motion preferences.
  • Primary navigation clutter for pages that belong in Explore or footer contexts.
  • New CSS primitives that duplicate existing utilities in src/styles/utilities.

Resources

This guide is allowed to change. The site is a living room, a lab bench, and a tiny observatory. Standards should help it feel more like itself, not trap it in amber.