# facett UI error codes — guide
How to use the `facet-<component>-<n>` error-code scheme (`facett_core::errcode`).
## Raise an error in a pane
```rust
use facett_core::facet_err;
// In the empty-state / failure branch of your Facet::ui:
let e = facet_err!(map, 2, "no positions to plot"); // code = "facet-map-2"
e.render(ui); // message (red) + pink code (debug)
```
`facet_err!(component, n, "msg", args…)`:
* `component` is the slug **ident** (`map`, `graph3d`, …).
* `n` is the **literal** integer (append-only per component — see the registry).
* the message is an ordinary `format!` string.
The code (`facet-<component>-<n>`) is formed at compile time; the codeberg URL is
resolved from `errcode::REGISTRY`.
## Put the code in `state_json`
Always fold the code into the pane's observable state so tests + consumers key off it:
```rust
fn state_json(&self) -> serde_json::Value {
let mut j = serde_json::json!({ /* … normal state … */ });
if let Some(e) = &self.error { // your pane holds the raised FacetError
j["error"] = e.to_json(); // { code, component, n, message, codeberg_url, severity }
}
j
}
```
## Report structural severity
A pane that raised a `FacetError` should also report it structurally so the Robot-UI
HARD GATE reads it:
```rust
fn severity(&self) -> facett_core::Severity {
if self.error.is_some() { facett_core::Severity::Error } else { facett_core::Severity::Info }
}
```
`FacetError::render` already attaches a `Severity::Error` a11y atom carrying the code,
so a headless robot reads the code off the AccessKit tree.
## Add a NEW error code
1. Add a row to `errcode::REGISTRY` in `facett-core/src/errcode.rs` with the **next
free `n`** for that component, the canonical message, the crate dir + source file.
2. Raise it with `facet_err!` at the site.
3. The uniqueness guard test fails the build if the `n` (or code) collides.
4. Re-export the registry to markdown (`.nornir/facett-error-codes-registry.md` +
`workspace_nordisk/facett-error-codes-registry.md`).
Never renumber or reuse an existing `n` — the catalog is append-only.
## Consumer mount-prefix (Phase 2)
A consumer that mounts a facett component namespaces the code with its mount:
```rust
let mounted = e.with_consumer_prefix("korp/cases"); // korp/cases:facet-map-2
mounted.to_json(); // carries BOTH `code` (base) and `mounted_code`
```
## Showcase (facett-demo)
* `Errors` tab — the pink codes, git-hash stamp, codeberg links, mount-prefix demo,
and the error-code MATRIX slide.
* `Manual` tab — the in-app manual.
* About / Diagnostics popup (the `legend` toggle) — git hash + codeberg per component.
Use `FacetError::render_demo` (neutral a11y atom, `Severity::Info`) — NOT `render` —
in any surface that displays codes as a *catalog* rather than a live failure, so it
does not trip the Robot-UI gate.