进阶 v0.dev 2026-11-12 04:30:30 · 16 阅读

第16章 设计系统 2.0

Design Systems 2.0

Design Systems 2.0 允许你一次向 v0 教授你的设计系统,让对话能够基于你真实的组件、tokens 和规范进行构建。

在 v0 中创建并使用自定义设计系统。

设计系统会以 skill 的形式保存在你当前的作用域中,例如团队或个人工作区。Skill 是一小组聚焦的指令,v0 会将其与你的工作保留在一起,并在相关时调用。设计系统 skill 并不是文档的副本,而是一个适配器,它告诉 v0 你的源码在哪里、哪些组件、props 和 tokens 可以安全使用,以及如何将该系统接入新应用。

寻找旧版 shadcn/ui registry 指南?请参阅 Design systems。

开始之前

收集当前定义你设计系统的所有资源。你无需一开始就备齐所有资源;先添加你手头有的,如果 v0 需要更多上下文,它会在导入过程中提出后续问题。

  • 可安装的设计系统包:公共或私有 npm 包、.tgz/.tar 归档文件,或包含独立 package.json 的源代码目录。如果你只有散乱的 CSS、主题文件、Figma 画板或组件,v0 会询问你是否能提供包,或者希望 v0 基于这些源创建一个新的可安装包。
  • 设计系统源:组件和 tokens 所在的仓库或包。
  • 消费该系统的真实应用:这往往是最有价值的资源,因为它展示了 providers、全局样式、字体、主题设置以及正确的组件用法。你的营销网站或主仪表板都很合适。
  • Storybook、文档或设计指南:解释组件、props、tokens、布局规则和品牌规范的链接。
  • Figma 画板或节点:展示组合、密度、排版和组件用法的视觉参考。
  • 私有包凭证:如果你的设计系统是私有 npm 包,请确保配置了团队共享的 NPM_TOKEN 或 NPM_RC,以便 v0 能安装私有包。这是一次性的团队设置;个人导入无需额外操作。
  • 安装说明和示例:包括 README、设置命令以及常用组件的正确使用示例。

保持资源的一致性。避免混合不相关的设计系统、框架,或与当前包 API 矛盾的旧文档。

导入设计系统

从 Design Systems 页面开始新的导入。指向定义你系统的资源,例如 GitHub 仓库、消费应用、Figma 画板和文档。v0 会读取这些资源,构建一个起始应用以验证它是否理解你的系统,并将一个 skill 保存在当前作用域。如果团队作用域的导入无法保存到团队,v0 会在将其保存为仅限个人的 skill 前进行询问。

添加资源

在导入表单中,添加 v0 学习你系统所需的任何资源:

  • 设计系统源或消费应用的 GitHub 仓库。
  • 作为视觉参考的 Figma 画板或节点。登录 Figma,然后粘贴特定画板或节点的链接。v0 会导入截图和提取的画板上下文,以便参考设计。
  • Storybook、文档站点或设计指南等链接。
  • 附件,如截图、ZIP 文件、导出的包或 .tgz 包归档。

v0 基于真实源进行定位。如果无法从资源中验证某个组件、prop 或 token,v0 不应使用它。

添加备注

备注是可选的,但对于难以从源代码推断的信息很有用:

  • 全局样式、providers、字体或必需的包装器
  • 已弃用的组件、反模式或陷阱
  • v0 应优先采用或避免的组件规范

理解 v0.json

在导入期间,v0 将可复用的设置存储在 v0.json 中。通常你无需手动编辑此文件,但该文件是 skill 使用时所应用内容的唯一事实来源。设计系统的 v0.json 遵循以下结构:

{
  "version": 1,
  "referenceWorkspace": {
    "sources": [
      {
        "id": "github-repo:owner/repo:main",
        "type": "github-repo",
        "repo": { "org": "owner", "name": "repo" },
        "ref": "main",
        "mountPath": "/vercel/share/v0-reference-workspace-sources/owner/repo/main"
      }
    ]
  },
  "starter": {
    "source": "skill-directory",
    "path": "assets/starter"
  }
}
  • version:v0.json 架构版本。使用 1。
  • referenceWorkspace.sources:v0 可浏览以作参考的只读 GitHub 资源。每个资源包含仓库、引用、生成的 id 和挂载路径。一个 v0.json 最多可包含三个参考资源。
  • starter:v0 在构建前应用的起始应用。设计系统 skill 通常使用 skill-directory,路径如 assets/starter。其他支持的起始源包括 empty 和 v0-default。

Figma 画板、文档链接和附件是导入输入。v0 会将它们提炼为保存的 skill 指令和参考,而不是将它们保留为长期的 v0.json 资源。

开始对话并审查起始应用

提交表单后,v0 开始一个专用对话并处理导入过程:

  1. 发现你的资源和设计系统基元。
  2. 使用你的设计系统构建并预览一个小起始应用。
  3. 在保存任何内容前暂停以供你审查。
  4. 仅在你批准后保存该 skill。
  5. 在确认前验证保存的 skill,并为你提供已验证的使用链接。

如果 v0 遇到阻塞项,如无法访问的仓库或无法安装的私有包,它会停止并请你修复该阻塞项。对于私有包,这意味着在 Vercel 上添加或更新团队共享的 NPM_TOKEN 或 NPM_RC;参见 Private Dependencies。

认真进行审查。 v0 会将此起始应用保存到 skill 中,之后使用设计系统构建的每个应用都将从此开始。检查其外观和内部连接方式:组件和 tokens、providers、主题设置、字体和全局样式。如果有任何问题,即使是很小的细节,也请在对话中要求 v0 修复,并在批准前重新检查。正确的起始应用意味着每个未来的应用都始于一个可用的基础,而不是每次都继承同样的问题。

一旦你批准,你的设计系统就保存在 skill 中,随时可用。你导入它的那个对话只是起点——你可以在新对话中附加该 skill,或继续在当前对话中构建。

使用保存的设计系统

保存的 skill 会出现在 Design Systems 页面的 “Your Design Systems” 下。

要使用其中一个,请从提示工具栏附加它,或在提示中直接引用它。你还可以尝试 Design Systems 页面或工具栏中的内置示例。

自定义标志和颜色

从 Design Systems 页面打开一个保存的设计系统,以自定义其在 v0 中的显示方式。

  • 要添加或替换其标志,请选择设计系统名称旁边的标志,并上传最大 4 MB 的图片。v0 将其作为 logo.png 存储在 SKILL.md 旁边的保存 skill 中。
  • 在 SKILL.md 的 frontmatter 中设置 v0.design-system.appearance,以用于聊天编辑器中的设计系统颜色:
    metadata:
      v0.kind: design-system
      v0.design-system:
        appearance:
          light:
            background: "#E6F4FF"
            foreground: "#002A3A"
          dark:
            background: "#004052"
            foreground: "#E6F4FF"
    

选择与标志相得益彰的颜色,并确保设计系统名称在浅色和深色模式下都易于阅读。这些颜色用于在 v0 中标识设计系统;它们不会改变你用其构建的应用中的颜色 tokens。

设置团队默认设计系统

付费计划中的团队所有者可以选择团队的默认设计系统。

  • 默认设置用于未选择设计系统的新对话。现有对话和手动选择的设计系统保持不变。
  • 在 Design Systems 页面,打开团队 skill 的操作菜单并选择 “Set as Default”。选定的 skill 将获得 Default 徽章,同一菜单也可清除该设置。
  • 在提示工具栏中手动选择设计系统会覆盖你新对话中的团队默认设置。

保持设计系统最新

你可以从任何对话更新保存的设计系统,在 Design Systems 页面上手动编辑,或通过 v0 API 更新。你无需回到最初导入的对话。

要更新 skill,请在对话中询问 v0 并说明变更内容,例如发布说明、迁移指南、新的包版本或更新的 GitHub 资源:

Update Acme UI to v2.3. Release notes and migration guide: [links]. The Button component renamed its type prop to variant.

