UI Design Package Rule

rule_id: R-UI-PROTOTYPE-01 category: Design status: locked owner: Project Manager / Architect scope: frontend UI, screens, components, interactions, visible states, responsive behavior, user stories, user flows

1. Rule

Frontend UI changes require a module-organized current-truth package (index.html + stories.md + flows.md + the four scenario JSON files + page HTML files) under docs/design/prototypes/<module>/ before FE/BE/SYNC contracts are locked.

The prototype describes the target behavior. The current implementation IS the baseline; no separate UI-BASELINE-* capture is required.

2. Trigger

Use this rule when a requirement changes any of:

• page layout or navigation
• visible component, form, table, modal, drawer, toolbar, or dashboard
• user interaction or state transition visible in the UI
• loading, empty, disabled, error, success, or permission state
• responsive behavior or accessibility behavior
• frontend-visible API field, error code, status, or side effect
• a module's user story or flow (even without visual change)

3. Required Evidence

When UI impact = changed:

1. Locate the affected module directory docs/design/prototypes/<module>/. Create it if missing.
2. Read the complete existing module package and merge the REQ behavior into its current truth. HTML pages link docs/design/tokens/tokens.css (see docs/rules/design-foundation.md); do not introduce unregistered hex.
3. Ensure the module ships index.html, stories.md, flows.md, scenario-model.json, cases.json, scenario-coverage.json, fixture-contract.json, and ≥1 page HTML file.
4. Update the complete module set; REQ is a source_refs value, not the owner of a copy.
5. Confirm every page HTML file carries the current 4-field header (see §5).
6. Confirm scenario JSON, stories.md, and flows.md satisfy §6 and §7, including positive/negative and 100% required branch gates.
7. Link the module current-truth package into FE/BE/SYNC contracts before contract lock (by directory path + fingerprint of the current contents).

When UI impact = unknown, contract lock is blocked until the REQ is clarified.

When UI impact = none, record N/A in REQ and contract templates.

4. Module Layout Minimum

docs/design/prototypes/<module>/ MUST contain:

Folder naming: use prototypes/ (not proto/). The two are unified; legacy proto/ paths must be migrated.

5. HTML Header Minimum

Every page HTML file carries a 4-field current-truth header in a dark gradient .proto-meta bar. No version, REQ, round, or owner fields.

The four tokens (设计代数 / 更新 / 路由 / index 链接) are machine-checked as fixed substrings in every page HTML — a page missing any of them fails the UI prototype gate with the missing tokens named.

REQ ID, lock status, owner, and related contracts are explicitly dropped — they are noise given the "only final version" rule, and they live elsewhere (REQ file, CONTRACTS-{id}.md index, git history).

Below the header, each page carries a sticky aside.proto-notes sidebar with 7 mandatory sections in canonical order: 本原型目标 → 设计推导 → PM 决策 → layout-specific section → FR coverage → API endpoints → Edge cases → Q&A. See skills/ui-prototyping/SKILL.md §Sidebar for full contract.

6. Stories Minimum

stories.md MUST contain:

• Personas section: lowercase-kebab IDs with role description, daily goal, and permissions
• Stories section: S-NNN zero-padded IDs, each with:
  • "作为 X, 我想要 Y, 以便 Z" statement
  • 入口 (route or trigger)
  • 目标 (measurable outcome)
  • 关联原型 (≥1 page HTML file)
  • E2E 锚点 (≥1 flow ID from flows.md)

7. Flows Minimum

flows.md MUST contain:

• One section per flow with F-NNN zero-padded ID
• Each flow carries: 触发 / 角色 / 前置 / 关联 story
• Numbered steps with action → expected → prototype reference / route
• 异常分支: edge cases with fallback paths
• E2E 转录 note: identifies which steps map to Playwright data-test hooks

Flows are dual-purpose: they validate design rationality at review time, and they become the E2E test script after dev complete.

8. Cross-REQ Module Regression

When a REQ modifies any file in docs/design/prototypes/<module>/, the resulting test plan MUST execute every flow listed in <module>/flows.md end-to-end, not only the flows directly touched by this REQ.

Rationale: a module's prototype set is shared across REQs. REQ-A adds a tab; REQ-B refines data loading. Both must verify the module's existing flows still pass. This rule prevents silent regression of prior REQs' shipped behavior.

The test plan owner (Builder for unit, DV Team for spec verification, QA Team for e2e) includes a "module-flow regression sweep" sub-block listing every F-NNN from the affected module.

9. Procedure Ownership

The prototype design procedure belongs to .claude/skills/specification-planning/SKILL.md (planning.design — design choices including the optional UI prototype artifact). Professional prototype criteria — the HTML shell, sidebar sections, visual tokens, stories/flows templates, and the Document Verifier quality bar — belong to .claude/skills/ui-prototyping/SKILL.md. The Loop Definition owns the planning_complete guard that fires TR-002; the prototype gate is now a manual checklist inside the planning skill, not a state-machine phase.

10. Forbidden

• locking FE/BE/SYNC contracts for UI changes before the module prototype set passes the §3 evidence gate
• shipping a prototype HTML file without the 4-field header
• shipping a module directory without stories.md or flows.md
• capturing or maintaining a separate UI-BASELINE-* document (the current code IS the baseline)
• tracking prototype file versions, design generations, addenda, REQ copies, or round copies
• creating target UI directly from a prompt without checking the module's existing stories/flows
• using chat screenshots or summaries as the only prototype evidence
• hiding UI-driven API/data requirements until Builder implementation
• treating lightweight mode as permission to skip the module prototype set gate
• skipping the §8 module-flow regression sweep when modifying an existing module