ui-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UI Design Skill

UI设计技能

Make every visual output look like a professional designed it — never generic AI slop — while doing the least hand-work necessary. This skill is the single entry point for all UI/UX decisions; it replaces the older

project-design

and

dashboard

skills.

让所有可视化输出看起来都像是专业设计师的作品——绝无同质化AI生成内容——同时尽可能减少手动工作量。本技能是所有UI/UX决策的唯一入口，替代了旧版的

project-design

和

dashboard

技能。

When to use

使用场景

Any time you generate HTML/CSS/JS the user will see: landing page, dashboard, web app, portfolio, internal tool, settings page, a single chart panel — anything visual. If it renders, this skill applies.

任何生成用户可见的HTML/CSS/JS内容的场景：着陆页、仪表盘、Web应用、作品集、内部工具、设置页面、单个图表面板——所有可视化内容。只要能渲染，本技能就适用。

Step 1 — Pick the track

步骤1 — 选择构建路径

Two ways to build a UI. Choose deliberately; they are not interchangeable.

	Track A — Hand-built	Track B — Component library
What	You write the markup + Tailwind/CSS yourself	You pull accessible React components from shadcn/ui, HeroUI, or coss ui
Best for	Single-file previews, quick dashboards, emails, anything with no build step	Real React/Next/Vite apps with forms, modals, tables, date pickers the user will keep
Build step	None — static `preview`	Bundler required (Vite/Next) + `preview` with `command` + `port`
Read	`references/design-process.md` (+ aesthetics/components/animations/charts)	`references/component-libraries.md`

Decision shortcut:

No build step / throwaway preview / static files only          → Track A
Real app, lots of interactive components, user will extend it  → Track B
User named "shadcn" / "HeroUI" / "Cal.com look" / "Origin UI"  → Track B (that library)
Just a dashboard?                                              → either track + references/dashboards.md

Taste is required on both tracks. A component library gives correct, accessible parts — it does NOT give a point of view. The palette / typography / layout-rhythm / anti-slop / copy rules from

design-process.md

apply on top of the library, or every app looks identically generic.

有两种UI构建方式，请谨慎选择，二者不可互换。

	路径A — 手动构建	路径B — 组件库构建
内容	自行编写标记语言 + Tailwind/CSS	从shadcn/ui、HeroUI或coss ui中获取可访问的React组件
适用场景	单文件预览、快速仪表盘、邮件、任何无需构建步骤的内容	包含表单、模态框、表格、日期选择器等用户会长期使用的React/Next/Vite实际应用
构建步骤	无——静态 `preview`	需要打包工具（Vite/Next） + 带 `command` + `port` 的 `preview`
参考文档	`references/design-process.md` （含美学/组件/动画/图表）	`references/component-libraries.md`

决策捷径：

无需构建步骤 / 一次性预览 / 仅静态文件          → 路径A
实际应用、大量交互组件、用户会扩展功能  → 路径B
用户指定“shadcn” / “HeroUI” / “Cal.com风格” / “Origin UI”  → 路径B（对应组件库）
仅需仪表盘？                                              → 任意路径 + references/dashboards.md

两种路径都需要把控设计品味。组件库提供合规、可访问的组件，但不提供设计风格。

design-process.md

中的配色/排版/布局节奏/规避同质化/文案规则需叠加在组件库之上，否则所有应用都会显得千篇一律。

Step 2 — Always-on design discipline (both tracks)

步骤2 — 始终遵循的设计准则（两种路径通用）

These are the non-negotiables. Full methodology, banned-value lists, and the pre-delivery checklist are in

references/design-process.md

— read it before writing markup on Track A, and for the taste layer on Track B.

