Reclaim Design

@reclaimprotocol/design is Reclaim Protocol's web design system for semantic HTML, HTMX, server-rendered templates, and framework applications. The package extends a pinned Oat foundation with Reclaim tokens, CSS, framework-neutral behaviors, icons, assets, and custom elements for stateful composites.

The source is TypeScript at the repository root. Published applications consume compiled ESM and declaration files from dist; they don't compile the SDK source.

Documentation

• Use DESIGN.md for visual rules, component composition, and agent-assisted product integration.

Deploy the catalog

The catalog is bound to the reclaim-design-catalog Firebase project. Build and deploy it from the repository root:

npm run deploy

Firebase Hosting publishes apps/catalog/dist. The configuration preserves SPA navigation, disables caching for the HTML entry point, and caches hashed assets immutably.

Install the package

Install the package with your package manager:

npm install @reclaimprotocol/design

Install a tagged Git revision directly when the repository is the package source:

npm install "git+https://<repository-url>.git#v1.0.0"

Or declare the package name explicitly:

{
  "dependencies": {
    "@reclaimprotocol/design": "git+ssh://git@<repository-url>.git#v1.0.0"
  }
}

The root prepare script compiles dist for Git installations. Pin a tag or commit for deterministic dependency resolution.

Load the styles

Import tokens before component styles in your application's JavaScript or CSS entry point:

import '@reclaimprotocol/design/tokens.css';
import '@reclaimprotocol/design/css';

The complete CSS entry includes the pinned Oat foundation, Reclaim's token bridge, components, interaction effects, and utilities. Add application overrides after these imports.

You can import smaller style entry points when you manage the cascade yourself:

import '@reclaimprotocol/design/tokens.css';
import '@reclaimprotocol/design/css/base';
import '@reclaimprotocol/design/css/components';
import '@reclaimprotocol/design/css/effects';
import '@reclaimprotocol/design/css/utilities';

Use semantic HTML, HTMX, or templates

Render normal HTML with the public rc- classes. JavaScript enhancement is optional for static controls.

<button class="rc-button" data-variant="primary">Verify claim</button>

<label class="rc-field">
  <span class="rc-field__label">Provider identifier</span>
  <input class="rc-input" name="provider" />
</label>

Initialize delegated behaviors once in the browser for dialogs, copy actions, comboboxes, expansion controls, themes, pointer effects, and the guilloche:

import {initReclaimBehaviors} from '@reclaimprotocol/design/behaviors';

const reclaim = initReclaimBehaviors(document);

// Call this when your application is unmounted.
reclaim.destroy();

Delegated event handling continues to work when HTMX or another server-driven framework replaces fragments.

Compose framework applications

React, HTMX, KitaJS, and other consumers render the same documented HTML. The application owns state, routing, validation policy, and product-specific composition; the SDK owns tokens, styling, accessibility contracts, and shared DOM behavior.

For tabs, render Oat's semantic element and load its browser runtime:

<ot-tabs class="rc-tabs">
  <div role="tablist" aria-label="Account settings">
    <button role="tab" type="button" aria-selected="true">Profile</button>
    <button role="tab" type="button">Security</button>
  </div>
  <div role="tabpanel">Profile settings</div>
  <div role="tabpanel">Security settings</div>
</ot-tabs>

import '@reclaimprotocol/design/oat';

Prepare and edit local assets

Register Reclaim custom elements once at the browser boundary:

import {defineReclaimElements} from '@reclaimprotocol/design/elements';

defineReclaimElements();

Compose a native file input with the local asset element:

<rc-local-asset-field accept="image/png,image/jpeg" max-size="5000000">
  <label class="rc-upload">
    <strong>Logo</strong>
    <span>Choose a PNG or JPEG image up to 5 MB.</span>
    <input type="file" />
  </label>
</rc-local-asset-field>

<rc-image-editor
  id="logo-editor"
  aspect-ratio="1"
  output-width="1600"
  fit="contain"
></rc-image-editor>

Set field.prepare when a file needs asynchronous local processing. Listen for reclaim:assetchange to receive the prepared local URL, then set editor.source and call editor.open(). The editor emits reclaim:imageapply with the PNG data URL. See docs/local-assets.md for the complete event and property examples.

Use tokens in TypeScript

import {
  coreTokens,
  cssVariable,
  themes,
  type TokenPath,
} from '@reclaimprotocol/design/tokens';

const token: TokenPath = 'color.action.primary';
const customProperty = cssVariable(token);
const darkPrimary = themes.dark[token];

