Error States

1// 1. Scope the boundary to the region, not the app2<ErrorBoundary fallback={<SectionError onRetry={refetch} />}>3  <DeploymentList />4</ErrorBoundary>56// 2. Retry transient failures silently before surfacing anything7const { data, error, refetch } = useQuery({8  queryKey: ['deployments'],9  queryFn: fetchDeployments,10  retry: (attempt, err) => err.status >= 500 && attempt < 2,11  retryDelay: (attempt) => 300 * 3 ** attempt,12})1314// 3. Map the failure to a specific message and a possible action15function describe(err: ApiError) {16  switch (err.status) {17    case 403: return { title: 'You do not have access',18                       body: 'Ask an administrator for the deploy:read scope.',19                       action: 'request-access' }        // NOT retry20    case 404: return { title: 'This deployment no longer exists',21                       body: 'It may have been deleted.', action: 'back' }22    case 429: return { title: 'Too many requests',23                       body: 'Wait ' + err.retryAfter + 's and try again.', action: 'retry' }24    default:  return { title: 'Something went wrong on our end',25                       body: 'We have logged this.', action: 'retry' }26  }27}2829// 4. Never clear the form on failure30async function onSubmit(values: Values) {31  try {32    await save(values)33  } catch (err) {34    setError(describe(err))      // values stay exactly as typed35    summaryRef.current?.focus()36  }37}

<!-- Field level -->
<label for="email">Work email</label>
<input id="email" type="email" aria-invalid="true"
       aria-describedby="email-error" value="ada.example.com" />
<p id="email-error" role="alert" class="ds-field__error">
  Enter an email that includes an @ — for example, ada@example.com
</p>

<!-- Form summary: focusable, one link per invalid field -->
<div class="ds-alert ds-alert--danger" role="alert" tabindex="-1" id="summary">
  <p class="ds-alert__title">2 fields need attention</p>
  <ul>
    <li><a href="#email">Work email</a> — must include an @</li>
    <li><a href="#password">Password</a> — at least 12 characters</li>
  </ul>
</div>

<!-- Page level: reference must be selectable -->
<p class="ds-error__ref">
  Error <code>4f21c-8821-9de3</code>
  <button type="button" aria-label="Copy error reference">Copy</button>
</p>

/* Field level: border + icon + message. Never colour alone. */
.ds-input[aria-invalid='true'] {
  border-color: var(--ds-danger-border);
}
.ds-input[aria-invalid='true']:focus {
  border-color: var(--ds-danger);
  box-shadow: 0 0 0 3px var(--ds-danger-subtle);
}

.ds-field__error {
  display: flex;
  gap: 6px;
  font-size: 12px;
  color: var(--ds-danger-text);       /* certified against the tint */
}

/* The summary must be focusable but must not show a ring on click */
.ds-alert[tabindex='-1']:focus { outline: none; }
.ds-alert[tabindex='-1']:focus-visible {
  outline: 2px solid var(--ds-focus-ring);
  outline-offset: 2px;
}

/* References are selectable by default and monospaced so characters
   like 0/O and 1/l are distinguishable when read aloud. */
.ds-error__ref code {
  font-family: var(--font-mono);
  user-select: all;
}

@media (forced-colors: active) {
  .ds-input[aria-invalid='true'] { border: 2px solid; }
}