--- 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:** Specify every state the UI can be in — loading, error, empty, and success are four different screens, and an unspecified one ships as a blank div. Reference the concrete component and form patterns the implementation must follow (file:line), bound the change to named directories, and write success criteria a reviewer can check with a yes/no: which element appears, what the validation rejects, what the user sees on a network error. --- ## CRITICAL: Before Specifying Frontend Work > **All specifications must be grounded in the codebase's real components, stores, and form patterns** — reference specific files with line numbers **(You MUST specify every UI state the feature can render — loading, error, empty, and success — or explicitly rule one out)** **(You MUST reference the concrete component, form, and store patterns to follow, with file and line numbers)** **(You MUST specify validation per field — the rule, when it fires, and the exact message shown)** **(You MUST bound the change to named files and directories, with an explicit do-not-touch list)** **(You MUST write success criteria as yes/no checks a reviewer can verify — never "works well" or "good UX")** --- **Auto-detection:** UI spec, component spec, frontend feature spec, form spec, modal spec, loading state, empty state, error state, client state design, frontend success criteria **When to use:** - Specifying new or changed UI components, pages, or flows - Specifying forms: fields, validation rules, submission behavior, error display - Specifying where client state lives and which store owns it - Specifying loading, error, empty, and success behavior - Defining measurable success criteria for user-facing work **When NOT to use:** - When implementing components (use the relevant web implementation skill) - For the API the UI calls (use the api planning skill) - For the planning PROCESS itself — research, scope fencing, success criteria structure — which the PM agent carries **Key patterns covered:** - UI-state completeness (loading, error, empty, success) - Pattern-reference discipline for components, forms, and stores - Form contracts: fields, validation, submission, feedback - State ownership and reuse boundaries - Scope fencing by directory - Measurable UI success criteria **Detailed Resources:** - [examples/core.md](examples/core.md) - Spec fragments and a worked example specification --- ## Philosophy **A UI spec is a contract about what the user sees, in every state.** The happy path is the easy fifth of the work; the loading spinner, the validation message, the empty list, and the failed request are where an unspecified feature quietly becomes four different developers' four different guesses. **When specifying frontend work:** - Find the closest existing component, form, and modal first — their patterns are the spec's vocabulary, referenced by file:line - Walk the feature through all four states — loading, error, empty, success — and write down what each renders - Specify validation as the user experiences it: the rule, when it fires, and the exact message - Name what must NOT change: the stores, shared components, and auth surfaces the feature merely touches **When NOT to specify:** - Don't specify implementation details (hook wiring, memoization) — behavior and patterns, not code - Don't design new UI primitives when the codebase's component library covers the need - Don't specify visual design beyond what the existing design system already decides - Don't add "should have" enhancements to the must-have list — scope creep starts in the spec **Core principles:** - **Four states or an explicit ruling-out**: an unhandled state ships as a blank screen - **Patterns by reference, not description**: "follow SettingsForm.tsx:45-89" beats "use proper form handling" - **State has one owner**: name the store or component that holds each piece; duplicated state is a spec defect - **Criteria are yes/no**: "invalid email shows an error message" is checkable; "validation works" is not --- ## Core Patterns ### Pattern 1: UI-State Completeness Every data-driven surface has four states. Specify each, or explicitly rule it out. ```markdown ## UI States For EACH data-driven surface the spec adds or changes: - [ ] Loading — what renders while data is in flight (skeleton, spinner, disabled control) - [ ] Error — what the user sees on failure, and whether retry is offered - [ ] Empty — what renders with zero items, and whether a call-to-action belongs there - [ ] Success — the populated state, including singular/plural and overflow behavior ``` ``` BAD: "Show the user's projects" GOOD: "Loading: 3 skeleton rows. Error: inline message with Retry button. Empty: 'No projects yet' with a Create button. Success: project cards, newest first, 20 per page." ``` **Why this matters:** the unspecified states are the ones users hit at the worst moments — slow networks and failures. A spec that covers only success delegates the other three to chance. --- ### Pattern 2: Pattern-Reference Discipline Reference the concrete implementation to follow, never a style in the abstract. ``` BAD: "Use proper form handling" GOOD: "Follow the form pattern from SettingsForm.tsx:45-89. Use the same validation approach, error display, and success messaging." BAD: "Open it in our usual modal" GOOD: "Use the ModalContainer pattern from components/modals/UpdateAllProjects.tsx:12-78 — overlay, positioning, and onClose handled by the container." ``` **Rules the spec must state:** - Every referenced pattern names a file and line range that was actually read — an unverified reference is a guess - Why each pattern is the right reference, in one line - Which utilities and components must be reused rather than re-created (validation helpers, API client wrappers, shared inputs) --- ### Pattern 3: Form Contracts A form is specified field by field, then as a whole. | Element | Specify | | ----------- | --------------------------------------------------------------------------------- | | Fields | Name, input type, initial value and where it comes from | | Validation | Rule per field, when it fires (on blur, on submit), exact error message | | Submission | What is sent, to which endpoint, and the button's disabled-while-pending behavior | | Success | The message or navigation that confirms the save | | Failure | Network and server-validation errors — what is shown, what is preserved | | Dirty state | Whether unsaved changes warn on close/navigation | ``` BAD: "Validate the email" GOOD: "email: required, format-validated on blur. Invalid: 'Enter a valid email address' below the field. Submit disabled while pending; server 422 maps field errors back to the matching inputs, values preserved." ``` --- ### Pattern 4: State Ownership Every piece of state has exactly one named owner. ```markdown ## State Ownership For EACH piece of state the feature introduces or touches: - [ ] Owner named: which store, or which component's local state - [ ] Derived values computed, not stored — if it can be computed from existing state, it is - [ ] Server data cached through the codebase's existing data-fetching layer, not mirrored into a store - [ ] Existing store structures unchanged unless the spec explicitly changes them ``` **Why this matters:** state added in the wrong place is the hardest thing to move later. A spec that says "add updateProfile to UserStore, do not restructure it" prevents both the second store and the accidental rewrite. --- ### Pattern 5: Scope Fencing by Directory Bound the change in file terms, both directions. ```markdown ## Scope Boundaries **Files to Modify:** [each named file, with what changes in it] **Files to Create:** [each new file, with its purpose] **Files NOT to Touch:** [the stores, shared components, and auth surfaces the feature merely consumes — with why each is off-limits] ``` ``` BAD: "Don't break anything" GOOD: "Do not modify: the authentication flow (auth/), existing stores (stores/), shared components (components/shared/). Changes are limited to profile/." ``` A verification command belongs with the fence: `git diff -- ` should be empty. --- ### Pattern 6: Measurable UI Success Criteria Each criterion is a yes/no check with a named verification method. ``` BAD: - Feature works well - Good user experience - No bugs GOOD: 1. Clicking "Edit Profile" opens the modal with current name, email, bio 2. Invalid email shows 'Enter a valid email address'; valid input clears it 3. Save updates the profile and shows the success message within 2 seconds 4. Network failure shows the retry message; entered values are preserved 5. All interactive elements reachable by keyboard; focus returns to the trigger button on close 6. No changes outside profile/ (git diff -- stores/ components/shared/ is empty) ``` **Rules the spec must state:** - Each criterion names how it is verified: a test file, a manual check, or a command - Accessibility criteria are stated for what the feature adds — keyboard reachability, focus behavior, labels - Performance criteria carry a number when they exist at all ("under 2 seconds", not "fast") --- ## Decision Framework ### Which Spec Sections Does This Feature Need? ``` Does the feature render data from an async source? ├─ YES → UI States section (Pattern 1) — all four states └─ Does it include a form? ├─ YES → Form Contract section (Pattern 3), field by field └─ Does it introduce or move client state? ├─ YES → State Ownership section (Pattern 4) └─ NO → Pattern references + scope fence + criteria may be the whole spec ``` Always applicable: Pattern-reference discipline (Pattern 2), Scope fencing (Pattern 5), Measurable criteria (Pattern 6). ### Common Spec Failures | Failure | Consequence | | -------------------------------------- | ------------------------------------------------------------- | | Only the success state specified | Loading, error, and empty ship as blank or broken screens | | "Use proper form handling" | Each form invents its own validation timing and error display | | No do-not-touch list | The feature "fixes" a store and breaks its other consumers | | Criteria like "works well" | Nothing gates the merge; review becomes opinion | | Server data mirrored into a store | Two sources of truth; stale UI after every mutation | | Pattern reference without line numbers | The reference was never verified to exist | --- ## RED FLAGS **High Priority Issues (a spec with one of these is incomplete):** - A data-driven surface with no loading, error, or empty behavior specified - A form without per-field validation rules and messages - No do-not-touch list on a feature that consumes shared stores or components - Success criteria that cannot be answered yes/no **Medium Priority Issues:** - A new component where the referenced codebase pattern already provides one - State introduced without a named owner - Accessibility unmentioned on new interactive elements - A pattern reference to a file that was never read **Common Mistakes:** - Specifying the modal's content but not its close/cancel/focus behavior - Leaving "what happens to entered values on failure" undecided - Writing enhancement wishes into the must-have list - Describing visual design the design system already decides **Gotchas & Edge Cases:** - Empty and error states can coincide (failed load of an empty list) — decide which wins - A disabled submit button needs a reason the user can see - Optimistic updates need a rollback story in the spec, or must be explicitly out of scope --- ## CRITICAL REMINDERS > **All specifications must be grounded in the codebase's real components, stores, and form patterns** **(You MUST specify every UI state the feature can render — loading, error, empty, and success — or explicitly rule one out)** **(You MUST reference the concrete component, form, and store patterns to follow, with file and line numbers)** **(You MUST specify validation per field — the rule, when it fires, and the exact message shown)** **(You MUST bound the change to named files and directories, with an explicit do-not-touch list)** **(You MUST write success criteria as yes/no checks a reviewer can verify)** **Failure to specify these contracts produces UIs whose error and empty states are accidents, whose forms each validate differently, and whose "done" nobody can verify.**