auth0-branding

Auth0 品牌定制

调整 Auth0 Universal Login 的样式，使其符合品牌风格。涵盖主题（颜色、字体、边框、组件布局）、租户级品牌设置（徽标、网站图标、主色）、页面模板（用于包裹组件的 Liquid HTML），以及每个屏幕的自定义文本。

功能

如果在开场消息中带有明确意图调用此技能（例如“根据 ferrari.com 为我的租户设置品牌风格”“重置主题”“检查 Universal Login 是否已启用”），请解析意图并直接转到下方对应的功能。不要显示选项列表。

如果在没有明确意图时调用此技能（直接输入 /auth0-branding，或笼统地说“帮我处理品牌定制”），请显示下表，并用一行询问：“选择一个编号、说出名称，或描述你想做什么。”解析回复——1、“为我的租户设置品牌风格”或“让它看起来像 acme.com”都可视为等效请求。

#	功能	说明
1	为我的租户设置品牌风格	根据我拥有的网站、现有品牌素材或手动输入，为 Universal Login 全面设置样式。统一应用颜色、徽标、字体、页面布局，以及（可选的）登录文本语气
2	更改特定设置	直接更新单项内容：徽标、颜色、字体、圆角半径、背景、按钮标签或页面模板。无需提取 URL 或解析素材
3	匹配我的品牌语气	根据我提供的来源（我的网站、文案示例或语气描述）改写 Universal Login 文本。仅修改文本；不会更改颜色或布局
4	恢复 Auth0 默认设置	选择要清除的内容：租户品牌设置、主题、页面模板，或特定提示词上的自定义文本
5	检查我的设置	验证租户上的登录、注册、密码重置和 MFA 是否实际使用 Universal Login，而非 Classic。适合作为安全的只读起点

所有功能均适用先决条件部分。

提示词风格

优先使用自由文本提示词。此技能应能解析自然语言回复，而不是强制用户点击选项。仅在以下情况使用 AskUserQuestion：

1. 需要多选且选项不明显，完整列表有助于用户做出选择（例如功能 3 的流程类别——用户不会凭记忆知道所有选项）。
2. 涉及破坏性操作的安全确认（例如功能 4 中询问“重置前是否保存备份？”）。
3. 需要在 3 条或更多具有实际权衡的不同路径之间消除歧义，且用户不太可能熟悉这些路径。

其他情况均使用自由文本。具体来说：

• 审核提示（“继续吗？应用／编辑／取消，或者告诉我需要更改什么”）应使用自由文本。解析回复。如果回复指出了具体更改，就直接应用这些更改并重新呈现方案；不要让用户再通过编辑子菜单逐步操作。
• **“粘贴一个值”**类询问（十六进制代码、URL、字体名称）应使用自由文本。不要把单字段输入放进选项列表。
• 入口处的功能路由应使用自由文本。请参阅功能表上方的说明。

便于发现功能的提示：每份方案都必须直接列出可编辑的选项，包括默认关闭的选项（语气改写、页面模板、布局覆盖）。用户无法请求编辑他们不知道存在的功能。功能 1 主方案下方的“另有选项”区块是标准示例。

不要自动执行可选步骤（例如检测语气流程，或对未经验证的域名进行 Brandfetch 查询）。应先询问用户是否要列出、检测或选择。

计划模式

当 Claude Code 处于计划模式时，技能中的写入操作——针对 Management API 的 PATCH/PUT/DELETE/POST，以及本地文件写入（备份 JSON、Brandfetch 密钥）——都会暂缓，直到计划获批。

允许的操作：

• 对 Management API 执行 GET（加载当前主题、品牌设置、自定义文本、提示词、连接和租户设置）。这些操作用于制定方案和进行诊断。
• 仅涉及大模型的工作：语气分类、生成翻译、呈现方案。
• 能力 5 按原样运行；它本身就是只读的。

暂缓的操作：

• 所有 Management API 写入操作（不执行 PATCH/PUT/DELETE/POST）。
• 本地文件写入：能力 4 的备份 JSON、能力 1 的 Brandfetch 密钥保存。
• auth0 test login（它会在浏览器中启动授权流程——这不会修改租户，但属于副作用；与写入操作一并暂缓）。

