ui-ux-pro-max-skill 的 design 技能全解：从 BM25 设计知识库检索到 Gemini Logo、CIP 与 SVG 图标生成

design 技能是 ui-ux-pro-max-skill 仓库中统一品牌设计的入口技能，它将 Logo 生成、企业视觉识别系统（CIP）样机、HTML 演示、Banner、社交图片与 SVG 图标七类设计任务整合在一份技能清单下，并通过 BM25 检索本地 CSV 设计知识库 + 调用 Gemini / Atlas Cloud 图像模型完成从“设计决策”到“成品产出”的闭环。读完后你将掌握：如何在该技能下检索 55 种 Logo 风格/配色/行业指南、用哪些命令行参数生成 Logo 与 CIP 样机、SVG 图标走的是哪条“文本模型出 XML”的管线，以及 Banner 与社交图片各平台的尺寸规范。

一、技能定位：何时使用 design 技能

design 技能的技能清单文件为 SKILL.md，其 frontmatter 声明了技能元信息：

• name: design，license: MIT，author: claudekit，version: "2.1.0"；
• argument-hint: "[design-type] [context]"，即调用时建议传入设计类型与上下文两个参数。

该技能适用于以下八类场景（引自 SKILL.md 的 When to Use 一节）：

• 品牌识别、品牌语调（voice）、品牌资产；
• 设计系统 Token 与规范；
• 基于 shadcn/ui + Tailwind 的 UI 样式；
• Logo 设计与 AI 生成；
• 企业识别系统（CIP）交付物；
• 演示文稿与融资路演 Deck；
• 面向社交媒体、广告、网站、印刷的 Banner 设计；
• Instagram、Facebook、LinkedIn、Twitter、Pinterest、TikTok 等平台的社交图片。

二、子技能路由：内置能力与外部子技能的分工

design 技能的核心架构是“路由表”——根据任务类型决定走内置脚本还是外部子技能，这是 SKILL.md 中 Sub-skill Routing 一节的完整内容：

任务	子技能	详情
品牌识别、语调、资产	brand	外部技能
Token、规范、CSS 变量	design-system	外部技能
shadcn/ui、Tailwind、代码	ui-styling	外部技能
Logo 创建、AI 生成	Logo（内置）	references/logo-design.md
CIP 样机、交付物	CIP（内置）	references/cip-design.md
演示文稿、路演 Deck	Slides（内置）	references/slides.md
Banner、封面、头图	Banner（内置）	references/banner-sizes-and-styles.md
社交媒体图片	Social Photos（内置）	references/social-photos-design.md
SVG 图标、图标集	Icon（内置）	references/icon-design.md

也就是说：品牌层（brand）、Token 层（design-system）、代码层（ui-styling）由三个外部子技能承担，而 Logo、CIP、Slides、Banner、Social Photos、Icon 六类产出型任务由 design 技能内置的 Python 脚本直接完成。三个外部子技能在本仓库中分别位于 .claude/skills/brand/SKILL.md、.claude/skills/design-system/SKILL.md 与 .claude/skills/ui-styling/SKILL.md。

三、前置条件与环境配置

3.1 Python 依赖

该技能所有脚本均为 Python 实现。Windows 环境下应将 python3 替换为 python（例如 python scripts/logo/search.py）。检查 Python 是否安装：

python3 --version || python --version

3.2 API Key 与依赖包

export GEMINI_API_KEY="your-key"  # 在 Google AI Studio 控制台获取
pip install google-genai pillow

Windows 下如需使用 pip，用 python -m pip install google-genai pillow。

3.3 环境变量加载的优先级（源码实现细节）

从源码结构看，三个生成脚本（logo/generate.py、cip/generate.py、icon/generate.py）都内置了 load_env() 函数，按以下优先级依次查找 .env 文件，且不会覆盖已存在的环境变量：

1. 技能目录下的 .env（~/.claude/skills/design/.env）；
2. ~/.claude/skills/.env；
3. ~/.claude/.env。

因此即使不导出 GEMINI_API_KEY，把 key 写入上述任一 .env 文件即可生效。另外 cip/generate.py 在读取 key 时同时兼容 GEMINI_API_KEY 与 GOOGLE_API_KEY 两个变量名。使用 Atlas Cloud 作为 Logo 生成提供方时，则额外需要 ATLASCLOUD_API_KEY。

四、Logo 设计：检索设计知识库 + AI 生成

Logo 模块覆盖 55+ 风格、30 种配色方案、25 个行业指南（数据文件实际条目见 data/logo/styles.csv 等），底层图像模型为 Gemini Nano Banana 系列。

4.1 生成 Logo 设计简报