Prefer CSS custom properties in UI code. Typed values are useful for tooling, data visualization, and integrations that can't read CSS.

Use icons

The framework-neutral icon entry returns local SVG strings:

import {icon} from '@reclaimprotocol/design/icons';

const accessibleIcon = icon('shieldCheck', 'Verified');

Applications can place the SVG in a trusted rendering boundary or wrap the icon entry with their own view helper.

Use Reclaim identity assets

Approved transparent marks, color tiles, wordmarks, and lockups are available from the isolated brand entry point. Importing this registry lets a bundler copy the approved identity set into the application build.

import {reclaimLogos} from '@reclaimprotocol/design/brand';

const blueMark = reclaimLogos.find(logo => logo.id === 'blue-transparent');

Each entry contains a stable id, a human-readable label, and a bundled image src. Use the label in asset pickers and use the source in an image element or canvas renderer.

Use custom elements

The custom-element entry is browser-only because it extends HTMLElement:

import {defineReclaimElements} from '@reclaimprotocol/design/elements';

defineReclaimElements();

Load it in a client entry point or dynamic import, not during server rendering. The optional vendored Oat runtime is also browser-only:

await import('@reclaimprotocol/design/oat');

Select a theme

Set data-theme on the nearest theme boundary:

<main class="rc-surface" data-theme="dark">
  <!-- Application content -->
</main>

Use createThemeController from @reclaimprotocol/design/behaviors when the choice must follow the system theme or persist in local storage.

Preserve tree shaking

Import the narrowest entry point that matches your runtime:

import {createDialogController} from '@reclaimprotocol/design/behaviors';
import {defineReclaimElements} from '@reclaimprotocol/design/elements';

Don't import files from @reclaimprotocol/design/dist directly. The package's public export map provides stable entry points, generated declarations, and separate ESM modules. CSS and browser registration modules are intentionally marked as side effects; other modules use named exports for tree shaking.

Configure TypeScript and Vite

Vite projects should use bundler module resolution and include Vite's ambient asset declarations:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler"
  }
}

Add this file when the project doesn't already contain it:

// src/vite-env.d.ts
/// <reference types="vite/client" />

The package publishes explicit declaration targets for /css, /tokens.css, and the other stylesheet exports. Current TypeScript versions can therefore resolve package CSS imports through the export map. Vite's declaration remains necessary for local imports such as ./app.css.

For a bundler that doesn't provide CSS declarations, add a project declaration:

// src/assets.d.ts
declare module '*.css';

Fix stale CSS import diagnostics

If VS Code reports error TS2882 for a package stylesheet:

1. Confirm that the installed package is current with npm ls @reclaimprotocol/design.
2. Reinstall dependencies if the package's exports map is stale.
3. Run your project's TypeScript check outside the editor.
4. In VS Code, run TypeScript: Select TypeScript Version, select the workspace version, and then run TypeScript: Restart TS Server.
5. For a local repository checkout, build the SDK with npm run build:sdk before opening the consumer.

Don't work around package CSS errors by importing private dist files. Report an unresolved public entry point as a package issue instead.

Build the package from source

From the repository root, run:

npm install
npm run tokens:build
npm run build:sdk

The build performs these operations:

1. Cleans the package dist directory.
2. Compiles TypeScript to ESM JavaScript.
3. Generates .d.ts declarations and declaration maps.
4. Copies CSS, token styles, fonts, images, and vendored Oat assets.

Run the complete verification suite before publishing:

npm run verify:full

Public entry points

Entry point	Purpose	Runtime
@reclaimprotocol/design	Behaviors and icons barrel	Browser or bundler
@reclaimprotocol/design/behaviors	Progressive DOM enhancement	Browser
@reclaimprotocol/design/behaviors/core	DOM-free behavior helpers	Any ESM runtime
@reclaimprotocol/design/elements	Custom-element registration	Browser only
@reclaimprotocol/design/icons	SVG icon strings	Any ESM runtime
@reclaimprotocol/design/brand	Approved identity assets	Browser or bundler
@reclaimprotocol/design/tokens	Typed token values	Any ESM runtime
@reclaimprotocol/design/tokens.css	Token variables and themes	CSS bundler
@reclaimprotocol/design/css	Complete component stylesheet	CSS bundler
@reclaimprotocol/design/oat	Optional Oat runtime	Browser only

Licensing

Read the included THIRD_PARTY_NOTICES.md before publishing or redistributing builds that include the optional GnuMICR font assets. Oat's MIT license and provenance records are also included in the npm package.