v0 会编辑 skill 并重新检查起始应用以防止回归。每次保存的编辑都会显示在设计系统页面的 Revision History 中,你可以查看文件、作者、时间戳和文本差异。

每当资源以影响生成应用的方式变更时,请更新设计系统。典型的更新应:

  • 标识新的包版本、GitHub 分支或引用以及文档。
  • 包括发布说明、迁移指南和任何破坏性变更。
  • 同时更新组件 API、tokens、安装说明、参考和起始应用。

现有项目不会自动更新。要采用新版本,请要求 v0 使用更新的 skill 更新该应用的代码。

最佳实践

  • 同时包含设计系统源和至少一个真实消费应用。
  • 优先使用当前文档、当前包版本和可用的示例,而非详尽但过时的参考。
  • 在导入私有包前配置团队共享的 npm 凭证,或在无法共享凭证时附加 .tgz 归档。
  • 记录全局设置:providers、主题包装器、字体、CSS 导入、Tailwind 配置和必需的环境变量。
  • 尽可能将资源聚焦于一个设计系统和一个框架栈。

FAQ

与设计系统 skill 保存的起始应用是什么?

新的 v0 对话始于一个使用 shadcn/ui 和 Tailwind CSS 的 Next.js 应用。此设置可能与拥有自己组件、tokens、样式或 providers 的设计系统发生冲突。在导入期间,v0 为你的设计系统配置一个小应用并将其与 skill 一起保存。未来的对话从该应用开始,因此 agent 无需花费时间和 tokens 来重复设置即可处理你的提示。

skill 的 v0.json 选择起始应用:

{
  "version": 1,
  "starter": {
    "source": "skill-directory",
    "path": "assets/starter"
  }
}

路径相对于 skill。对于与 skill 保存的文件,使用 skill-directory;对于标准 v0 起始应用,使用 v0-default;对于空白项目,使用 empty。设计系统导入通常使用 skill-directory。

包版本更新或 GitHub 资源更新后,我如何更新设计系统?

在任何对话中要求 v0 更新 skill,并包括新版本、更改的资源、发布说明、迁移指南和任何破坏性变更。v0 会更新保存的 skill 并再次验证起始应用。你也可以从 Design Systems 页面手动编辑 skill。

我是否需要回到导入设计系统的对话来更新它?

不需要。该对话只是创建设计系统的地方。告诉 v0 变更内容,即可从任何对话更新保存的 skill,或在 Design Systems 页面上手动编辑。

当我更新设计系统时,现有对话会发生什么?

更新设计系统 skill 会改变 v0 加载该 skill 时使用的共享指令、参考和起始应用。现有对话和项目不会自动重写其已生成的代码;它们保留应用该 skill 时的代码和起始应用。新对话,以及加载该 skill 的任何新工作,都会使用更新后的版本。

要让现有对话或应用保持最新,请要求 v0 在该对话中使用最新版本 skill 更新其代码。

v0 可以使用私有包吗?

可以。私有包通过团队共享的 NPM_TOKEN 安装(对于非 registry.npmjs.org 的注册表,使用 NPM_RC),在 Vercel 上作为共享环境变量一次性配置。v0.app 中的设计系统导入和对话会自动使用它;设计中系统本身不存储任何内容。对于 Platform API 对话,在创建对话时启用共享 npm 访问。如果 v0 在导入期间无法安装私有包,它会要求你添加或更新该凭证。如果无法共享凭证,请附加 .tgz 包归档。参见 Private Dependencies。

谁可以创建、编辑、删除或设置默认设计系统 skill?

默认情况下,任何具有编辑访问权限团队成员都可以创建、编辑和删除团队 skill。在任何付费团队计划中,团队所有者可以在工作区设置中将 “Team Memories & Skills” 从 “All team members” 更改为 “Owners and selected members”。当访问权限受限时,只有具有编辑权限的团队所有者和选定的具有编辑权限的成员可以创建、编辑和删除团队记忆和 skill,包括设计系统 skill。所有团队成员仍可查看和使用它们。如果计划后续变更,所有者始终可以重新打开限制。

只有团队所有者可以更改团队的默认设计系统。

评论 (0)