python3 scripts/logo/search.py "tech startup modern" --design-brief -p "BrandName"

--design-brief 模式下，search.py 中的 generate_design_brief() 会调用 search_all() 跨 style/color/industry 三个域各取前 2 条结果，再按“INDUSTRY ANALYSIS → STYLE RECOMMENDATIONS → COLOR PALETTE OPTIONS”三段式输出行业分析、风格建议与配色方案，-p 指定品牌名后会作为简报标题。

4.2 按域检索风格、配色、行业

python3 scripts/logo/search.py "minimalist clean" --domain style
python3 scripts/logo/search.py "tech professional" --domain color
python3 scripts/logo/search.py "healthcare medical" --domain industry

支持的全部命令行参数（见 search.py 的 argparse 定义）：

参数	说明
query（位置参数）	检索查询
--domain, -d	指定域，可选 style / color / industry
--max-results, -n	最大结果数，默认 3
--json	以 JSON 输出
--design-brief, -db	生成综合设计简报
--brand-name, -p	简报所用的品牌名

4.3 检索的底层实现：BM25 排序算法

从源码看，检索引擎并非简单的子串匹配，而是 logo/core.py 中自实现的 BM25 排序：

• 分词器将查询小写化、去标点、过滤长度 ≤2 的词；
• fit() 阶段为每个词计算 IDF（log((N - df + 0.5) / (df + 0.5) + 1)），score() 阶段按 k1=1.5, b=0.75 的标准 BM25 公式对每行 CSV 文档打分排序；
• 文档由 CSV_CONFIG 中各域的 search_cols 列拼接而成，例如 style 域检索 Style Name / Category / Keywords / Best For 四列，输出则返回 output_cols 中包括 Primary Colors、Typography、Effects、Avoid For 等 11 列设计要素；
• 未指定 --domain 时，detect_domain() 会对查询做关键词计分自动判域（如查询含 "vintage"、"wordmark" 判为 style 域，含 "#"/"palette" 判为 color 域），全部未命中则默认 style 域；
• MAX_RESULTS 默认为 3，且只返回得分 > 0 的结果。

4.4 用 AI 生成 Logo

约定：输出的 Logo 图像一律要求白色背景。

python3 scripts/logo/generate.py --brand "TechFlow" --style minimalist --industry tech
python3 scripts/logo/generate.py --prompt "coffee shop vintage badge" --style vintage
python3 scripts/logo/generate.py --brand "TechFlow" --provider atlas

generate.py 的关键实现参数：

• 模型选择：默认 gemini-2.5-flash-image（Nano Banana，快、低成本），--pro 切换为 gemini-3-pro-image-preview（Nano Banana Pro，专业质量、高级推理）；
• 风格修饰：--style 的可选值来自 STYLE_MODIFIERS 字典，共 18 种（minimalist、vintage、modern、luxury、playful、corporate、organic、geometric、hand-drawn、3d、abstract、lettermark、wordmark、emblem、mascot、gradient、lineart、negative-space），每种风格会被扩展成一段英文修饰语注入提示词；
• 行业提示：--industry 可选 10 个值（tech、healthcare、finance、food、fashion、fitness、eco、education、real-estate、creative），同样映射到 INDUSTRY_PROMPTS；
• 提示词组装：enhance_prompt() 将品牌名、风格修饰、行业提示按序拼入 LOGO_PROMPT_TEMPLATE，模板强制“矢量风格、清晰轮廓、居中构图、纯白或透明背景、不生成文字（除非明确要求）”等 Logo 硬性要求；
• 宽高比：--aspect-ratio 支持 1:1 / 16:9 / 9:16 / 4:3 / 3:4，Logo 场景默认 1:1（正方形）；
• 批量模式：--batch N --output-dir ./logos 会按内置的 9 种批次风格（minimalist、modern、geometric、gradient、abstract、lettermark、negative-space、lineart、3d）逐一生成变体，每次请求间 sleep 2 秒做限流；
• Atlas Cloud 提供方：--provider atlas 走异步生成 API，模型为 google/nano-banana-2-lite/text-to-image，提交后每 2 秒轮询一次状态、最多 90 次；源码中 _validate_public_https_url() 会对媒体下载地址做 HTTPS、非内网 IP 校验，防止重定向到私有地址。--pro 与 --provider atlas 互斥，会直接报错。

可用 --list-styles 与 --list-industries 查看完整可选值。

生成完成后，SKILL.md 要求始终通过 AskUserQuestion 询问用户是否需要 HTML 预览，若需要则调用 /ui-ux-pro-max 进入画廊展示。另外文档中有一条重要运维约定：当脚本失败时，应尝试直接修复脚本，而不是跳过。

