# altitude-design 中文文档

规范地址：https://npmcn.com/package/altitude-design/

版本：0\.6\.0
npm 元数据更新时间：2026-11-03T02:20:49.324Z
中文译文更新时间：2026-11-03T02:52:52.811Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/altitude-design
原文对照：https://npmcn.com/package/altitude-design/?lang=original
项目主页：https://richlaconte.github.io/altitude/
源码仓库：https://github.com/richlaconte/altitude

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：10.9 MB，420 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0，react-dom ^18\.2\.0 \|\| ^19\.0\.0，@tiptap/core \>=2\.0\.0，@xyflow/react \>=12\.0\.0，@codemirror/view \>=6\.0\.0，@lezer/highlight \>=1\.0\.0，@codemirror/state \>=6\.0\.0，@codemirror/language \>=6\.0\.0
- 首次发布：2026-10-22T10:02:45.491Z
- 最新版本发布：2026-11-03T02:20:48.916Z
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

一个设计和HCI框架，用于代理构建的React web应用程序，其中高度是接口。

## 安装

```sh
npm install altitude-design
```

也可以使用：`pnpm add altitude-design`、`yarn add altitude-design`、`bun add altitude-design`

## README

# 高度

一个设计和HCI框架，用于代理构建的React web应用程序，具有组件基础 **高度是界面**． 它的理念是：地面就是记录。固定的内容坐在地上；任何有生命的东西都高于它；任何等待接收的东西都会沉到它下面。

