opencodekit 0.18.8 → 0.18.10

package/dist/index.js

@@ -18,7 +18,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 //#endregion
 //#region package.json
-var version = "0.18.8";
+var version = "0.18.10";
 
 //#endregion
 //#region src/utils/errors.ts

package/dist/template/.opencode/agent/explore.md

@@ -6,7 +6,6 @@ steps: 25
 tools:
   edit: false
   write: false
-  bash: false
   todowrite: false
   memory-update: false
   observation: false
@@ -14,6 +13,14 @@ tools:
   websearch: false
   webfetch: false
   codesearch: false
+permission:
+  bash:
+    "*": allow
+    "rm*": deny
+    "git push*": deny
+    "git commit*": deny
+    "git reset*": deny
+    "sudo*": deny
 ---
 
 You are OpenCode, the best coding agent on the planet.
@@ -32,8 +39,14 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 
 ## Tools — Use These for Local Code Search
 
+**Prefer tilth CLI** (`npx -y tilth`) for symbol search and file reading — it combines grep + tree-sitter + cat into one call. See `tilth-cli` skill for full syntax.
+
 | Tool | Use For | Example |
 |------|---------|--------|
+| `tilth` (symbol) | AST-aware symbol search (definitions + usages) | `npx -y tilth handleAuth --scope src/` |
+| `tilth` (read) | Smart file reading with outline for large files | `npx -y tilth src/auth.ts --section 44-89` |
+| `tilth` (glob) | Find files by pattern with token estimates | `npx -y tilth "*.test.ts" --scope src/` |
+| `tilth` (map) | Codebase structural overview | `npx -y tilth --map --scope src/` |
 | `grep` | Find text/regex patterns in files | `grep(pattern: "PatchEntry", include: "*.ts")` |
 | `glob` | Find files by name/pattern | `glob(pattern: "src/**/*.ts")` |
 | `lsp` (goToDefinition) | Jump to symbol definition | `lsp(operation: "goToDefinition", filePath: "...", line: N, character: N)` |
@@ -42,29 +55,32 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 | `read` | Read file content | `read(filePath: "src/utils/patch.ts")` |
 
 **NEVER** use `websearch`, `webfetch`, or `codesearch` — those search the internet, not your project.
+**NEVER** modify files or run destructive commands — bash is for tilth CLI and read-only operations only.
 
 ## Rules
 
 - Never modify files — read-only is a hard constraint
+- Bash is enabled **only** for tilth CLI (`npx -y tilth`) — do not use bash for anything else
 - Return absolute paths in final output
 - Cite `file:line` evidence whenever possible
-- **Always start with `grep` or `glob`** to locate files and symbols — do NOT read directories to browse
+- **Prefer tilth** for symbol search, then fall back to `grep` or `glob`
 - Use LSP for precise navigation after finding candidate locations
 - Stop when you can answer with concrete evidence
 
 ## Navigation Patterns
 
-1. **Search first, read second**: `grep` to find where a symbol lives, then `read` only that section
+1. **tilth first, grep second**: `npx -y tilth <symbol> --scope src/` finds definitions AND usages in one call; fall back to `grep` if tilth is unavailable
 2. **Don't re-read**: If you already read a file, reference what you learned — don't read it again
-3. **Follow the chain**: definition → usages → callers via LSP findReferences
-4. **Target ≤3 tool calls per symbol**: grep → read section → done
+3. **Follow the chain**: definition → usages → callers via tilth symbol search or LSP findReferences
+4. **Target ≤3 tool calls per symbol**: tilth search → read section → done
 
 ## Workflow
 
-1. `grep` or `glob` to discover candidate files
-2. `lsp` goToDefinition/findReferences for precise symbol navigation
-3. `read` only the relevant sections (use offset/limit)
-4. Return findings with file:line evidence
+1. `npx -y tilth <symbol> --scope src/` or `grep`/`glob` to discover symbols and files
+2. `npx -y tilth <file> --section <range>` or `read` for targeted file sections
+3. `lsp` goToDefinition/findReferences for precise cross-file navigation when needed
+4. `npx -y tilth --map --scope <dir>` for structural overview of unfamiliar areas
+5. Return findings with file:line evidence
 
 ## Output
 
@@ -74,6 +90,7 @@ Find relevant files, symbols, and usage paths quickly for the caller.
 
 ## Failure Handling
 