五、CIP 设计：50+ 交付物、20 风格、20 行业的视觉识别样机

CIP 模块基于 Gemini Nano Banana（Flash/Pro）生成企业识别样机，其数据由 data/cip/ 下的 4 个 CSV 支撑：deliverables.csv（约 50 条交付物）、styles.csv、industries.csv（各约 20 条）、mockup-contexts.csv（约 20 条样机场景）。

5.1 生成 CIP 简报

python3 scripts/cip/search.py "tech startup" --cip-brief -b "BrandName"

5.2 按域检索

CIP 检索比 Logo 多一个 mockup 域，四个域分别映射 cip/core.py 的 CSV_CONFIG：

python3 scripts/cip/search.py "business card letterhead" --domain deliverable
python3 scripts/cip/search.py "luxury premium elegant" --domain style
python3 scripts/cip/search.py "hospitality hotel" --domain industry
python3 scripts/cip/search.py "office reception" --domain mockup

deliverable 域输出包含 Dimensions、Logo Placement、Mockup Context 等 12 列；mockup 域输出包含 Scene Description、Lighting、Camera Angle、Props 等摄影场景要素——这些字段会直接进入后续提示词。

5.3 生成 CIP 样机

# 带 Logo（推荐）
python3 scripts/cip/generate.py --brand "TopGroup" --logo /path/to/logo.png --deliverable "business card" --industry "consulting"

# 完整 CIP 套装
python3 scripts/cip/generate.py --brand "TopGroup" --logo /path/to/logo.png --industry "consulting" --set

# Pro 模型（4K 文字渲染）
python3 scripts/cip/generate.py --brand "TopGroup" --logo logo.png --deliverable "business card" --model pro

# 无 Logo 纯文生图
python3 scripts/cip/generate.py --brand "TechFlow" --deliverable "business card" --no-logo-prompt

模型选择：flash（默认，gemini-2.5-flash-image，快速低成本）与 pro（gemini-3-pro-image-preview，高质量、4K 文字渲染），与 cip/generate.py 中 MODELS 字典一致。

关键参数补充（来自 argparse 定义）：--deliverables 可传逗号分隔列表自定义套装内容；--set 缺省套装为 business card, letterhead, office signage, vehicle, polo shirt 五项；--ratio 指定宽高比（默认 1:1）；--output 指定输出目录；--prompt-only 只打印提示词不调用模型；--json 以 JSON 输出。

从源码结构看，CIP 的“带 Logo 模式”实质是 Gemini 的文生图 + 图生图编辑双模式：

• load_logo_image() 用 Pillow 读取 Logo，若是 RGBA/P 模式会自动合成到白底 RGB 图上（Gemini 对 RGB 处理最佳）；
• 提供 --logo 时，build_cip_prompt() 会生成强调“使用提供的原始 Logo、不得修改或重绘、Logo 必须与输入图像完全一致”的编辑型提示词，且调用 generate_content 时 contents = [prompt, logo_image] 同时传入文本与图像；未提供 Logo 时走纯文生图，提示词中则显式注入检索到的主色、字体、材质、场景与情绪字段；
• 未提供 Logo 且未加 --no-logo-prompt 时，脚本会交互询问三选一：继续无 Logo（AI 自行诠释品牌 Logo）/ 先去用 Logo 脚本生成 / 退出并补 --logo 参数。

提示词的组装逻辑在 build_cip_prompt() 中：先以 search(deliverable, "deliverable", 1) 取交付物详情，再依次检索 style（缺省 "corporate minimal"）、industry（缺省 "technology"）、mockup 场景，最终拼接为“photorealistic product photography、soft natural lighting、8K resolution”一类的摄影级提示词。

5.4 渲染 HTML 展示页

将生成的样机图渲染为 HTML 展示页：

python3 scripts/cip/render-html.py --brand "TopGroup" --industry "consulting" --images /path/to/cip-output

文档提示：若品牌尚无 Logo，应先走上文 Logo 设计流程生成，再回来到 CIP 中传 --logo。

六、Slides：基于知识库的 HTML 演示文稿

Slides 子能力是“策略驱动的 HTML 演示文稿”，使用 Chart.js、设计 Token 与文案公式。创建流程加载 references/slides-create.md。其知识库文件索引如下：

主题	文件
创建指南	slides-create.md
版式模式	slides-layout-patterns.md
HTML 模板	slides-html-template.md
文案公式	slides-copywriting-formulas.md
策略	slides-strategies.md

