快速开始

本页带你在已有应用中添加一个 Shadcn Button，并完成首次渲染。你可以直接从这里开始，无需先读白皮书。

请在已有的 React、Vue 或 Web Components 应用中执行这些命令。下面以一个已经安装 react 的 React 应用为例。

CLI 会按照自身精确版本安装所选 Adapter 与 Prototype package。使用当前 @latest 时，这条流程新增的全部公开 @proto.ui/* dependency 都解析为 0.2.0，不会混用不同 release train。

可以直接通过 npx 调用 CLI，不需要全局安装：

npx @proto.ui/cli@latest --help

显式写出 @latest 是为了让稳定 channel 策略一目了然。如果需要永久可复现的安装或 CI 流程，请改用 @0.2.0。

在应用根目录执行：

npx @proto.ui/cli@latest init

接受默认选项后，CLI 会创建本地 Proto UI workspace 与 Shadcn 样式预设：

your-project/
├── src/
│   └── styles/
│       ├── proto-ui-style.css
│       ├── proto-ui-tokens.generated.css
│       └── shadcn-theme.css
├── proto-ui/
│   ├── adapters/
│   ├── prototypes/
│   ├── components/
│   └── config.json
├── package.json
└── ...

• proto-ui/config.json 记录后续 CLI 命令读取的项目配置。
• proto-ui/components/ 保存应用需要导入的已生成 host 入口。
• proto-ui/adapters/ 与 proto-ui/prototypes/ 是 CLI 管理区。
• src/styles/proto-ui-style.css 组合生成的 theme 与 token CSS。

生成文件由 CLI 管理，请勿手动修改。如果项目要使用 Brutalist preset，请在初始化时加上 --prototypes brutalist；如果应用会自行提供完整的语义 token surface，可使用 --no-styles。

从应用入口导入生成的样式表：

import './styles/proto-ui-style.css';

如果入口文件位于其他位置，请调整相对路径。应用未主动选择主题时，生成的 Shadcn theme 会跟随 prefers-color-scheme。在根元素设置 data-theme="light" / data-theme="dark"，或使用兼容的 .light / .dark class，可以覆盖系统偏好。

如果应用没有使用 CSS named cascade layers，保留上面的单次 import 即可。如果应用使用了 named layers，请改为在一个 CSS 入口中、任何 reset、Proto UI 或 consumer layer 首次声明之前建立完整顺序：

@layer theme, base, proto-ui, components, utilities;

@import './reset.css' layer(base);
@import './styles/proto-ui-style.css';
@import './app-components.css' layer(components);
@import './app-utilities.css' layer(utilities);

应用入口只需 import 一次 app.css，不要再分别导入这些 stylesheet。生成入口会把 theme 默认值放进 theme layer，因此更后的 named consumer layer 或 unlayered consumer CSS 声明的变量值仍然拥有优先权。完整关系是 theme defaults < reset/base < proto-ui < explicit consumer layers。使用 Tailwind 时，应保留它的 theme < base < components < utilities 顺序，并在最早的 layer order statement 中把 proto-ui 插入 base 之后、应用的 components 与 utilities layers 之前。

Named layer 的顺序会在首次出现时固定。生成的 @layer theme, proto-ui; 只有在该入口先加载时才能预留这两个 slot；它无法修复更早 stylesheet 已经建立的顺序。只要应用引入 named reset 或 consumer layers，上面的 host order statement 就仍然是必要的集成配置。

请按应用实际使用的 host 添加官方 Shadcn Button facade。下面把 React 与 Web Components 各自的 CLI 命令和应用入口放在同一个示例中；支持当前站点 Adapter 偏好时，示例会以该 host 作为初始页签。

npx @proto.ui/cli@latest add wc shadcn-button

import '../proto-ui/components/wc';

document.body.innerHTML = '<proto-ui-shadcn-button variant="outline">Proto UI 0.2.0</proto-ui-shadcn-button>';

npx @proto.ui/cli@latest add react shadcn-button

import { ShadcnButton } from '../proto-ui/components/react';

export function App() {
  return <ShadcnButton variant="outline">Proto UI 0.2.0</ShadcnButton>;
}

命令会安装匹配的 Adapter 与 @proto.ui/prototypes-shadcn@0.2.0，并在 proto-ui/components/ 下生成 host 入口。Vue 项目在同一命令中使用 vue。这里有意使用相对路径：不同应用并不共享同一套路径别名与目录层级。生成的 facade 会保留 Prototype 声明的 props、事件 listener 与 ref/expose surface。

启动应用后，应能看到标有 “Proto UI 0.2.0” 的 outline Button。检查样式是否加载，并尝试用 Tab 聚焦、用 Enter 或空格激活。如果导入失败，先核对生成目录与相对路径；如果外观缺失，先检查应用入口是否引入生成的样式表。

完成这一步后，再按具体组件文档接入业务状态与事件。

npx @proto.ui/cli@latest add react shadcn-toggle
npx @proto.ui/cli@latest add react shadcn-dialog

生成的 host 入口会持续累积导出，因此应用可以始终从同一路径导入：

import { ShadcnButton, ShadcnDialogRoot, ShadcnToggle } from '../proto-ui/components/react';

如果只想生成文件而不安装缺失 package，可添加 --no-install。CLI 会打印精确安装命令，但在补齐这些 dependency 前，生成入口无法完成构建。

• 0.2.0 是 0.2 release line 的稳定版本，但不等于 v1 兼容性承诺。
• Spec entity lifecycle 仍然有效：active entity 是当前保证；即使相关可执行 package 已发布，draft entity 仍属于推进中的工作。
• CLI 会安装官方 Prototype package 并生成本地 component facade；它不会把 styled Prototype 源码复制到应用中供直接编辑。
• 当前 Adapter 架构仍包含 runtime；Compiler 输出与零运行时交付属于未来方向。
• Shadcn 兼容是明确目标，但尚不完整；当前模型不提供 Radix 风格的 asChild。
• 用于生产环境前，请按实际场景核对组件与 Adapter 覆盖，并在应用中验证 accessibility、SSR 与 bundle 表现。

• Proto UI 0.2.0 Release

完成第一个组件的接入后，可以按你的兴趣继续：