+- If tilth is unavailable, fall back to `grep` + `glob` + targeted `read`
 - If LSP is unavailable, fall back to `grep` + targeted `read`
 - If results are ambiguous, list assumptions and best candidate paths
 - Never guess — mark uncertainty explicitly

package/dist/template/.opencode/agent/general.md

@@ -147,12 +147,14 @@ Before claiming task done:
 
 ## Workflow
 
-1. Read relevant files
+1. Read relevant files (prefer `npx -y tilth <symbol> --scope src/` for fast symbol lookup)
 2. Confirm scope is small and clear
 3. Make surgical edits
 4. Run validation (lint/typecheck/tests as applicable)
 5. Report changed files with `file:line` references
 
+**Code navigation:** Use tilth CLI for AST-aware search when available — see `tilth-cli` skill for syntax. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for symbol definitions.
+
 ## Progress Updates
 
 - For multi-step work, provide brief milestone updates

package/dist/template/.opencode/agent/plan.md

@@ -381,12 +381,14 @@ When planning under constraint:
 
 ## Workflow
 
-1. **Ground**: Read bead artifacts (`prd.md`, `plan.md` if present)
+1. **Ground**: Read bead artifacts (`prd.md`, `plan.md` if present); use `npx -y tilth --map --scope src/` for codebase overview
 2. **Calibrate**: Understand goal, constraints, and success criteria
-3. **Transform**: Launch parallel research (`task` subagents) when uncertainty remains; decompose into phases/tasks with explicit dependencies
+3. **Transform**: Launch parallel research (`task` subagents) when uncertainty remains; use `npx -y tilth <symbol> --scope src/` for fast codebase discovery; decompose into phases/tasks with explicit dependencies
 4. **Release**: Write actionable plan with exact file paths, commands, and verification
 5. **Reset**: End with a concrete next command (`/ship <id>`, `/start <child-id>`, etc.)
 
+**Code navigation:** Use tilth CLI for AST-aware search and `--map` for structural overview — see `tilth-cli` skill.
+
 ## Output
 
 - Keep plan steps small and executable

package/dist/template/.opencode/agent/review.md

@@ -193,11 +193,13 @@ return <div>No messages</div>  // State exists but not used
 
 ## Workflow
 
-1. Read changed files and nearby context
+1. Read changed files and nearby context (prefer `npx -y tilth <symbol> --scope src/` for fast cross-file tracing)
 2. Identify and validate findings by severity (P0, P1, P2, P3)
 3. For each finding: explain why, when it happens, and impact
 4. If no qualifying findings exist, say so explicitly
 
+**Code navigation:** Use tilth CLI for AST-aware symbol search when tracing cross-file dependencies — see `tilth-cli` skill. Prefer `npx -y tilth <symbol> --scope <dir>` over grep for understanding call chains.
+
 ## Output
 
 Structure:

package/dist/template/.opencode/command/ui-slop-check.md

