GRACE

GRACE is state components for the off-happy-path: the moment before data arrives, the case where there is none, the failure, and the dead route. AI-built surfaces ship the happy path and skip these, so a list shows a blank instead of "nothing yet," a fetch shows a bare spinner, and a failed request white-screens. GRACE renders the four states honestly, accessible by default, themed by TEMPER. It is the reusable form of LUCID's off-happy-path principle.

No build step is required to use it: the framework-agnostic core is one small ES module and one CSS file, with a React binding alongside. The package name is grace-states; it is planned for npm but not yet published.

The four states

• Skeleton (pending): a content-shaped placeholder, not a bare spinner, so the layout does not jump when the real content lands.
• Empty (absent): why it is empty and the one next step, not a blank and not "no data."
• Error (failed): plain language and a way back, never a raw code or a silent swallow.
• NotFound (unreachable): says it is not here and points somewhere real, for a 404 or a dead route.

Contents

• grace.css: the skeleton and the shared state layout, written against TEMPER's tokens with a fallback for each.
• grace.js: the zero-dependency core. Registers <grace-empty>, <grace-error>, and <grace-notfound>; the pending state is the .grace-skeleton class.
• react/index.js: the React binding, Skeleton, Empty, ErrorState, and NotFound.
• demo.html: a self-contained preview of all four states.

Quickstart

Any site, no framework

Copy grace.css and grace.js into your project. Apply the skeleton class to placeholders and use the elements for the rest.

<linkrel="stylesheet" href="/grace.css"><scripttype="module" src="/grace.js"></script><!-- pending: shape the skeleton like what will arrive --><divclass="grace-skeleton" style="height: 1.5rem; width: 60%"></div><!-- absent --><grace-emptyheading="No projects yet"
message="Your projects will show up here once you create one."
action="Create a project" href="/new"></grace-empty><!-- failed: an action with no href dispatches grace-action, which is your retry --><grace-errorheading="That did not load"
message="Something went wrong fetching your data. Try again in a moment."
action="Retry"></grace-error>

React

import'grace-states/grace.css'import{Skeleton,Empty,ErrorState,NotFound}from'grace-states/react'functionProjects({ loading, error, items, onRetry }){if(loading)return<Skeletonstyle={{height: '1.5rem',width: '60%'}}/>if(error)return<ErrorStateheading="That did not load"message="Try again in a moment."action="Retry"onAction={onRetry}/>if(!items.length)return<Emptyheading="No projects yet"message="They will show up here."action="Create a project"href="/new"/>returnitems.map(renderProject)}

Accessibility

The error state uses an assertive live region so a screen reader announces it; empty and not-found use a polite one. Every action is a real button or link, keyboard-operable with a visible focus ring. The skeleton pulse runs only under prefers-reduced-motion: no-preference, and the placeholder carries no text for assistive tech to read.

Composing with TEMPER

GRACE reads TEMPER's semantic tokens (surface, border, text, accent, danger, plus the spacing and type scales) with a fallback for each. Set a TEMPER mode on the root and GRACE follows it; where TEMPER is absent, the fallbacks render a clean neutral state.

Part of DS4AI, the Design Suite for AI

GRACE is one instrument in DS4AI, the Design Suite for AI, from Polymathie-Studio: small, dependency-free pieces that each close one axis of the invisible-correctness layer, the part of a shipped surface a look-at-it review cannot see and that fast, AI-assisted building drops.

• TEMPER: perceivable, color and design tokens
• GRASP: operable, interaction components
• LUCID + GRACE: honest off the happy path, disclosure and state components
• HASP: hardened, client-surface security posture
• BEACON: findable, head metadata and site files
• FLEET: fast and stable, delivery

MISSING is the standard at the center of DS4AI: it names the axes, routes each to its instrument, and ships a machine-readable manifest and a conformance auditor. Adopt one and the others compose with it.

License

Apache-2.0. Copyright 2026 Regis Lloyd Chapman. See LICENSE and NOTICE.