# loui-ds 中文文档

规范地址：https://npmcn.com/package/loui-ds/

版本：0\.7\.0
npm 元数据更新时间：2026-11-04T00:27:43.641Z
中文译文更新时间：2026-11-04T02:36:25.550Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：7.6 MB，1080 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：4 个
- peer 依赖：react ^19\.0\.0，react-dom ^19\.0\.0
- 首次发布：2026-11-03T12:50:37.384Z
- 最新版本发布：2026-11-04T00:27:43.344Z
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

Loui DS：一个黑暗的，最小的，功能性的React设计系统。

## 安装

```sh
npm install loui-ds
```

也可以使用：`pnpm add loui-ds`、`yarn add loui-ds`、`bun add loui-ds`

## README

# Loui DS

一个黑暗的，最小的，功能性的React设计系统，用于内部工具，仪表板和应用程序。设计令牌，构建可访问的组件 [React Aria组件](https://react-aria.adobe.com/)，以及AI-ready文档，在一个包中： `loui-ds`。

**生活故事书:** [https://xrazai.github.io/loUI/](https://xrazai.github.io/loUI/) · **对于AI代理：** [llms.txt](https://xrazai.github.io/loUI/llms.txt)， [llms-full.txt](https://xrazai.github.io/loUI/llms-full.txt)， [manifest.json](https://xrazai.github.io/loUI/manifest.json)， [tokens.json](https://xrazai.github.io/loUI/tokens.json)

> 状态：1.0之前版本，在MIT许可下发布在npm上。所有组件都是 `experimental`;api仍然可以改变。

## 突出了

-   **默认情况下可访问。** WCAG 2.2 AA目标，键盘合同，每个楼层都有斧头。
-   **令牌。** 每个颜色、空间、半径和持续时间都是一个 `--ds-*` 从DTCG JSON构建的CSS变量。组件中没有原始值。
-   **React 19，安全的，** 命名级联层中的CSS模块，没有运行时样式库。
-   **它是内置的。** 默认为英语， `pt-BR` 包括，每个字符串都可通过重写 `DSProvider`。
-   **也是为特工设计的。** 生成的组件清单、令牌清单和 `llms.txt` 保持AI工具的准确性。

## 安装

```sh
pnpm add loui-ds react react-dom
```

`npm install loui-ds` 和 `yarn add loui-ds` 工作太。要升级，请运行 `pnpm update loui-ds` 然后阅读 [发布说明](https://github.com/xrazai/loUI/releases) 首先：1.0之前的小版本可能会中断。如果您需要通过URL安装一个版本，每个版本还附加了包tarball。

需要React 19和Node 24或更高版本的工具。

## 快速启动

```tsx
import 'loui-ds/styles.css';
import { Alert, Button, DSProvider } from 'loui-ds';

export function App() {
  return (
    <DSProvider locale="en-US">
      <Alert tone="warning" title="Low stock">
        3 rolls of linen are left. Reorder to avoid delays.
      </Alert>
      <Button variant="primary" onPress={() => console.log('created')}>
        Create order
      </Button>
    </DSProvider>
  );
}
```

更多的 [开始](https://npmcn.com/package/loui-ds/docs/guides/getting-started.md)：样式表； `DSProvider`、字体、主题和服务器端呈现。

## 文档

| 在 | 什么 |
| --- | --- |
| 故事书(`pnpm storybook`） | 组件、令牌、指南和实例 |
| [介绍](https://npmcn.com/package/loui-ds/docs/guides/introduction.md) | 包中包含什么以及它是如何构建的 |
| [原则](https://npmcn.com/package/loui-ds/docs/guides/principles.md) | 三个规则，清晰和专注，代理原则，视觉基础 |
| [内容指南](https://npmcn.com/package/loui-ds/docs/guides/content-guidelines.md) | 缩微本规则 |
| [可访问性](https://npmcn.com/package/loui-ds/docs/guides/accessibility.md) | 一致性目标，键盘模型，我们如何测试 |
| [与AI一起使用](https://npmcn.com/package/loui-ds/docs/guides/using-with-ai.md) | 清单, `llms.txt`，内容规则，故事书MCP |
| [体系结构决策](https://npmcn.com/package/loui-ds/docs/adr) | 为什么事情是这样的（ADR-0001到ADR-0010） |
| [AGENTS.md](https://npmcn.com/package/loui-ds/AGENTS.md) | 用于处理此存储库的人员和代理的约定 |

## 对于人工智能工具

生成，始终与源同步，在 `docs/` 然后运来 `dist/`：

-   [`docs/llms.txt`](https://npmcn.com/package/loui-ds/docs/llms.txt) 和 [`docs/llms-full.txt`](https://npmcn.com/package/loui-ds/docs/llms-full.txt)：索引和完整文档。
-   [`docs/manifest.json`](https://npmcn.com/package/loui-ds/docs/manifest.json)：每个组件、钩子和实用程序，包括道具、变量、消息、故事和使用说明。
-   [`docs/tokens.json`](https://npmcn.com/package/loui-ds/docs/tokens.json)：允许文本和面对的所有标记。
-   [`docs/ai/content-rules.json`](https://npmcn.com/package/loui-ds/docs/ai/content-rules.json)：将规则作为数据复制。
-   [`docs/ai/components/`](https://npmcn.com/package/loui-ds/docs/ai/components)：每个组件一个Markdown页面。

## 快速入门（Windows）

双击 `start.cmd` 在repo根目录下（或从终端运行）。它会安装pnpm和依赖项（如果缺少的话），启动Storybook并在浏览器中打开http://localhost:6006。在任何操作系统上， `pnpm install` 然后 `pnpm start` 也一样。

## 脚本

| 命令 | 目的 |
| --- | --- |
| `pnpm start` | 在端口6006上启动Storybook，并在浏览器中打开它 |
| `pnpm storybook` | 端口6006上的Storybook（也为MCP端点提供服务） `/mcp`） |
| `pnpm build` | 图书馆建到 `dist/`，那么人工智能就显现出来了 |
| `pnpm build-storybook` | 静态的故事书 |
| `pnpm lint` / `pnpm typecheck` | ESLint和样式/ TypeScript |
| `pnpm test` | 所有Vitest项目（单元、浏览器、可视化、故事书） |
| `pnpm test:unit` / `pnpm test:browser` | Chromium中的仅节点测试/组件测试 |
| `pnpm test:a11y` | 故事11检查和浏览器斧测试 |
| `pnpm test:visual` / `pnpm test:visual:update` | 视觉回归/回顾基线更新 |
| `pnpm tokens:build` / `pnpm tokens:check` | 构建令牌/验证提交的输出是否是当前的 |
| `pnpm manifest:build` / `pnpm manifest:check` | 重新生成/验证舱单； `llms.txt` 以及组件页面 |
| `pnpm check` | 闸门：令牌、lint、类型检查、测试和构建 |
| `pnpm changeset` | 记录放行通知 |

## 贡献

阅读 [AGENTS.md](https://npmcn.com/package/loui-ds/AGENTS.md) 首先，它是传统真理的唯一来源。工作来自 [TODO.md](https://npmcn.com/package/loui-ds/TODO.md);完成的工作记录在 [CHANGELOG.md](https://npmcn.com/package/loui-ds/CHANGELOG.md)． 组件遵循 [组件的工作流](https://npmcn.com/package/loui-ds/docs/contributing/component-workflow.md)． 提交遵循常规提交。此存储库中的所有内容都是用英语编写的。

添加或更改组件后，重新生成面向ai的文档并提交：

```sh
pnpm manifest:build
```

## 项目布局

```
src/
  components/<Name>/   component, CSS Module, messages, stories, tests, <Name>.md
  tokens/              DTCG JSON sources and generated output
  styles/              layered base CSS and fonts
  hooks/ utils/ i18n/  hooks, locale-aware utilities, message catalogs
  docs/                Storybook guide pages
  patterns/            domain patterns (second entry point)
docs/                  guides, ADRs, architecture notes, generated AI docs
schemas/               JSON Schemas for the manifests and content rules
scripts/               token and manifest tooling
```

## 许可证

[麻省理工学院](https://npmcn.com/package/loui-ds/LICENSE)． 捆绑的Geist字体是在SIL开放字体许可证([src /风格/字体/ LICENSE.txt](https://npmcn.com/package/loui-ds/src/styles/fonts/LICENSE.txt)）.

## 常见问题

### loui-ds 是什么？

Loui DS：一个黑暗的，最小的，功能性的React设计系统。

### 如何安装 loui-ds？

在项目目录运行 npm install loui-ds，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.0）、react-dom（^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### loui-ds 支持 TypeScript 吗？

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

### loui-ds 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### loui-ds 需要什么版本的 Node\.js？

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

### loui-ds 可以商用吗？

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

### loui-ds 还在维护吗？

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