Local candidate consumption
安装与本地验证
Quartz 当前采用 Registry 优先的本地消费方式：组件源码进入你的项目，可读、可改、可长期拥有。 这仍是本地候选，尚未公开发布。
边界说明Registry JSON 来自本机；CLI 与依赖安装可能访问包管理器配置的 registry 或缓存，因此首次运行可能联网。命令不会发布 Quartz、不会触发购买，也不会读取 Quartz 远程凭据。
01 / Prepare
先启动本地 Registry
在 Quartz UI 仓库根目录启动文档站，并保持进程运行。Registry JSON 由同一个本地地址提供。
pnpm docs:dev- 打开
http://127.0.0.1:3000，确认文档站能够访问。 - 检查
http://127.0.0.1:3000/r/button.json返回本地候选清单。 - 回到你的消费项目，再执行下面的固定版本命令。
02 / Registry first
把 Button 源码加入项目
固定 shadcn@4.16.0，并显式使用本地 URL。 命令会把可拥有的组件代码写入消费项目；Registry 清单地址为本机，但 CLI 与依赖解析仍遵循包管理器的网络和缓存配置。
pnpm dlx shadcn@4.16.0 add http://127.0.0.1:3000/r/button.json你会获得
组件源码、依赖声明与可继续维护的本地文件。
你不会触发
Quartz 发布、Quartz 远程凭据读取、购买或生产环境变更。
03 / Optional namespace
为多组件配置本地命名空间
如果要连续加入多个组件，可以在消费项目的 components.json 中保存本地映射：
{
"registries": {
"@quartz": "http://127.0.0.1:3000/r/{name}.json"
}
}配置后可运行 pnpm dlx shadcn@4.16.0 add @quartz/button。这个别名仍然指向本机，不是公开 Registry。
04 / Provider
接入样式与四个主题轴
在应用入口加载公开样式，并分别声明主题、密度、动效和透明度。四个轴互不替代。
import { ThemeProvider } from "@richardqiu/quartz";
import "@richardqiu/quartz/styles.css";
<ThemeProvider
theme="system"
density="default"
motion="system"
transparency="system"
>
<App />
</ThemeProvider>05 / Secondary distribution
发布后的 npm 路径
现在不要把下面的包名当作可公开安装的产物。npm 路径只完成了本地候选验证；必须在人工确认并完成真实发布后才能使用。
# 仅在公开发布完成后
pnpm add @richardqiu/quartz
import { Button } from "@richardqiu/quartz/button";Next
继续验证公开合同
从 Button 的真实示例开始，再确认四个主题轴与设计 Token。