@@ -0,0 +1,146 @@
+---
+description: Audit changed UI files for AI slop patterns and design-system violations
+argument-hint: "[path|auto] [--staged] [--since=<ref>] [--full-report]"
+agent: vision
+model: proxypal/gemini-3-pro-preview
+---
+
+# UI Slop Check: $ARGUMENTS
+
+Run a focused anti-slop audit against changed UI files using the frontend-design taxonomy.
+
+## Load Skills
+
+```typescript
+skill({ name: "frontend-design" }); // Anti-pattern taxonomy + design references
+skill({ name: "visual-analysis" }); // Structured visual/code analysis workflow
+skill({ name: "accessibility-audit" }); // Keyboard/focus/contrast checks
+```
+
+## Parse Arguments
+
+| Argument        | Default | Description                                        |
+| --------------- | ------- | -------------------------------------------------- | ----------------------------------------------------------- |
+| `[path          | auto]`  | `auto`                                             | Specific file/dir to audit, or auto-detect changed UI files |
+| `--staged`      | false   | Audit staged changes only (`git diff --cached`)    |
+| `--since=<ref>` | `HEAD`  | Compare against ref (`main`, `HEAD~1`, commit SHA) |
+| `--full-report` | false   | Include all categories even when no issues found   |
+
+## Phase 1: Resolve Target Files
+
+If `[path]` is provided:
+
+- Audit that path directly
+
+If `auto`:
+
+```bash
+# unstaged + staged by default
+git diff --name-only $SINCE_REF -- \
+  '*.tsx' '*.jsx' '*.css' '*.scss' '*.sass' '*.less' '*.html' '*.mdx'
+```
+
+If `--staged`:
+
+```bash
+git diff --cached --name-only -- \
+  '*.tsx' '*.jsx' '*.css' '*.scss' '*.sass' '*.less' '*.html' '*.mdx'
+```
+
+Prioritize files under:
+
+- `src/components/**`
+- `src/app/**`
+- `src/pages/**`
+- `app/**`
+- `components/**`
+
+If no UI files changed, return: **PASS (no changed UI files)**.
+
+## Phase 2: Run AI Slop Checklist
+
+Evaluate each target file (or rendered screenshot if provided) against these checks.
+
+### A) Typography
+
+- Banned default aesthetics (Inter/Roboto/Arial/Open Sans as dominant display voice)
+- Body text uses `rem/em`, not fixed `px`
+- Clear hierarchy (size/weight/spacing), not color-only hierarchy
+- Body line length near readable measure (around 65ch when applicable)
+
+### B) Color and Theming
+
+- No AI default palette tropes (purple-blue gradient defaults, neon-on-dark clichés)
+- No pure `#000` / `#fff` as dominant surfaces
+- Gray text is not placed on saturated backgrounds
+- Semantic tokens are used (not random per-component hardcoded colors)
+- Dark mode is adapted, not simple inversion
+
+### C) Layout and Spatial Rhythm
+
+- No cards-inside-cards without strong information architecture reason
+- No repetitive cookie-cutter card blocks with identical structure
+- Spacing rhythm is consistent (4pt-style cadence), not arbitrary jumps
+- Uses `gap`/layout primitives cleanly; avoids margin hacks when possible
+
+### D) Motion and Interaction
+
+- No bounce/elastic gimmick motion for product UI
+- Animations use transform/opacity (avoid layout-thrashing properties)
+- Reduced motion support exists for meaningful motion
+- States exist: hover, focus-visible, active, disabled, loading/error where relevant
+
+### E) UX Writing
+
+- Buttons are verb + object (e.g. "Save changes")
+- Error copy includes what happened + why + how to fix
+- Empty states include guidance + next action
+- Terminology is consistent (avoid mixed synonyms for same action)
+
+### F) Accessibility Safety Nets
+
+- Keyboard-visible focus treatment (`:focus-visible`)
+- Contrast baseline expectations (WCAG AA)
+- Touch targets reasonable (44x44 context where applicable)
+
+## Phase 3: Severity and Scoring
+
+Group findings by severity:
+
+- **Critical**: accessibility failures, broken interaction states, unreadable contrast
+- **Warning**: strong AI fingerprint/slop patterns, inconsistent design system usage
+- **Info**: polish/consistency opportunities
+
+Score each category 1-10 and include evidence (`file:line` for code audits).
+
+## Phase 4: Output
+
+Return:
+
+1. **Result**: PASS / NEEDS WORK
+2. **Audited files** (list)
+3. **Category scores**
+4. **Findings by severity** with actionable fixes
+5. **Fast remediation plan** (top 3 fixes first)
+
+If `--full-report` is false, omit empty categories.
+
+## Record Findings
+
+```typescript
+observation({
+  type: "warning",
+  title: "UI Slop Check: [scope]",
+  narrative: "Detected [count] critical, [count] warning slop issues in changed UI files.",
+  concepts: "ui, design, anti-patterns, frontend",
+  confidence: "high",
+});
+```
+
+## Related Commands
+
+| Need                                     | Command      |
+| ---------------------------------------- | ------------ |
+| Design from scratch                      | `/design`    |
+| Full UI review (single screen/component) | `/ui-review` |
+| Implementation work                      | `/start`     |

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.2.24"
+    "@opencode-ai/plugin": "1.2.27"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",

package/dist/template/.opencode/plugin/lib/context.ts