Slides 没有独立 Python 脚本（见 SKILL.md 的 Scripts 表），产出依赖 Agent 按知识库文档编写 HTML，这与 Logo/CIP/Icon 三条脚本化管线形成对照。

七、Banner 设计：22 种艺术指导风格的跨平台头图

Banner 子能力覆盖社交、广告、网站、印刷四类用途共 22 种艺术指导风格，流程中会激活 frontend-design、ai-artist、ai-multimodal、chrome-devtools 等技能。完整尺寸与风格参考见 references/banner-sizes-and-styles.md。

7.1 五步工作流

1. 收集需求（AskUserQuestion）——用途、平台、内容、品牌、风格、数量；
2. 调研——激活 ui-ux-pro-max，在 Pinterest 浏览参考图；
3. 设计——用 frontend-design 编写 HTML/CSS Banner，用 ai-artist/ai-multimodal 生成视觉素材；
4. 导出——用 chrome-devtools 截屏为精确像素尺寸的 PNG；
5. 呈现——所有方案并排展示，按反馈迭代。

7.2 常用尺寸速查表

平台	类型	尺寸 (px)
Facebook	封面	820 x 312
Twitter/X	头图	1500 x 500
LinkedIn	个人主页	1584 x 396
YouTube	频道头图	2560 x 1440
Instagram	快拍	1080 x 1920
Instagram	帖子	1080 x 1080
Google Ads	中矩形	300 x 250
网站	Hero 头图	1920 x 600-1080

7.3 高频艺术风格

风格	适用场景
极简 Minimalist	SaaS、科技
粗体排版 Bold Typography	公告类
渐变 Gradient	现代品牌
照片主导 Photo-Based	生活方式、电商
几何 Geometric	科技、金融科技
玻璃拟态 Glassmorphism	SaaS、App
霓虹/赛博朋克 Neon/Cyberpunk	游戏、活动

7.4 设计硬规则

• 安全区：关键内容放在中央 70–80% 区域；
• 每个 Banner 只放一个 CTA，置于右下角，高度不低于 44px；
• 最多 2 种字体，正文最小 16px，标题不小于 32px；
• 广告类文字面积不超过 20%（Meta 会对超量文字广告降权）；
• 印刷品：300 DPI、CMYK、3–5mm 出血。

八、Icon 设计：文本模型直出 SVG 的管线

Icon 子能力共 15 种风格、12 个分类，使用 Gemini 3.1 Pro Preview 纯文本输出生成 SVG（因为 SVG 本身就是 XML 文本，无需图像生成 API）。

8.1 单个图标生成

python3 scripts/icon/generate.py --prompt "settings gear" --style outlined
python3 scripts/icon/generate.py --prompt "shopping cart" --style filled --color "#6366F1"
python3 scripts/icon/generate.py --name "dashboard" --category navigation --style duotone

8.2 批量变体与多尺寸导出

python3 scripts/icon/generate.py --prompt "cloud upload" --batch 4 --output-dir ./icons
python3 scripts/icon/generate.py --prompt "user profile" --sizes "16,24,32,48" --output-dir ./icons

8.3 风格速查与模型说明

风格	适用场景
outlined	UI 界面、Web 应用
filled	移动 App、导航栏
duotone	营销页、落地页
rounded	友好型 App、健康类
sharp	科技、金融科技、企业级
flat	Material 设计、Google 风格
gradient	现代品牌、SaaS

模型为 gemini-3.1-pro-preview，仅输出文本（SVG 为 XML 文本），不需要图像生成 API。

从源码看，icon/generate.py 的管线有几个值得注意的设计：

