docs: update fuz-stack patterns

Author: ryanatkn

package-lock.json

@@ -25,7 +25,7 @@
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.58.0",
     "@fuzdev/fuz_ui": "^0.191.4",
-    "@fuzdev/fuz_util": "^0.55.0",
+    "@fuzdev/fuz_util": "^0.56.0",
     "@fuzdev/gro": "^0.197.3",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.10.1",

package.json

@@ -388,9 +388,8 @@ file's location on disk.
 Tests live in `src/test/` (NOT co-located). Use `assert` from vitest —
 choose methods for TypeScript type narrowing, not semantic precision.
 `assert(x instanceof Error)` narrows the type;
-`expect(x).toBeInstanceOf(Error)` does not. Some repos have legacy `expect`
-usage — prefer `assert` in new code and migrate opportunistically. Name
-custom assertion helpers `assert_*` (not `expect_*`).
+`expect(x).toBeInstanceOf(Error)` does not. Name custom assertion helpers
+`assert_*` (not `expect_*`).
 
 Use `describe` blocks to organize tests — one or two levels deep is typical.
 Use `test()` (not `it()`).
@@ -428,6 +427,15 @@ TaskContext, error handling, override patterns, and task composition.
 See ./references/css-patterns.md for setup, variables, composites, modifiers,
 extraction, and dynamic theming.
 
+**Minimal component styles**: Components should have minimal or zero custom CSS,
+delegating to fuz_css utilities and design tokens. Use `box`/`row`/`column`
+for layout, token classes for spacing/colors, and `<style>` only for
+component-specific logic (positioning, pseudo-states, responsive breakpoints).
+See css-patterns.md §Component Styling Philosophy for the full guide.
+
+**Class naming**: fuz_css tokens use `snake_case` (`p_md`, `gap_lg`).
+Component-local classes use `kebab-case` (`site-header`, `nav-links`).
+
 ### 3-Layer Architecture
 
 | Layer              | File        | Purpose                                                   |
@@ -449,13 +457,13 @@ extraction, and dynamic theming.
 
 ### When to Use Classes vs Styles
 
-| Need                   | Style tag | Utility class | Inline style |
-| ---------------------- | --------- | ------------- | ------------ |
-| Style own elements     | **Best**  | OK            | OK           |
-| Style child components | No        | **Yes**       | Limited      |
-| Hover/focus/responsive | Yes       | **Yes**       | No           |
-| Runtime dynamic values | No        | No            | **Yes**      |
-| IDE autocomplete       | **Yes**   | No            | Partial      |
+| Need                   | Utility class | Style tag | Inline style |
+| ---------------------- | ------------- | --------- | ------------ |
+| Style own elements     | **Preferred** | Complex cases | OK        |
+| Style child components | **Yes**       | No        | Limited      |
+| Hover/focus/responsive | **Yes**       | Yes       | No           |
+| Runtime dynamic values | No            | No        | **Yes**      |
+| IDE autocomplete       | No            | **Yes**   | Partial      |
 
 ## Dependency Injection
 

skills/fuz-stack/SKILL.md

@@ -433,15 +433,156 @@ are arrays of `StyleVariable` overrides. Theme CSS rendered via
 `render_theme_style()` with higher specificity (default `:root:root`) to
 override bundled theme variables regardless of CSS insertion order.
 
