Zone Composer

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:

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 domain nouns (not implementation gestures like "manager," "registry," "modal"), you're not done with Phase 1; do not proceed. Reaching for Record<string, SomeEntryType> or "let me sketch the interface first" before completing this is the pitfall this section exists to prevent.

Phase 1: Domain discovery (before any code). Don't start by deciding chassis, layout, parts. Start by understanding what this feature is:

1. The folder you're about to make has a name. That name is a domain concept: the entity this feature is about.
2. Does this concept have a hierarchical expression? Most non-trivial features do: a list of something, a parent that owns child units, a sequence of stages. Name the children.
   • A wizard → its children are steps.
   • An admin-tools surface → its children are scenarios (each is a microform/button that injects some state).
   • A slideshow → its children are slides.
   • An editor of items → its children are items (often inside a list tier).
3. Lay out folders to mirror that domain hierarchy. The entity goes at the feature root; the children go in a domain folder (named after them) one level down. If a child has its own children, recurse one more tier (rare).
4. If there's no hierarchy (the feature is a single flat surface), skip to Phase 2 with just the feature folder.

Phase 2: Structural application (drop into each folder). With the domain layout decided, apply the zone composer alphabet inside every folder:

• index.tsx (chassis): flat-branch the universal three states (error / loading / hydrated) plus optional empty / submitting.
• layout.tsx: zone container. Pair with .web.tsx and .types.ts if platform diverges.
• parts/: small UI atoms feature-scoped to this folder.
• actions/ (folder) or actions.tsx (collapsed): transaction hooks.
• utils/: pure helpers grouped by category.
• An orchestration hook (inline / paired with a domain file / standalone use<Feature>.ts / context provider): pick by complexity.
• A <x>.types.ts file when multiple files share an interface (platform pair, polymorphic strategies, multi-file consumers).

Every folder uses the same alphabet. Drop into any tier and you'll see the same reserved roles. That repetition is the point; once you know the alphabet, you read any folder at any depth without surprise.

Heuristic when stuck on "is this a domain concept?" Three quick checks:

• Domain vocabulary: would a domain expert (PM, designer, user) use this word for what the feature does, not how it's built? "Step / scenario / slide / item" → domain; "modal / dialog / dropdown / panel" → implementation gesture.
• Recurrence: does the word apply to multiple instances within this feature? (multiple steps, multiple scenarios, multiple slides). If just one → it's the feature itself, not a sub-domain folder.
• Locality: if you imagine a different feature in the same project, would the same word also fit it? If yes → it probably belongs higher up (components/ui/ or shared), not nested. If no → it's a feature-local axiom and a domain folder is justified.

What it organizes

The pattern speaks to several cross-cutting concerns at once:

• File organization: chassis lives in index.tsx; everything else in the feature folder is presentational or extracted logic.
• Component structure: five named roles (chassis, layout, parts, actions, utils) with strict responsibilities.
• Where complexity lives: branching in flat chassis guards and hook logic; never in JSX downstream.
• Platform variance: .tsx / .web.tsx file pairs, shared .types.ts. Runtime polymorphism (theme, role, flag) uses the same dispatch shape.
• Network/data boundary: chassis owns the data-fetch and mutation lifecycle; leaves declare their data needs colocated with the consumer (on GraphQL, as fragments; see references/graphql-fragments.md).
• Side-effect placement: mutations and toasts live in actions/use<Noun>Actions.ts; component files don't import useMutation or Toast.show.
• Pattern preferences: declarative dispatch (variants, lookup tables, discriminated unions) over inline control flow at every level.

Scope: when zone composer applies

Default for domain features. Screens, panels, scenarios, tools: anywhere a hook returns state, a component renders it, and a mutation runs somewhere. Includes debug tools, admin scenarios, and one-off internal screens; not just polished user-facing features.

Skip the full pattern for:

• UI primitives (shadcn-style reusable components; follow shadcn/ui conventions instead).
• Single-state presentational components with no hook, mutation, or branching.
• Pure utility components with no domain knowledge.

Add layout / parts / domain folders (beyond the minimum chassis + hydrated split) when 2+ are true:

