builder-design-system
Apply the Autonomous Agent Builder design system to the autonomous-agent-builder codebase. Use when building or restyling Builder dashboard pages, adding or auditing primitive components, generating theme presets, wiring status language, motion hooks, or validating a screen against the locked Builder design system.
What this skill does
# Autonomous Agent Builder — Design System Skill
You are applying the **Autonomous Agent Builder design system v0.5** to the `autonomous-agent-builder` codebase. This skill bundles the locked tokens, themes, primitive APIs, page patterns, and status language into a deterministic playbook.
## When to invoke
Use this skill when the user asks you to:
- Build a new page or surface in the agent-builder app
- Restyle an existing page to match the system
- Add or audit a primitive component
- Generate a new theme preset
- Validate that a screen conforms to the system
## What's in this skill
| File | Use |
|---|---|
| `tokens.css` | Single source of truth for color, type, spacing, radii, shadows, status colors. Drop into `frontend/src/index.css` or import alongside it. |
| `themes.json` | Six locked theme presets — `calm`, `operator`, `sage`, `ember`, `midnight`, `paper`. Each declares hue, density, radius, mode. |
| `components.md` | Primitive component API contracts — core (`StatusPill`, `Surface`, `Eyebrow`, `Tabs`, `Button`, `StatusDot`, `Code`, `Kbd`, `Meter`, `Stat`, `Input`, `BrandMark`) + editorial (`EditorialContent`, `KnowledgeCard`, `KnowledgeEditorialSummary`, `MemorySidebar`, `RelatedSidebar`, `TagCloud`, `EmptyState`, `SectionLabel`). |
| `patterns.md` | Page-level patterns — page intro, three-column chrome, condense-on-scroll, configurable design-system drawer, Settings page hierarchy, command palette, status pill rules, **Motion choreography (GSAP)** with named recipes and `data-*` hooks. |
| `status-language.md` | Status taxonomy + tone mapping, plus the **memory-type tones** (`decision` / `pattern` / `correction`). |
## Operating rules
1. **Never invent colors.** Use `var(--*)` tokens or `oklch()` with the system's hue/lightness scale. New accents must be one of the 9 hues in `themes.json`.
2. **Never invent statuses.** Every state-bearing UI must use a status string from `status-language.md` and the `StatusPill` / `StatusDot` primitives.
3. **Always use the primitives** in `components.md` for buttons, surfaces, tabs, dots, pills, eyebrows, code, kbd, editorial blocks, knowledge cards, tag clouds, drawers, empty states, section labels. Never hand-roll equivalents.
3a. **Motion is part of the contract.** When building a List+Detail, Stream, or Dashboard page, attach the right `data-*` hooks (`data-board-section`, `data-agent-stage`, `data-kpi`, `data-cost-bar`, `data-stagger`) so the page picks up the system's choreography automatically. Every new tween must respect `prefers-reduced-motion` and `clearProps: "all"`.
4. **Page intros follow the pattern** in `patterns.md` — Eyebrow + display heading + 60ch lede paragraph + content. No exceptions on top-level pages.
5. **Status pills are read-only.** Don't make them buttons or links — they describe state, they don't change it.
6. **Density is a multiplier**, not a category. Read `--density` and multiply paddings/heights inside primitives. Don't fork primitives per density.
7. **Dark mode is data-driven.** Set `data-theme="dark"` on `<html>` — never hard-code dark hex values in components.
8. **Information architecture beats paint.** The reference system's main value is how it makes Builder objects legible: tasks, runs, approvals, traces, memories, docs, costs, and decisions. Do not stop at matching colors, cards, or typography if the page still hides the operational object in the wrong place.
9. **Theme configuration is a product surface.** Preserve the reference `tweaks.jsx` model: preset cards with mini previews, advanced controls for hue/chroma/density/radius/mode/display face, live CSS-variable updates, and a reset path back to presets. Do not replace it with a static theme picker.
## Standard workflow
When asked to build or modify a page in the codebase:
1. **Read the locked system.** Open `tokens.css`, `components.md`, `patterns.md`. Don't guess.
2. **Identify the page archetype and owning object.** Most pages are one of:
- **List + detail** (Board, Backlog, Inbox): scan many records; selected detail stays secondary.
- **Agent chat + run trace** (Agent): operator chat/voice is one mode; task/run evidence is a separate mode centered on one run.
- **Dashboard** (Metrics, Observability): health bands first, then trace/event/history drill-down.
- **Reference** (Knowledge, Memory): durable records with readable detail, not raw dumps.
3. **Wrap in the standard page intro** (Eyebrow + heading + lede).
4. **Compose with primitives** — never `<div>` a button, never bare-color a status.
5. **Wire status strings** to the lookup in `status-language.md`.
6. **Audit before finishing** — run the checklist at the bottom of `patterns.md`.
## Builder product IA rules
Apply these before page-level styling:
- **Agent is two modes.** Use `Agent chat` for operator-to-Builder-Agent text and realtime voice. Use `Run trace` for task/run inspection: prompt, thinking, tool calls, tool args/results, gates, approvals, logs, diffs, cost, runtime, model, duration, and stop reason.
- **Voice is transport, not a route.** Voice controls live in Agent chat and voice preferences live in Settings. Voice utterances may mirror into Run trace only when they affect run evidence.
- **Board is the work horizon.** Board cards and drawers summarize task ownership, current state, and run list. Detailed thinking/tool/gate inspection belongs in Agent Run trace. Add an "Open in Agent Run trace" path rather than duplicating the full run viewer in the Board drawer.
- **Settings are operator preferences first.** Prefer this order: Voice & Realtime, Agent surface, Board & layout, Runtime, Appearance/design tokens. Do not lead with token controls when the user is configuring how to operate Builder.
- **Design configuration remains rich.** If the app has both a design-system drawer and a Settings page, keep the drawer focused on live theme/preset/advanced preview controls and keep the Settings page focused on durable operator preferences. The Settings page may mirror appearance state, but it should not lose the full configurable theme editor.
- **Compare and Observability stay evidence-first.** Compare should use real AgentRun records and highlight baseline vs variant outcomes. Observability should show health bands, trace waterfall/spans, SDK events, and run history with dense readable drill-down.
- **Knowledge and Memory are reference records.** Use filter/list plus persistent editorial detail. Long-form content must render through `EditorialContent`; never expose final prose as raw `pre` text.
## Theme application
The configurable design system is modeled by the reference `src/tweaks.jsx`. It is a live operator control, not just internal CSS:
- Theme presets bundle `id`, `name`, `tagline`, `hue`, `density`, `radius`, `mode`, `fontDisplay`, and `fontUi`.
- Picking a preset updates all knobs at once and shows a compact preview tile.
- Advanced/custom mode may override `hue`, `accent chroma`, `density`, `radius`, `mode`, and display face independently.
- Persist preferences in one runtime-preference object. Use `null` for "follow preset" overrides so reset is deterministic.
- Apply theme state by setting CSS variables and root attributes/classes; do not branch component styles by theme id.
At minimum the active theme writes:
```css
:root {
--accent-hue: <hue>;
--accent-chroma: <chroma>;
--density: <density>;
--radius-base: <radius>px;
}
:root[data-theme="dark"] { /* dark token overrides */ }
```
All primitives derive every visual from these knobs + the static token base. To add a new theme: append to `themes.json` with a unique `id`, `name`, `tagline`, `hue`, `density`, `radius`, `mode`, and font metadata. Avoid adding per-page theme conditionals.
## Generating a new component
If you must add a new primitive (rare):
1. Confirm an existing primitive doesn't already cover it.
2. Use only `var(--*)` tokens for color, spacing, radius, shadow.
3. Honor `--density` for any vertical padding or height.
4. HRelated in Design
contribute
IncludedLocal-only OSS contribution command center. Auto-refreshes the user's in-flight PR and issue state on invoke so conversations start with full context — no need to brief Claude on what's in flight. Helps the user find issues to contribute to on GitHub, builds per-repo dossiers of what each upstream expects (CLA, DCO, branch convention, AI policy, draft-first, review bots, issue templates), runs deterministic gates before any external action so AI-assisted contributions don't reach maintainers as slop. State is markdown-only: candidate files at ~/.contribute-system/candidates/, repo dossiers at ~/.contribute-system/research/, append-only event log at ~/.contribute-system/log.jsonl. No database, no cloud calls. Use when the user asks about their PRs / issues / contributions, wants to find new work to take on, claim an issue, build/refresh a repo's dossier, or draft a Design Issue or PR. Trigger with "/contribute", "what's my PR status", "find a contribution", "claim issue X", "draft a Design Issue for Y", "refresh dossier for Z".
architectural-analysis
IncludedUser-triggered deep architectural analysis of a codebase or scoped subtree across eight modes — information architecture, data flow, integration points, UI surfaces, interaction patterns, data model, control flow, and failure modes. This skill should be used when the user asks to "diagram this codebase," "map the architecture," "show the data flow," "give me an ERD," "trace control flow," "find the integration points," "verify the layout pattern," "audit the UX architecture," or any similar request whose primary deliverable is mermaid diagrams plus cited reports under docs/architecture/. Dispatches haiku/sonnet sub-agents in parallel for per-mode exploration, then verifies every citation mechanically before any node lands in a diagram. Not for one-off prose explanations of code (use code-explanation) or for high-level system design from scratch (use system-design).
mcp
IncludedModel Context Protocol (MCP) server development and tool management. Languages: Python, TypeScript. Capabilities: build MCP servers, integrate external APIs, discover/execute MCP tools, manage multi-server configs, design agent-centric tools. Actions: create, build, integrate, discover, execute, configure MCP servers/tools. Keywords: MCP, Model Context Protocol, MCP server, MCP tool, stdio transport, SSE transport, tool discovery, resource provider, prompt template, external API integration, Gemini CLI MCP, Claude MCP, agent tools, tool execution, server config. Use when: building MCP servers, integrating external APIs as MCP tools, discovering available MCP tools, executing MCP capabilities, configuring multi-server setups, designing tools for AI agents.
react-native-skia
IncludedDesign, build, debug, and optimise high-polish animated graphics in React Native or Expo using @shopify/react-native-skia, Reanimated, and Gesture Handler. Use when the user wants canvas-driven UI, shaders, paths, rich text, image filters, sprite fields, Skottie, video frames, snapshots, web CanvasKit setup, or performance tuning for custom motion-heavy elements such as loaders, hero art, cards, charts, progress indicators, particle systems, or gesture-driven surfaces. Also use when the user asks for fluid, glow, glass, blob, parallax, 60fps/120fps, or GPU-friendly animated effects in React Native, even if they do not explicitly say "Skia". Do not use for ordinary form/layout work with standard views.
plaid
IncludedProduct Led AI Development — guides founders from idea to launched product. Six capabilities: Idea (discover a product idea), Validate (pressure-test the idea against fatal flaws, problem reality, competition, and 2-week MVP feasibility), Plan (vision intake + document generation), Design (translate image references into a design.md spec), Launch (go-to-market strategy), and Build (roadmap execution). Use when someone says "PLAID", "plaid idea", "help me find an idea", "product idea", "idea from my business", "idea from my expertise", "plaid validate", "validate my idea", "pressure-test", "is this idea good", "find fatal flaws", "validate the problem", "plan a product", "define my vision", "generate a PRD", "product strategy", "plaid design", "design from image", "translate image to design", "create design.md", "extract design tokens", "plaid launch", "go-to-market", "launch plan", "GTM strategy", "launch playbook", "plaid build", "build the app", "start building", or "execute the roadmap".
nextjs-framer-motion-animations
IncludedAdds production-safe Motion for React or Framer Motion animations to Next.js apps, including reveal, hover and tap micro-interactions, whileInView, stagger, AnimatePresence, layout and layoutId transitions, reorder, scroll-linked UI, and lightweight route-content transitions. Use when the user asks to add, refactor, or debug Motion or Framer Motion in App Router or Pages Router codebases, especially around server/client boundaries, reduced motion, LazyMotion, bundle size, hydration, or route transitions. Avoid for GSAP-style timelines, WebGL or 3D scenes, heavy scroll storytelling, or CSS-only effects unless Motion is explicitly requested.