# @lapismd/design-core 中文文档

规范地址：https://npmcn.com/package/%40lapismd/design-core/

版本：0\.10\.1
npm 元数据更新时间：2026-11-01T16:04:58.506Z
中文译文更新时间：2026-11-01T16:57:50.616Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：13.6 MB，4469 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.11 \|\| ^24 \|\| \>=26
- 运行依赖：41 个
- peer 依赖：svelte ^5\.0\.0
- 首次发布：2026-08-27T19:32:41.150Z
- 最新版本发布：2026-11-01T16:04:58.179Z
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

共享的Lapis设计系统、表单、外壳和工作空间原语

## 安装

```sh
npm install @lapismd/design-core
```

也可以使用：`pnpm add @lapismd/design-core`、`yarn add @lapismd/design-core`、`bun add @lapismd/design-core`

## README

# `@lapismd/design-core`

[![Release public packages](https://github.com/lapismd/design-core/actions/workflows/release.yml/badge.svg)](https://github.com/lapismd/design-core/actions/workflows/release.yml) [![Storybook Pages](https://github.com/lapismd/design-core/actions/workflows/publish-storybook-pages.yml/badge.svg)](https://github.com/lapismd/design-core/actions/workflows/publish-storybook-pages.yml) [![npm version](https://img.shields.io/npm/v/@lapismd/design-core.svg)](https://www.npmjs.com/package/@lapismd/design-core) [![Storybook](https://img.shields.io/badge/storybook-live-ff4785?logo=storybook&logoColor=white)](https://lapismd.github.io/design-core/)

用于LapisMD应用程序的Svelte 5设计系统包。它提供原生css 组件族，表单原语，搜索/过滤控件，AI聊天 表示、diff视图、shell布局和工作空间框架。

Design Core拥有可重用的表示和控制器行为。消费者的 路由、数据加载、持久化、域状态、传输和应用程序 政策。

## 当前包状态

-   公共包: `@lapismd/design-core@0.1.0`.
-   运行时同行: `svelte@^5`.
-   源包：导出指向跟踪 `.svelte`， `.ts`, `.css` 源 文件为现代苗条/维特消费者。
-   规范存储库: `lapismd/design-core`.
-   目录: [https://lapismd.github.io/design-core/](https://lapismd.github.io/design-core/).

## 安装

此版本需要用户授权的临时版本 `bits-ui@2.20.2` 规划补丁。 每个安装根必须显式地配置相同的补丁并冻结 lockfile;Design Core的依赖项元数据不会传播该设置。 遵循 [打包的补丁合同](https://npmcn.com/package/%40lapismd/design-core/patches/README.md) 以及它的校验和清单 在确定运行时行为之前。补丁保留链接预览和滑块 在反复安装FocusScope期间拆卸安全性和键盘焦点。

```sh
pnpm add @lapismd/design-core svelte
```

在应用程序边界处导入一次共享样式表：

```ts
import "@lapismd/design-core/styles.css";
```

然后从它们的公共层导入组件族：

```svelte
<script lang="ts">
  import { Button } from "@lapismd/design-core/shadcn/button";
  import { StructuredForm } from "@lapismd/design-core/forms";
  import * as AppShell from "@lapismd/design-core/shell";
</script>
```

## 公共层

| 层 | 进口 | 使用 |
| --- | --- | --- |
| 样式和主题 | `@lapismd/design-core/styles.css`， `@lapismd/design-core/themes/lapis.css` | 主题令牌，基础包样式，青金石主题资产 |
| shadcn原语 | `@lapismd/design-core/shadcn/<family>` | 低级按钮、输入、对话框、弹出窗口、菜单、选项卡、滚动区域和布局原语 |
| 形式 | `@lapismd/design-core/forms`， `@lapismd/design-core/forms/core` | 结构化表单、字段呈现器、表单控件、编辑器、审查/差异功能 |
| 过滤器 | `@lapismd/design-core/filter` | 搜索栏、强力搜索令牌和过滤查询CodeMirror语言 |
| 人工智能 | `@lapismd/design-core/ai`， `@lapismd/design-core/ai/chat` | 主机控制的聊天布局、消息、编写器、工具调用、听写和状态表示 |
| 人工智能实验 | `@lapismd/design-core/ai/experimental` | 实验室衍生的聊天提示标记为实验性 |
| Diff | `@lapismd/design-core/diff` | 文件清单、更改统计、文件差异、合并表示和无头差异模型 |
| 壳牌 | `@lapismd/design-core/shell` | 有边界的应用chrome、侧边栏、主体区域、响应式shell状态和shell布局持久性适配器 |
| 工作空间 | `@lapismd/design-core/workspace` | 已注册的视图、选项卡、拆分、侧边栏、面板、插件、命令、设置和工作区持久性适配器 |

聚焦的组件子路径也被导出以保持兼容性，特别是在 `forms` 和 `workspace`． 治疗 `package.json` 导出为支持的导入 边界。

## 组件覆盖

已实现的shadcn家族包括：

手风琴，警报，警报对话框，徽章，面包屑，按钮，按钮组，卡片， 复选框、代码、代码块、可折叠、列画布、命令、命令视图、 上下文菜单，对话框，抽屉，下拉菜单，空白，字段，悬停卡，输入， 输入组，标签，分页，弹出窗口，进度，可调整大小，滚动区域， 选择、分隔符、工作表、侧边栏、框架、滑块、旋转器、滑动项、 开关，表，选项卡，文本区，切换，切换组和工具提示。

更高层组成了这些原语：

-   表单提供结构化呈现、基于YAML/ json的编辑、列表编辑、 自动补全/芯片输入，日期/时间/参考选择器，代码/YAML编辑器，以及 修补检查表面。
-   过滤器提供了可重用的搜索chrome +解析器/语言助手 过滤查询语法。
-   AI提供仅显示的聊天部分。它没有自己的模式呼叫，网络 传输、会话存储或主机操作。
-   Diff提供文件/更改/合并UI。宿主自己的存储库状态和文件 内容。
-   Shell提供应用程序chrome和响应侧边栏，而无需拥有 应用程序导航。
-   工作区为注册视图、布局提供了较重的应用框架 持久性、命令、面板和插件。

使用Shell应用程序chrome。当主机需要注册时使用Workspace 视图、选项卡/分割布局、插件、设置、命令调色板或完整的工作空间 持久性。

## 样式合同

Design Core使用本地CSS和公共自定义属性。消费者应该注意着装 通过令牌和类型化的道具，而不是修补内部选择器。

1.  进口 `@lapismd/design-core/styles.css` 一次。
2.  覆盖公共 `--ui-*` 变量在 `:root` 或者是共同的祖先。
3.  为变量、密度、布局和状态选择组件道具。
4.  避免重写私有DOM结构或内部类名。

发布的档案包含准备好的浏览器CSS和字体资产。消费者做 不需要Tailwind，它的Vite插件，或源扫描配置。顺风 编译停留在内部创作和转换；生成私有CSS 变量仍然是普通的浏览器CSS。现有的Mira依赖仍然可以 安装一个Tailwind peer，但是Design Core的准备样式不使用它。 使用 `pnpm package:local` 当验证 归档边界，而不是导入未准备好的创作样式表。

源和存档门拒绝实用程序选择器，包括复合和 嵌套的选择器。组件状态清理由 [切片2记录](https://npmcn.com/package/%40lapismd/design-core/spec/records/plain-browser-css-components.md)． 主题/导入 重组和下游发布仍然是分开的可审查的片段。

令牌的家庭:

| 范围 | 令牌的例子 | 来源 |
| --- | --- | --- |
| 全球主题 | `--background`， `--foreground`， `--primary`， `--border`， `--radius` | `src/theme.css` |
| Shadcn家族代币 | `--ui-button-*`， `--ui-input-*`， `--ui-card-*` | 并置家族令牌文件 |
| 形式 | `--ui-form-*` | `@lapismd/design-core/forms/form.tokens.css` |
| 人工智能 | `--ui-ai-*` | `@lapismd/design-core/ai/tokens` |
| Diff | `--ui-diff-*` | `@lapismd/design-core/diff/tokens` |
| 壳牌 | `--ui-shell-*` | `@lapismd/design-core/shell/shell.tokens.css` |
| 工作空间 | `--ui-workspace-*` | `@lapismd/design-core/workspace/workspace.tokens.css` |

分量根戳稳定 `data-ui-component` 和 `data-ui-part` 属性 用于包拥有的样式。消费者可以使用侧通道属性 ，但不应覆盖设计核心标识属性 包装组件。

## 布局规范

源代码布局遵循公共目录层和包层：

```text
src/
  styles.css, theme.css, storybook.css
  shared/
    shadcn/<family>/
    forms/<family>/
    filter/<family>/
    ai/<component>/
    ai/experimental/<component>/
    diff/<family>/
    shell/app-shell/
    workspace/<family>/
```

一个目录拥有一个独立的组件族或一个复合族。 多部分组件一起保存在所属的家族文件夹中。公共桶 生活在层根或家庭根。

## 用法示例

### shadcn原始

```svelte
<script lang="ts">
  import { Button } from "@lapismd/design-core/shadcn/button";
</script>

<Button variant="default" size="sm">Save</Button>
```

### 壳牌布局

```svelte
<script lang="ts">
  import * as AppShell from "@lapismd/design-core/shell";

  const shell = AppShell.createAppShellController({
    layoutId: "app",
  });
</script>

<AppShell.Root controller={shell}>
  <AppShell.Sidebar side="left">
    <AppShell.Sidebar.Header>Navigation</AppShell.Sidebar.Header>
    <AppShell.Sidebar.Body>...</AppShell.Sidebar.Body>
  </AppShell.Sidebar>

  <AppShell.Main>
    <AppShell.Toolbar>Toolbar</AppShell.Toolbar>
    <AppShell.Body>
      <AppShell.Body.Content>Application content</AppShell.Body.Content>
    </AppShell.Body>
  </AppShell.Main>
</AppShell.Root>
```

### 形式

```svelte
<script lang="ts">
  import { FormField } from "@lapismd/design-core/forms";
  import { Textarea } from "@lapismd/design-core/shadcn/textarea";
</script>

<FormField label="Summary" description="Short text shown in previews">
  <Textarea bind:value={summary} />
</FormField>
```

## 故事书和本地文档

运行本地目录：

```sh
pnpm storybook
```

构建静态目录：

```sh
pnpm build-storybook
```

线下打包指导：

```sh
pnpm ui guide
pnpm ui guide styling
pnpm ui components
pnpm ui components button
```

规范规范存在于 `spec/src`． 将它用于包的行为， 架构、样式规则和验证证据：

```sh
pnpm spec:search "tokens"
pnpm spec:check
```

### CI和局部宇称

`pnpm checks` 运行非可视化管理，质量，单元，故事书，指针， 和AI浏览器通道通过Turbo。执行治理、质量和单元工作 同时使用一半可用处理器，上限为4个。曾推高 故事书和浏览器套件在本地一次运行一个，因此目录启动和 交互准备仍然是确定性的；集 `TURBO_CONCURRENCY` 到一个 正数或百分比，以覆盖一般任务范围。

本地任务输出缓存在 `.turbo/`． 相同的任务使用带符号的 组织缓存在CI中，并在正常执行时失败 不可用。要在本地使用远程缓存，请复制 `.env.example` 致被忽视的人 根 `.env` 并提供 `TURBO_TOKEN` 和 `TURBO_REMOTE_CACHE_SIGNATURE_KEY`． 永远不要提交这些凭证。

CI将9条非视觉通道并行展开，包括独立的工作区， Shell、Shadcn和AI浏览器运行程序。它完全依赖于生产环境运行 审核后，他们通过并报告一个稳定 `Validate` 结果。视觉 比较仍然是一个明确的、单独的命令。

## 发布和确认

常用验证命令：

```sh
pnpm spec:first
pnpm spec:check
pnpm check
pnpm test:unit
pnpm build-storybook
pnpm checks:release
```

发布计划和打包工件：

```sh
pnpm changeset
pnpm release:check
pnpm release:plan --registry https://registry.npmjs.org
pnpm packages:pack
```

`@lapismd/design-core@0.1.0` 已手动从已审阅的压缩文件中引导。 未来的版本使用变更集和存储库发布工作流。

## 进一步的阅读

| 资源 | 使用 |
| --- | --- |
| [`spec/src/index.md`](https://npmcn.com/package/%40lapismd/design-core/spec/src/index.md) | 规范设计核心规范 |
| [`spec/src/component-inventory.md`](https://npmcn.com/package/%40lapismd/design-core/spec/src/component-inventory.md) | 已实现的组件清单 |
| [`spec/src/styling-and-themes.md`](https://npmcn.com/package/%40lapismd/design-core/spec/src/styling-and-themes.md) | 样式和令牌合约 |
| [`spec/src/packages.md`](https://npmcn.com/package/%40lapismd/design-core/spec/src/packages.md) | 公共出口要求 |
| [`AGENTS.md`](https://npmcn.com/package/%40lapismd/design-core/AGENTS.md) | 贡献者和代理工作流 |

## 常见问题

### @lapismd/design-core 是什么？

共享的Lapis设计系统、表单、外壳和工作空间原语

### 如何安装 @lapismd/design-core？

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

### @lapismd/design-core 支持 TypeScript 吗？

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

### @lapismd/design-core 支持 ESM 还是 CommonJS？

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

### @lapismd/design-core 需要什么版本的 Node\.js？

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

### @lapismd/design-core 可以商用吗？

@lapismd/design-core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @lapismd/design-core 还在维护吗？

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