• Platform chrome diverges (.web.tsx swap).
• Presentation chrome may vary at runtime (card ↔ accordion ↔ table).
• Multiple meaningful UI states (error / loading / empty / hydrated).
• Multi-step or branching UI.
• Children need independent GraphQL fragments.
• Refactor-safety is worth extra structure.

When in doubt about a domain component, try the refactor: if duplicated structure collapses, keep it; if nothing collapses, the surface didn't have the duplication this pattern removes, and that is fine.

What to expect

This is an at-scale pattern. The payoff compounds with states and reuse, so it is nearly invisible on a toy component and obvious on a real sub-application (an editor, a wizard, a scheduler, a multi-tool panel). Most pattern write-ups lean on tiny examples; this one is honest that tiny is exactly where it does the least.

The mechanism is duplication removal. Read a surface as layouts × states. Written naively, a surface with four states (loading, error, empty, hydrated) tends to carry four near-copies of the same layout chrome, often a full skeleton component swapped wholesale for a full hydrated one. Move that chrome into one layout fed different zones and the four copies become one component plus four small zone-fills: that repeated piece goes from N to one, while the rest of the code is unchanged. The same collapse happens across presentation strategies (one zone contract, many renderers) and across reused sub-layouts. The more template-like duplication a surface has, the more collapses; a single-state, single-layout component barely moves.

So the code usually gets smaller, but size is a signal, not the goal. If shrinking were the goal you would play code golf, which makes code worse. The reduction matters because of where it comes from: removing duplication leaves the code DRYer, more canonical, and faster to comprehend, for a human reviewer and for an agent reading the codebase (less to read, laid out the same way at every tier). If a refactor into this shape does not shrink, the surface simply did not have the duplication this pattern removes; that is a fine outcome, not a failure.

The vocabulary

A zone-composer feature uses two kinds of folders and files:

1. Reserved roles: five fixed names the pattern always uses when they're present.
2. Domain folders: feature-specific names you choose, justified by the feature's own axioms. The pattern recurses inside them.

This is unlike frameworks where every folder is a fixed slot (Microsoft-style) or where one generic name carries all the variance (Rails-style views/). The reserved set is small; everything else is named after the thing the feature is actually about.

Reserved roles

Chassis naming convention: the chassis is named after the surface kind it represents (Panel, Screen, Editor, Wizard, Inspector, Viewer, Dialog, etc.), and branches into suffixed state components; the hydrated success case drops the suffix:

Layouts stay small (~30 lines). If a layout grows, logic is leaking in.

Parts promotion rule (prevents parts/ from becoming a junk drawer):

• Default: reused only inside one feature → feature/parts/.
• Promote: reused by 2–3+ unrelated features and stable → components/ui/ (shadcn-style).
• Keep local: encodes domain semantics (not just styling) → stay feature-local even if duplicated elsewhere.

Actions return { data, error } tuples and always use async/await: never .then() chains in the action body. Sequential code reads top-to-bottom without mental unwinding.

Utils: file name = category, not individual function. A dates.ts file holds related helpers (displayDate, getMaxDate, temporalToUTC), not one function per file. Tests colocate as <category>.test.ts.

Folder vs file for actions. Same role, different scale. actions/ (folder) is the canonical form when there are multiple transaction hooks or one large enough to warrant its own file. actions.tsx (single file) is the collapsed form when there's just enough to keep together; the role is identical, the boundary is the same. A small feature can write actions.tsx and promote it to actions/use<Noun>Actions.ts later when it grows. The collapsed form shows up most often inside small domain folders.

The orchestration hook

Beyond the five reserved roles, every zone-composer feature has an orchestration hook: the function that holds local state, composes action hooks, dispatches transitions, and returns the destructured state the chassis consumes. It has no fixed filename, which is why it is not counted among the five; only its placement varies. Pick by complexity:

Spectrum, not a hierarchy. As the orchestration grows, more responsibility extracts upward: from inline useState (placement 1) → bundled hook (2) → standalone hook file (3) → provider-as-orchestration (4). Each step extracts more.

Cross-tree state via optional context. When parts of a feature live in separate React trees but should share state (e.g., an editor + a preview screen on a split route), wrap both with a context provider; the orchestration hook reads from context if present, falls back to local state otherwise. Pair useX (required) and useOptionalX (returns null) so Storybook can render leaves in isolation.

