Frontend experience core

Ground frontend work in the consuming product and repository, define a concrete contract, and block completion when the result is generic, behaviorally incomplete, or unsupported by evidence.

When to invoke

• "Design this frontend feature from the repository evidence."
• "Implement this screen without making it look generic."
• "Review this UI for complete states and product fit."
• "Plan a web, mobile, PWA, or desktop experience."
• "Route this frontend request to the right specialist."

Evidence and precedence

Use evidence in this order:

1. User requirements, approved stories, product documentation, code, tests, schemas, tokens, runtime behavior, and actual assets.
2. Applicable normative standards and official platform or framework documentation.
3. Properly licensed user-provided references.
4. Community guidance only when authoritative evidence is unavailable and clearly labeled.

Read references/product-evidence.md when the product job, local stack, content, states, or supported surfaces are unclear. Unknowns remain unknown; do not invent users, metrics, research, analytics, business rules, or compatibility.

Required design contract

Before a material visual or interaction decision, record:

Start with assets/design-contract.md when the consuming project has no equivalent.

Workflow routing

Load only capabilities that match the task:

Finish gate

Read references/anti-generic-interface-gate.md before declaring a material interface complete. Block completion when:

• the interface could belong to an unrelated product after changing the logo;
• hierarchy does not follow the user's decision sequence;
• cards, gradients, oversized text, blur, elevation, or animation replace information architecture;
• visible controls have no implemented result, unavailable state, or explanation;
• important states, access behavior, or recovery are absent;
• responsive behavior only stacks desktop regions;
• a new one-off token or component system conflicts with the established one;
• acceptance criteria lack executed or documented manual evidence.

Use assets/human-review-checklist.md for subjective review. Record pass, needs revision, blocked, or not applicable with evidence for each item.

Limits

• Do not replace product management, user research, branding, backend ownership, legal review, or accessibility certification.
• Do not force a framework, design system, chart library, state library, or testing tool onto an established project.
• Do not copy proprietary screens, assets, text, or exact layouts from references.
• Do not claim product-market fit, conversion, ranking, certification, compatibility, or performance outcomes without evidence.

Output template

## Frontend experience contract
**Status:** ready | needs revision | blocked
**Surface:** web | PWA | mobile | desktop | mixed

### Evidence
| Source | Finding | Confidence |
| --- | --- | --- |

### Contract
| Field | Decision | Evidence |
| --- | --- | --- |

### Applicable skills and gates
- <skill>: <reason>

### Unknowns and blockers
- <fact still needed, owner, and impact>

Quality gate

• Product and repository evidence was inspected before design or implementation decisions.
• The design contract names the user, job, hierarchy, actions, states, visual grammar, adaptation, and forbidden defaults.
• Only relevant domain skills were selected.
• Unknowns are labeled and no product facts were fabricated.
• Visible controls and applicable states are complete or explicitly blocked.
• The anti-generic finish gate has evidence for every applicable item.