/meta-planning-web-planning

name: meta-planning-web-planning
description: Frontend specification planning frameworks. Use when a spec touches UI components, forms, client state, or user-facing flows. Covers UI-state completeness (loading, error, empty, success), component boundaries, form validation contracts, state ownership, and measurable UI success criteria.

Web Planning Frameworks

> **Quick Guide:** A UI spec is a contract about what the user sees in every state, and a state nobody specified still renders — as whatever the developer improvised. For each data-driven surface, specify loading, error, empty and success; for each UI piece, decide reuse, extend or create against a named component; for each form field, the rule, when it fires and the exact message; for each piece of state, one owner; and for each success criterion, what a reviewer will see. Apply a framework only where the feature touches its artifact — a feature with no form carries no form contract.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — bad and good spec fragments for each pattern; read in order, the good ones are the web sections of a worked profile-editing spec

---

<critical_requirements>

Before writing a frontend spec

**Specify loading, error, empty and success for every data-driven surface, or rule a state out in writing.** An unspecified state still renders — as a blank region, a spinner that never resolves, or whatever the developer guessed.

**Decide reuse, extend or create for each UI piece, naming by file and lines the existing component each decision was measured against.** A spec that says "a modal" gets a new modal; one that names the existing modal gets its focus handling and dismissal for nothing.

**Give each form field its rule, when the rule fires, and the exact message.** Timing and wording left open are decided form by form, so two forms in one product validate differently.

**Bound the change to named files and directories, with a do-not-touch list naming each shared store, component and auth surface the feature only consumes.** Without one, the feature "fixes" a shared store or component on the way through and breaks its other consumers.

**Name one owner for each piece of state the feature introduces.** Two owners drift apart after the first update, and state in the wrong owner is the costliest thing in the feature to move later.

**Write each success criterion as something a reviewer can see or do in the UI, with how it is checked.** "Validation works" is met by any implementation; "an invalid email shows 'Enter a valid email address' below the field" is met by one.

</critical_requirements>

---

**Auto-detection:** UI spec, frontend spec, component spec, page spec, form spec, modal spec, loading state, empty state, error state, skeleton screen, validation message, validation timing, error summary, client state ownership, URL state, do-not-touch list, UI acceptance criteria

**Applies to:**

• Specifying new or changed components, pages, dialogs and flows
• Specifying forms: fields, validation, submission, success and failure
• Deciding whether a store, a component or the URL owns each piece of client state
• Writing success criteria a reviewer checks against the rendered UI

**Handled elsewhere:**

• The spec's own structure — goal, context, requirement tiers, the list of files to modify and create, and the handoffs to testing and review — belongs to the specification format these sections sit inside.
• The endpoint the UI calls — its request and response shapes, status codes and auth are specified on the API side; this spec names the endpoint and maps each of its failures to what the user sees.
• How components are built — their internals, data wiring, memoisation and styling approach — is the implementation's; the spec states behaviour and the patterns to follow.
• Visual design — spacing, colour and type are the design system's, and the spec restates none of it.

---

<decision_framework>

Which sections the spec needs

Each yes adds a section. A section the feature never touches is left out rather than filled with "N/A".

• **Renders data, fetched or held locally** → UI states (Pattern 1), one block per surface
• **Includes a form** → form contract (Pattern 3)
• **Introduces or moves client state** → state ownership (Pattern 4)
• **Changes any UI** → component boundaries (Pattern 2), the shared-surface fence (Pattern 5) and observable criteria (Pattern 6)

Inside a section that applies, the rule reverses: a state or field that cannot occur is ruled out in writing, because silence there reads as an oversight.

</decision_framework>

---

<patterns>

Core patterns

Pattern 1: UI-State Completeness

Every data-driven surface gets four states, each specified or ruled out. A surface rendering local data — a cart held in a store, recently viewed items — still gets an empty state; its loading and error are ruled out.

- Loading — what renders, and after what delay it appears
- Error — the message, whether Retry is offered, and what stays on screen
- Empty — first use, and no results for the current filters, where they differ
- Success — one item, many, and overflow: pagination, truncation or scroll

Where the data refreshes after first load, also specify what stays visible during the refresh and what a failed refresh does to data already on screen.

Full fragments: [examples/core.md](examples/core.md#pattern-1-ui-state-completeness)

Pattern 2: Component Boundaries

For each UI piece the feature adds, the spec decides reuse, extend or create, and names what it measured against by file and lines.

- [UI piece] — reuse | extend | create [file:lines] — [what it supplies, or why nothing fits]
- Edit dialog — reuse components/modals/modal-container.tsx:12-78 — focus trap, Escape, overlay

The references a frontend spec usually needs are the nearest component, form, dialog and store, the wrapper the codebase calls its API through, and the v