diff --git a/AGENTS.md b/AGENTS.md index a1e01410..82ca1a15 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,14 @@ Owns the Angular public website, operator dashboard and embeddable authentication widget. Backend APIs, persistence and session policy belong to sibling `user-proxy`; connected applications own business authorization. -Start with the canonical [work state](../user-proxy/docs/WORK-STATE.md), [architecture](../user-proxy/docs/ARCHITECTURE.md), [capabilities](../user-proxy/docs/CAPABILITIES.md), [development](../user-proxy/docs/DEVELOPMENT.md), [security](../user-proxy/docs/SECURITY-OPERATIONS.md) and [design](../user-proxy/docs/DESIGN.md). Preserve existing README contribution rules and DESIGNGUIDE.md. Read widget integration/event guides before changing the custom element contract. + +## Guidance for this kind of repository + +Kept by the middleware (version 046fbf2131b2). Read these before changing anything here: +- [docs/guidance/product-ui.md](docs/guidance/product-ui.md) + + +Both apps are client-only and call a backend "proxy" API that lives in another repo. ## Commands diff --git a/docs/guidance/product-ui.md b/docs/guidance/product-ui.md new file mode 100644 index 00000000..a4880ba4 --- /dev/null +++ b/docs/guidance/product-ui.md @@ -0,0 +1,10 @@ + + +Product UI work: the product must stay coherent for the person in the middle of a task. +- Follow the journey before and after the changed step: navigation, shared components, state, saved preferences, permissions, analytics events, responsiveness, accessibility, loading, empty and error states, and recovery. +- A reported defect in one place usually has siblings: inspect the shared component, its callers and sibling flows; fix the confirmed instances within scope; keep intentional differences and record them. +- Reuse the design system, tokens and existing components. Do not introduce a parallel pattern for one screen. +- Keep business rules and API behaviour shared; UI changes must not fork them. +- Verify in the browser where possible and say what you verified. A working button is not a finished task if the end-to-end outcome still fails. +- For different roles, check what each role sees and can do after the change. +- A/B tests need no backend: when this prompt has an Experiments section, assign the variant in the browser and send exposure and conversion events with its snippet (hash assignment, sendBeacon to the events URL with the publishable key, both read from the site's environment variables, never written in the code), fire-and-forget: the page never waits for the middleware and works the same when it is down. Without that section, report a blocker whose "needed" is "Experiments enabled for this repository in the middleware (allowed origins) and experiment defined", not a missing API.