+## Component Styling Philosophy
+
+The fuz stack's core styling principle: **components should have minimal custom
+CSS, delegating styling to fuz_css**. Most components need zero or near-zero
+lines in their `<style>` block. The design system exists so components don't
+reinvent layout, spacing, color, or typography.
+
+### What "Minimal Styles" Looks Like
+
+Well-designed fuz components (fuz_ui, zzz, fuz_code, fuz_gitops) share these
+traits:
+
+- **Many components have no `<style>` block at all** — all styling comes from
+  utility classes and semantic HTML
+- **When `<style>` exists, it's 5-30 lines** — only component-specific layout
+  logic (positioning, complex pseudo-states, responsive breakpoints)
+- **All colors, spacing, typography come from design tokens** — never hardcoded
+  values
+- **Layout uses composites and utilities** — `box`, `row`, `column`, `panel`,
+  `p_md`, `gap_lg` instead of manual flex declarations
+
+```svelte
+<!-- GOOD: No <style> block needed — utility classes handle everything -->
+<div class="column gap_md p_lg">
+  <header class="row gap_sm">
+    <h2>{title}</h2>
+    <small class="text_50">{subtitle}</small>
+  </header>
+  <div class="panel p_md">{@render children()}</div>
+</div>
+```
+
+### Anti-Patterns
+
+These patterns indicate a component is doing too much styling work:
+
+#### Writing flex layout in `<style>` instead of using composites
+
+```svelte
+<!-- BAD: manual flex in <style> -->
+<div class="container">...</div>
+<div class="header">...</div>
+<style>
+  .container { display: flex; flex-direction: column; gap: var(--space_md); }
+  .header { display: flex; align-items: center; }
+</style>
+
+<!-- GOOD: utility classes -->
+<div class="column gap_md">...</div>
+<div class="row">...</div>
+```
+
+#### Referencing design tokens in `<style>` when a utility class exists
+
+```svelte
+<!-- BAD: token reference in <style> for something a class does -->
+<span class="subtitle">...</span>
+<style>
+  .subtitle { color: var(--text_70); font-size: var(--font_size_sm); }
+</style>
+
+<!-- GOOD: utility classes (or semantic HTML) -->
+<small class="text_70">...</small>
+```
+
+#### Repeating the same layout patterns across components
+
+If multiple components each define their own `.sidebar`, `.header`,
+`.content` classes with the same flex/padding/border patterns, those
+should be utility classes, project `style.css` classes, or composites.
+
+#### Hardcoding pixel values
+
+```svelte
+<!-- BAD: hardcoded pixels -->
+<style>
+  .sidebar { width: 220px; padding-top: 40px; }
+</style>
+
+<!-- GOOD: design tokens or CSS custom properties -->
+<style>
+  .sidebar { width: var(--sidebar_width); padding-top: var(--space_xl2); }
+</style>
+```
+
+### When Custom CSS IS Justified
+
+Custom `<style>` blocks are appropriate for:
+
+- **Complex interactive states** — multi-property hover/active/selected
+  combinations, especially with `color-mix` shadows or parent-child selectors
+  like `.parent:hover .child`. Examples: tab shadow state machines,
+  hover-to-reveal controls.
+- **Structural behavior** — `flex-direction: column-reverse` for bottom-up
+  scrolling, `position: sticky/absolute/fixed` with calculated offsets
+- **Responsive layouts** — `@media` queries for structural layout changes
+- **Animations/transitions** — `@keyframes`, `transition` definitions
+- **Rendering contexts** — canvas, 3D, or other surfaces with inherently
+  custom layout
+
+Even justified custom CSS should use design tokens (`var(--space_md)`,
+`var(--border_color)`) rather than hardcoded values.
+
+### Project `style.css` for Shared App Patterns
+
+When a pattern recurs across multiple components in one app but isn't
+general enough for fuz_css, put it in the project's `style.css` (e.g.,
+`src/routes/style.css`). This is the right place for app-scoped shared
+classes — button variants, layout columns, drag indicators, scroll
+shadows, etc.
+
+Mark patterns with `// TODO upstream` if they might belong in fuz_css.
+This keeps component `<style>` blocks focused on truly component-specific
+logic while avoiding premature generalization into the design system.
+
+### Class Naming Conventions
+
+Two naming systems coexist:
+
+- **fuz_css design tokens**: `snake_case` — `p_md`, `color_a_50`, `gap_lg`,
+  `font_size_sm`. These are the global vocabulary.
+- **Component-local classes**: `kebab-case` — `nav-separator`, `edit-sidebar`,
+  `character-entry`. Distinguishes component-scoped styles from design
+  system classes at a glance.
+
+```svelte
+<!-- snake_case = fuz_css utility, kebab-case = component-local -->
+<div class="column gap_md site-header">
+  <nav class="row gap_sm nav-links">...</nav>
+</div>
+
+<style>
+  .site-header { position: sticky; top: 0; z-index: 10; }
+  .nav-links { border-bottom: var(--border_width_1) var(--border_style) var(--border_color); }
+</style>
+```
+
+This convention is aspirational — existing components use `snake_case` for
+component-local classes too. A cross-repo audit will migrate to kebab-case
+over time.
+
 ## When to Use Classes vs Styles
 
-| Need                   | Style tag | Utility class | Inline style |
-| ---------------------- | --------- | ------------- | ------------ |
-| Style own elements     | **Best**  | OK            | OK           |
-| Style child components | No        | **Yes**       | Limited      |
-| Hover/focus/responsive | Yes       | **Yes**       | No           |
-| Runtime dynamic values | No        | No            | **Yes**      |
-| IDE autocomplete       | **Yes**   | No            | Partial      |
+| Need                   | Utility class | Style tag | Inline style |
+| ---------------------- | ------------- | --------- | ------------ |
+| Style own elements     | **Preferred** | Complex cases | OK        |
+| Style child components | **Yes**       | No        | Limited      |
+| Hover/focus/responsive | **Yes**       | Yes       | No           |
+| Runtime dynamic values | No            | No        | **Yes**      |
+| IDE autocomplete       | No            | **Yes**   | Partial      |
 
 ### Rules of Thumb
 
