# UI + Web Components Standards (Human Digest)

This is the short human-readable version of our UI coding standards.

## What this standard is trying to achieve

- Keep UI code predictable.
- Keep responsibilities separated.
- Make features easier to test and maintain.

## Core idea in one minute

- Shared UI state belongs in a small host store (reducer-style).
- Local form/widget details stay in the DOM/component.
- Host reconciler reads state and updates UI in small sections.
- Components render UI and emit user intent events.
- Services/IO/auth stay outside components and outside pure rendering.

## Who owns what

- **Host store + reconciler own:** app mode, busy/loading state, cross-component rules, enable/disable logic.
- **Components own:** local visual behavior and interaction details.
- **Services own:** API calls, auth, external integrations, side effects.

## Practical rules

- One source of truth per value (avoid mirroring the same value in two places).
- No business logic or network calls in web components.
- No side effects inside pure render/reconcile functions.
- Component events describe user intent; host decides workflow.
- Keep reconciler small: split by concern (visibility, gating, feedback, side effects).
- Extensions running inside Azure DevOps must read the host theme via the official SDK and avoid hard-coded background colors in HTML entrypoints.

## What to avoid

- Global event-bus style UI syncing when direct component methods are available.
- Two-way binding every input to global store by default.
- Mixing reducer logic, DOM updates, and service calls in one function/class.

## Testing expectation (simple)

- Test reducer transitions.
- Test reconciler output for key states.
- Test component methods and emitted events.
- Test host wiring from user event -> action -> UI update.

## Canonical LLM standards

For strict code-generation instructions, use:

- `documentation/llm-codegen-standards/ui-state-architecture.md`
- `documentation/llm-codegen-standards/web-components-guidelines.md`