# Shared theme exploration

Generated as a starting point for a reusable personal design system that can support Network Brouhaha, Octant docs, project microsites, web apps, and eventually shell or TUI palettes.

## Design principles

- **Personal before corporate.** Borrow discipline from Instinct, not the AMD identity. The result should feel like Matt: technical, direct, curious, occasionally funny, and allergic to unnecessary ceremony.
- **Token-first.** Colors, type, spacing, radii, shadows, syntax colors, and semantic status colors should live in a portable source. Initial targets: SCSS for Jekyll, JSON for future apps, and terminal palette exports.
- **Readable by default.** Blog posts need calm long-form reading surfaces. Technical pages can be denser, but prose should still breathe.
- **Dark frame, flexible content.** Use a dark technical shell as the shared identity. Allow light or warm reading panels where long-form text benefits from it.
- **Useful texture, no wallpaper.** Grid, dot, or circuit textures should clarify the surface hierarchy. They should disappear while reading.
- **Levity in the right places.** Humor belongs in examples, post intros, empty states, command snippets, and side notes. Navigation and operational status should stay plain.

## Option A: Field notebook

**Feel:** Warm, readable, writerly, still technical.

**Use it for:** Network Brouhaha home, posts, link pages, conference notes, reflective technical essays.

**Shape:**
- Dark sidebar or top frame
- Warm paper reading surface
- Strong post cards with dates, tags, and short excerpts
- Subtle teal/amber accents
- Excellent print and saved-PDF behavior

**Risk:** It may feel less distinctive for Octant unless paired with diagram modules.

## Option B: Lab console

**Feel:** Dark, technical, diagram-forward, operational.

**Use it for:** `octant.foo`, architecture explainers, runbooks, service catalogs, topology diagrams, lab status pages.

**Shape:**
- Near-black background with a restrained grid
- Teal for primary links and topology relationships
- Amber for caution, drift, or "read this before touching things"
- Berry as a small humanizing accent
- Dense cards, status pills, topology blocks, runbook callouts

**Risk:** Too much of this on long posts could feel tiring, so pair it with a lighter article layout.

## Option C: Workbench

**Feel:** Component library, project OS, app-ready.

**Use it for:** Shared documentation, project dashboards, generated reports, CLI documentation, app shells, TUI palette development.

**Shape:**
- Split-pane layouts
- Reusable cards for docs, commands, state, errors, and next actions
- Terminal block as a first-class component
- Token palette designed to map cleanly into shell prompt colors

**Risk:** More up-front design/build work. Worth it if the shared theme becomes a long-term asset.

## Recommended path

Start with a hybrid:

1. **Field notebook** for the Network Brouhaha refresh.
2. **Lab console** for the first `octant.foo` landing page and explainers.
3. **Workbench** as the underlying component and token model so future apps and CLI/TUI tooling do not become a separate design universe.

The implementation should begin as local Jekyll theme pieces inside `/Users/matt/git/shamsway.github.io`, then be extracted only after the second project proves which components are truly shared.

## Early token direction

```scss
$shamsway-bg: #0e1113;
$shamsway-surface: #15191c;
$shamsway-surface-2: #20262a;
$shamsway-paper: #fffaf0;
$shamsway-text: #e8ecef;
$shamsway-muted: #b7c0c5;
$shamsway-teal: #28d7e8;
$shamsway-amber: #f0b35a;
$shamsway-berry: #c9587a;
$shamsway-green: #76c893;
```

## First build targets

- `_data/theme.yml`: canonical tokens and surface modes.
- `_sass/shamsway/_tokens.scss`: generated or manually synced SCSS variables.
- `_sass/shamsway/_base.scss`: typography, links, prose, code, tables.
- `_sass/shamsway/_components.scss`: nav, post cards, project cards, status pills, callouts, terminal blocks.
- `_layouts/home.html`, `_layouts/post.html`, `_layouts/project.html`, `_layouts/docs.html`.
- `_includes/post-card.html`, `_includes/project-card.html`, `_includes/status-pill.html`, `_includes/terminal-block.html`.

## CLI/TUI mapping

Use the same palette semantically:

- Teal: active selection, links, prompts, primary actions.
- Amber: warnings, pending state, "read before running."
- Berry: destructive or risky actions, only when needed.
- Green: healthy state, successful checks.
- Muted gray: timestamps, paths, metadata.
- Near black: terminal background.

This keeps web pages, generated reports, shell prompts, and TUI surfaces visually related without forcing every surface to look like a website.