@@ -453,8 +594,10 @@ override bundled theme variables regardless of CSS insertion order.
   and colors (`color_a_50`) maintain consistency; avoid hardcoded values
 - **Inline `style:prop` for runtime values** — dynamic widths, computed
   colors, CSS variable overrides
-- **Keep class strings manageable** — if a `<div>` accumulates 5+ utility
-  classes, consider a `<style>` rule
+- **Utility class strings are fine at length** — 6-12 classes per element is
+  common and works well. Only move to `<style>` when readability suffers
+  (complex responsive logic, multi-property pseudo-elements) not just because
+  the class list is long
 - **`<style>` for responsive layouts** — `@media` queries in component styles
   are conventional; reserve responsive modifiers for simple one-off overrides
 

skills/fuz-stack/references/css-patterns.md

@@ -1,7 +1,8 @@
 # Rust Patterns for the Fuz Ecosystem
 
 **Applies to**: `fuz` (daemon + CLI), `tsv` (parser/formatter), `blake3` (WASM
-bindings). All projects use **Rust edition 2024**, resolver 2.
+bindings), `zzz_server` (axum web server). All projects use **Rust edition
+2024**, resolver 2.
 
 Each project's `CLAUDE.md` is authoritative for project-specific conventions.
 This covers shared patterns.
@@ -355,23 +356,31 @@ without explicit request.
 
 ### Shared
 
-| Crate                 | Purpose          | Used by                            |
-| --------------------- | ---------------- | ---------------------------------- |
-| `serde`, `serde_json` | Serialization    | fuz, tsv (blake3 bench crate only) |
-| `thiserror`           | Error derivation | fuz, tsv                           |
+| Crate                              | Purpose            | Used by                            |
+| ---------------------------------- | ------------------ | ---------------------------------- |
+| `serde`, `serde_json`              | Serialization      | fuz, tsv, zzz_server (blake3 bench crate only) |
+| `thiserror`                        | Error derivation   | fuz, tsv, zzz_server               |
+| `tracing`, `tracing-subscriber`    | Structured logging | fuz, zzz_server                    |
 
 ### Domain-specific
 
-**Async / networking** (fuz):
+**Async / networking** (fuz, zzz_server):
 
 | Crate         | Purpose                        |
 | ------------- | ------------------------------ |
 | `tokio`       | Async runtime                  |
 | `axum`        | HTTP server (built on hyper)   |
-| `reqwest`     | HTTP client                    |
+| `reqwest`     | HTTP client (fuz only)         |
 | `tokio-util`  | CancellationToken, TaskTracker |
 | `parking_lot` | Faster mutex (no poisoning)    |
 
+**Database** (zzz_server):
+
+| Crate               | Purpose                        |
+| -------------------- | ------------------------------ |
+| `tokio-postgres`     | Async PostgreSQL client        |
+| `deadpool-postgres`  | Connection pooling             |
+
 **Parsing** (tsv):
 
 | Crate                | Purpose                             |
@@ -447,10 +456,14 @@ O(log n) binary search on span positions.
 - **Secure file permissions**: `0o600` for files, `0o700` for directories
 - **Environment isolation**: Strip sensitive env vars before spawning sidecars
 
-### Logging (fuz)
+### Logging
+
+**Servers** (zzz_server): `tracing` with `tracing-subscriber` for structured
+logging. axum integrates with `tracing` natively. Use `tracing::info!`,
+`tracing::error!`, etc.
 
-No tracing framework — `eprintln!` for daemon and CLI. Batched request logging
-for performance. `--json` for machine-readable output.
+**CLIs / daemons** (fuz, tsv): `eprintln!` — simple, no framework. Batched
+request logging for performance. `--json` for machine-readable output.
 
 ## Documentation
 

skills/fuz-stack/references/rust-patterns.md

@@ -1141,6 +1141,19 @@ Avoid destructuring if you need to mutate the item (e.g.,
 
 ## CSS in Components
 
+**Goal: minimal `<style>` blocks.** Components should delegate styling to
+fuz_css utility classes and design tokens. Many well-designed components
+have no `<style>` block at all. See `css-patterns.md` §Component Styling
+Philosophy for the full rationale, anti-patterns, and examples.
+
+When a `<style>` block is needed, keep it focused on component-specific
+layout logic (positioning, complex pseudo-states, responsive breakpoints).
+All values should reference design tokens, not hardcoded pixels or colors.
+
+**Class naming**: fuz_css utilities use `snake_case` (`p_md`, `gap_lg`).
+Component-local classes use `kebab-case` (`site-header`, `nav-links`) to
+distinguish them visually.
+
 ### JS Variables in CSS
 
 Use `style:` directive to pass JS values as CSS custom properties: