Error codes and message registry

Never hardcode user-facing error, alert or empty-state strings in components or controllers. Every message has a code in one registry.

Why

1. One wording per situation, reused everywhere.
2. Type-safe references (no typos).
3. The server reports what happened; the client decides how to say it.
4. Ready for translation and for docs that link per code.

Registry

// {{MESSAGES_FILE}}
export interface AppMessage {
  code: string;
  title?: string;
  message: string;
  severity: "success" | "info" | "warning" | "error";
}

export const MESSAGES = {
  ERR_NETWORK_TIMEOUT: {
    code: "ERR_NETWORK_TIMEOUT",
    title: "Connection timed out",
    message: "We couldn't reach the server. Check your connection and try again.",
    severity: "error",
  },
} as const satisfies Record<string, AppMessage>;

Rules

1. No inline strings. Bad: <Alert severity="error">Service not configured. Check settings.</Alert> Good: const m = MESSAGES.ERR_SERVICE_OFFLINE; <Alert severity={m.severity}>{m.message}</Alert>
2. Structured API errors. The server never sends plain text:

   { "error": true, "code": "ERR_INVALID_BARCODE", "details": "expected 13 digits" }
   

   details is for logs and developers, never shown raw to users.
3. New message: add the key, fill code/title/message/severity, reference it by key.
4. Prefixes: ERR_ failures, WARN_ warnings, INFO_ neutral/empty states, SUCC_ confirmations.
5. Copy: say what happened and what to do next; no blame, no "please", no exclamation marks. Never leak internals (stack traces, SQL, hostnames).
6. Codes are stable: rename the message, never the code.

Customize for your project

{{MESSAGES_FILE}} (e.g. src/registry/messages.ts), your server error middleware, and where help pages per code live ({{DOCS_DIR}}/errors/<code>).