仍要进行交互式询问。 能力 1 中询问 Brandfetch 密钥的提示、能力 3 中询问来源/屏幕/区域设置的提示、能力 4 中询问界面/备份的提示——都仍然会出现。计划模式暂缓的是执行，而不是收集意图。对于答案会触发写入的询问（例如“粘贴 Brandfetch 密钥”），请收集答案，并在计划中注明“获批后将保存至 ${XDG_CONFIG_HOME:-$HOME/.config}/auth0-branding/brandfetch.key”。

计划内容。 制定一份完整计划，涵盖：

• 目标租户（来自 auth0 tenants list）以及当前活动租户确认。
• 技能将按顺序执行的每个具体 API 调用：方法、路径，以及请求体摘要（对于 PATCH /branding 这类小型对象，列出完整载荷；对于合并后的主题对象或自定义文本 PUT 这类大型对象，列出键名和变更数量）。
• 每项本地文件写入及其绝对路径。
• 能力 4 的范围预检结果，以便在审批前发现范围错误。
• 适用时，应用后的 auth0 test login 步骤。

然后调用 ExitPlanMode。

获批后。 恢复正常执行。所有现有确认关卡仍然适用：活动租户确认、生产环境写入确认、WCAG 对比度警告、模板标签验证、对自定义文本执行 PUT 前先合并，以及破坏性操作的范围检查。

在浏览器中验证（应用后）

在任何能力向租户写入内容后（能力 1–4），请询问是否打开实际的 Universal Login 页面，让用户立即查看结果。使用自由文本提示，而不是选项列表：

是否在浏览器中打开登录页面进行验证？（yes / no）

如果回答 yes：对活动租户运行 auth0 test login。CLI 会针对默认应用启动授权码流程并打开浏览器。如果环境为无头环境或浏览器无法打开，CLI 会将授权 URL 输出到标准输出——请捕获该 URL 并提供给用户，以便他们手动打开。

如果回答 no：以所写入内容的摘要结束。

注意：

• 这适用于能力 1（为租户设置品牌）、能力 2（更改特定设置）、能力 3（匹配品牌语气）和能力 4（回滚至 Auth0 默认设置）。对于回滚，浏览器页面应显示 Auth0 内置的默认设置——这就是验证方式。
• 能力 5（检查我的设置）为只读；跳过此步骤。
• 如果用户有首选的测试客户端，他们会说明；auth0 test login --client-id <id> 可指定特定应用。否则使用默认应用。

核心概念

概念	描述
主题	应用于 Universal Login 的视觉设置（颜色、字体、边框、组件布局、背景）。Auth0 目前只会渲染默认主题；可以通过 API 创建其他主题，但 Universal Login 不会使用这些主题
品牌设置	租户级别的徽标、favicon、主色和页面背景色
页面模板	使用 Liquid 语法的自定义 HTML，用于包裹登录组件；需要自定义域名
文本自定义	对 Universal Login 页面中各提示词、各屏幕、各语言的文本进行覆盖
自定义文本变量	Custom Text API 中由客户定义的键（前缀为 var-），在模板和局部模板中以 camelCase 格式引用
自定义域名	页面模板必需；将你的域名映射到 Auth0 的登录页面
Universal Login 与 Classic	租户可以在任一种体验中渲染各个流程（登录/注册、密码重置、MFA）。主题、模板和无代码编辑器仅适用于运行 Universal Login 的流程

先决条件

这些要求适用于任何会写入租户的功能。“检查我的设置”为只读操作，可以先运行以确认这些要求已满足。

CLI 租户上下文（使用 auth0 CLI 时）

Auth0 CLI 一次只会登录一个租户。所有 auth0 ... 命令都会针对 CLI 当前登录的租户运行：

auth0 tenants list       # shows all tenants; the active one is marked with →
auth0 tenants use <name> # switch active tenant; prompts for browser login if not already authenticated

**在任何功能执行写入操作前，运行 auth0 tenants list，向用户显示当前活动租户，并获得明确确认后再继续。**如果租户不正确，请停止。告知用户自行运行 auth0 tenants use <name>（如果目标租户不在列表中，则运行 auth0 login），然后重新调用该技能。不要代替用户切换租户。

对于非交互式或多租户自动化，请跳过 CLI，直接调用 Management API，并在每次调用时明确指定域名和 bearer token。参见 references/examples.md。

要设置品牌的流程已启用 Universal Login

主题和模板仅适用于实际运行 Universal Login 的流程。租户可以处于混合模式，其中一些流程使用 Classic。运行功能 5（“检查我的设置”），以诊断哪些流程会受到影响，哪些不会。Classic 切换机制请参见 references/capability-check.md。

