0055 — Forms use react-hook-form and Zod with thin HeroUI field adapters

Proposed · 2026-10-19

Amended by 0255: the PWA port plan.

Amended by 0165: the HeroUI field adapters move into @stackra/ui and the renderer packages.

Context

Validation must run on the client and in the service from one definition, and Zod schemas are the shared validation language (0015). Forms in the console need a state library and fields that match the UI kit (0056).

Decision

1. Form state is react-hook-form; validation is Zod, with the same schemas used by the API client and services.
2. HeroUI inputs are wrapped by thin FormField adapters that connect a HeroUI component to a react-hook-form controller and show Zod errors.
3. Adapters contain no business rules; a form builds on a schema, not the reverse.
4. Mobile forms reuse the schemas, not the web adapters.

Consequences

• One schema validates in the browser and on the server.
• The adapters are a small surface we maintain against HeroUI changes.

Enforcement

Planned — architecture-guardian review; no automated check yet.

Supersedes and sources

Supersedes: none. Sources: owner decision in chat, 2026-10-19.