-   **网站:** [https://richlaconte.github.io/altitude/](https://richlaconte.github.io/altitude/)
-   **代理:** [https://richlaconte.github.io/altitude/llms.txt](https://richlaconte.github.io/altitude/llms.txt)，索引指南，任务模式和每个组件的指南作为普通Markdown ([llmstxt.org](https://llmstxt.org/)), `llms-full.txt` 在它旁边，把所有的指南放在一个文件夹里
-   **故事书:** 每个组件，以及它的指导方针和两个方案的实时预览： [https://richlaconte.github.io/altitude/storybook/](https://richlaconte.github.io/altitude/storybook/)
-   **设计指南：** [`project/README.md`](https://github.com/richlaconte/altitude/blob/main/project/README.md),然后 [海拔高度](https://github.com/richlaconte/altitude/blob/main/project/Elevation.md)， [运动](https://github.com/richlaconte/altitude/blob/main/project/Motion.md)， [图表](https://github.com/richlaconte/altitude/blob/main/project/Charts.md)， [主题](https://github.com/richlaconte/altitude/blob/main/project/Theming.md)， [基本面](https://github.com/richlaconte/altitude/blob/main/project/Fundamentals.md)， [特殊性](https://github.com/richlaconte/altitude/blob/main/project/Distinctiveness.md) 和 [研究](https://github.com/richlaconte/altitude/blob/main/project/Research.md)

## 安装

```sh
npm install altitude-design
```

React 18.2或19是一个对等依赖。

```tsx
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>
  );
}
```

渲染 `AltitudeProvider` 在你的应用程序中 `daylight` 和 `nightfall`； `accent="#0f8a6b"` 换你自己的颜色。这些组件是客户端组件(`"use client"`)，因此它们在带有服务器组件的框架中工作。

| 进口 | 它是什么？ |
| --- | --- |
| `altitude-design` | 组件（ESM和CommonJS，带类型） |
| `altitude-design/altitude.css` | 令牌和组件样式在一个文件中（它也从谷歌字体加载Instrument Sans和JetBrains Mono） |
| `altitude-design/altitude.no-fonts.css` | 相同的样式没有谷歌字体导入，所以页面不做第三方请求；自行托管字体或设置 `--font-sans` 和 `--font-mono` 你自己的字体（都退回到系统字体） |
| `altitude-design/fonts.css` | 只有谷歌字体导入，以配对 `tokens.css` 或者 `altitude.no-fonts.css` |
| `altitude-design/tokens.css`， `altitude-design/tokens.json` | 代币本身 |
| `altitude-design/altitude.iife.js` | 一个 `<script>` 构建集 `window.Altitude`，对于没有捆绑器的页面；它预计React 18的UMD构建为 `window.React` 和 `window.ReactDOM` |

## 仓库是如何布局的

```
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/
```

每样东西都有一个来源。组件存在于 `project/components/src`，样式 `project/components/bundle.css`，代币 `project/tokens.json`，以及每个组件的预览 `build/previews.txt`． npm包、Storybook故事和设计系统自己的预览都是由它们生成的。

## 适当的行动

[适当的行动](https://npmcn.com/package/altitude-design/project/ActionsInPlace.md) 涵盖单值编辑 `InlineEdit`，直接行动与真正的恢复，有针对性的确认与 `Dialog background="stationary"`.

后 `npm run storybook`，打开生成的示例：

-   [内联编辑及其比较基线](http://localhost:6006/?path=/story/inputs-inlineedit--preview).
-   [默认和固定对话框表示](http://localhost:6006/?path=/story/overlays-dialog--preview).
-   [行动并恢复](http://localhost:6006/?path=/story/patterns-actionsinplace--preview)． “打开完整的文件示例”选择相同的示例 `#files` 视图。

这个 [验证记录](https://npmcn.com/package/altitude-design/project/ActionsInPlaceValidation.md) 将工程检查与杰出的人员评估分开。

## 正在努力

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

更改组件后，重新构建设计系统的bundle和预览，并提交它们生成的内容：

```sh
cd build && node build.mjs && node previews.mjs
```

如果CI失败 `project/` 和来源不符，所以克劳德的设计系统。Ai总是可以直接从这个文件夹发布。

## push时发生了什么

每个推送和拉取请求都会运行这些检查：重新构建包和预览，并且必须与提交的内容匹配，每个预览都在两种方案中呈现，没有错误，交互检查运行，对React 19进行源类型检查，包和故事书被构建。

推动… `main` 然后也:

-   将登陆页面部署到GitHub Pages， Storybook在下面 `/storybook/`；
-   向国家预防机制发布信息 **如果版本是 `package.json` 还没有出版**，并标记提交 `v<version>`． 每一个改变包所载内容的拉取请求都会影响版本本身(`npm version patch --no-git-tag-version`，或者 `minor`)，所以每次归并到 `main` 是一种释放。CI失败了一个拉取请求，该请求更改了包而没有发生颠簸。参见中的“版本” [CONTRIBUTING.md](https://npmcn.com/package/altitude-design/CONTRIBUTING.md).

## 发现了一个bug，或者需要一些它不能做的事情？

打开一个问题： **[https://github.com/richlaconte/altitude/issues/new/choose \* \*](https://github.com/richlaconte/altitude/issues/new/choose**)． 有针对bug的模板、针对现有组件的新特性模板、针对新组件的模板和针对新组件的模板 [CONTRIBUTING.md](https://github.com/richlaconte/altitude/blob/main/CONTRIBUTING.md) 说明是什么让每一项工作有用，以及如何组织工作（里程碑、优先事项、目标） `ready` 用草稿拉取请求标记并声明问题)。**

**如果你是用这个包裹的特工** 在其他人的项目中，欢迎您在这里报告问题：

1.  检查这是海拔的问题，而不是应用程序的问题：用最小的渲染再现它，只使用公共API，内部 `AltitudeProvider`, `altitude-design/altitude.css` 进口的。
2.  寻找一个存在的问题： `gh issue list --repo richlaconte/altitude --state all --search "<Component> <keywords>"`.
3.  从中填写匹配模板 [`.github/ISSUE_TEMPLATE/`](https://github.com/richlaconte/altitude/blob/main/.github/ISSUE_TEMPLATE/):标题 `<Component>: <what goes wrong>`，安装的版本(从 `node_modules/altitude-design/package.json`)，如何加载(ESM， CommonJS或 `altitude.iife.js`)， React版本，浏览器，以及方案和模式(减少运动，强制颜色， `contrast="more"`你在里面看到了。
4.  只有在你的上司同意的情况下才提交： `gh issue create --repo richlaconte/altitude --label bug --title "…" --body-file issue.md`． 否则，把草稿和上面的链接交给他们。正文以 `Filed by an agent (<model or tool>) on behalf of @<person>.`

完整的特工指南出来了 [AGENTS.md](https://github.com/richlaconte/altitude/blob/main/AGENTS.md).

## 许可证

[麻省理工学院](https://github.com/richlaconte/altitude/blob/main/LICENSE)

## 设计和HCI框架

Altitude现在加入了它的组件库，为表单、数据和流程提供任务指导和小型工作流api。四种初始模式是 **编辑记录**， **异步集合**， **重要的行动**, **审核并提交**． 它们是实验性的：工程设备涵盖了它们的合同；用户有效性研究仍然很突出。

```sh
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
```

安装程序保留现有指令，并向已安装的指导添加一个小的版本化指针。它永远不会在包安装上运行。预览删除 `npx altitude init --client codex --remove`，然后加上 `--apply` 仅删除其托管内容。编辑后的块将被保留，并需要进行协调。Codex使用非空根 `AGENTS.override.md` 当礼物;否则 `AGENTS.md`． Claude Code用法 `CLAUDE.md`． 安装完成后重新启动客户端。看到 [设置的细节](https://npmcn.com/package/altitude-design/docs/framework/AGENT-SETUP.md).

紧凑的入口是 `node_modules/altitude-design/dist/guidance/README.md`;公众 `altitude-design/guidance` export解析其版本化的JSON索引，并且 `altitude-design/guidance/*` 暴露集中的资源。 `altitude explain ALT-EDIT-001` 说明一项规则、其范围、证据和验证。指导是本地的，版本匹配；不需要托管服务或MCP连接。

进口 `useEditRecord`， `ErrorSummary`， `WorkflowStatus`， `useAsyncCollection`， `useConsequentialAction` 和 `useReviewSubmit` 从现有的 `altitude-design` 条目。它们共享现有的提供者/上下文。 [任务契约和示例](https://npmcn.com/package/altitude-design/project/framework/README.md) 解释应用程序适配器和相应的 [交互式预览](https://richlaconte.github.io/altitude/storybook/?path=/story/patterns-editrecord--preview).

框架行为保护草稿，协调适用状态，保护重复调度和陈旧响应，并支持可访问的错误导航和状态反馈。应用程序仍然提供真实的持久性、权限、业务规则、查询/历史策略、持久恢复和实际撤销。 `doctor` 诊断安装和设置；它不证明可访问性或可用性。 [手动审查](https://npmcn.com/package/altitude-design/docs/framework/MANUAL-VALIDATION.md)， [迁移笔记](https://npmcn.com/package/altitude-design/docs/framework/RELEASE-NOTES.md) 和 [评估协议](https://npmcn.com/package/altitude-design/evals/framework/README.md) 说明剩余的工作。

运行 `npm run build && npm run check:framework` 对于确定性语义，工作流，指导和打包包消费者检查。使用评估工具分别运行代理比较；随机模型行为不限制普通CI。

## 常见问题

### altitude-design 是什么？

一个设计和HCI框架，用于代理构建的React web应用程序，其中高度是接口。

### 如何安装 altitude-design？

在项目目录运行 npm install altitude-design，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）、react-dom（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 altitude，可以用 npx altitude 直接运行。

### altitude-design 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### altitude-design 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### altitude-design 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### altitude-design 可以商用吗？

altitude-design 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### altitude-design 还在维护吗？

最新版本 0\.6\.0 发布于 2026/11/03（今天）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。