docs: add Color Fundamentals / Color Schemes / Color Detection

Three new foundation pages covering terminal color from the ground up:

- **Color Fundamentals** (fundamentals/color-fundamentals.md) — ANSI 16 vs
  256-color vs truecolor, SGR vs OSC escape families, the universally-supported
  SGR attrs (bold, dim, italic, underline, inverse, strikethrough), and the
  tier-based rendering pattern modern TUIs use.

- **Color Schemes** (fundamentals/color-schemes.md) — the 22-slot scheme every
  terminal exposes (16 ANSI + fg/bg/cursor×2/selection×2), how it's queried
  via OSC 10/11/4/12/17/19, and the 'detect + derive' pattern for adopting
  the user's theme.

- **Color Detection** (fundamentals/color-detection.md) — the full detection
  stack (NO_COLOR → TERM=dumb → isatty → COLORTERM → $TERM heuristics),
  OSC probing for authoritative slot values, and graceful tier degradation.

All three cross-link each other + to silvery.dev/guide/{color-schemes,
capability-tiers,custom-tokens} where applicable. Wired into the VitePress
nav + sidebar + transformPageData SEO metadata.

Companion pages to silvery.dev/guide/{color-schemes,capability-tiers,
custom-tokens} shipped in km-silvery.theme-public-docs — completes the
cross-linked ecosystem.

Also: frameworks.json silvery entry updated '38 palettes' → '84 color schemes'
(catalog growth from the km-silvery.theme-catalog bead).

Bead: km-silvery.theme-public-docs (terminfo.dev side)

Author: beorn

content/frameworks.json

@@ -7,7 +7,7 @@
     "runtime": "Bun / Node.js",
     "description": "React TUI framework with 30+ components, layout feedback, 100+ terminal protocol sequences. 177KB gzipped, zero native dependencies.",
     "baseline": "modern",
-    "body": "<p><strong>Silvery</strong> is a React-based TUI framework that brings component-driven development to the terminal. With 30+ built-in components (SelectList, TextInput, VirtualList, CommandPalette, ProgressBar), semantic theming with 38 palettes, and layout feedback via useBoxRect, it enables responsive terminal UIs that were previously impossible.</p><p>Silvery works best with the <strong>Modern TUI</strong> baseline — truecolor for its theme system, mouse tracking for interactive components, bracketed paste for text input, and synchronized output for flicker-free rendering. It gracefully degrades on terminals missing Rich features (Kitty keyboard, graphics protocols).</p><div class=\"callout-tip\"><p class=\"callout-title\">Origin story</p><p>Building Silvery required understanding exactly which terminal features could be relied on — and which couldn't. That need led directly to <a href=\"https://termless.dev\" class=\"hover-link\">Termless</a> (headless terminal testing) and <a href=\"/\" class=\"hover-link\">terminfo.dev</a> (this site). The feature matrix, baselines, and probe infrastructure all exist because Silvery needed answers that didn't exist anywhere else.</p></div>"
+    "body": "<p><strong>Silvery</strong> is a React-based TUI framework that brings component-driven development to the terminal. With 30+ built-in components (SelectList, TextInput, VirtualList, CommandPalette, ProgressBar), semantic theming with 84 color schemes, and layout feedback via useBoxRect, it enables responsive terminal UIs that were previously impossible.</p><p>Silvery works best with the <strong>Modern TUI</strong> baseline — truecolor for its theme system, mouse tracking for interactive components, bracketed paste for text input, and synchronized output for flicker-free rendering. It gracefully degrades on terminals missing Rich features (Kitty keyboard, graphics protocols).</p><div class=\"callout-tip\"><p class=\"callout-title\">Origin story</p><p>Building Silvery required understanding exactly which terminal features could be relied on — and which couldn't. That need led directly to <a href=\"https://termless.dev\" class=\"hover-link\">Termless</a> (headless terminal testing) and <a href=\"/\" class=\"hover-link\">terminfo.dev</a> (this site). The feature matrix, baselines, and probe infrastructure all exist because Silvery needed answers that didn't exist anywhere else.</p></div>"
   },
   "ink": {
     "label": "Ink",

docs/.vitepress/config.ts

@@ -346,6 +346,9 @@ function buildSidebar() {
         { text: "TTY Architecture", link: "/fundamentals/tty-architecture" },
         { text: "Terminal Modes & stty", link: "/fundamentals/stty" },
         { text: "Terminal Detection", link: "/fundamentals/term-detection" },
+        { text: "Color Fundamentals", link: "/fundamentals/color-fundamentals" },
+        { text: "Color Schemes", link: "/fundamentals/color-schemes" },
+        { text: "Color Detection", link: "/fundamentals/color-detection" },
         { text: "Terminal Security", link: "/fundamentals/security" },
       ],
     },
