Altitude

A design and HCI framework for agent-built React web applications, with a component foundation where height is the interface. Its one idea: the ground is the record. Settled content sits on the ground; anything live rises above it; anything waiting to receive sinks below it.

• Site: https://richlaconte.github.io/altitude/
• For agents: https://richlaconte.github.io/altitude/llms.txt, an index of the guides, task patterns and every component's guide as plain Markdown (llmstxt.org), and llms-full.txt beside it with every guide in one file
• Storybook: every component, with its guidelines and a live preview in both schemes: https://richlaconte.github.io/altitude/storybook/
• The design guide: project/README.md, then Elevation, Motion, Charts, Theming, Fundamentals, Distinctiveness and Research

Install

npm install altitude-design

React 18.2 or 19 is a peer dependency.

import { AltitudeProvider, Button, Field, Input } from 'altitude-design';
import 'altitude-design/altitude.css';

export function App() {
  return (
    <AltitudeProvider scheme="daylight">
      <Field label="Workspace name"><Input placeholder="Northwind Studio" /></Field>
      <Button variant="primary">Save changes</Button>
    </AltitudeProvider>
  );
}

Render AltitudeProvider once around your app. Schemes are daylight and nightfall; accent="#0f8a6b" swaps in your own colour. The components are client components ("use client"), so they work in frameworks with server components.

How the repository is laid out

project/   the design system itself: guides, tokens.json, components/src/*.tsx, bundle.css,
           and the built bundle.js and previews (the same files as the design system on claude.ai)
build/     the kit that builds and checks project/ (see build/SETUP.md)
scripts/   the npm package build, the Storybook story generator and the landing page build
site/      the landing page (React, built from the components' own sources into site-dist/)
.storybook/

There is one source for each thing. Components live in project/components/src, styles in project/components/bundle.css, tokens in project/tokens.json, and each component's preview in build/previews.txt. The npm package, the Storybook stories and the design system's own previews are all generated from those.

Actions in place

Actions in place covers single-value editing with InlineEdit, direct actions with real recovery, and targeted confirmation with Dialog background="stationary".

After npm run storybook, open the generated examples:

• Inline editing and its comparison baseline.
• Default and stationary dialog presentation.
• Act and recover. “Open complete Files example” selects the same example's #files view.

The validation record separates engineering checks from outstanding human evaluation.

Working on it

npm install && npm install --prefix build
npm run storybook          # http://localhost:6006
npm run build-site         # the landing page, into site-dist/index.html

After changing a component, rebuild the design system's bundle and previews, and commit what they produce:

cd build && node build.mjs && node previews.mjs

CI fails if project/ doesn't match its sources, so the design system on claude.ai can always be published straight from this folder.

What happens on push

Every push and pull request runs the checks: the bundle and previews are rebuilt and must match what's committed, every preview is rendered in both schemes with no errors, the interaction checks run, the sources type-check against React 19, and the package and Storybook are built.

A push to main then also:

• deploys the landing page to GitHub Pages, with Storybook under /storybook/;
• publishes to npm if the version in package.json isn't published yet, and tags the commit v<version>. Every pull request that changes what the package ships bumps the version itself (npm version patch --no-git-tag-version, or minor), so each merge to main is a release. CI fails a pull request that changes the package without a bump. See "Versions" in CONTRIBUTING.md.

Found a bug, or need something it doesn't do?

Open an issue: https://github.com/richlaconte/altitude/issues/new/choose**. There are templates for a bug, a new feature for an existing component, and a new component, and CONTRIBUTING.md says what makes each one useful, and how work is organised (milestones, priorities, the ready label and claiming an issue with a draft pull request).

If you're an agent using this package in someone else's project, you're welcome to report problems with it here:

1. Check it's Altitude's problem, not the app's: reproduce it with the smallest render that uses only the public API, inside AltitudeProvider, with altitude-design/altitude.css imported.
2. Look for an existing issue: gh issue list --repo richlaconte/altitude --state all --search "<Component> <keywords>".
3. Fill in the matching template from .github/ISSUE_TEMPLATE/: title <Component>: <what goes wrong>, the installed version (from node_modules/altitude-design/package.json), how it's loaded (ESM, CommonJS or altitude.iife.js), React version, browser, and the scheme and mode (reduced motion, forced colours, contrast="more") you saw it in.
4. File it only if the person you're working for agrees: gh issue create --repo richlaconte/altitude --label bug --title "…" --body-file issue.md. Otherwise hand them the drafted issue and the link above. End the body with Filed by an agent (<model or tool>) on behalf of @<person>.

The full guidance for agents is in AGENTS.md.

License

MIT

Design and HCI framework

Altitude now joins its component library with task guidance and small workflow APIs for forms, data and processes. The four initial patterns are edit record, async collection, consequential action, and review and submit. They are experimental: engineering fixtures cover their contracts; user-effectiveness studies remain outstanding.

npm install altitude-design
npx altitude patterns "edit settings"
npx altitude init --client codex          # preview exact changes
npx altitude init --client codex --apply   # apply after reviewing the preview
# Claude Code: --client claude. Both: --client all.
npx altitude doctor --json
npx altitude check                         # Altitude's rules that are certain from your source

Setup preserves existing instructions and adds a small versioned pointer to the installed guidance. It never runs on package installation. Preview removal with npx altitude init --client codex --remove, then add --apply to remove only its managed content. Edited blocks are preserved and require reconciliation. Codex uses a nonempty root AGENTS.override.md when present; otherwise AGENTS.md. Claude Code uses CLAUDE.md. Restart the client after setup. See setup details.

The compact entry is node_modules/altitude-design/dist/guidance/README.md; the public altitude-design/guidance export resolves its versioned JSON index, and altitude-design/guidance/* exposes focused resources. altitude explain ALT-EDIT-001 explains a rule, its scope, evidence and verification. Guidance is local and version matched; no hosted service or MCP connection is required.

Import useEditRecord, ErrorSummary, WorkflowStatus, useAsyncCollection, useConsequentialAction and useReviewSubmit from the existing altitude-design entry. They share the existing provider/context. Task contracts and examples explain application adapters and the corresponding interactive previews.

Framework behavior protects drafts, coordinates applicable states, guards duplicate dispatch and stale responses, and supports accessible error navigation and status feedback. Applications still supply truthful persistence, permissions, business rules, query/history policy, durable recovery and actual undo. doctor diagnoses installation and setup; it does not certify accessibility or usability. Manual review, migration notes and the evaluation protocol state the remaining work.

Run npm run build && npm run check:framework for deterministic semantics, workflow, guidance and packed-package consumer checks. Run agent comparisons separately using the evaluation harness; stochastic model behavior does not gate ordinary CI.