• ICON_STYLES 字典内置 15 种风格指令（比 SKILL.md 表格多出 thin、bold、glassmorphism、pixel、isometric、glyph、animated-ready），ICON_CATEGORIES 内置 12 个分类词表，均与文档声明的“15 styles, 12 categories”一致，风格数据另有 data/icon/styles.csv 承载；
• 提示词模板 SVG_PROMPT_TEMPLATE 硬性要求：ViewBox 0 0 24 24、stroke/fill 使用 currentColor（可继承 CSS 颜色）、不嵌字体与栅格图、必须带 <title> 无障碍描述、仅输出 ```svg 代码块；
• extract_svgs() 采用三级回退提取模型输出：先匹配 ```svg 代码块，再匹配 ```xml 块，最后匹配裸 <svg> 标签，提升了对模型输出格式漂移的鲁棒性；
• apply_color() 将 currentColor 替换为 --color 指定的色值；generate_sizes() 对每个尺寸以对应 viewbox 单独生成一次并 sleep 1 秒限流；
• 单图标生成为 temperature=0.7, max_output_tokens=4096，批量模式为 temperature=0.9, max_output_tokens=16384。

九、Social Photos：HTML/CSS 到截屏的社交图片流水线

Social Photos 支持多平台社交图片设计，走“HTML/CSS → 截屏导出”路线，会用到 ui-ux-pro-max、brand、design-system、chrome-devtools 等技能，尺寸与模板细则见 references/social-photos-design.md。

9.1 八步工作流

1. 编排——project-management 技能拆解 TODO，独立任务用并行子代理；
2. 解析——拆解提示词中的主体、平台、风格、品牌上下文、内容要素；
3. 构思——产出 3–5 个概念，经 AskUserQuestion 呈现；
4. 设计——依次调用 /ckm:brand → /ckm:design-system → 随机调用 /ck:ui-ux-pro-max 或 /ck:frontend-design，按“概念 × 尺寸”逐个写 HTML；
5. 导出——chrome-devtools 或 Playwright 按精确像素截屏（2x deviceScaleFactor）；
6. 校验——用 Chrome MCP 或 chrome-devtools 技能目视检查导出结果，修复布局/样式问题后重新导出；
7. 报告——设计决策摘要写入 plans/reports/；
8. 整理——调用 assets-organizing 技能归档输出文件与报告。

9.2 关键尺寸表

平台	尺寸 (px)	平台	尺寸 (px)
IG 帖子	1080×1080	FB 帖子	1200×630
IG 快拍	1080×1920	X 帖子	1200×675
IG 轮播	1080×1350	LinkedIn	1200×627
YouTube 缩略图	1280×720	Pinterest	1000×1500

十、组合工作流：品牌全案与设计系统落地

SKILL.md 定义了两条端到端组合流程：

完整品牌包（Complete Brand Package）

1. Logo → scripts/logo/generate.py → 生成 Logo 变体；
2. CIP → scripts/cip/generate.py --logo ... → 创建交付物样机；
3. Presentation → 加载 slides-create.md → 构建路演 Deck。

新设计系统（New Design System）

1. Brand（brand 技能）→ 定义色彩、字体、语调；
2. Tokens（design-system 技能）→ 创建语义化 Token 分层；
3. Implement（ui-styling 技能）→ 配置 Tailwind、shadcn/ui。

十一、参考资料与脚本清单

11.1 参考资料索引

主题	文件
设计路由	design-routing.md
Logo 设计指南	logo-design.md
Logo 风格	logo-style-guide.md
Logo 色彩	logo-color-psychology.md
Logo 提示词	logo-prompt-engineering.md
CIP 设计指南	cip-design.md
CIP 交付物	cip-deliverable-guide.md
CIP 风格	cip-style-guide.md
CIP 提示词	cip-prompt-engineering.md
Slides 创建	slides-create.md
Slides 版式	slides-layout-patterns.md
Slides 模板	slides-html-template.md
Slides 文案	slides-copywriting-formulas.md
Slides 策略	slides-strategies.md
Banner 尺寸与风格	banner-sizes-and-styles.md
社交图片指南	social-photos-design.md
图标设计指南	icon-design.md

11.2 脚本清单

脚本	用途
scripts/logo/search.py	检索 Logo 风格、配色、行业
scripts/logo/generate.py	调用 Gemini AI 生成 Logo
scripts/logo/core.py	Logo 数据 BM25 检索引擎
scripts/cip/search.py	检索 CIP 交付物、风格、行业、样机场景
scripts/cip/generate.py	调用 Gemini 生成 CIP 样机
scripts/cip/render-html.py	将 CIP 样机渲染为 HTML 展示页
scripts/cip/core.py	CIP 数据 BM25 检索引擎
scripts/icon/generate.py	用 Gemini 3.1 Pro 生成 SVG 图标

11.3 集成关系

• 外部子技能：brand、design-system、ui-styling；
• 关联技能：frontend-design、ui-ux-pro-max、ai-multimodal、chrome-devtools。

十二、总结

design 技能的价值在于把“设计决策”数据化、把“设计执行”脚本化：BM25 检索引擎（logo/core.py、cip/core.py）让 Agent 能在生成前先给出有数据依据的风格/配色/交付物建议；三条生成管线（Logo 文生图、CIP 图生图编辑、Icon 文本出 SVG）各有明确模型分工（gemini-2.5-flash-image / gemini-3-pro-image-preview / gemini-3.1-pro-preview）；Banner 与 Social Photos 则规定了平台尺寸、安全区与导出校验的完整工程化流程。按本文第三节完成 API Key 配置后，即可从 4.1 的设计简报检索起步，沿第十节的品牌全案工作流走完一个品牌的 Logo → CIP → 路演 Deck 完整闭环。