The chassis always destructures from the orchestration hook. When following code, the orchestration is always findable: either inline in the chassis function or via the import at the top of index.tsx (./use<Feature>, ./<wizard>.tsx, ./<feature>-context).

Domain folders

Beyond the five reserved roles, a feature may add domain folders (and domain files at the feature root) named after concepts the feature itself owns. These names come from the domain; they're DDD vocabulary, not zone-composer slots. Inside a domain folder, the zone-composer pattern repeats one level deeper, scoped to the sub-domain.

The domain provides the names; zone composer arranges them. A wizard that puppeteers steps, a surface that composes self-contained tool units, an editor that contains a list of items; those are domain hierarchies the feature owns. Zone composer expresses those hierarchies with the same alphabet it uses everywhere else: the chassis lives in index.tsx, an orchestrating sub-domain (e.g., the wizard) sits at the feature root because it's the chassis's peer, and the things it dispatches over live in a domain folder one level down. The parent→child relationship in the file tree mirrors the parent→child relationship in the domain; that's the alignment zone composer is enforcing.

Typical examples of domain folders:

• steps/: when the feature is a multi-step wizard. The folder has its own steps/layout.tsx (a StepLayout), and each step file is a mini-composer that fulfills the StepLayout's zones.
• scenarios/: when the feature is a surface composing many self-contained units. Each scenario file exports its own chassis-leaf split (<Name>Description, <Name>Content, <Name>CTA, <Name>CTALoading) plus a hook use<Name>. The feature's chassis composes scenarios into the larger surface.
• form/: when "form" is the recurring concept inside the feature (an editor of structured rules, for example). The folder has its own form/index.tsx, form/layout.tsx, plus feature-local UI files and its own form/utils/. Same pattern, one level deeper.
• list/ → list/item/: two-level recursion. list/ is the domain folder for the collection; inside, item/ is itself a domain folder for one element, with its own index.tsx, layout.tsx, actions.tsx, etc. A chassis branch like loading.tsx can be broken out to its own file rather than inline when it grows enough to warrant it.

These names aren't interchangeable or generic; each works only because that name is the axiom that specific feature owns. A form/ folder in a feature where forms aren't a coherent axiom would be wrong.

Recipe, not contract. Tooling doesn't enforce this; the pattern is a target. Real codebases accumulate small inconsistencies: components at a domain folder root that could live in a parts/ subfolder, naming variations, etc. When in doubt, follow the recipe; small deviations elsewhere aren't license to abandon it.

Justification rule. A sub-folder exists because its name represents a domain axiom this specific feature owns. If the concept isn't tightly coupled to the feature (if it could plausibly be reused by another feature), it belongs higher up (components/<domain>/) instead, not nested inside.

Sub-domain prefixing rule. When one name is overloaded within a feature or scope, qualify it with its sub-domain. This is the universal move any DDD practitioner would agree on: an overloaded account in a domain that touches finance, identity, and incident reports doesn't disambiguate on its own; it resolves into financial-account / user-account / eyewitness-account, and every consumer says which it means. The same move applies anywhere a reserved or domain name appears more than once in the same folder. Layout disambiguation (editor-layout.tsx, viewer-layout.tsx when more than one layout is in scope; see the Layout row in the reserved-roles table) is one application of this rule, not its definition. Apply it to parts, actions, hooks, anything: when the bare name is ambiguous, the sub-domain prefix carries the meaning.

Recursion rule. Inside a domain folder, the same reserved roles repeat, scoped to the sub-domain. Open one and you'll see the familiar machinery: index.tsx (mini-chassis with the same universal-three / optional-two branching: always error / loading / hydrated, plus empty and submitting when the sub-surface has those concepts), layout.tsx, possibly parts/, actions/ or actions.tsx, utils/. Each file may itself be a mini-chassis. There's no special "second-level" rulebook; it's the same pattern applied again, one scope deeper. The collapsed form (actions.tsx instead of actions/) is common at this scale because the sub-domain is smaller.

Nesting is shallow in practice. Most features stay at one level (feature/steps/..., feature/scenarios/...). Going deeper is rare and usually a sign the feature should split into sibling features instead.

The rules (a stricter standard)

A stricter React pattern, not a divergent one. The rules below catch patterns that snowball into complexity upfront, before they spread.

