aw-spec-cli 0.1.8 → 0.1.9

package/assets/guardrails/technology/nextjs/api-integration.java-spring.md

@@ -0,0 +1,203 @@
+# API Integration — nextjs ⇄ java-spring
+
+> The CROSS-LANE pairing rules: how the `nextjs` frontend lane consumes a `java-spring`
+> (Spring Boot) service lane. NON-NEGOTIABLE where marked.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-IV (the contract is the only server input).
+
+This file is named for the service lane it pairs with, and a project maps it through the
+`{{backend_stack}}` placeholder — it is loaded only when `.appweaver/stacks.json` declares a
+`java-spring` backend, and the `dotnet-webapi` pairing file is not.
+
+**THE PUBLISHED SCHEMA OUTRANKS THIS FILE.** The `java-spring` service corpus is unauthored
+(`guardrails/technology/java-spring/README.md`), so unlike the `dotnet-webapi` pairing there
+is no service rule file to cite: the rules below state what this pairing REQUIRES and where
+Spring's own defaults will violate it if nothing was configured. Every one of them is
+checkable against the service's OpenAPI document, and **where the document and this file
+disagree, the document wins and the disagreement is a finding** — raised to the service lane,
+recorded in `design.ui.md §8`, never worked around in the client.
+
+⚠ **If the service was generated by AppWeaver `implement`**, its API shape follows whichever
+technical rule pack its lane maps. A Spring service generated against a pack still pointing
+at `guardrails/technology/dotnet-webapi/` will carry .NET-shaped conventions in Java, and a
+service generated against no pack at all will carry Spring's raw defaults. Those two produce
+**different paging, different error bodies and different id types**. Read the OpenAPI before
+designing §5; do not assume either.
+
+## The contract is the interface
+
+- The service publishes an **OpenAPI document** (springdoc, conventionally at
+  `/v3/api-docs`). That document — not an entity class, not a `@RestController`, not a table
+  — is the whole of what this lane may assume.
+- The typed client in `lib/api/` is GENERATED from it and **never hand-edited**.
+- A field the UI needs that the document does not carry is a **contract delta** raised back
+  to the service lane and recorded under `design.ui.md §5` "Contract deltas needed".
+- The UI never assumes a repository, an entity, a JPA relationship or a service bean. Those
+  are the service lane's internals.
+
+## Paging (NON-NEGOTIABLE — read this before designing a list)
+
+**This is the highest-risk difference in the whole pairing.** Spring Data's `Pageable` is
+**ZERO-BASED** and its `Page<T>` serializes with entirely different field names from the
+`PagedResult<T>` shape a .NET-paired UI expects:
+
+| | Spring Data default | The `dotnet-webapi` pairing |
+|---|---|---|
+| request | `?page=<0-based>&size=<n>&sort=<field,dir>` | `?pageNumber=<1-based>&pageSize=<n>` |
+| items | `content` | `Items` |
+| total rows | `totalElements` | `TotalCount` |
+| total pages | `totalPages` | `TotalPages` |
+| current index | `number` (0-based) | `PageNumber` (1-based) |
+| page size | `size` | `PageSize` |
+
+- **Read the index base off the OpenAPI document and state it in `design.ui.md §5`.** Getting
+  it wrong does not fail — it silently skips or repeats the first page, which is why it
+  survives review.
+- The conversion between the UI's paging state and the wire happens **at the client boundary
+  and nowhere else**. Paging arithmetic scattered through components is how the two bases get
+  mixed.
+- **Assert the index base in a test** ([[frontend-testing]]): request page one, assert the
+  wire value. This is the cheapest guard against the defect.
+- Serializing `PageImpl` directly is unstable across Spring Boot versions and the framework
+  warns about it — so a service may migrate to a wrapper DTO or `PagedModel` and change the
+  field names without changing behaviour. **Pin the client to a regenerated schema**, and
+  treat a silent field rename as the breaking change it is.
+- Paging, sorting and filtering are SERVER concerns. The UI never fetches everything and
+  pages in the browser.
+- `sort` is a contract value, not a free-text field. Sortable fields come from the document;
+  a sort on a field the service does not expose is a `400` or, worse, silently ignored.
+
+## Numeric and temporal precision (NON-NEGOTIABLE)
+
+Java's types do not all survive JSON in a browser, and every one of these fails **quietly**:
+
+- **`long` / `Long` identifiers beyond 2^53 lose precision in JavaScript.** An id read,
+  displayed and sent back will not be the id that was read. Ids are transported as **strings**
+  — or the service uses UUIDs. If the document declares `integer/int64`, that is a contract
+  delta, not something the client can round-trip safely.
+- **`BigDecimal` serialized as a JSON number loses precision.** Money and quantities are
+  transported as a **string** or as integer minor units, and are never parsed into a JS
+  `number` for arithmetic. A total computed client-side from floats will disagree with the
+  service's total, and the user will believe the screen.
+- **`LocalDateTime` carries no offset.** A zoneless timestamp is ambiguous: the UI must not
+  assume UTC and must not assume the browser's zone. The contract states the zone, or the
+  field is `Instant`/`OffsetDateTime`; anything else is a contract gap recorded as a `DA-n`.
+- Dates are ISO-8601 on the wire and formatted locale-aware at render ([[i18n]]).
+- Jackson's absent-vs-null distinction is a configuration choice (`@JsonInclude`). **The UI
+  cannot tell "not set" from "not permitted to see" from field absence alone** — the contract
+  must distinguish them, and until it does, the design records the assumption.
+
+## Optimistic concurrency
+
+- Where an aggregate is version-tracked (JPA `@Version`), **the version is part of the
+  record's client state** and is held beside it ([[state-management]]). A record held
+  without its version cannot be updated safely.
+- Updates send it back — as the version field in the body, or as **`If-Match`** where the
+  contract exposes an ETag. Which one is a contract fact, not a client choice.
+- ⚠ **A Spring shallow ETag is not a version token.** `ShallowEtagHeaderFilter` hashes the
+  response body and emits a weak validator (`W/"…"`); it saves bandwidth and does not carry
+  entity identity. Treat the `@Version` field as the authoritative token and the ETag as one
+  only if the document says so.
+- A version conflict surfaces as **`409`** (`ObjectOptimisticLockingFailureException` mapped
+  by the service's handler). That is a designed state: the UI renders the stale-record state
+  and offers a reload, and **NEVER retries automatically** — a blind retry with a fresh
+  version is exactly the overwrite the mechanism prevents.
+- An optimistic UI update on a version-tracked record declares its rollback and is not
+  settled until the response carries the new version.
+
+## Errors
+
+Spring Boot 3 serves **RFC 7807 `ProblemDetail`** — `type`, `title`, `status`, `detail`,
+`instance`, plus extension members — from a `@RestControllerAdvice`.
+
+- The UI maps failures by **`status` and the `type` URI** (the machine-readable code). It
+  **never matches on `detail`**: that is human prose, it may be localized, and it changes
+  without a version bump.
+- `detail` is **never surfaced verbatim** — Spring's own defaults can carry internal messages
+  and exception text. The user-facing text is the design's; the raw body goes to telemetry
+  with the classification rules applied ([[observability]]).
+- Bean Validation (`@Valid`) failures return `400` with field-level errors. Map them onto the
+  matching fields by field path, and surface an unattributable one at form level rather than
+  dropping it ([[forms-and-validation]]).
+
+| From the service | Design state |
+|---|---|
+| `400` validation | field-level failure, focus to the first offending field |
+| `401` | session expired / no valid token — re-authenticate |
+| `403` | permission-denied, distinct from not-found and from error |
+| `404` | not-found for that route |
+| `409` | stale record — reload, never auto-retry |
+| `422` where the service uses it | domain rule rejected — a designed state, not a crash |
+| `5xx` / network | retryable error, and only where the operation is safe to repeat |
+
+## Authorization
+
+- Identity is a **JWT from an external IdP**, validated by Spring Security's OAuth2 resource
+  server. Roles arrive as `ROLE_` authorities and scopes as `SCOPE_` authorities; **both are
+  enforced server-side** by method security. The client hides or disables an affordance and
+  is never the authority ([[auth-session]]).
+- **`401` and `403` mean different things and must map to different states.** Spring returns
+  `401` for a missing or invalid token and `403` for authenticated-but-denied. A UI that
+  treats both as "signed out" logs the user out when they merely lacked a scope.
+- ⚠ **The API must be stateless.** If form login or the default login page is left enabled, a
+  protected route answers an unauthenticated request with a **`302` to an HTML login page**
+  rather than a `401`. The browser follows it, and the client gets HTML where it expected
+  JSON. **HTML from an API route is an auth misconfiguration, not a parse error** — surface
+  it as such rather than rendering a generic failure.
+- Field-level redaction happens server-side (projections, `@JsonView`, DTO mapping). The same
+  endpoint may legitimately return a different field set to different users: the UI renders
+  the design's "not available to you" affordance, never an error, and never infers, caches or
+  reconstructs the missing value.
+- Health and discovery endpoints (Actuator `/actuator/health`, `/actuator/info`) are
+  **not a data source** for the UI.
+
+## Caching
+
+- Spring Security sends `Cache-Control: no-cache, no-store, max-age=0, must-revalidate` on
+  secured responses by default. **The lane must not cache in front of them** — no
+  route-segment cache, no memoisation outliving the render, no service-worker entry.
+- Every other fetch and route segment **declares** its caching and revalidation policy
+  explicitly (UX-VI). A default that happens to work is not a policy.
+
+## Transport and origin
+
+- HTTPS only.
+- **CORS is an explicit allow-list.** A wildcard origin with credentials is rejected by the
+  browser outright, so a credentialed call needs the origin named server-side — that is a
+  service change, not something the client can route around.
+- A custom request header makes the call non-simple and adds a **preflight round trip** to
+  every request. Headers are added deliberately, and where a call must be same-origin it goes
+  through this lane's own server layer as a design decision recorded in §5, not an ad-hoc
+  proxy added during generation.
+- Every request carries W3C trace context (`traceparent`) so a UI action is followable
+  through the service's Micrometer traces ([[observability]]) — the other reason raw `fetch`
+  outside `lib/api/` is forbidden.
+
+## Versioning
+
+- Spring has no built-in API versioning, so the service's scheme is a contract fact: a path
+  prefix (`/api/v1/`), a header, or a media type. Read it from the document and pin the
+  client to it.
+- Moving version means **regenerating the client**, not editing paths in place, and the
+  design's §5 rows are re-checked against the new document.
+- **Enums are a breaking-change surface.** Jackson serializes the enum name, and a value
+  added server-side reaches a client that never heard of it. The client's mapping handles an
+  unknown value by falling back to the design's stated default rather than crashing the
+  screen ([[api-client]]).
+
+## Events are not a browser channel
+
+The service publishes domain events to a broker (Kafka, RabbitMQ, or Spring's own application
+events). **The browser is never a consumer**: this lane does not subscribe to a broker, does
+not read the service's datastore, and does not treat an event contract as a UI contract.
+Freshness comes from the invalidation policy the design states ([[state-management]]) —
+refetch on mutation, revalidate on navigation, or a server-pushed channel the OpenAPI
+document explicitly declares.
+
+## Related
+
+- [[api-client]] — the generated client layer these rules are realised in
+- [[auth-session]] — how the token is obtained and attached
+- [[error-handling]] — the states the failure table maps onto
+- [[state-management]] — where the version token and the cached projection live
+- [[frontend-testing]] — the paging-base and redaction assertions this pairing demands

package/assets/guardrails/technology/nextjs/auth-session.md

@@ -0,0 +1,68 @@
+# Authentication & Session Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-VIII (client state carries no secret) and
+> UX-IV (the contract is the only server input).
+
+Identity comes from an **external IdP**; local identity stores are forbidden service-side,
+and this lane has no identity store of its own at all. Authorization is **role-based AND
+scope-based, both enforced by the service** — this lane's job is to reflect that decision,
+never to make it.
+
+## What the design owns
+
+`design.ui.md` states these, because they are experience decisions:
+
+- **Which screens require what** — authentication state, role, or record state — each citing
+  the `CN-` that imposes it (§1 access conditions).
+- **Hidden vs disabled vs denied.** Three different outcomes with three different meanings:
+  hidden says "not for you", disabled says "not yet", denied says "you tried and may not".
+  The design picks one per affordance; `implement-ui` does not get to choose.
+- **What an expired session does to work in progress** — discarded, preserved, or restored
+  after re-authentication. A form that silently loses ten minutes of typing on a token
+  expiry is a design omission, not an implementation bug.
+- **What an unauthenticated deep link does** — sign in and return, or land on a public
+  screen.
+
+## What implement-ui owns
+
+- The token is obtained from the IdP through the lane's configured auth integration. **No
+  bespoke login form posting credentials to a hand-written endpoint.**
+- **The token NEVER enters client state, `localStorage`, `sessionStorage`, a cookie readable
+  by script, the URL, or telemetry.** It is held server-side or in an `httpOnly`, `Secure`,
+  `SameSite` cookie, and attached by `client.ts` ([[api-client]]).
+- Refresh is transparent and **single-flight**: concurrent calls hitting an expired token
+  wait on one refresh, they do not each start their own. A refresh storm on token expiry is
+  a real outage mode.
+- A failed refresh ends the session deterministically: the client caches are cleared, the
+  design's expiry state renders, and no request goes out with a dead token.
+- **Sign-out clears every server-derived cache.** A cached projection surviving a sign-out is
+  one user seeing another user's data on a shared machine.
+
+## Reflecting authorization, not making it
+
+- Roles and scopes are read from the session for **display and affordance** decisions only.
+  Every guarded action is still guarded by the service, and the UI is written on the
+  assumption that its own check can be bypassed — because it can.
+- A guarded route renders its denied state on a `403` rather than assuming the client-side
+  check was sufficient. A route that never renders `403` has not been tested against the
+  service.
+- **No authorization rule is duplicated into the client as logic.** A client that computes
+  "may this user approve" from claims will drift from the service's matrix; it reads a
+  capability the contract exposes, or it renders the denied state.
+- Scope and role names are contract values. They are referenced from one place, not spelled
+  as string literals across components.
+
+## Multi-tab and session lifetime
+
+- Sign-out and expiry propagate across tabs. A second tab still showing an authenticated
+  shell after sign-out in the first is a real disclosure.
+- Idle timeout, if the design states one, warns before it acts.
+
+## Related
+
+- [[api-integration.<service-stack>]] — how the service enforces role AND scope, and redacts
+- [[api-client]] — where the token is attached
+- [[client-security]] — why storage choice is a security decision
+- [[state-management]] — what must be cleared on sign-out

package/assets/guardrails/technology/nextjs/client-security.md

@@ -0,0 +1,69 @@
+# Client Security Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-VIII (client state carries no secret).
+
+The client is a hostile environment: its code is readable, its storage is inspectable, and
+its user may not be the person the account belongs to. Every rule here follows from that.
+
+## The trust boundary
+
+- **The client enforces nothing.** It hides, disables, formats and validates for feedback.
+  Every rule that matters is re-decided by the service ([[api-integration.<service-stack>]]).
+- A check written in the client is written on the assumption it will be bypassed.
+- **Nothing in the bundle is secret.** Environment values reaching client code are public,
+  whatever the variable is called. Server-only configuration stays on the server.
+
+## Injection
+
+- Rendering is escaped by default. `dangerouslySetInnerHTML` requires a sanitizer **and** a
+  comment naming where the markup came from; unsanitised use is a Forbidden Pattern.
+- A URL from data is validated before it becomes an `href` or `src` — `javascript:` and
+  `data:` schemes are rejected.
+- User content is never interpolated into a template that is then evaluated, and never
+  assembled into a selector, a query string fragment or a header value without encoding.
+- A Content-Security-Policy is configured, without `unsafe-inline` and `unsafe-eval`. A CSP
+  loosened to make a library work is a dependency decision recorded in the delta.
+
+## Storage
+
+| Holds | Where | Never |
+|---|---|---|
+| Session token | server-side, or `httpOnly` `Secure` `SameSite` cookie | `localStorage`, `sessionStorage`, script-readable cookie, URL |
+| Server-derived data | the data layer's cache, in memory | persistent storage that outlives sign-out |
+| Preferences (locale, theme) | cookie or local storage | anything classified |
+| Anything the contract marks sensitive | nowhere on the client | logs, telemetry, URL, storage, error messages |
+
+- Persisted client state is cleared on sign-out ([[auth-session]]).
+- Data classified by the spec's `DC-` ids does not reach the URL — not as a path segment,
+  not as a query parameter, not in a fragment. URLs are logged, shared and kept in history.
+
+## Requests
+
+- Mutations are protected against cross-site submission — a `SameSite` cookie plus the
+  framework's own action protection, or an explicit token. A mutation reachable by a
+  cross-origin form post is a real vulnerability, not a theoretical one.
+- Third-party origins are an explicit allow-list, matching the service's own CORS posture.
+- External links opened in a new context carry `rel="noopener noreferrer"`.
+
+## Dependencies
+
+- A dependency added to this lane is a decision recorded in the delta, not an import
+  (UX-IX). It is judged on bundle cost, maintenance and what it is allowed to reach.
+- Dependency audit is a CI gate. A known-vulnerable transitive dependency blocks the build.
+- No dependency is loaded from a CDN at runtime: it is unpinned, unaudited third-party code
+  with full access to the page.
+
+## Errors and telemetry
+
+- An error surfaced to the user carries no stack trace, internal identifier, raw service
+  message or classified field ([[error-handling]]).
+- Telemetry carries no token, no credential and nothing the `DC-` ids restrict
+  ([[observability]]).
+
+## Related
+
+- [[auth-session]] — the token's lifecycle
+- [[api-integration.<service-stack>]] — where enforcement actually happens
+- [[observability]] — what may be recorded

package/assets/guardrails/technology/nextjs/component-architecture.md

@@ -0,0 +1,60 @@
+# Component Architecture Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). Commands: `/aw-spec-design-ui`.
+> Detail layer under `constitution.ui.md` UX-II (design system) and UX-III (server components).
+
+The rules the UI design author composes a feature's `§3 Component Structure` from. They
+constrain the SHAPE of the composition, not the framework names used to express it —
+`design.ui.md` stays technology-agnostic, so these read as "one responsibility per
+component", never as "one `.tsx` per component".
+
+## The four component roles
+
+Every component a feature owns is one of these, and the role is decided in the design:
+
+- **Screen** — owns a route's composition and its data requirements. One per `§1`
+  navigation row. Holds no presentation logic of its own beyond layout.
+- **Feature component** — owns one decision or one piece of the flow for THIS feature.
+  Lives with the feature, never in the shared set.
+- **Shared composition** — a design-system composition reused across features. A feature
+  may only COMPOSE these; introducing one is a decision recorded as a `DA-n`.
+- **Form** — owns a submission and its validation surface. Always paired with a `§5`
+  binding row and a `§4` interaction row.
+
+A component that fits two roles is two components.
+
+## Responsibility rule
+
+- One component, one responsibility, stated as a verb phrase in the `§3` table. "Renders
+  the order and lets the user cancel it" is two components.
+- A component's INPUTS are declared as field shapes with conceptual types, never as a
+  framework's prop type. Optional inputs state their default.
+- A component's OUTPUTS are named EVENTS. A component never reaches past its parent to
+  mutate state it does not own — the event goes up, the new state comes down.
+- A component that renders another feature's data declares the dependency in `§5` and
+  consumes it through that feature's published surface, never by importing its internals.
+
+## Server-first composition
+
+Per UX-III, a component is server-rendered unless it needs interactivity or a browser-only
+API. The design records WHICH components need client interactivity and WHY — that list is
+what `implement-ui` turns into client-boundary decisions, and a design that marks the whole
+screen interactive has not made the decision.
+
+- Interactivity is pushed to the LEAF that needs it, never to a screen or layout root.
+- Data fetching belongs to the server component that owns the data, not to a client
+  component that would fetch on mount.
+
+## Composition axes
+
+`§3`'s subsections are the axes THIS feature actually uses — screens, feature components,
+forms, shared compositions. Create the ones the feature has and stop; an empty axis is a
+section that should not exist, not a section filled with "N/A".
+
+## Related
+
+- [[state-management]] — who owns what a component reads
+- [[routing-navigation]] — how screens are addressed
+- [[design-system]] — the shared compositions a feature component is built from
+- [[forms-and-validation]] — the form role's own contract
+- [[component-conventions]] — how these roles land as files at `implement-ui`

package/assets/guardrails/technology/nextjs/component-conventions.md

@@ -0,0 +1,58 @@
+# Component Conventions — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). Commands: `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-II (design system) and its Mandatory
+> Frontend Folder Structure.
+
+HOW the roles `design.ui.md §3` names land as files. The folder structure itself is the
+constitution's and is not restated here; these are the rules for placing, naming and
+writing within it.
+
+## Placement
+
+- A feature's screens, components, hooks and actions live under
+  `features/<Feature>/`, where `<Feature>` is the spec feature name verbatim — that
+  match is what makes a slice traceable in both lanes.
+- Route segments under `app/` are thin: they compose a screen from
+  `features/<Feature>/` and declare the segment's own `loading`, `error` and `not-found`
+  states. Business composition does not live in a route file.
+- A component reused by two or more features moves to `components/` — and moving it is a
+  decision, recorded in the design, not a refactor made mid-generation.
+- Nothing this lane generates is written outside the lane's declared source path.
+
+## Naming
+
+- Components `PascalCase`, one exported component per file, file named for the component.
+- Hooks `useX`, colocated with the feature that owns them.
+- Route segments kebab-case, matching the design's `§1` route shape.
+- The design's ubiquitous-language terms are used VERBATIM as identifiers. A renamed
+  concept is a broken trace.
+
+## Writing rules
+
+- `"use client"` is opt-in at the leaf that needs interactivity, never at a layout root
+  and never to cover a subtree (UX-III). A generated client boundary corresponds to a
+  component the design marked interactive.
+- Props mirror the design's input field shapes, typed explicitly. `any` on a contract
+  type is forbidden.
+- No business rule evaluation in a component. A client-side check echoing a `BR-`/`FR-`
+  for feedback cites that id in a comment.
+- Styling comes from the design system and its tokens (UX-II). No ad-hoc values, no
+  second component library, no inline design constants.
+- `dangerouslySetInnerHTML` requires a sanitizer and a comment naming the source of the
+  markup.
+- Generated code is never hand-edited — it is regenerated.
+
+## Marking deferrals
+
+Code that leans on a design Assumption (`DA-n`) or Workaround (`WA-n`) carries a comment
+citing that id. That comment is how the ledger stays findable once the design is closed.
+
+## Related
+
+- [[component-architecture]] — the roles being placed
+- [[design-system]] — tokens, shared compositions and what may not be styled ad hoc
+- [[api-client]] — the one path to the service
+- [[client-security]] — escaping, storage and dependency rules
+- [[i18n]] — where user-visible strings come from
+- [[frontend-testing]] — the test that ships with each file

package/assets/guardrails/technology/nextjs/design-system.md

@@ -0,0 +1,60 @@
+# Design System Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). NON-NEGOTIABLE.
+> Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-II (the design system is the only source of
+> visual truth).
+
+## The single source
+
+- Components, spacing, type scale, colour, radius, elevation and motion come from the
+  declared design system and its **tokens**. There is no second component library and no
+  second token set.
+- **No ad-hoc design values in feature code** — no hard-coded hex, pixel spacing, font size
+  or duration. A value not in the token set is either a token that should exist, or a
+  mistake.
+- A feature COMPOSES shared components. Introducing a new shared component is a decision
+  recorded in `design.ui.md §8` and it moves to the shared set; it is not a component
+  quietly copied into a second feature.
+
+## What the design owns
+
+`design.ui.md §3` names, for each component, the shared composition it is built from. That
+list is what stops two features solving the same interaction differently. A component whose
+`§3` row says "custom" without a `§8` entry explaining why is unreviewed divergence.
+
+## Tokens
+
+- Tokens are semantic, not literal: `surface`, `danger`, `muted` — never `gray-400`. A
+  literal token cannot be re-themed and cannot be dark-mode-corrected.
+- Theme variants (light, dark, high-contrast where the design names one) are defined at the
+  token layer. A component that branches on the theme has leaked a token decision into
+  feature code.
+- **Colour never carries meaning alone** — every colour-coded state has a text, icon or
+  shape signal beside it ([[accessibility-implementation]]).
+- Contrast ratios are a token-set property and are verified there, so a compliant component
+  cannot be composed into a non-compliant screen.
+
+## Layout and responsiveness
+
+- Layout uses the system's spacing scale and its breakpoint set. A one-off media query in a
+  feature is a token gap.
+- The design's Experience Scope names the device and viewport floors. The lane is built for
+  those floors — not for the developer's monitor — and a layout that only works above the
+  floor is a defect.
+- Content is not clipped or made unreachable at the smallest supported viewport or at
+  increased text size.
+
+## Iconography and copy
+
+- Icons come from the system's set and always have a text alternative or an adjacent label.
+- User-visible strings come from the locale catalogue ([[i18n]]), and their TONE follows the
+  content-design rules the spec's `UX-` standards lift. An error message written inline
+  during generation is copy nobody reviewed.
+
+## Related
+
+- [[component-architecture]] — the roles the system's components are composed into
+- [[component-conventions]] — how compositions land as files
+- [[accessibility-implementation]] — the floor the tokens have to meet
+- [[i18n]] — where the strings come from

package/assets/guardrails/technology/nextjs/error-handling.md

@@ -0,0 +1,72 @@
+# Interaction & Error State Standards — nextjs (frontend lane)
+
+> Pure technology (domain-agnostic). Commands: `/aw-spec-design-ui`, `/aw-spec-implement-ui`.
+> Detail layer under `constitution.ui.md` UX-V (every interaction state is specified).
+
+The rules behind `design.ui.md §4 Interaction & Flow` — the section a backend-shaped
+process silently drops, and the one where most UI defects live. `§4` is never omitted and
+never thinned to the happy path, however small the feature.
+
+## The five states, every time
+
+Every interaction that crosses the network is designed in all five, and each gets a row:
+
+| State | The question it answers |
+|---|---|
+| **Loading** | what the user sees while the answer is unknown, and whether the surface stays interactive |
+| **Empty** | what a valid, zero-result answer looks like — distinct from loading and from error |
+| **Error** | what the user sees, what they can DO about it, and whether a retry is safe |
+| **Permission-denied** | distinct from error and from not-found; what is disclosed and what is not |
+| **In-flight / disabled** | what a second submit does while the first is unresolved |
+
+An interaction whose design shows only success and failure is incomplete. A state the UI
+can reach that the spec does not describe is a SPEC gap routed to `specify` — it is
+recorded as a `DA-n`, never invented in the component.
+
+## Mapping the service's failures
+
+The five states above are produced by real service responses, and the mapping is stated
+once — by status code and machine-readable error code, **never by matching message text**.
+The per-status table for the declared service stack lives in
+[[api-integration.<service-stack>]]; the two rules that matter here are that every response
+the service can return maps to a state in `§4`, and that an **unmapped failure is an
+unhandled state** — which is the one users actually meet.
+
+## Error content is designed, not generated
+
+- The user-facing message says what happened and what to do next. It never contains a
+  stack trace, an internal identifier, a raw service message, or anything the `DC-` ids
+  restrict.
+- The design distinguishes an error the user can fix (validation, conflict) from one they
+  cannot (service unavailable). They get different affordances.
+- A retry is offered only where the operation is safe to repeat. The design says which
+  ones are.
+
+## Validation timing
+
+- The design states WHEN validation runs — on change, on blur, on submit — per field
+  group, and how the failure is surfaced and announced.
+- A client-side check restates a `BR-`/`FR-` for feedback. It NEVER replaces the
+  service-side rule, and the design cites the id it echoes so the two cannot drift apart
+  silently.
+
+## Recovery
+
+The design states what happens on a double submit, on a stale record, on navigate-away
+mid-flight, and on a lost connection. Where a mutation is optimistic, the rollback is
+stated with it.
+
+## At implement-ui
+
+Each row above becomes real code and a real test. A route's own loading, error and
+not-found states are realised in the router's state files rather than as conditionals
+inside a component, and an interaction with no test for its error state is not done.
+
+## Related
+
+- [[api-integration.<service-stack>]] — the service's status/error-code contract
+- [[state-management]] — the in-flight and cached state these transitions move through
+- [[api-client]] — where a failure enters the lane
+- [[forms-and-validation]] — field-level failures and submission states
+- [[observability]] — what is reported when a state is reached
+- [[accessibility-implementation]] — announcing a state change to assistive technology