@@ -110,10 +110,14 @@ function compressMessage(msg: TransformMessage): TransformMessage {
  * Keeps first and last sentence, truncates middle.
  */
 function createSummary(text: string, role: string): string {
-	const maxChars = 200;
+	const maxChars = 500;
 
 	if (text.length <= maxChars) return text;
 
+	// For very large messages (>5000 chars), be more aggressive
+	const isLarge = text.length > 5000;
+	const effectiveMax = isLarge ? 300 : maxChars;
+
 	// Split into sentences
 	const sentences = text
 		.split(/(?<=[.!?])\s+|\n+/)
@@ -121,16 +125,16 @@ function createSummary(text: string, role: string): string {
 		.filter((s) => s.length > 0);
 
 	if (sentences.length <= 2) {
-		return `${text.slice(0, maxChars)}...`;
+		return `${text.slice(0, effectiveMax)}...`;
 	}
 
 	const first = sentences[0];
 	const last = sentences[sentences.length - 1];
 
-	const summary = `[compressed ${role} message] ${first} [...${sentences.length - 2} more sentences...] ${last}`;
+	const summary = `[compressed ${role}] ${first} [...${sentences.length - 2} sentences...] ${last}`;
 
-	return summary.length > maxChars * 2
-		? `${summary.slice(0, maxChars * 2)}...`
+	return summary.length > effectiveMax
+		? `${summary.slice(0, effectiveMax)}...`
 		: summary;
 }
 

package/dist/template/.opencode/plugin/lib/db/types.ts

@@ -38,7 +38,7 @@ export const MEMORY_CONFIG = {
 	},
 	context: {
 		enabled: true,
-		maxContextTokens: 100_000,
+		maxContextTokens: 80_000,
 		protectedMessages: 5,
 	},
 	fts: {

package/dist/template/.opencode/plugin/lib/memory-hooks.ts

@@ -90,13 +90,24 @@ export function createHooks(deps: HookDeps) {
 				}
 			}
 
-			// --- Session error: warn user ---
+			// --- Session error: show actual error details ---
 			if (event.type === "session.error") {
-				await showToast(
-					"Session Error",
-					"Save important learnings with observation tool",
-					"warning",
-				);
+				const props = event.properties as Record<string, unknown> | undefined;
+				const errorMsg = props?.error
+					? String(props.error).slice(0, 120)
+					: props?.message
+						? String(props.message).slice(0, 120)
+						: "Unknown error";
+
+				// Classify: match the specific AI SDK error pattern
+				const isTokenOverflow =
+					/token.{0,20}(exceed|limit)/i.test(errorMsg) ||
+					errorMsg.includes("context_length_exceeded");
+				const guidance = isTokenOverflow
+					? "Context too large — use /compact or start a new session"
+					: "Save important learnings with observation tool";
+
+				await showToast("Session Error", `${guidance} (${errorMsg})`, "warning");
 			}
 		},
 

package/dist/template/.opencode/skill/frontend-design/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces. Use when building web components, pages, or applications with React-based frameworks. Includes Tailwind CSS v4, shadcn/ui components, Motion animations, and visual design philosophy for avoiding generic AI aesthetics.
-version: 1.0.0
+version: 1.1.0
 tags: [ui, design]
 dependencies: []
 ---
@@ -21,7 +21,6 @@ dependencies: []
 
 - Backend-only tasks or minimal UI with no visual design requirements.
 
-
 ## Reference Documentation
 
 ### Tailwind CSS v4.1
@@ -46,7 +45,7 @@ Search: `Field`, `InputGroup`, `Spinner`, `ButtonGroup`, `next-themes`
 
 ### Animation (Motion + Tailwind)
 
-- `./references/animation/motion-core.md` - Core API, variants, gestures, layout animations
+- `./references/animation/motion-core.md` - Timing system, easing constants, performance rules, reduced motion, core patterns
 - `./references/animation/motion-advanced.md` - AnimatePresence, scroll, orchestration, TypeScript
 
 **Stack**:
@@ -64,6 +63,15 @@ Search: `Field`, `InputGroup`, `Spinner`, `ButtonGroup`, `next-themes`
 
 For sophisticated compositions: posters, brand materials, design systems.
 
+### Design Systems (Deep Guides)
+
+- `./references/design/color-system.md` - OKLCH, semantic tokens, dark mode architecture
+- `./references/design/typography-rules.md` - Fluid type, modular scale, OpenType features
+- `./references/design/interaction.md` - State models, focus, dialogs/popovers, loading patterns
+- `./references/design/ux-writing.md` - Button copy, error structure, empty states, i18n
+
+Search: `AI Slop Test`, `tinted neutrals`, `focus-visible`, `verb + object`, `65ch`
+
 ## Design Thinking
 
 Before coding, commit to BOLD aesthetic direction:
@@ -74,23 +82,60 @@ Before coding, commit to BOLD aesthetic direction:
 
 Bold maximalism and refined minimalism both work. Key is intentionality.
 
-## Anti-Patterns (NEVER)
+## Anti-Patterns (AI Fingerprints — NEVER)
+
+These patterns immediately signal "AI made this." Avoid them all.
+
+### Typography
+
+- **Banned fonts**: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, Space Grotesk, system-ui as display font
+- Monospace used as "developer aesthetic" shorthand
+- Big icons centered above every heading
+- Using `px` for body text (use `rem`/`em` to respect user settings)
+
+### Color
 
-- Overused fonts: Inter, Roboto, Arial, system fonts, Space Grotesk
-- Cliched colors: purple gradients on white
-- Predictable layouts and component patterns
-- Cookie-cutter design lacking character
-- Generic AI-generated aesthetics
+- **AI palette**: Cyan-on-dark, purple-to-blue gradients, neon accents on dark backgrounds
+- Gray text on colored backgrounds (use darker shade of background color instead)
+- Pure `#000` or `#fff` (always tint — pure black/white don't exist in nature)
+- Gradient text on headings or metrics
+- `rgba()` / heavy alpha transparency as primary palette (design smell — define explicit colors)
+
+### Layout
+
+- Cards nested inside cards (use typography, spacing, dividers for hierarchy within a card)
+- Identical card grids (icon + heading + text repeated 3-6 times)
+- Hero metric template (big number + small label + gradient accent)
+- Center-aligning everything
+- Same spacing everywhere (no visual rhythm)
+
+### Visual
+
+- Glassmorphism used decoratively (blur cards, glow borders)
+- Thick colored border on one side of rounded rectangles
+- Sparklines as decoration (not connected to real data)
+- Generic drop shadows on everything
+- Rounded rectangles as the only shape language
+
+### Motion
+
+- Bounce or elastic easing (real objects decelerate smoothly)
+- Animating `height`, `width`, `padding`, `margin` (causes layout recalculation)
+- Default `ease` (compromise that's rarely optimal — use exponential easing)
+- Missing `prefers-reduced-motion` handling
+
+> **The AI Slop Test**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that's the problem.
 
 ## Best Practices
 
-1. **Accessibility First**: Radix primitives, focus states, semantic HTML
-2. **Mobile-First**: Start mobile, layer responsive variants
-3. **Design Tokens**: Use `@theme` for spacing, colors, typography
-4. **Dark Mode**: Apply dark variants to all themed elements
-5. **Performance**: Automatic CSS purging, avoid dynamic class names
-6. **TypeScript**: Full type safety
-7. **Expert Craftsmanship**: Every detail matters
+1. **Accessibility First**: Radix primitives, `:focus-visible` (not `:focus`), semantic HTML, 44px touch targets
+2. **Mobile-First**: Start mobile, layer responsive variants with `min-width` queries
+3. **Design Tokens**: Two-layer system — primitives (`--blue-500`) + semantic (`--color-primary: var(--blue-500)`); dark mode redefines semantic layer only
+4. **Dark Mode**: Not inverted light mode — lighter surfaces create depth (no shadows); desaturate accents; base at `oklch(15-18% …)`
+5. **Container Queries**: Use `@container` for component layout, viewport queries for page layout
+6. **Performance**: `transform` + `opacity` only for animations; CSS purging; avoid dynamic class names
+7. **TypeScript**: Full type safety
+8. **Expert Craftsmanship**: Every detail matters — squint test for hierarchy validation
 
 ## Core Stack Summary
 
@@ -102,63 +147,88 @@ Bold maximalism and refined minimalism both work. Key is intentionality.
 
 ## Typography
 
-Choose beautiful, unique fonts. Pair distinctive display with refined body:
+→ Consult `./references/design/typography-rules.md` for full fluid type system
+
+Choose distinctive fonts. Pair display with body:
+
+- **Preferred**: Instrument Sans, Plus Jakarta Sans, Outfit, Onest, Figtree, Urbanist (sans); Fraunces, Newsreader (editorial)
+- **Fluid sizing**: `clamp(1rem, 0.5rem + 2vw, 1.5rem)` — never fixed `px` for body
+- **Modular scale**: Pick one ratio (1.25 major third, 1.333 perfect fourth) — 5 sizes max
+- **Measure**: `max-width: 65ch` for body text
+- **OpenType**: `tabular-nums` for data, `diagonal-fractions` for recipes, `all-small-caps` for abbreviations
 
 ```css
 @theme {
-  --font-display: "Playfair Display", serif;
-  --font-body: "Source Sans 3", sans-serif;
+  --font-display: "Fraunces", serif;
+  --font-body: "Instrument Sans", sans-serif;
 }
 ```
 
 ## Color
 
-Use OKLCH for vivid colors. Dominant colors with sharp accents:
+→ Consult `./references/design/color-system.md` for OKLCH deep guide
+
+Use OKLCH for perceptually uniform colors. Two-layer token system:
 
 ```css
 @theme {
-  --color-primary-500: oklch(0.55 0.22 264);
-  --color-accent: oklch(0.75 0.18 45);
+  /* Primitives */
+  --blue-500: oklch(0.55 0.22 264);
+  --amber-400: oklch(0.75 0.18 80);
+  /* Semantic (redefine these for dark mode) */
+  --color-primary: var(--blue-500);
+  --color-accent: var(--amber-400);
+  /* Tinted neutrals — chroma 0.01 for subconscious brand cohesion */
+  --color-surface: oklch(0.97 0.01 264);
+  --color-surface-dark: oklch(0.16 0.01 264);
 }
 ```
 
 ## Motion
 
-**Primary**: Motion for React animations. **Fallback**: CSS `@starting-style` for simple enter/exit.
+→ Consult `./references/animation/motion-core.md` for Motion API
+
+**Timing**: 100-150ms instant feedback | 200-300ms state changes | 300-500ms layout | exit = 75% of enter
+
+**Easing**: Exponential only — `cubic-bezier(0.16, 1, 0.3, 1)` for entrances. Never `ease`, never bounce/elastic.
+
+**Performance**: Only animate `transform` and `opacity`. Height expand → `grid-template-rows: 0fr → 1fr`.
+
+**Accessibility**: `prefers-reduced-motion` is mandatory (affects ~35% of adults over 40). Swap spatial animations for crossfades.
 
 ```tsx
 import { motion, AnimatePresence } from 'motion/react';
 
-// Basic animation
-<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
+<motion.div initial={{ opacity: 0, y: 12 }} animate={{ opacity: 1, y: 0 }}
+  transition={{ duration: 0.3, ease: [0.16, 1, 0.3, 1] }} />
 
-// Exit animations
 <AnimatePresence>
-  {show && <motion.div exit={{ opacity: 0 }} />}
+  {show && <motion.div exit={{ opacity: 0 }} transition={{ duration: 0.2 }} />}
 </AnimatePresence>
+```
 
-// Layout animations
-<motion.div layout />
+CSS stagger: `animation-delay: calc(var(--i, 0) * 50ms)` — cap total at 500ms.
 
-// Gestures
-<motion.button whileHover={{ scale: 1.05 }} whileTap={{ scale: 0.95 }} />
-```
+## Spatial Composition
 
-CSS fallback (no JS):
+- **4pt spacing system**: 4, 8, 12, 16, 24, 32, 48, 64, 96px — not 8pt (too coarse at small gaps)
+- **`gap` over margins** for sibling spacing (eliminates margin collapse)
+- **Self-adjusting grids**: `repeat(auto-fit, minmax(280px, 1fr))` — responsive without breakpoints
+- **Container queries** for components: `container-type: inline-size` on wrapper, `@container` on children
+- **Optical text alignment**: `margin-left: -0.05em` for text that appears indented due to letterform whitespace
+- Asymmetry, overlap, diagonal flow, grid-breaking elements. Generous negative space OR controlled density.
 
-```css
-dialog[open] {
-  opacity: 1;
-  @starting-style {
-    opacity: 0;
-    transform: scale(0.95);
-  }
-}
-```
+## Interaction
 
-## Spatial Composition
+→ Consult `./references/design/interaction.md`
+
+Design all 8 states: Default, Hover, Focus, Active, Disabled, Loading, Error, Success. Use `:focus-visible` not `:focus`. Native `<dialog>` + `inert` for modals. Popover API for tooltips/dropdowns. Skeleton screens over spinners. Undo over confirmation dialogs.
+
+## UX Writing
+
+→ Consult `./references/design/ux-writing.md`
 
-Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+Button labels: specific verb + object ("Save changes" not "OK"). Error formula: What happened + Why + How to fix. Empty states are onboarding opportunities. Plan for 30% text expansion (i18n).
 
 ## Backgrounds