videojs-skin

设计 Video.js 皮肤

皮肤是播放器的 UI：围绕媒体的控件、布局、样式和交互。videojs skin create 会搭建一个项目，其中 src/ 存放一款皮肤的源代码，apps/preview/ 提供工作台，可在不同尺寸、语言和播放设置下预览皮肤。这项技能会完成项目搭建，并确保设计工作符合媒体播放器的需求。

若要在现有应用中重设皮肤样式，请改用 Shadcn 安装方法添加皮肤源代码；videojs 技能会介绍该方法。

1. 设置项目

如果工作目录中已有 skin.json，请跳过此步骤。

请假设用户可能从未使用过终端。自行运行每条命令，用通俗的语言说明每条命令的作用；只有在用户必须亲自操作时才请他们行动：例如安装需要密码的软件，或登录账号。

1. 运行 node --version。如果缺少 Node.js，或版本低于当前 LTS 版本，请停止并说明：该项目需要 Node.js，用户可以通过 https://nodejs.org 上的 LTS 安装程序一次性安装。不要替他们安装；安装程序会要求输入密码。等到 node --version 可以正常运行后再继续。
2. 运行 npx @videojs/cli skin create <directory> --name <name>。如果未提供终端，该命令不会更改任何内容，并会列出尚待选择的选项及其默认值；--help 会说明各选项。如果无法识别 skin create，说明 CLI 版本过旧。此时请改用 videojs 技能中的 Shadcn 方法，将皮肤源代码添加到应用中，并告知用户该方案没有独立工作台。该方案不会创建 skin.json、apps/preview/ 或 deploy 脚本，因此请跳过本技能中的工作台和发布步骤；第 3 步和第 4 步中的设计指导以及 videojs-ui 技能仍然适用，但需要在应用中进行检查。
3. 在一条消息中提出所有选项，并一次性确认。框架可选 React 或 HTML。对于 React，样式方案可选 Tailwind CSS 或纯 CSS；HTML 皮肤使用 CSS。建议采用用户的应用已在使用的方案。选择初始皮肤时，询问用户是想从基础模板着手，构建自己的设计（Scaffold，所有控件均已接好，仅含最少样式），还是为完整设计添加品牌元素（Neutral 易于添加品牌元素，Default 是独具特色的 Video.js 设计，Compat 则以牺牲功能换取更广的浏览器支持）。预设项用于选择播放器类型：视频、音频、直播视频或直播音频。如果皮肤需要匹配现有播放器或设计，请先阅读 references/match-reference.md；该参考文件会决定初始皮肤。
4. 将所有选项作为标志传入，再次运行该命令。命令会安装依赖项，并打印启动工作台所需的命令。在后台启动开发服务器，并分享它打印的工作台 URL，同时说明皮肤文件的位置以及如何打开。

2. 熟悉项目

编辑前先阅读项目的 AGENTS.md、README.md 和 skin.json。这些文件介绍当前版本的目录结构、脚本和工作台；应以这些文件为准，而非本技能说明。Video.js 文档随已安装的软件包附带，路径为 node_modules/@videojs/<react|html>/docs/llms.txt；如无法使用，请访问 https://videojs.org/docs/framework/<react|html>/llms.txt，并在页面 URL 后追加 .md。请先按以下标题阅读这些页面：

需求	阅读内容
确认哪一个文件负责某项更改	Customize skins，“Style skin source”
了解控件如何公开状态、属性和渲染自定义选项	UI components，然后阅读每个组件的参考页面
快捷键和手势	Keyboard shortcuts
标签、语言、从右向左书写	Internationalization
了解组件已有的无障碍功能	Accessibility

3. 确定设计

先确定皮肤应是什么样子，再开始设置样式；临场发挥细节再事后修正，是最慢的做法。

• 匹配参考，例如指定的产品、现有播放器、截图或设计文件：遵循 references/match-reference.md。它会保存参考截图，编写包含尺寸数据的 design/spec.md，并只就参考内容无法展示的信息询问用户。匹配播放器也包括匹配其控制图标：从用户自己的设计文件中导出，或重新绘制，绝不复制他人播放器的图标。
• 原创设计：根据用户的需求编写简短的 design/spec.md，涵盖布局和控制项顺序、菜单、图标风格、字体、颜色和表面、滑块及动效，并确认一次。

