Moved. This standard now lives in the consolidated DS4AI suite at Polymathie-Studio/ds4ai/standards/grace. This repository is archived and read-only.

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 closes the resilient axis of the suite: a surface discloses its condition, not only its content.

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.

What it governs

A surface has a happy path, where the data is present and the request succeeds, and it has the rest: the moment before the data arrives, the case where there is none, the failure, and the dead route. These are not edge cases; a real surface spends much of its life in them, and each is a condition the reader must be told plainly rather than left to guess. The principle is one line: disclose the condition, not only the content.

GRACE governs what is disclosed, the condition made plain and navigable, with a way forward. It does not govern the mechanism that catches the failure or retries the request, which is framework-specific and belongs to the host. The components here are that disclosure, made honest and accessible by default.

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.

<link rel="stylesheet" href="/grace.css">
<script type="module" src="/grace.js"></script>

<!-- pending: shape the skeleton like what will arrive -->
<div class="grace-skeleton" style="height: 1.5rem; width: 60%"></div>

<!-- absent -->
<grace-empty
  heading="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-error
  heading="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'

function Projects({ loading, error, items, onRetry }) {
  if (loading) return <Skeleton style={{ height: '1.5rem', width: '60%' }} />
  if (error) return <ErrorState heading="That did not load" message="Try again in a moment." action="Retry" onAction={onRetry} />
  if (!items.length) return <Empty heading="No projects yet" message="They will show up here." action="Create a project" href="/new" />
  return items.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: understandable, layered disclosure of complexity
• GRACE: resilient, honest states off the happy path
• 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.