Design Read first. One line: page type · audience · atmosphere · aesthetic family · light/dark/tinted. Every later choice serves it.
Spin the Design Dials (Track A) to avoid converging on the same dark-blue-card layout every time: Surface · Accent · Typography · Aesthetic Family, derived from the current UTC time. User-stated preferences always override the dials.
Anchor dark surfaces with a Scene Sentence — never default to
```
#0a-#0f
```
blue-black.
Banned by default: Inter/Roboto/Arial fonts; generic blue (
```
#3b82f6
```
) and AI purple (
```
#8b5cf6
```
/
```
#6366f1
```
); cream/beige backgrounds; blue-black dark; em-dashes in copy; marketing buzzwords; centered-hero-plus-three-cards;
```
border-radius > 16px
```
on cards; gradient text;
```
transition: all
```
;
```
100vh
```
(use
```
100dvh
```
).
Copy reads human, not LLM. No buzzwords, no aphoristic "Simple. Fast. Powerful.", no fake-precise numbers, no scroll cues, zero em-dashes.
Accessibility is mandatory: ≥4.5:1 body contrast, visible focus rings, alt text, sequential headings,
```
aria-label
```
on icon buttons, color never the sole signal, 44×44px touch targets,
```
prefers-reduced-motion
```
.
Light/dark theme with a toggle, CSS custom properties, system-preference default,
```
localStorage
```
persistence — both themes fully designed, not just inverted.
Refinement pass + checklist before delivery. The instinct to add more is usually wrong; fix spacing, contrast, and typography instead. Run the pre-delivery checklist in
```
design-process.md
```
.

这些是不可协商的要求。完整方法论、禁用项列表及交付前检查清单均在

references/design-process.md

中——在路径A编写标记语言前阅读该文档，路径B则需阅读该文档以把控设计品味。

先明确设计定位：一句话概括：页面类型 · 受众 · 氛围 · 美学风格 · 亮色/暗色/色调。后续所有选择都需服务于此定位。
调整设计参数（路径A）：避免每次都采用相同的深蓝色卡片布局：根据当前UTC时间确定底色 · 强调色 · 排版 · 美学风格。用户明确的偏好始终优先于参数调整。
用场景描述锚定暗色背景——绝不默认使用
```
#0a-#0f
```
区间的蓝黑色。
默认禁用项：Inter/Roboto/Arial字体；通用蓝色（
```
#3b82f6
```
）和AI紫色（
```
#8b5cf6
```
/
```
#6366f1
```
）；米白/米色背景；蓝黑色暗色模式；文案中的破折号；营销术语；居中 hero 加三卡片布局；卡片圆角
```
border-radius > 16px
```
；渐变文字；
```
transition: all
```
；
```
100vh
```
（改用
```
100dvh
```
）。
文案需像人类撰写，而非LLM生成。无营销术语，无“简洁、快速、强大”这类空洞口号，无虚假精确数字，无滚动提示，无破折号。
无障碍设计是强制要求：正文对比度≥4.5:1，可见焦点环，替代文本，顺序化标题，图标按钮添加
```
aria-label
```
，颜色不能作为唯一标识，44×44px触摸目标，支持
```
prefers-reduced-motion
```
。
亮色/暗色主题切换：提供切换按钮，使用CSS自定义属性，默认遵循系统偏好，通过
```
localStorage
```
持久化——两种主题均需完整设计，而非简单反转颜色。
交付前需优化检查。通常添加更多内容的本能是错误的；应优先修复间距、对比度和排版问题。执行
```
design-process.md
```
中的交付前检查清单。

Step 3 — Reduce work with open-source component libraries (Track B)

步骤3 — 利用开源组件库减少工作量（路径B）

When there's a build step, don't hand-roll dropdowns, dialogs, and date pickers — that's where hand-written code fails on a11y and keyboard handling. Pull them from a library instead.

Library	Model	Reach for it when
shadcn/ui	Copy-paste via CLI + registry + MCP (Radix/Base UI + Tailwind)	Largest ecosystem, you want to own/edit every component; lowest-effort for an agent via MCP/CLI
HeroUI v3 (was NextUI)	npm package, auto-updating (React Aria + Tailwind v4)	Polished defaults with zero maintenance; just update the package
coss ui (was Origin UI)	Copy-paste (Base UI + Tailwind), Cal.com's system	Dense, production-grade Cal.com-style UI; OK with beta churn

Never paste component code into work from memory. These libraries ship fast and APIs drift. Look up the current component + props at build time — via the library's MCP server, its
llms.txt
, its CLI registry, or its docs page. The library's own source is the truth, every time. Exact lookup URLs, CLI/MCP setup, the copy-paste-vs-package tradeoff, and the build-step reality are in
references/component-libraries.md
.