无论哪种方式，只构建规范和用户要求的内容。不要添加两者都未提及的控制项、叠加层或文本。

绝不臆造设计方向。开始构建前，以及构建过程中出现新问题时，都要先判断问题类型：

• 方向：询问。 任何会改变设计意图，且无法从需求、参考或项目中找到答案的问题，例如品牌色、氛围、信息密度、要包含哪些控制项或布局风格。将这些问题汇总到一条消息中，为每个问题提供两三个具体选项和一个推荐默认选项，然后等待答复。
• 执行：自行决定。 根据已确定的设计自然得出的细节，例如从强调色推导出的悬停色调，或两个按钮之间的间距。自行决定，并在规范中将其标记为 derived，不要询问。

4. 构建

videojs-ui 技能涵盖各控制项的设计技巧：视频画面上的对比度、图标状态、动效、字体、颜色、标签，以及与之搭配的设计和审查技能。皮肤项目还需遵循以下规则：

• 修改皮肤，而非工作台。 所有皮肤代码都放在 src/ 中，且不导入 apps/preview/ 中的任何内容，以便原样移入应用。
• 先修改令牌，再修改规则。 颜色、表面、圆角、尺寸和动效都通过皮肤主题文件中的 CSS 自定义属性设置。确保打包后的皮肤对外暴露的公共属性仍能正常工作，例如 --media-accent-color。
• 每轮修改后进行整理。 删除被后续规则覆盖的规则，并将多个位置共用的值设为共享令牌，例如菜单表面、图标尺寸和描边、间距及滑块几何参数。
• 使用组件设置的 data-* 属性设置状态样式，例如 data-paused，而不是使用脚本切换的类。
• 使用容器查询设置尺寸。 播放器的宽度很少与视口宽度相同。
• 保留容器的 data-theme 和 data-preset。 样式会根据这些属性进行选择。
• 通过皮肤的动效令牌添加动效；在减少动效偏好下，皮肤的偏好设置样式表会将其收敛。
• 保留皮肤提供的非视觉功能：错误对话框、快捷键、手势和状态播报器。只有在提供等效功能时才替换它们。
• 在源代码中调整控制项顺序，不要使用 CSS。 焦点顺序必须与视觉顺序一致；皮肤会处理从右到左布局这一例外。

然后遵循文档中的框架组合规则：在 React 中，展开 render 函数接收的 props；在 HTML 中，导入每个要渲染的元素部分，并确保将工具提示和弹出窗口连接到按钮的 id、trigger 和 commandfor 配对均唯一且相互匹配。

5. 验证

1. 运行项目的 typecheck 和 build 脚本。
2. 检查还原度，而不只是功能。进行参考匹配时，在宣布皮肤完成或请用户审核之前，先通过 references/match-reference.md 中的还原度检查。否则，先将第一个可用预览与 design/spec.md 对比，再进行润色。自行修复发现的差异，并在报告中附上截图。
3. 在工作台中检查此更改可能影响的每种状态：其选项面板可设置宽度、宽高比、配色方案、方向、语言和播放状态；项目的 README.md 则说明了如何通过 URL 打开某种状态。关于检查内容，请参考 videojs-ui 的审核指南；它涵盖了通用 UI 审核容易忽略的视频播放器问题。

6. 按需发布

项目的 deploy 脚本会将工作台发布到 Vercel、Netlify 或 Cloudflare Pages。该脚本会生成公开 URL，并登录托管平台，因此只有在用户提出要求时才运行。无法使用终端时，请指定托管平台： <package manager> run deploy vercel。使用 pnpm 时，请保留 run：pnpm deploy 是另一个内置命令。用户需要完成托管平台的登录。

如果皮肤与其他公司的播放器相似，请在用户发布或交付前提醒他们确认是否有权使用借鉴的内容：图标、字体、颜色以及整体外观。私下构建或研究是一回事；用于生产环境可能需要获得许可。

征得同意后向上游反馈

如果任务发现了 Video.js 或 skin create 中的错误或文档缺失，请在适当的暂停点主动提出起草反馈，并遵循 videojs 技能中的反馈规则。未经明确批准确切文本，绝不发送。