# Brain Component Composition > Design and maintain composable data-backed Brain MDSvX components for pi-notes. Use when creating or editing `.brain/**/*.svx`, `.brain/components`, `.brain/data`, pi-notes Document Host components, review surfaces, or notes that should render JSONL, SQLite, Postgres, remote data, or reusable web shapes. - Skill: `joelhooks/brain-component-composition` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add joelhooks/brain-component-composition` - Raw SKILL.md: https://api.skillmd.com/api/skills/joelhooks/brain-component-composition/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - License: MIT - Author: joelhooks (https://skillmd.com/u/joelhooks) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/joelhooks/brain-component-composition --- # Brain Component Composition Use this before substantial Brain note, MDSvX component, review surface, or data-backed documentation work. This adapts the useful parts of Vercel's composition patterns to Svelte, MDSvX, and pi-notes. Brain is not flat markdown. Brain is frontmatter, prose, data contracts, and components composed into surfaces that agents and humans can both understand. ## Mandate - Treat `.brain/components` as a real project component library, not demo code. - When a Brain shape repeats or depends on structured data, make or improve a component. - Keep raw machine facts in `.brain/data` or a named data source. Keep `.svx` readable and sparse. - Components should make the data easier for an agent to consume and a human to review. If the component hides provenance or schema, it is wrong. - Prefer components that can later flow into local review pages, static reports, emails, or product pages. ## Brain hierarchy Before designing a Brain surface, locate the relevant layers: 1. System Brain: the user-level Brain, often `~/.brain`, for global operator doctrine, reusable concepts, and cross-project context. 2. Project Brain: `./.brain`, for local projects, areas, resources, archives, receipts, and private domain data. 3. pi-notes core components: baseline components shipped by the Document Host. 4. Project components: `./.brain/components`, for project-specific overrides and richer shapes. Project Brain wins for local facts. System Brain supplies broad operating patterns. Do not fake cross-brain imports if the runtime does not support them yet. Link the source and leave the component/data contract clear. ## Composition workflow 1. Name the shape, for example `TriagePreflight`, `AttributionCharts`, `ReviewCard`, or `ValuePathReview`. 2. Split the contract: - `.svx`: durable prose, headings, links, short summaries, component invocation. - `.brain/data`: JSON, JSONL, SQLite snapshots, receipts, and stable machine records. - `.brain/components`: Svelte components that load, normalize, compose, and render. - data adapter: source path, query, API, schema, freshness, privacy, and provenance. 3. Prefer a shell/provider component that owns data loading and normalization. 4. Compose child components for focused views, summaries, controls, warnings, and receipts. 5. Register top-level MDSvX components in `.brain/pipeline.config.ts` when the local pipeline requires explicit registration. 6. Run `pi-notes brain check` after changes. ## Pattern rules - Composition over configuration. Do not add boolean prop soup to one mega component. - Use explicit variants, for example `TeamSaleReviewCard` over ``. Impossible states should not be representable. - Lift shared state into a provider or data shell. In Svelte, use typed props plus `setContext` and `getContext` when siblings need the same data. - Define a generic interface with `data`, `actions`, and `meta` when a surface has shared data and review actions. - Keep data loading decoupled from presentational children. Children should consume the interface, not know whether data came from JSONL, SQLite, Postgres, or a remote API. - Prefer snippets, children, and nested composition over render-prop-like callback props. - Every data-backed component needs empty, loading, stale, error, and privacy states. - Every component that reads private data needs a clear boundary before anything is published outside local pi-notes. ## Svelte 5 quick rules - Use `$props()` with explicit `Props` interfaces for new Svelte components. - Use `Snippet` and `{@render children?.()}` for composable content. - Prefer callback props and DOM event attributes such as `onclick` over `createEventDispatcher` or legacy `on:` syntax in new code. - Use `$derived` for pure computed state. Use `$effect` only for side effects, subscriptions, DOM work, or browser events. - Use a shell/provider component, type-safe context, or a `.svelte.ts` state capsule when siblings need shared data. - In context, mutate the existing `$state` object. Do not reassign it and break the link. - Use `$state.raw` or plain imports for large static data. Use `$state.snapshot` before sending reactive data to APIs. See [the Svelte 5 appendix](references/svelte-5-brain-components.md) for provider shapes, context rules, examples, and the shipped `examples/brain-provider-variant-surface/` scaffold. ## Agent-readable contract For every new component, leave enough for the next agent to reason without opening a browser: - component name and purpose - input props and expected schema - data source path or query - freshness and privacy rules - action side effects, or explicit read-only status - verification command and any rendered Brain URL if available ## Example shape ```svx --- title: "Latest triage preflight" source: ".brain/data/triage/latest.json" --- # Latest triage preflight ``` `TriagePreflight` loads the snapshot and referenced JSONL, sets a typed context, and composes focused child views. The `.svx` stays readable. The JSON and JSONL remain the machine contract. See [the adapted source map](references/vercel-composition-patterns-map.md) for how the Vercel composition rules map into Brain components.