@@ -491,6 +494,21 @@ export default defineConfig({
       pageData.description =
         "Terminal attack surfaces \u2014 OSC 52 clipboard exfiltration, OSC 8 hyperlink spoofing, paste injection without bracketed paste, escape sequence injection in logs, and title bar spoofing."
     }
+    if (rel === "fundamentals/color-fundamentals.md") {
+      pageData.title = "Terminal Color Fundamentals: ANSI 16, 256-Color, Truecolor"
+      pageData.description =
+        "Three generations of terminal color \u2014 ANSI 16 named slots, 256-color indexed cube, 24-bit truecolor hex. SGR vs OSC escape families, the SGR attrs (bold, dim, italic, underline, inverse), and how modern TUIs negotiate tiers."
+    }
+    if (rel === "fundamentals/color-schemes.md") {
+      pageData.title = "Terminal Color Schemes: The 22-Slot User-Configurable Palette"
+      pageData.description =
+        "The 22-slot color scheme every major terminal exposes: 16 ANSI + foreground, background, cursor (\u00d7 2), selection (\u00d7 2). How applications adopt the user's theme via OSC 10/11/4/12/17/19 queries."
+    }
+    if (rel === "fundamentals/color-detection.md") {
+      pageData.title = "Terminal Color Detection: NO_COLOR, COLORTERM, OSC Probes"
+      pageData.description =
+        "The detection stack TUIs use to pick truecolor, 256-color, ANSI 16, or monochrome \u2014 NO_COLOR, COLORTERM, $TERM, OSC 10/11/4 probing, and graceful tier degradation."
+    }
 
     // Static index pages
     if (rel === "standards.md") {
@@ -690,6 +708,9 @@ export default defineConfig({
           { text: "TTY Architecture", link: "/fundamentals/tty-architecture" },
           { text: "Terminal Modes & stty", link: "/fundamentals/stty" },
           { text: "Terminal Detection", link: "/fundamentals/term-detection" },
+          { text: "Color Fundamentals", link: "/fundamentals/color-fundamentals" },
+          { text: "Color Schemes", link: "/fundamentals/color-schemes" },
+          { text: "Color Detection", link: "/fundamentals/color-detection" },
           { text: "Terminal Security", link: "/fundamentals/security" },
         ],
       },

docs/fundamentals/color-detection.md

@@ -0,0 +1,127 @@
+---
+outline: [2, 3]
+prev: false
+next: false
+---
+
+# Color Detection
+
+<p class="page-tagline">NO_COLOR, COLORTERM, OSC probes — how applications figure out what color to emit</p>
+
+<div class="beginner-intro">
+<p>Before emitting its first colored byte, a TUI must decide: is this terminal truecolor, 256-color, ANSI 16, or monochrome? Should I use color at all? Applications answer these with a stack of detection signals — environment variables, terminal queries, and explicit opt-outs. Getting the stack right is the difference between "looks great in every terminal" and "spews mojibake on SSH."</p>
+</div>
+
+## The detection stack
+
+Modern applications consult signals in this order (highest priority first):
+
+1. **Explicit app flags** — `--no-color`, `--color-tier=<tier>`, app-specific `SILVERY_COLOR`, `CLICOLOR_FORCE`
+2. **`NO_COLOR`** (any value) → disable color entirely ([no-color.org](https://no-color.org))
+3. **`TERM=dumb`** → disable color entirely
+4. **Not a TTY** (`!isatty(stdout)`) → disable color (pipe-safe)
+5. **`COLORTERM=truecolor` or `=24bit`** → enable truecolor
+6. **`TERM=*-direct`** → truecolor (less common convention)
+7. **`TERM=*-256color`** → 256-color
+8. **`TERM` contains `xterm` / `screen` / `tmux` / `rxvt`** → ANSI 16
+9. **Fallback** → ANSI 16 (or mono if in doubt)
+
+This is a heuristic stack. Lower tiers are safer defaults; higher tiers require explicit signals.
+
+## `NO_COLOR` — the universal opt-out
+
+The [no-color.org](https://no-color.org) standard: if `NO_COLOR` is set to any non-empty value, applications MUST NOT add color to their output. This is an accessibility + user-preference feature, not a capability question. Honor it absolutely.
+
+```sh
+NO_COLOR=1 myapp     # no color
+NO_COLOR= myapp      # empty → treated as unset (color OK)
+```
+
+Implementation: check `process.env.NO_COLOR` before anything else. If set, render mono-only. Applications that attempt to "override" NO_COLOR lose user trust.
+
+## `COLORTERM` — the truecolor flag
+
+Set by terminal emulators that support 24-bit color. Values:
+
+- `truecolor` — canonical
+- `24bit` — older alternative
+
+Either value signals truecolor support. Modern terminals set it automatically. If it's unset, assume at most 256-color (the `*-256color` `$TERM` heuristic is a decent backup).
+
+## `$TERM` — the baseline claim
+
+`$TERM` tells you how the terminal wants to be *treated*, not what it actually is. See [Terminal Detection](/fundamentals/term-detection) for the full discussion. For color purposes, the practical rules:
+
+| `$TERM` pattern | Tier inferred |
+|-----------------|---------------|
+| `dumb` | mono |
+| `*-direct` | truecolor |
+| `*-256color` | 256-color |
+| `*xterm*`, `*screen*`, `*tmux*`, `rxvt*` | ANSI 16 (fallback: assume COLORTERM for truecolor) |
+| empty | mono |
+
+Most modern terminals ship `$TERM=xterm-256color` — the broadest compatibility setting — even when they support truecolor. `COLORTERM` is the truecolor signal; `$TERM` is the baseline floor.
+
+## OSC probing — the authoritative check
+
+Environment variables lie. Applications that really need to know can ask the terminal directly via OSC queries:
+
+### OSC 10/11 — foreground/background
+
+```
+\e]10;?\a           # query foreground
+\e]11;?\a           # query background
+```
+
+Response: `\e]10;rgb:abcd/ef12/3456\a` (each channel is 16-bit hex in most terminals). Timing out? The terminal probably doesn't support the query — degrade gracefully. See [OSC colors](/extensions/osc-colors) for the support matrix.
+
+### OSC 4 — ANSI slots
+
+```
+\e]4;<index>;?\a    # query ANSI slot index (0–15 portable, 16–255 for 256-color)
+```
+
+Same response shape as OSC 10/11. Slot 0–15 are the ANSI palette.
+
+### OSC 12 — cursor color
+
+```
+\e]12;?\a           # query cursor color (background under cursor)
+```
+
+### OSC 17/19 — selection
+
+```
+\e]17;?\a           # selection background
+\e]19;?\a           # selection foreground
+```
+
+Less widely supported — iTerm2, Kitty, and Terminal.app do; many others drop the query silently.
+
+### Practical probing
+
+- Set a short timeout (100–200ms). Terminals that don't support a query won't respond — don't block on it forever.
+- Run queries in parallel when possible (fire all OSC writes, then collect responses).
+- Accept partial results: missing slots fall back to formulas (e.g., `cursorText = background` is universally safe).
+- Put the terminal into raw mode for the probe; restore the prior mode after.
+
+The [@silvery/theme-detect](https://npmjs.com/package/@silvery/theme-detect) library implements a full probe + fingerprint pipeline you can drop into any TUI.
+
+## Degradation strategy
+
+After detection, emit at the detected tier:
+
+- **truecolor** — full 16.7M via `\e[38;2;r;g;bm`
+- **256-color** — quantize hex to the 256-color cube's nearest index, emit `\e[38;5;Nm`
+- **ANSI 16** — map to named slots, emit `\e[31m` / `\e[91m` / etc. Let the user's theme decide what "red" looks like.
+- **mono** — strip color, rely on SGR attrs (bold, inverse, underline) for hierarchy
+
+Your semantic token (`$error`) resolves to different concrete outputs depending on tier, but the *token* stays the same in your component code. That's the point of the abstraction.
+
+## See also
+
+- [Color Fundamentals](/fundamentals/color-fundamentals) — ANSI 16 / 256 / truecolor escape sequences
+- [Color Schemes](/fundamentals/color-schemes) — the 22-slot user-configurable scheme
+- [Terminal Detection](/fundamentals/term-detection) — broader detection mechanisms
+- [OSC color queries](/extensions/osc-colors) — per-terminal support matrix
+- [silvery.dev/guide/capability-tiers](https://silvery.dev/guide/capability-tiers) — silvery's detection + degradation implementation

docs/fundamentals/color-fundamentals.md

@@ -0,0 +1,95 @@
+---
+outline: [2, 3]
+prev: false
+next: false
+---
+
+# Color Fundamentals
+
+<p class="page-tagline">ANSI 16, 256-color, truecolor, and the escape sequences that carry them</p>
+
+<div class="beginner-intro">
+<p>Terminals speak color through escape sequences. Three generations of color specs coexist: ANSI 16 (1980s), 256-color indexed (1990s), and truecolor (2000s). Each adds capability without breaking the last. Understanding which terminal supports which — and how applications negotiate down when needed — is the foundation of every modern TUI.</p>
+</div>
+
+## The three color generations
+
+### ANSI 16
+
+The original color model from the VT100 era. Sixteen named colors — 8 base plus 8 bright variants — accessed by `SGR` codes 30–37 (fg) and 40–47 (bg), plus 90–97 and 100–107 for the bright variants. These are **named slots**, not specific RGB values. Your terminal emulator chooses what "red" actually looks like; the same ANSI "red" is crimson in Solarized Dark, peach in Gruvbox, and tomato in default xterm.
+
+```
+\e[31m red text \e[0m              # normal red
+\e[91m bright red text \e[0m       # bright red
+\e[1;31m bold+red text \e[0m       # bold changes color on some terminals
+```
+
+The user's color scheme maps the 16 names to actual hex values. This is what makes ANSI 16 *portable*: you write "red" and the user's theme decides whether that's vivid or muted. It's also what makes it *unreliable* if your app needs a specific shade — the same ANSI code renders differently everywhere.
+
+### 256-color indexed
+
+xterm introduced a 256-color palette in the 1990s: 16 ANSI (as above) + 216 RGB cube entries (6×6×6 with 51-unit steps) + 24 grayscale steps. Accessed via `\e[38;5;<n>m` for fg and `\e[48;5;<n>m` for bg.
+
+```
+\e[38;5;196m vivid red (cube)    \e[0m   # index 196 = #FF0000
+\e[38;5;244m middle gray         \e[0m   # index 244
+```
+
+The RGB cube entries (16–231) map to fixed hex values — theme-independent. This is the cheapest way to get "specific color" without requiring truecolor. Index 16–231 formula: `16 + 36*r + 6*g + b` where `r,g,b ∈ 0..5`. Grayscale 232–255: evenly-spaced grays from near-black to near-white.
+
+Terminals almost universally support 256-color (it's 30+ years old). Whether an application *uses* it depends on `$TERM` (`*-256color` signals support) and `COLORTERM`.
+
+### Truecolor (24-bit)
+
+The modern standard: full 16.7M colors via `\e[38;2;<r>;<g>;<b>m` (fg) and `\e[48;2;<r>;<g>;<b>m` (bg). Each channel is 0–255. No palette, no indirection — the terminal renders exactly the RGB you send.
+
+```
+\e[38;2;255;87;34m #FF5722 \e[0m
+```
+
+Almost every modern terminal supports truecolor (Ghostty, Kitty, iTerm2, WezTerm, Alacritty, Windows Terminal, modern xterm, GNOME Terminal). See [Color compliance](/display/color-truecolor) for the per-terminal matrix.
+
+## SGR vs OSC — two different escape families
+
+Color delivery uses two escape-sequence families:
+
+- **SGR (Select Graphic Rendition)** — inline character styling. Embedded in text output. The `\e[...m` codes above are SGR. Applied per-cell as the terminal parses the stream.
+- **OSC (Operating System Command)** — out-of-band terminal queries and configuration. `\e]10;?\a` asks the terminal "what's your foreground color?"; the terminal replies with `\e]10;rgb:abcd/ef12/3456\a`. OSC sets the palette, not the content.
+
+Your app emits SGR to color its output. Your terminal emits OSC responses when probed. The color scheme lives in OSC; the colored characters flow as SGR. Confusing these is a common source of bugs — see [Terminal Detection](/fundamentals/term-detection).
+
+## The SGR attrs that aren't colors
+
+SGR also carries **attrs** — bold, italic, underline, inverse, dim, strikethrough. These layer *on top of* color and are independent of it. Universally supported attrs:
+
+| Code | Attr | Note |
+|------|------|------|
+| `1` | bold | Some terminals also brighten the color |
+| `2` | dim | Uneven support — alpha-blend on some, intensity-reduction on others |
+| `3` | italic | Truly italic if the font has an italic variant; slanted otherwise |
+| `4` | underline | Basic single underline |
+| `7` | inverse | Swaps fg + bg |
+| `9` | strikethrough | Newer — check [terminal matrix](/text) |
+| `22` | normal intensity | Turns off bold/dim |
+| `23` | no italic | |
+| `24` | no underline | |
+| `27` | no inverse | |
+
+Modern terminals add curly/dotted/dashed underlines, underline colors, and more — see [underlines](/text/underline-style).
+
+## Portability: writing TUI code that works everywhere
+
+Applications face a choice for each colored output:
+
+1. **ANSI 16 always** — maximum compatibility, user's theme wins, can't pin specific shades. Old-school portability.
+2. **Truecolor always** — modern, exact colors, degrades badly on old terminals (color fallback or mojibake).
+3. **Tier-based rendering** — detect at startup, emit the best tier the terminal supports. The right answer for 2020s TUIs.
+
+[silvery](https://silvery.dev) and modern frameworks use approach 3: design in semantic tokens (`$primary`, `$muted`, `$error`), detect the terminal's tier on startup, and let the framework pick ANSI 16 / 256 / truecolor at render time. See [Color Detection](/fundamentals/color-detection) for the detection mechanisms.
+
+## See also
+
+- [Color Schemes](/fundamentals/color-schemes) — the 22-slot user-configurable scheme
+- [Color Detection](/fundamentals/color-detection) — `NO_COLOR`, `COLORTERM`, OSC probes
+- [Truecolor compliance](/display/color-truecolor) — per-terminal test results
+- [256-color support](/display/color-256) — baseline-tier compatibility