The forcing question

Before writing or accepting a prop on a React component, ask:

"Does this prop describe the leaf's appearance, or a chassis-level state choice?"

• Appearance (text, color, size, content slot) → real prop, fine.
• Chassis-level state (disabled, loading, isSubmitting, canCreateX, hasError) → prop shouldn't exist; chassis should swap which leaf renders.

Nuance: interaction state on the same component can stay as a flag prop. A SubmitButton that takes isSubmitting because clicking it triggers the mutation owns its in-flight UI; that's its own interaction lifecycle, not a relayed chassis decision. The rule is "no chassis-level flags on leaves," not "no flags ever." Likewise, a leaf may own its input/field state when lifting it would re-render a large list per keystroke or blur a focused input (a search box with a loading state); keep it uncontrolled and read it through a ref at the commit boundary (see When to keep a leaf uncontrolled in references/key-patterns.md).

What "correctly applied" looks like

• The hydrated render reads as a declarative outline: a small DSL over named zones. You can understand the feature by reading index.tsx + the orchestration hook (whichever placement it landed in).
• Zero null guards in hydrated components. All existence checks live at the chassis.
• No flag props relayed downstream for chassis-decided states.
• No useMutation / graphql() / Toast.show() imports in scenario or feature files; those live in actions/.
• Stories ordered by chassis branch: ErrorState, Loading, Hydrated (always); plus NoData and Submitting only when those branches are present in this surface. Order matches the trunk early-return order; the sidebar reads like the chassis.
• Platform pairs share a .types.ts so .tsx and .web.tsx can't drift on contract.
• Duplication collapses (see What to expect). Repeated layout chrome across states and strategies factors into one component fed zones; the code usually gets smaller, but that shrink is the signal, not the target. Per-state accounting: a flag-driven leaf pays for a type, a hook-return field, a prop pass-through, an internal ternary, and the chassis still setting the flag; the zone version is N small leaves the chassis swaps once, with zero downstream branching and O(1) read-time scanning.

When refactoring flag-driven code, watch the duplicated chrome collapse into shared layouts; if nothing collapses, the surface didn't have the duplication this pattern targets. For a step-by-step migration of existing flag-driven code into zones, see references/refactoring.md.

The proactive shape: declarative dispatch

Tactical fallbacks for inline conditionals are reactive. The proactive form: design components so the conditional never needs to exist at the call site. Principle: declarative dispatch over inline control flow: a closed enumeration dispatched declaratively beats branching at every call site. This isn't invented here; it's an existing idea imported from other languages, where the same move appears as message dispatch in Smalltalk, polymorphism in object-oriented languages, and pattern matching in ML and Haskell.

Concrete forms:

• shadcn cva / variants pattern for UI primitives. Instead of <Button className={isDestructive ? '...' : isPrimary ? '...' : '...'}/>:

  const buttonVariants = cva('base-classes', {
    variants: {
      variant: { default: '...', destructive: '...', outline: '...' },
      size: { sm: '...', md: '...', lg: '...' },
    },
  });
  

  Call sites become <Button variant="destructive" size="md"/>. Branching lives in one table; every call site is a closed enumeration tag. Use for any UI primitive with more than one visual mode.
• Named-zone swap at the chassis (same pattern, one level up). if (isSubmitting) return <Layout ctaZone={<CTALoading/>}/>; return <Layout ctaZone={<CTA>: dispatch on chassis state, table is the flat-branch sequence.
• Step lookup objects for multi-step flows: <Wizard currentStep={currentStep} steps={{ selectDay: <SelectDayStep/>, selectTime: <SelectTimeStep/>, ... }}/>. Beats currentStep === 'select-day' ? ... : ... chains.
• Discriminated unions with an exhaustive switch. The type system enforces every case is handled in one location.

components/
  <domain>/                  # Business domains: e.g., session/, account/, billing/
    <feature>/               # Zone-composer features within a domain
      index.tsx              # Chassis
      ...
    <thing>.tsx              # Simple domain components (file = no internal structure)
  ui/                        # shadcn-style UI primitives, reusable, defensive
  charts/, datetime/, ...    # Shared language: cross-domain visual vocabulary
  primitives/                # Low-level web↔native interop infrastructure