自定义域名（仅在使用页面模板时需要）

租户必须配置自定义域名才能使用页面模板。品牌设置、主题和文本自定义不需要自定义域名。如果任务涉及页面模板，但尚未配置自定义域名，请使用 auth0-custom-domains 技能进行设置。

功能 1：为我的租户设置品牌

根据网站 URL、内联品牌值或简短需求端到端设置品牌——填写主色、徽标、字体和页面背景，提供一个方案并应用主题。

参见 references/capability-brand.md。

功能 2：更改特定设置

根据用户的自然语言意图手动更新品牌——该技能会将描述映射到具体字段、暂存更改，并批量应用。

参见 references/capability-manual.md。

功能 3：匹配我的品牌语气

根据用户提供的来源（网站、文案示例或语气描述）改写 Universal Login 文本；不会更改颜色、布局或徽标。

参见 references/capability-voice.md。类别 → 提示词 → 屏幕映射请参见 references/screens.md。

功能 4：还原为 Auth0 默认设置

按品牌界面清除一个或多个品牌界面并还原 Auth0 默认设置。此操作具有破坏性；写入前始终要先确认。

参见 references/capability-rollback.md。

功能 5：检查我的设置

只读诊断。回答“我关心的流程中，主题更改实际上会显示出来吗？”诊断“为什么我的主题没有显示？”时，可以安全地先运行此功能。

参见 references/capability-check.md。

常见错误

错误	应改为
通过 POST /branding/themes 创建其他主题（Universal Login 只会渲染默认主题；通过 POST 创建的主题虽然存在，但不会生效）	始终更新默认主题：先执行 GET /branding/themes/default，再通过其 themeId 执行 PATCH
对主题发送不完整的 PATCH（PATCH 要求包含所有顶层部分）	GET 主题，应用更改，然后使用完整对象执行 PATCH
主题或页面模板更改未显示在登录／重置／MFA 页面上（租户级开关将该流程强制切换为 Classic）	运行“Check my setup”。修复导致问题的租户开关：universal_login_experience: classic（登录／注册）、change_password.enabled: true（重置）或 guardian_mfa_page.enabled: true（MFA）
模板中缺少 auth0:head 或 auth0:widget（两者都是必需的；缺少时页面无法渲染）	始终包含两者；否则拒绝执行 PUT
设置自定义文本时未合并就使用 PUT（PUT 会替换该提示词／语言的所有文本）	先 GET 当前文本，合并后再 PUT 完整对象

有关扩展列表（主题字段要求、Brandfetch 服务条款、仅提取主页信息的缺漏、CSS 类名、CLI 租户上下文），请参阅 references/api.md。

参考资料

技能内（渐进式披露）：

• references/capability-brand.md：“Brand my tenant”流程；提取流水线、来源优先级、应用步骤
• references/capability-manual.md：“Change specific settings”流程；意图映射、各界面的写入机制、应用／防护措施
• references/capability-voice.md：“Match my brand voice”流程；来源提示词、类别检查清单、选择加入检测、区域设置处理、生成并应用
• references/capability-rollback.md：“Rollback to Auth0 defaults”流程；范围预检查、界面选择、备份、执行
• references/capability-check.md：“Check my setup”流程；Classic 开关背景、检查项、输出格式
• references/screens.md：“Match my brand voice”的类别 → 提示词 → 界面映射（起点；Auth0 会不断添加新界面）
• references/api.md：Management API 端点、主题／品牌架构、CLI 命令、错误代码
• references/examples.md：cURL 代码示例，以及 CI/CD 部署和租户迁移模式
• references/advanced.md：使用 Liquid 语法创建页面模板、模板变量、文本自定义详情

相关技能：

• auth0-custom-domains：配置自定义域名（页面模板的必需项）
• auth0-organizations：面向 B2B 多租户的组织专属品牌设置
• auth0-actions：通过 Auth0 Actions 在登录流程中使用自定义逻辑
• acul-screen-generator：Universal Login 的高级自定义（ACUL）——构建超出主题和模板功能范围的完全自定义界面

外部资源：

• 自定义 Universal Login
• 自定义主题
• 自定义页面模板
• 自定义文本元素
• 品牌 API 参考
• Brandfetch 品牌 API
• Brandfetch Logo API 指南