Default when unspecified and a build is justified: shadcn/ui (MCP + CLI make it the lowest-effort), unless "zero maintenance" → HeroUI, or "Cal.com look" → coss ui.

当需要构建步骤时，不要手动编写下拉菜单、对话框和日期选择器——手写代码在无障碍和键盘交互方面容易出错。改用组件库中的现成组件。

组件库	模式	适用场景
shadcn/ui	通过CLI + 注册表 + MCP（Radix/Base UI + Tailwind）复制粘贴	生态系统最完善，希望自主编辑所有组件；通过MCP/CLI实现最低工作量
HeroUI v3（原NextUI）	npm包，自动更新（React Aria + Tailwind v4）	精致默认样式，无需维护；只需更新包即可
coss ui（原Origin UI）	复制粘贴（Base UI + Tailwind），Cal.com的设计系统	高密度、生产级Cal.com风格UI；可接受测试版迭代

绝不要凭记忆粘贴组件代码。这些组件库更新频繁，API会变化。构建时务必查阅当前组件及属性——通过组件库的MCP服务器、
llms.txt
、CLI注册表或文档页面。组件库自身的源代码始终是权威依据。具体查阅URL、CLI/MCP设置、复制粘贴与包管理的权衡及构建步骤详情均在
references/component-libraries.md
中。

未指定且需要构建步骤时的默认选择：shadcn/ui（MCP + CLI实现最低工作量），除非要求“零维护”→ HeroUI，或要求“Cal.com风格”→ coss ui。

Advanced motion: GSAP (works on BOTH tracks)

高级动效：GSAP（两种路径均适用）

Component libraries give you correct components; they don't give you cinematic motion. For scroll-driven storytelling, multi-step timelines, text-into-characters reveals, SVG morph/draw, or FLIP layout transitions, reach for GSAP — now 100% free (incl. all former-paid plugins: ScrollTrigger, SplitText, MorphSVG, Flip…). Unlike the component libraries, GSAP is plain JS that loads via a CDN

<script>

tag with no build step, so it works in a single-file Track A preview and a Track B app.

