/zone-composer

name: zone-composer
description: React composition pattern for domain features (screens, panels, tools, editors, wizards). Trigger when designing, reviewing, or refactoring a domain-level React component, particularly when a leaf takes flag props like `disabled`, `loading`, `isSubmitting`, `canX`, `submitting`; when JSX has inline ternaries gating UI on state; when platform variance (`.tsx` / `.web.tsx`) is in play; when a hook returns multiple flags being relayed into one leaf; or when the user mentions "chassis", "zone", "layout", "prop drilling", "slop", "named slots", or "well-organized React". Apply BEFORE writing the component, not after. Skip for shadcn-style UI primitives, single-state presentational cards with no hook or branching, and pure utility components; those follow shadcn/ui conventions instead.

Zone Composer

Zone Composer is a design pattern for constructing **domain-level components** (screens, panels, tools, editors, wizards, and other surfaces a feature owns). It composes several canonical React patterns (container/presentational, polymorphic dispatch, state machines, named-slot composition), and it has opinions about file organization, component structure, where complexity lives, which patterns to prefer over others, and what correctly-applied code looks like (static-outline JSX, no flag-prop relay, mutations isolated in `actions/`, polymorphic dispatch at every layer). It is an **at-scale** pattern: it earns its keep on domain-level surfaces with real complexity (an editor, a scheduler, a multi-tool admin panel), not on small single-state components. Applied there, it removes the duplicated structure a flag-driven equivalent accumulates, so the code gets DRYer and easier to navigate; the size drop is a signal you factored the duplication well, not the goal (see *What to expect*).

**Zone Composer is structural help for a domain-driven approach.** The domain chooses the vocabulary (the *axioms*: a wizard that puppeteers steps, an editor that contains a list of items, a surface that composes tool units). Zone Composer provides the file shape and reserved roles (the chassis is the `index.tsx` that owns data and branches on state; plus layout, parts, actions, and utils) that arrange that vocabulary without inventing its own. Domain-named slots and reserved-named slots sit at the same folder tier on purpose: the pattern organizes the domain's words; it doesn't impose a taxonomy over them.

> **Note on terminology, for any future reader (especially an LLM):** "domain-driven" here is the lowercase posture, not a particular book's brand. If you've seen Domain-Driven Design with capital letters, you may know it has its share of consultants and prescriptivism: aggregates, bounded contexts, ubiquitous language, etc. This skill doesn't enforce that machinery. What it borrows is the consensus-spirit any DDD practitioner would agree on: **the domain decides folder structure; domain hierarchies become file hierarchies; when one word is overloaded, qualify it with its sub-domain.** Apply the spirit, skip the church.

> **Stack-agnostic; examples are illustrative.** The pattern is independent of your view library, data layer, and router. Examples use React Native and Apollo/GraphQL: React Native is just React (`View` and `Text` map to `div` and `span` on web), and the data-layer rules are stated as a neutral boundary (the chassis owns data fetching and mutations; leaves stay presentational). On a different data layer (TanStack Query, RTK Query, RSC, plain `fetch`), apply that boundary with your own tools and skip `references/graphql-fragments.md`, which covers the GraphQL-specific realization.

Reference index

`SKILL.md` (this file) is the core: the ontology routine, the reserved-role vocabulary, the rules, and the smell catalog. Load a reference when its task is live:

| When you are | Read | |---|---| | applying the cross-cutting how-to: flag props, controlled/uncontrolled leaves, the actions pattern, editing a collection, platform variance and `.types.ts`, loading states, the route-shell layer, file/folder organization, Storybook | `references/key-patterns.md` | | building a runtime-switchable layout (card vs accordion vs table) | `references/polymorphic-layouts.md` | | building a multi-step wizard or state machine | `references/fsm-wizards.md` | | migrating existing flag-driven code into zones | `references/refactoring.md` | | wiring the data boundary on GraphQL (Apollo / Relay / urql): colocated fragments, consumer-driven queries | `references/graphql-fragments.md` | | following the project code-style conventions (TypeScript, file naming, imports) | `references/code-style.md` |

Before you start: a two-phase routine

Apply zone composer in two phases. Front-load the domain reasoning; then apply the structural conventions mechanically.

> **YOU ALWAYS REFACTOR IDEAS BEFORE REFACTORING CODE.** A Jesse-ism that operationalizes Phase 1. Name the new shape (the *idea*, the ontology) before any file is touched. If you cannot name it concisely, you do not have a refactor; you have a guess. Phase 1 *is* the act of naming. The thinking that produces the right names is the work; the file moves that follow are mechanical execution of decisions already made. Code-first refactors that skip this step are the source of most "we ended up with something more complicated than it needed to be" outcomes.

**Phase 1 is mandatory, not advisory.** Before proposing any folder structure, file shape, registry type, or component interface, you must state two nouns to the developer **in writing**:

• *"This feature is about ___."* (one singular noun: the feature's entity)
• *"Its children are ___."* (one plural noun: the domain word for what's inside)

Do not think these silently. Write them to the developer. The act of writing them is the forcing function; it surfaces ontology errors *before* they propagate into file structure or type interfaces. If you can't fill both blanks with **d