主题色中性灰生成器
Overview
把任意主题色转成一组「带色相方向的中性灰」——肉眼仍是灰，但微妙地泛出品牌色，比纯
中性灰（zinc/neutral）更有记忆点，且能与主色自然衔接。适用于背景、描边、次级文字与
深色模式表面。浅色灰锚定浅色主题色；若提供深色主题色，深色灰独立锚定其色相，支持
深浅不同色相。一次输入主题色（或双色），输出双模式（浅色 + 深色背景）十阶灰、色卡预览，
并可导出 Markdown 速查表。
When to Use
- 用户给出一个主色/品牌色，要求生成配套的中性灰阶。
- 用户提到「带主题色色向」「品牌灰」「色相一致的灰」「深色模式背景灰」等需求。
- 需要快速预览一组灰的观感（色卡），或要一份可交付的色阶文档。
Workflow
Step 1 — 解析主题色
从用户输入提取 HEX（带不带 # 均可），用 rgb_to_hsl 取出色相 H。整组灰锁死该 H，
只调明度 L 与饱和度 S。
Step 2 — 生成双模式灰阶
调用 scripts/generate_hue_gray.py，传入 --theme：
- 浅色模式：
gray-50(最浅) →gray-900(最深)，L 从 97% 降到 13%，S 从 6% 抬到 24%。 - 深色模式（背景/表面）：命名反转，
gray-900(最深 App 底) →gray-50(最浅抬升表面)，
L 从 9% 升到 42%，S 从 10% 抬到 17%。
--theme 决定浅色灰色相；--dark-theme（可选）决定深色灰色相——两者色相可不同，
分别锚定各自主题色。省略 --dark-theme 时深色灰复用浅色主题色色相（默认同色相）。
--strength 控制色向强度（0=纯中性灰，1=默认，1 以上更明显）。--mode 可选 light /
dark / both。
提醒规则（执行时必须遵循，不可省略）
当用户只提供了浅色模式主题色、未提供深色模式主题色时，脚本会按"深浅同色相"的
假设回退生成深色灰，这仅是一个简化默认、并非最终结论。此时必须在交付色卡的同时，
主动提醒用户补充深色模式主题色（即给出 --dark-theme 的取值），说明：深色模式带
色相中性灰的色相应由深色模式主题色决定，深浅主题色未必同色相，给出深色主题色后深色
灰才能独立锚定其色相。提醒是强制步骤，不得跳过；不要假设"未指定深色主题色"就是用户
的最终意图。
Step 3 — 渲染色卡预览
脚本自动输出 gray_light.png 与 gray_dark.png（色块 + HEX + HSL 标注）。用
show_widget 把两张 PNG 内联渲染给用户看实际观感，并说明：
- 浅色区（50–200）几乎中性，大面积铺底不抢戏；
- 中段起色向浮现，越深越明显但 S 始终压住、不脏；
- 深色模式是独立表面梯度，不可把浅色灰反相。
Step 4 — 交付与落地
- 默认同时生成 Markdown 速查表（
hue-gray-{hex}.md，含中文用途说明）。 - 确认观感后，把双模式灰固化成 Ardot 颜色变量（
gray-50…gray-900）：
通过ardot-design-core的能力，在已打开的 Ardot 文件里建 Color Variable，便于主题切换联动。
Usage Examples
# 生成 #3FD4CF 的双模式灰 + 色卡 + Markdown
python scripts/generate_hue_gray.py --theme 3FD4CF
# 仅浅色、色向更强
python scripts/generate_hue_gray.py --theme #14C9C9 --mode light --strength 1.3
# 仅深色背景灰
python scripts/generate_hue_gray.py --theme #14C9C9 --mode dark
# 深浅主题色不同：浅色 #F5319D、深色 #5B8CFF，两套灰各自锚定各自色相
python scripts/generate_hue_gray.py --theme #F5319D --dark-theme #5B8CFF
运行环境：使用 WorkBuddy 受管 Python（/Users/wst/.workbuddy/binaries/python/envs/default，
已装 Pillow）；脚本在缺失依赖时会自动 pip install pillow。
Design Notes（交付时向用户说明的原则）
- 色相锚定主题色 H，整组灰与主色同宗，叠用不显脏。
- 深色模式灰的色相应由深色模式主题色决定；深浅主题色色相可不同，需分别锚定（用 --dark-theme 传入）。
- 明度按 Tailwind 式 50→900 十阶，直接对应设计系统命名。
- 深色模式需配套浅色文字梯阶（如
#EAF1F1主文 →#8BA7A6次级）。 - 浅色版与深色版建议分别固化为 Ardot 颜色变量（带浅色/深色模式标记），便于联动。
