# Conventions

Use the existing owners and enforce boundaries in code and tooling.

## Hooks and components [#hooks-and-components]

Hooks coordinate asynchronous state, mutations, subscriptions, error presentation and navigation. Components render that state and compose primitives. A small static component does not need an artificial hook; a screen should not own a second session authority.

## Module boundaries [#module-boundaries]

- No new barrels on server-capable modules. Use safe leaves for values needed by clients.
- No dynamic `import()` in new implementation. Use static imports and framework-supported build splitting.
- Enumerate cross-package exports deliberately.
- Do not use `window.confirm`; use the shared accessible confirmation dialog.
- Validate external payloads once at their boundary with Zod. Keep internal state typed.
- Preserve Organization scope, current authorization and transactional audit requirements.

## UI and language [#ui-and-language]

Read `apps/web/PRODUCT.md` before UI work. shadcn is the visual authority; neutral semantic tokens make rebranding inexpensive. Use existing Base UI primitives and the component catalog. Authenticated screens follow the product’s operating interface; marketing has separate design guidance.

Add chrome strings to English, German and French catalogs together. Preserve keyboard navigation, visible focus, reduced-motion preferences and meaningful labels. Use semantic links for destinations and buttons for actions.

## Changes and evidence [#changes-and-evidence]

Use logical Conventional Commits. Keep generated migration SQL and relevant tests with their feature. Record measurements for runtime or bundle changes, including exact commands and limitations. Read the relevant ADR before altering an established boundary; historical measurements describe their captured revision, not a guarantee about the current tree.


## Key files [#key-files]

- [`AGENTS.md`](https://github.com/CarlosZiegler/doro/blob/main/AGENTS.md)
- [`apps/web/PRODUCT.md`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/PRODUCT.md)
- [`packages/config/oxlint-client-boundary.json`](https://github.com/CarlosZiegler/doro/blob/main/packages/config/oxlint-client-boundary.json)