Task: Create PAGESPEC.md for a Single Web Page

Task: Create PAGE_SPEC.md for a Single Web Page

Objective

Produce a PAGE_SPEC.md that pins the full spatial composition of one web page: page shell, named regions, section ordering and grouping, per-component layout overrides, every interactive control with its placement and visibility rule, layout differences across states, breakpoint reflow, page-specific motion, and accessibility commitments beyond the global rules. The defining discipline — and the definition of "done" — is that the gap between the design layer and the page is purely compositional: an implementing agent reading WEB_IA.md's per-page blueprint, DESIGN.md's tokens and components, and this PAGE_SPEC.md composes the page exactly as designed without inventing any spatial decision (token literals, region anchors, button order, breakpoint reflow, focus order). PAGE_SPEC is a Tier 2 leaf artifact: WEB_IA.md owns identity (the page exists, has these named sections, has these states); PAGE_SPEC.md owns composition (where everything sits, how it groups, how it reflows).

The commonest violation is silently inventing a token literal, a component variant, or a layout template name that does not exist in DESIGN.md. When DESIGN.md is silent, ambiguous, or contradictory on a question the page must answer — a token for a specific spacing, a component for a specific affordance, a breakpoint name — the question belongs in § 12 Open Questions with options, tradeoffs, and a recommendation. Do not invent. The PAGE_SPEC must never introduce a design decision that is not already traceable to DESIGN.md (tokens, components, templates, breakpoints, motion principles) or WEB_IA.md (sections, primary CTA, states, data dependencies, traceability).

Inputs

1. Page identifier (required) — the stable ID from WEB_IA.md (e.g., B5, C1). The skill operates on exactly one page per invocation. If the supplied identifier does not exist in WEB_IA.md's per-page blueprints, set status: blocked and surface the gap in § 12.
2. WEB_IA.md (required) — the parent IA hub. Provides the per-page blueprint this PAGE_SPEC extends: route pattern, URL parameters, purpose, audience, auth requirement, referenced use cases, sections list, primary CTA, secondary actions, data dependencies, state matrix, entry/exit points, parameter-dependent behavior, and shared surfaces invoked. Read end-to-end — partial reads cause silent identity drift.
3. DESIGN.md (required if present) — the global design system: tokens (color, type, spacing, radii, elevation), component library, layout templates (named page shapes — centered-narrow, workspace-three-pane, settings-rail, marketing-bleed, dashboard-stack, modal-dialog), responsive breakpoints, and motion principles. The PAGE_SPEC cites these by name; it never redefines them. If DESIGN.md is absent, set status: blocked and surface the gap.
4. Sibling PAGE_SPEC.md files referenced from this page's flows (optional, auto-discovered) — when this page links into a multi-page flow declared in WEB_IA.md § Flows, sibling PAGE_SPECs may be read to keep transition behavior consistent. Discovery: walk the flows in WEB_IA.md that reference this page, then read each sibling page's web-pages/<page-id>/PAGE_SPEC.md if it exists. Read only the specific siblings cited.
5. Prior web-pages/<page-id>/PAGE_SPEC.md (optional, auto-discovered if refining) — preserve every resolved open question, every named region, every breakpoint reflow rule already calibrated. Re-run citations against the current DESIGN.md and WEB_IA.md — do not assume stale token names or section names are still valid.

Read-set size: 2–4 artifacts typically (page identifier is metadata, not a read; WEB_IA + DESIGN.md + optionally sibling specs + optionally prior PAGE_SPEC).

When PAGE_SPEC creation is warranted

PAGE_SPEC is opt-in. Most pages stay with their inline Composition note in WEB_IA.md. Recommend a PAGE_SPEC when any of the following hold:

• Composition would exceed ~30 lines if expressed inline in WEB_IA's per-page entry
• The page has multiple states whose layouts differ materially (not just skeleton vs. content swap)
• The page uses interaction patterns not covered by DESIGN.md's component library (multi-select trees, drag-drop, virtualized scrolling, custom data viz)
• The page has page-specific motion or choreography beyond DESIGN.md's global motion rules
• Multiple work units touch the same page and need a stable shared composition reference
• The page is flagship or high-traffic, where the cost of redesign is high

If none of these hold and the user is asking for a PAGE_SPEC anyway, produce the document but state in § 1 under a brief preamble line that "Inline composition in WEB_IA would have sufficed for this page" — do not refuse to produce the artifact.

Workflow

PAGE_SPEC generation proceeds in five phases. Phases are sequential — later phases depend on earlier decisions — but revisit earlier phases if a later phase reveals a gap.

Phase 1: Read & Reconcile