Decision: plain CSS for hovers/toggles/simple reveals (the default — don't pull 50KB for a button); GSAP only when the motion is a feature (landing-page scroll story, hero text reveal, animated SVG). Full guidance — when-to-use table, CDN loading, core/timeline/ScrollTrigger API, plugin list, the React

useGSAP

hook, and the reduced-motion/cleanup rules — is in

references/animations.md

(GSAP section). Look up the current version and plugin APIs at gsap.com at build time; don't ship memorized snippets.

组件库提供合规组件，但不提供电影级动效。如需滚动驱动叙事、多步骤时间线、文字拆分展示、SVG变形/绘制或FLIP布局过渡，请使用**GSAP**——现在完全免费（包括所有原付费插件：ScrollTrigger、SplitText、MorphSVG、Flip…）。与组件库不同，GSAP是纯JS，可通过CDN

<script>

标签加载，无需构建步骤，因此适用于路径A的单文件预览和路径B的应用。

决策原则：普通CSS用于悬停/切换/简单展示（默认选择——不要为一个按钮加载50KB的资源）；仅当动效是核心功能时使用GSAP（着陆页滚动故事、Hero文本展示、SVG动画）。完整指导——使用场景表、CDN加载方式、核心/时间线/ScrollTrigger API、插件列表、React

useGSAP

钩子及动效简化/清理规则——均在

references/animations.md

的GSAP章节中。构建时务必在gsap.com查阅当前版本和插件API；不要使用记忆中的代码片段。

AI-generated visual assets (optional quality boost)

AI生成视觉资产（可选质量提升）

When the user wants a premium, polished look — or when the project would benefit from custom imagery (hero backgrounds, logos, decorative illustrations, themed graphics) — load the image-create skill and use it to generate visuals with AI.

When to use:

Landing pages, portfolios, or dashboards where a custom hero image would elevate the design
Projects where the user explicitly wants "better looking" / "more polished" / "premium" output
Any time a stock photo or generic gradient feels insufficient

How to use:

Load the
```
image-create
```
skill (read its SKILL.md) and follow its instructions to generate an image with a prompt that matches the project's Design Read (atmosphere, aesthetic family, color palette)
The generated image is saved to
```
output/images/
```
. You MUST copy it into the project's preview/serve directory before referencing it in HTML:
```
bash("cp output/images/GENERATED_FILE.png output/projects/{slug}/src/hero.png")
```
Reference the image with a relative path in HTML:
```
url('./hero.png')
```
— NOT
```
url('../images/...')
```
. Preview can only serve files within its own directory.
If image generation fails, fall back to CSS gradients or abstract SVG patterns — never leave a broken
```
<img>
```
or
```
background-image
```
reference.

当用户需要高端、精致的视觉效果——或项目可从自定义图像（Hero背景、Logo、装饰插画、主题图形）中获益时，加载image-create技能并使用AI生成视觉内容。

使用场景：

着陆页、作品集或仪表盘，自定义Hero图像可提升设计质感
用户明确要求“更好看”/“更精致”/“高端”输出的项目
任何使用库存照片或通用渐变不足以满足需求的场景

使用方法：

加载
```
image-create
```
技能（阅读其SKILL.md）并按照说明生成与项目设计定位（氛围、美学风格、配色）匹配的图像
生成的图像保存至
```
output/images/
```
。必须将其复制到项目的预览/服务目录后，才能在HTML中引用：
```
bash("cp output/images/GENERATED_FILE.png output/projects/{slug}/src/hero.png")
```
在HTML中使用相对路径引用图像：
```
url('./hero.png')
```
——不要使用
```
url('../images/...')
```
。预览仅能加载自身目录内的文件。
若图像生成失败， fallback到CSS渐变或抽象SVG图案——绝不要留下无效的
```
<img>
```
或
```
background-image
```
引用。

Dashboards

仪表盘

For multi-panel monitoring views (portfolio, prices, system health), read

references/dashboards.md

after picking a track: it covers finding real data (Starchild proxied APIs + rate-limit math), real-time updates (polling/SSE/WebSocket), dashboard layout, loading/error/empty states, and performance. Charts setup is in

references/charts.md

. Never put fabricated numbers on a dashboard.

对于多面板监控视图（作品集、价格、系统健康），选择路径后阅读

references/dashboards.md

：内容涵盖真实数据获取（Starchild代理API + 限流计算）、实时更新（轮询/SSE/WebSocket）、仪表盘布局、加载/错误/空状态及性能优化。图表设置在

references/charts.md

中。绝不要在仪表盘中使用虚构数据。

Reference map

参考文档地图

File	Read when
`references/design-process.md`	The full quality gate — Design Read, Dials, Scene Sentence, all design rules, copy rules, anti-slop tests, theme support, pre-delivery checklist
`references/aesthetics.md`	Building a palette / choosing type — methodology + real-brand values + dark-surface tint guide
`references/components.md`	Hand-building nav, cards, tables, buttons, forms, hero, CTAs
`references/animations.md`	Motion — scroll reveals, hover, modals, entrance strategies, timing, + GSAP advanced-motion layer (timelines, ScrollTrigger, SplitText, SVG, FLIP, useGSAP)
`references/charts.md`	Charts — Chart.js/ECharts setup, chart-type selection, mock data
`references/component-libraries.md`	shadcn/ui · HeroUI · coss ui — when to use which + how to look up components dynamically
`references/dashboards.md`	Data sourcing, real-time, dashboard layout, performance

文件	阅读场景
`references/design-process.md`	完整质量管控——设计定位、参数调整、场景描述、所有设计规则、文案规则、同质化内容规避测试、主题支持、交付前检查清单
`references/aesthetics.md`	构建配色/选择字体——方法论 + 真实品牌案例 + 暗色背景色调指南
`references/components.md`	手动构建导航、卡片、表格、按钮、表单、Hero、CTA
`references/animations.md`	动效——滚动展示、悬停、模态框、入场策略、时序、+ GSAP高级动效层（时间线、ScrollTrigger、SplitText、SVG、FLIP、useGSAP）
`references/charts.md`	图表——Chart.js/ECharts设置、图表类型选择、模拟数据
`references/component-libraries.md`	shadcn/ui · HeroUI · coss ui——适用场景 + 动态查阅组件方法
`references/dashboards.md`	数据源、实时更新、仪表盘布局、性能优化