Back to Details

uikit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

uikit

uikit

AI-generated UI has a signature. Three equal feature cards, a violet gradient, Inter on slate-900, a div-built fake dashboard in the hero, 
01 / 02 / 03
eyebrows over content that isn't a sequence. None of these are bugs and no test catches them. They are defaults — reached for because the model had no reason to reach anywhere else.
uikit is the reason. It supplies the constraint that makes a UI decision this project's decision, and it names the tells so they can be avoided deliberately rather than reproduced accidentally.
The whole skill hangs off one idea: taste is spent only where nothing else constrains the choice. A project with a recorded design system gets consistency. A project with shipped components gets conformity. A greenfield project gets a point of view drawn from its own subject matter. None of them get a default. That is the precedence ladder, and every other section defers to it.
AI生成的UI具有标志性特征：三个尺寸相同的功能卡片、紫色渐变、slate-900配色搭配Inter字体、Hero区域用div搭建的假仪表盘、非序列内容上方标注
01 / 02 / 03
的小标题。这些都不是Bug，也没有测试能检测出来——它们是默认选项，模型只是因为没有理由选择其他方案才会使用它们。
uikit就是解决这个问题的关键。它提供约束，让UI决策成为该项目专属的决策，同时明确那些AI生成痕迹的特征，从而主动避免而非意外复刻它们。
整个工具的核心思想是：只有在没有其他约束的情况下，才需要发挥审美判断。已有设计系统的项目将获得一致性；已有组件的项目将保持兼容性；全新项目则会从自身业务领域中提炼设计视角。所有项目都不会使用默认风格。这就是优先级层级，其他所有规则都以此为基础。

What uikit is not

uikit 不是什么

  • Not a design-system recorder. 
    DESIGN.md
    has one owner, and it isn't this skill. uikit reads it and never writes it — a skill that both invents the taste and records it can't be held to either job honestly.
  • Not a taste library. No bundled palettes, no font pairings, no style catalog. A lookup table of 161 palettes is exactly how every project styled from it ends up looking like every other one.
  • Not the code reviewer. Convention-fit, correctness, and completeness are a general review's job. uikit's audit is visual and interaction-level only.
  • Not a gate. The pre-flight critiques its own output; it never fails a build. Taste is not a pass/fail check, and a build that can fail for it fails on something unfalsifiable.
  • Not an environment provisioner. It never installs a browser, never starts a dev server it wasn't told to start, never seeds data.
  • 不是设计系统记录工具：
    DESIGN.md
    只有一个所有者，绝非此工具。uikit仅读取该文件，绝不写入——一个既要创造审美风格又要记录风格的工具无法胜任任何一项工作。
  • 不是风格库：不提供预设调色板、字体配对或样式目录。包含161种调色板的查找表只会让所有使用它的项目看起来千篇一律。
  • 不是代码审查工具：符合规范、正确性和完整性是通用代码审查的职责。uikit的审计仅针对视觉和交互层面。
  • 不是准入门槛：预检查会自我批判输出内容，但绝不会阻止构建。审美不是非黑即白的检查项，因审美而失败的构建是基于无法验证的标准。
  • 不是环境配置工具：它绝不会安装浏览器、启动未被要求启动的开发服务器，也不会填充测试数据。

When this fires

触发场景

  • build
     — "build this page", "add a settings screen", "make this look good", "design the onboarding flow", or any UI work handed over by an implementation step. Generates the UI.
  • audit
     — "does this look AI-generated", "audit our UI", "why does this feel like a template", "check the frontend for slop". Read-only sweep. Writes nothing, ever.
If a request is plainly one or the other, just run it. Ask only when a request could genuinely go either way ("look at the dashboard") — 
audit
is free and 
build
edits source.
  • build
     —— 当用户提出“build this page”、“add a settings screen”、“make this look good”、“design the onboarding flow”或任何由实现步骤交付的UI工作时，生成UI。
  • audit
     —— 当用户提出“does this look AI-generated”、“audit our UI”、“why does this feel like a template”、“check the frontend for slop”时，执行只读扫描。绝不会写入任何内容。
如果请求明确属于其中一种模式，直接执行即可。仅当请求确实存在歧义时（如“look at the dashboard”）才需要询问——
audit
是无侵入的，而
build
会修改源代码。

The precedence ladder

优先级层级

Four rungs. Take the first that matches, and say which one it was before writing any code. A lower rung never overrides a higher one; it only fills what the higher one leaves open.
RungMatches whenWhat it constrains
1 — 
DESIGN.md
a 
DESIGN.md
exists at the repo root		its tokens are the palette, type scale, spacing, and radii. Full stop. Its Do's and Don'ts are the voice rules for UI copy.
2 — The shipped componentsa component directory, a 
components.json
, or a token home (
@theme
, 
:root
custom properties, a theme config)		the existing Button is the Button. Read three or four real components and match their composition, naming, and spacing habits.
3 — The subject's own worldneither of the above, but the product is knowable — README, a context file, route names, domain models, the actual thing being builtthe product's materials, vocabulary, and artifacts. A tool for a print shop should not look like a tool for a hedge fund.
4 — Stack defaultsgreenfield and the subject is genuinely opaquethe house default below, declared out loud as a default rather than a choice.
Rung 3 is where distinctiveness actually comes from. Not from a style vocabulary — from the subject. Its instruments, its materials, its jargon, the artifacts the people who use it already handle. That is a well no other project can draw from, which is precisely why the result can't be generic.
共四个层级。选择第一个匹配的层级，并在编写任何代码前说明使用的层级。低层级绝不会覆盖高层级，仅会补充高层级未定义的内容。
层级匹配场景约束内容
1 — 
DESIGN.md
仓库根目录存在
DESIGN.md
该文件中的标记即为调色板、字体层级、间距和圆角半径的标准，完全遵循。其中的“注意事项”是UI文案的语气规则。
2 — 已交付组件存在组件目录、
components.json
或标记源（
@theme
、
:root
自定义属性、主题配置）		现有Button组件即为标准。读取3-4个真实组件，匹配它们的组合方式、命名规则和间距习惯。
3 — 业务自身领域不满足上述两种情况，但产品可被识别（通过README、上下文文件、路由名称、领域模型、实际构建内容）产品的物料、术语和工件。印刷厂工具不应看起来像对冲基金工具。
4 — 技术栈默认值全新项目且业务领域完全不明确使用以下内部默认值，并明确声明这是默认选项而非刻意选择。
层级3是独特性的真正来源。并非来自风格词汇，而是来自业务本身——它的工具、物料、行话，以及用户日常处理的工件。这是其他项目无法复制的资源，因此最终结果不会是通用模板。

Signature materials by rung

各层级的标志性物料

The rung licenses what the signature may be made of — see the design read for what the signature is:
  • Rungs 1–2 — composition, interaction, and motion. The tokens are fixed and are not yours to move. The room is in layout, in how the surface behaves, and in what it does at rest.
  • Rungs 3–4 — palette, type, and grid as well. Nothing is fixed, so the signature can be structural.
Rung 1 or 2 with a rung 3 palette is the single most damaging thing this skill could do: one rogue component that matches nothing around it, in a codebase that was consistent before you arrived.
层级决定了标志性元素可使用的素材——标志性元素的定义见设计说明：
  • 层级1–2 —— 布局、交互和动效。标记是固定的，不可修改。可发挥的空间在于布局、界面行为和静态状态表现。
  • 层级3–4 —— 还包括调色板、字体和网格系统。无固定规则，因此标志性元素可以是结构性的。
在层级1或2中使用层级3的调色板是本工具可能造成的最严重问题：在原本一致的代码库中引入一个与周围完全不匹配的独立组件。

The design read

设计说明

Five declared words, stated before any code is written. Cheap, and it is what stops the model jumping straight to a default aesthetic — a choice you have named out loud is a choice you can be argued out of.
Design read — surface: product · audience: internal ops staff · rung: 2 (shipped components)
· signature: the save affordance — rows commit on change and confirm in place, no page-level Save
· density: compact
WordValuesWhy it's here
surface
product
or 
marketing
the two have disjoint slop signatures; this is what filters the catalog
audiencefree text, concrete"internal ops staff who live here 6 hours a day" implies different density than "a first-time visitor deciding in 8 seconds"
rung
1
–
4
plus what matched		declares which constraint is in force and what the signature may be made of
signaturethe one element this surface is remembered by, and its materialsee below
density
compact
, 
comfortable
, 
spacious
the one axis that genuinely varies independently of the rung
编写代码前需明确五个要素。成本低，但能阻止模型直接跳转到默认审美——你明确命名的选择才是可被讨论的选择。
Design read — surface: product · audience: internal ops staff · rung: 2 (shipped components)
· signature: the save affordance — rows commit on change and confirm in place, no page-level Save
· density: compact
要素取值作用
surface
product
或 
marketing
两者的AI生成痕迹不同，用于过滤反模板目录
audience具体自由文本“每天在此工作6小时的内部运维人员”与“8秒内做决策的首次访客”对界面密度的需求不同
rung
1
–
4
及匹配依据		声明当前生效的约束，以及标志性元素可使用的素材
signature界面最核心的记忆点及其物料见下文说明
density
compact
, 
comfortable
, 
spacious
唯一独立于层级的变量维度

The signature

标志性元素

One element per surface. Exactly one. The thing a person would describe if asked what the screen was like. Everything around it stays quiet and disciplined — spend your boldness in one place, and cut any decoration that doesn't serve the brief.
This is deliberately not framed as "take a creative risk." Asked to be bold, a model retrieves what boldness looks like, and what it retrieves is the average of every bold thing it has seen — which today means one of three looks: warm cream (near 
#F4F1EA
) with a high-contrast serif and a terracotta accent; near-black with a single acid-green or vermilion accent; or a broadsheet layout with hairline rules, zero radius, and dense columns. All three are legitimate for some brief. None of them are a choice when they appear regardless of subject.
"Name the one thing this screen is remembered by" has no average to regress toward. It is also the only version that survives a pre-flight, which can check that exactly one signature exists and that its materials are legal at the declared rung, but cannot check whether a risk was taken.
Worked examples:
  • Rung 2, a settings page. Default output: card, label-left/toggle-right rows, "Save changes" bottom-right. Correct and forgettable. Signature: there is no Save button — each row commits on change and confirms in place with an inline undo. Zero new tokens; the risk is real, because a slow network now has to be handled honestly.
  • Rung 3, a booking tool for a letterpress print shop. Default output: Inter, slate-900, three feature cards, violet CTA. Signature: the price list is a type specimen sheet — sizes shown at their real sizes, ranged left on a baseline grid, palette drawn from paper stock and ink.
每个界面仅一个标志性元素。即当被问及屏幕是什么样时，用户会描述的那个元素。周围所有元素都需保持简洁克制——将注意力集中在一个点上，移除所有不符合需求的装饰。
这并非“承担创意风险”。当要求大胆设计时，模型会检索它所见过的所有“大胆”设计的平均值——如今通常是三种风格：暖奶油色（接近
#F4F1EA
）搭配高对比度衬线字体和赤陶色强调色；近黑色搭配单一酸绿色或朱红色强调色；或带有细线规则、零圆角、密集列的报纸版式。这三种风格对某些场景来说是合理的，但无论业务主题如何都使用它们，就不是刻意选择了。
“命名屏幕最核心的记忆点”没有平均值可回归。这也是唯一能通过预检查的方式，预检查可以验证是否恰好存在一个标志性元素，以及其物料是否符合当前层级的规则，但无法验证是否承担了风险。
示例：
  • 层级2，设置页面：默认输出为卡片、标签左对齐/开关右对齐的行、右下角的“Save changes”按钮。正确但平淡。标志性元素：无保存按钮——每行内容变更时自动提交，并在原位显示确认和撤销选项。无需新增标记，但需要真实处理慢网络场景，这才是真正的改变。
  • 层级3，凸版印刷店预订工具：默认输出为Inter字体、slate-900配色、三个功能卡片、紫色CTA按钮。标志性元素：价格表为字体样本页——尺寸按实际大小展示，左对齐基线网格，调色板取自纸张和油墨颜色。

Never block on the design read

不要因设计说明停滞

It is a declaration, not an interview. When the subject is unclear at rung 3 or 4, infer it from whatever the repo shows and state the inference — never stop to ask. Wrong-but-stated beats correct-but-hung: uikit runs inside unattended pipelines where nothing is there to answer, and a stated read is the thing a reviewer corrects. Ask only when the user is plainly present and the request itself is ambiguous.
这是声明，而非访谈。当层级3或4的业务主题不明确时，从仓库现有内容推断并声明推断结果——绝不要停下来询问。错误但明确的声明胜过正确但停滞的状态：uikit运行在无人值守的流水线中，没有可回答问题的对象，而明确的声明是评审者可以修正的内容。仅当用户明确在场且请求本身存在歧义时才需要询问。

Mode: 
build

模式：
build

1. Ground it

1. 锚定基础

Walk the ladder and name the rung that matched. Detect the stack from the project's manifest and config rather than assuming — framework, styling system, component library, and whether it's Tailwind v3 or v4, because that distinction changes what renders. Greenfield or undeclared, default to Tailwind v4 + shadcn/ui and say out loud that it's a default.
遵循优先级层级，确定匹配的层级。通过项目清单和配置检测技术栈，而非假设——包括框架、样式系统、组件库，以及Tailwind是v3还是v4，因为版本差异会影响渲染。全新项目或未声明技术栈的项目，默认使用Tailwind v4 + shadcn/ui，并明确声明这是默认选项。

2. State the design read

2. 声明设计说明

Five words, one line, before any code exists.
在编写任何代码前，先写出五个要素。

3. Build

3. 构建UI

Compose before you invent. Use the existing component before writing a styled 
div
; extend it before forking it; fork it only when the difference is real and say why. An agent's instinct is to write fresh markup because it's faster than reading what's there — that instinct is what produces a codebase with four Buttons.
  • Clear the accessibility floor without announcing it. It is a floor, not a feature.
  • Motion is justified in one sentence or it doesn't ship. Animate 
    transform
    and 
    opacity
    only — never 
    transition: all
    , never animate layout properties. One orchestrated moment beats scattered effects, and extra animation is itself a tell.
  • Write the strings as design material. Follow 
    DESIGN.md
    's voice rules when it has them. Otherwise: active voice, sentence case, name things by what people control rather than how the system is built. A control says what happens — "Save changes", not "Submit" — and keeps the same verb through the whole flow, so a button that says "Publish" produces a toast that says "Published." Errors name the fix, not the failure. An empty screen is an invitation to act.
  • Match complexity to the direction. Maximalist needs elaborate execution; minimal needs precision in spacing and type. Elegance is executing the chosen direction well, not choosing the smaller one.
先组合，再创造。优先使用现有组件，而非编写带样式的
div
；优先扩展组件，而非重写；仅当差异真实存在时才重写，并说明原因。Agent的本能是编写新标记，因为这比读取现有内容更快——但这种本能会导致代码库出现四个不同的Button组件。
  • 达到无障碍底线，无需特意说明。这是底线，而非特色。
  • 动效需有合理理由，否则不发布。仅对
    transform
    和
    opacity
    执行动画——绝不使用
    transition: all
    ，绝不动画布局属性。一个协调的动效胜过零散的效果，多余的动画本身就是AI生成的痕迹。
  • 将文案作为设计物料。若
    DESIGN.md
    有语气规则则遵循。否则：使用主动语态、句首大写，按用户可控制的内容命名，而非系统实现方式。控件应说明操作结果——如“保存更改”而非“提交”——且整个流程使用相同动词，例如按钮显示“发布”，提示信息则显示“已发布”。错误提示应说明修复方法，而非仅指出问题。空屏幕应引导用户操作。
  • 复杂度匹配设计方向：极繁设计需要精细执行；极简设计需要间距和字体的精准控制。优雅是出色执行所选方向，而非选择更简洁的方向。

4. Pre-flight

4. 预检查

Run self-critique. It is a critique, not a gate — findings get fixed or get named, and the build is not blocked either way.
执行自我批判。这是批判，而非准入门槛——发现的问题要么修复，要么说明原因，无论哪种情况都不会阻止构建。

5. Hand off

5. 交付

Write every hand-off in this skill in the procedural register: one instruction per sentence, active voice, present tense, no metaphor.
What changed — the components and pages written or edited, one line each, and the composition decisions (what was reused, what was extended, what was newly written and why).
Where it landed — the file paths, and the pre-flight result including anything left unfixed.
Next — repeat the design read verbatim in this hand-off. It is the only durable record of why the UI looks the way it does, and repeating it here is what carries it into a PR body when this runs inside a pipeline. Then: if the project has no 
DESIGN.md
, the crowned next move is designkit 
init
when installed (otherwise write one by hand) — it derives the system from shipped UI, and there is now shipped UI to derive from. If a 
DESIGN.md
already exists, the next move is committing the work with commitkit when installed, otherwise 
git add
and commit. Changes are left unstaged either way; uikit does not commit.
本工具的所有交付内容均使用流程化表述：每句一个指令，主动语态，现在时态，无隐喻。
变更内容——列出编写或编辑的组件和页面，每行一个，以及组合决策（复用了什么、扩展了什么、新编写了什么及原因）。
交付位置——文件路径，以及预检查结果，包括未修复的内容。
下一步——在交付内容中逐字重复设计说明。这是UI设计风格的唯一持久记录，在流水线中运行时，重复此内容会将其带入PR描述。然后：若项目无
DESIGN.md
，则优先推荐安装
designkit
后执行
init
（否则手动编写）——它会从已交付UI中衍生设计系统，而现在已有可衍生的UI内容。若已存在
DESIGN.md
，则优先推荐安装
commitkit
后提交工作，否则执行
git add
和提交。无论哪种情况，变更内容均保持未暂存状态；uikit不会执行提交操作。

Mode: 
audit

模式：
audit

Read-only. Writes nothing, ever. It reports and routes; fixing is a separate 
build
invocation, deliberately.
只读模式。绝不会写入任何内容。仅报告和路由问题；修复需单独调用
build
模式，这是刻意设计的。

1. Resolve the target

1. 确定目标

In order, taking the first that applies:
  1. Explicitly named paths — a directory, a component, a route. This leads because the UI most worth auditing predates the skill and appears in no diff at all; "audit our UI" is the actual ask, and a diff cannot answer it.
  2. The UI files in the working tree or the branch diff — when uncommitted or branch changes exist and no path was named. Note that a plain diff never shows untracked files, so list those separately and read them too.
  3. Ask — when neither resolves. Don't sweep a whole repository by reflex; that's unbounded on any real application.
State the target in one line before reading anything.
按以下顺序选择第一个适用的目标：
  1. 明确指定的路径——目录、组件、路由。优先选择此目标，因为最值得审计的UI早于本工具存在，且不会出现在差异中；“audit our UI”是实际需求，而差异无法回答此问题。
  2. 工作树或分支差异中的UI文件——当存在未提交或分支变更且未指定路径时。注意：普通差异不会显示未跟踪文件，因此需单独列出并读取这些文件。
  3. 询问用户——当上述两种情况都不适用时。不要 reflexively 扫描整个仓库；在实际应用中这是无边界的操作。
在读取任何内容前，先以一行文字说明目标。

2. Sweep

2. 扫描

Run the catalog, filtered to the surface — 
product
entries don't fire on a marketing page and 
marketing
entries don't fire on a settings screen. Then the accessibility floor, which fires on both.
运行反模板目录，按界面类型过滤——
product
条目不会在营销页面触发，
marketing
条目不会在设置页面触发。然后运行无障碍底线，该规则对两种界面都适用。

3. Report

3. 报告

Terse, clickable, no preamble. One finding per line:
src/components/Features.tsx:34   🔴  three equal feature cards for four features — show the real count, grouped by weight
src/components/Hero.tsx:12       🔴  fake dashboard built from divs — use a real screenshot or an embedded live component
src/app/settings/page.tsx:88     🟡  icon-only button with no accessible name — add aria-label
src/components/Card.tsx:7        🟢  rounded-3xl here, rounded-lg everywhere else — pick one corner language
🔴 Blocker · 🟡 Should-fix · 🟢 Nit. Then a mechanical verdict, and — mandatory — a coverage line: how many files were read and how many were skipped. An audit that reached three files reads exactly like a clean bill of health unless it says otherwise.
On the seam with a general code review: a code-review pass hunts code signatures — dead abstractions, over-commenting, defensive noise. uikit hunts visual ones. Running both against the same diff produces complementary findings, not duplicates. Neither defers to the other.
简洁、可点击、无开场白。每行一个发现：
src/components/Features.tsx:34   🔴  四个功能却用三个尺寸相同的卡片——展示真实数量，按权重分组
src/components/Hero.tsx:12       🔴  用div搭建的假仪表盘——使用真实截图或嵌入实时组件
src/app/settings/page.tsx:88     🟡  仅图标按钮无无障碍名称——添加aria-label
src/components/Card.tsx:7        🟢  此处为rounded-3xl，其他地方为rounded-lg——统一圆角规则
🔴 阻塞问题 · 🟡 建议修复 · 🟢 细节问题。然后给出机械性结论，以及必须包含的覆盖范围说明：读取了多少文件，跳过了多少文件。仅读取三个文件的审计，除非明确说明，否则看起来完全像没有问题。
与通用代码审查的边界：代码审查寻找代码痕迹——废弃抽象、过度注释、冗余代码。uikit寻找视觉痕迹。对同一差异运行两者会得到互补的发现，而非重复内容。两者互不干涉。

4. Hand off

4. 交付

What changed — nothing. Say it outright; a reader should never have to wonder whether a read-only mode wrote something.
Where it landed — inline in this reply. No artifact by default; offer to save one only if asked.
Next — crown the single worst finding and route it to 
build
. "Nothing here reads as generated" is a valid, stated result — say the UI is clean and stop rather than inventing a finding to justify the run.
变更内容——无任何变更。明确说明这一点；读者不应怀疑只读模式是否写入了内容。
交付位置——直接在回复中展示。默认不生成文件；仅当用户要求时才提供保存选项。
下一步——指出最严重的问题，并引导至
build
模式。“未发现AI生成痕迹”是有效的明确结果——说明UI干净整洁即可，无需为了证明运行价值而编造问题。

The anti-slop catalog

反模板目录

The discipline is the point, and it travels with the list. A tell earns a line only if it is stateable as a ban with the correct alternative beside it, and an agent can check its own output for it without rendering anything. The cap is ~30 entries, enforced by displacement: adding one means deleting one. Lists like this rot into hundred-item checklists that nobody honestly ticks, and a checklist nobody ticks is decoration. A capped list that can only improve is worth more than an exhaustive one that can only grow.
Scope tags: P product · M marketing · B both.
纪律是核心，且随列表传递。只有当某一痕迹可被表述为禁令+正确替代方案，且Agent无需渲染即可检查自身输出是否存在该痕迹时，才会被列入列表。列表上限为约30条，采用替换机制：新增一条则删除一条。此类列表会逐渐膨胀为上百条的检查清单，没人会真正逐条核对，而无人核对的清单只是装饰。一个可不断优化的有限列表比一个只会增长的 exhaustive 列表更有价值。
范围标签：P 产品 · M 营销 · B 两者通用。

Visual and CSS

视觉与CSS

BanInstead
BViolet/purple gradient as the accent, on the hero or the primary CTAthe project's own accent; at rung 3–4, a color the subject actually implies
BGradient text on headingssolid color — reach for weight or size when a heading needs emphasis
BGlassmorphism by reflex: 
backdrop-blur
over translucent white cards		an opaque surface with a real border
BA drop shadow on every surfaceshadow marks elevation; a card sitting in normal flow has none
B
rounded-2xl
/
rounded-3xl
on everything		one corner language, taken from the system
BDecorative status dots — a pulsing green dot bound to nothingbind it to real state, or delete it
禁令替代方案
B将紫色渐变作为强调色用于Hero区域或主CTA按钮使用项目自身的强调色；层级3–4时，使用业务领域隐含的颜色
B标题使用渐变文字使用纯色——需要强调标题时，调整字重或字号
B习惯性使用玻璃态效果：半透明白色卡片添加
backdrop-blur
使用带真实边框的不透明界面
B所有界面都添加阴影阴影用于标记层级；正常流中的卡片无需阴影
B所有元素都使用
rounded-2xl
/
rounded-3xl
统一圆角规则，遵循系统规范
B装饰性状态点——无绑定状态的脉动绿点绑定真实状态，或删除

Typography

排版

BanInstead
BInter (or the bare system stack) on slate-900 as the entire type decisionname a display face and a body face deliberately; make the type treatment part of the design, not a delivery vehicle
MAn eyebrow/kicker label above every headingdelete it — if the section needs context, the heading carries it
M
01 / 02 / 03
numbered markers on content that is not a sequence		use them only when order is information the reader needs
BEm-dashes in interface stringsa period, a comma, or two sentences. This governs strings on screen, not prose in the repo
BAll-caps letterspaced micro-labels scattered as textureone label style, used where a label is genuinely needed
禁令替代方案
B将Inter（或原生系统字体栈）搭配slate-900作为唯一字体决策刻意选择显示字体和正文字体；将字体处理作为设计的一部分，而非仅用于传递内容
M每个标题上方都添加小标题/引导标签删除——若章节需要上下文，标题应包含该信息
M非序列内容使用
01 / 02 / 03
编号标记		仅当顺序是读者需要的信息时才使用
B界面文案中使用破折号使用句号、逗号或拆分为两句。此规则适用于屏幕上的文案，而非仓库中的散文
B零散分布全大写、字间距扩大的微标签作为装饰统一标签样式，仅在真正需要标签时使用

Layout

布局

BanInstead
BThree equal feature cardsshow the real count, sized by real weight — four features get four
MEvery section centered, 
max-w
+ 
mx-auto
+ 
text-center
all the way down		vary alignment; centering is for the one thing that deserves it
MA 
Scroll ↓
cue or bouncing chevron		delete it — content bleeding past the fold does that job
MDecorative hairline grids or dot-pattern backgroundsdelete; structure should encode something true, not decorate
MRotated vertical text down the side of a sectiondelete
MA locale / weather / local-time stripdelete, unless the product is genuinely about time or place
禁令替代方案
B三个尺寸相同的功能卡片展示真实数量，按实际权重调整大小——四个功能则使用四个卡片
M所有章节居中，全程使用
max-w
+ 
mx-auto
+ 
text-center
调整对齐方式；仅让最值得关注的内容居中
M使用“Scroll ↓”提示或弹跳箭头删除——内容超出视口即可提示滚动
M装饰性细线网格或点阵背景删除；结构应传递真实信息，而非仅用于装饰
M章节侧边使用旋转的竖排文字删除
M显示地区/天气/本地时间条删除，除非产品确实与时间或地点相关

Content and copy

内容与文案

BanInstead
B"Jane Doe" / "John Smith" placeholder peoplenames from the product's own domain, or the real empty state
MAn "Acme Inc / Company Name" logo rowreal customers, or cut the section until they exist
MInvented metrics — "99.99% uptime", "10,000+ users", "2M requests"real numbers, or no numbers
BLorem ipsumreal copy; when it's unknown, the shortest true sentence
MTestimonial cards with invented quotes and stock avatarscut the section until real ones exist
禁令替代方案
B使用“Jane Doe”/“John Smith”作为占位人名使用产品自身领域的名称，或真实的空状态
M使用“Acme Inc / Company Name”作为Logo行使用真实客户，或在有真实客户前删除该章节
M虚构指标——“99.99% uptime”、“10,000+ users”、“2M requests”使用真实数据，或不使用数据
B使用Lorem ipsum占位文本使用真实文案；若未知，则使用最短的真实句子
M使用虚构引用和库存头像的推荐卡片在有真实推荐前删除该章节

Fake product

虚假产品元素

BanInstead
MA dashboard or app screenshot built out of 
div
s		a real screenshot, an embedded live component, or nothing
MFake browser chrome wrapped around a mocksame — a fake window frame is the most recognizable tell on the list
禁令替代方案
M使用div搭建的仪表盘或应用截图使用真实截图、嵌入实时组件，或不使用
M为模拟界面添加虚假浏览器框架同上——虚假窗口框架是最容易识别的AI生成痕迹

Product-UI state gaps

产品UI状态缺失

Silence in these is the product-side equivalent of a purple gradient — nobody designed it, it's just what got generated.
BanInstead
PA list or table that renders nothing at zero rowsan empty state naming the thing and offering the action that creates one
PNo loading statea skeleton matching the real layout, or a labeled loading region
PNo error statean error naming what failed and the recovery action
PIcon-only buttons with no accessible name
aria-label
, plus a tooltip when the icon isn't obvious
P"Invalid input" as validation copyname the constraint and the fix — "Password needs 12+ characters"
PA disabled control with no stated reasonsay why it's disabled, or don't disable it
PDestructive actions with no confirmation and no undoconfirm, or make it undoable — undo is usually better
这些状态的缺失是产品端的紫色渐变等价物——没人设计过，只是生成的默认结果。
禁令替代方案
P列表或表格在零行时无任何内容显示空状态，说明缺失的内容并提供创建操作
P无加载状态使用匹配真实布局的骨架屏，或标记加载区域
P无错误状态显示错误信息，说明失败原因和恢复操作
P仅图标按钮无无障碍名称添加
aria-label
，若图标不明显则添加 tooltip
P验证文案使用“Invalid input”说明约束条件和修复方法——如“密码需包含12个以上字符”
P禁用控件未说明原因说明禁用原因，或不禁用
P破坏性操作无确认和撤销机制添加确认，或支持撤销——通常撤销更好

The accessibility floor

无障碍底线

Not findings — a floor. Every build clears these without announcing it, and 
audit
reports any that a shipped surface doesn't:
  • Visible 
    :focus-visible
    on every interactive element. Never remove a focus ring without replacing it.
  • prefers-reduced-motion
    honored wherever anything moves.
  • WCAG AA contrast on text and on meaningful non-text.
  • Semantic elements before ARIA — a 
    button
    beats a 
    div
    with 
    role="button"
    and a click handler, always.
  • Every control labeled, every image with 
    alt
    (empty 
    alt=""
    when decorative, deliberately).
  • Everything reachable and operable by keyboard, in a sane tab order, with focus trapped in modals and restored on close.
  • Touch targets no smaller than 44px on coarse pointers.
这不是发现项，而是底线。每个构建都会自动满足这些要求，无需声明；
audit
模式会报告已交付界面未满足的项：
  • 所有交互元素都有可见的
    :focus-visible
    状态。绝不要移除焦点环而不替换它。
  • 任何动效都遵循
    prefers-reduced-motion
    设置。
  • 文本和有意义的非文本元素满足WCAG AA对比度要求。
  • 优先使用语义元素而非ARIA——
    button
    始终优于添加
    role="button"
    和点击事件的
    div
    。
  • 所有控件都有标签，所有图片都有
    alt
    属性（装饰性图片使用空
    alt=""
    ，需明确设置）。
  • 所有内容都可通过键盘访问和操作，Tab顺序合理，模态框中焦点被锁定，关闭后恢复焦点。
  • 粗指针的触摸目标不小于44px。

The stack layer

技术栈层

The house default, and skippable whole by a project on another stack. These are correctness rules that prevent silent wrongness, not style preferences.
内部默认值，使用其他技术栈的项目可完全跳过。这些是正确性规则，用于防止隐性错误，而非风格偏好。

Tailwind v4

Tailwind v4

v4 is CSS-first. Theme lives in 
@theme
inside the stylesheet, not in a JS config: 
@import "tailwindcss"
, then 
@theme
, 
@utility
, 
@custom-variant
, 
@source
, and 
@reference
when a separate stylesheet needs the theme.
These renames are the reason to check the version first. Every one of them is a valid class name in v4 that renders smaller than the author intended — no error, no warning, just a subtly wrong result that reads as a design decision:
v3v4
shadow-sm
shadow-xs
shadow
shadow-sm
rounded-sm
rounded-xs
rounded
rounded-sm
blur-sm
blur-xs
blur
blur-sm
outline-none
outline-hidden
ring
ring-3
bg-gradient-to-r
bg-linear-to-r
!text-center
text-center!
Prefer a generated utility over an arbitrary value (
p-4
, not 
p-[16px]
) and a variant over hand-written CSS — arbitrary values are how a design system quietly stops being one.
v4是CSS优先的。主题位于样式表内的
@theme
中，而非JS配置：先
@import "tailwindcss"
，然后使用
@theme
、
@utility
、
@custom-variant
、
@source
，当其他样式表需要主题时使用
@reference
。
这些重命名是先检查版本的原因。每个重命名在v4中都是有效的类名，但渲染效果比预期的更小——无错误、无警告，只是细微错误的结果，会被误认为是设计决策：
v3v4
shadow-sm
shadow-xs
shadow
shadow-sm
rounded-sm
rounded-xs
rounded
rounded-sm
blur-sm
blur-xs
blur
blur-sm
outline-none
outline-hidden
ring
ring-3
bg-gradient-to-r
bg-linear-to-r
!text-center
text-center!
优先使用生成的工具类而非任意值（如
p-4
而非
p-[16px]
），优先使用变体而非手写CSS——任意值会导致设计系统悄然失效。

shadcn/ui

shadcn/ui

  • Install through the CLI; don't hand-copy component source. The components are yours to edit after they land, but the initial copy should be the real one.
  • className
    adjusts layout, not appearance.     Margin, width, grid placement — yes. Restyling the component's internals from the outside means the variant should have been extended instead.
  • Semantic tokens only — 
    bg-background
    , 
    text-muted-foreground
    , 
    bg-primary
    . Never a raw 
    bg-blue-500
    on a shadcn surface.
  • No manual 
    dark:
    overrides.     Semantic tokens already flip. A 
    dark:
    override on a token-styled element means the token was wrong.
  • gap-*
    inside a flex or grid container, never 
    space-x-*
    /
    space-y-*
    .
  • size-*
    over 
    w-N h-N
     when both are equal, and 
    truncate
    over the three-property longhand.
  • cn()
    for conditional classes     — never string concatenation, which breaks conflict resolution.
  • No manual 
    z-index
    on overlays.     Dialog, Sheet, Popover, and Dropdown manage their own stacking; a hand-set z-index is how one ends up behind another.
  • Forms compose as 
    FieldGroup
    → 
    Field
    , and items live inside their group (
    SelectItem
    in 
    SelectGroup
    , and so on).
  • asChild
    (Radix) or 
    render
    (Base UI) for triggers     — never a nested button inside a trigger.
  • Dialog, Sheet, and Drawer each need a title, visually hidden if the design doesn't show one. A screen reader announcing an unnamed dialog is a dead end.
  • Cards compose fully — header, title, content, footer — rather than a bare 
    Card
    with markup dumped inside.
  • 通过CLI安装；不要手动复制组件源码。组件落地后可自行编辑，但初始副本应是官方版本。
  • className
    用于调整布局，而非外观    。如边距、宽度、网格位置——可以。从外部重新设置组件内部样式意味着应扩展变体。
  • 仅使用语义标记——
    bg-background
    、
    text-muted-foreground
    、
    bg-primary
    。绝不在shadcn界面上使用原始
    bg-blue-500
    。
  • 不要手动添加
    dark:
    覆盖    。语义标记已自动适配深色模式。在使用标记样式的元素上添加
    dark:
    覆盖意味着标记设置错误。
  • 在flex或grid容器内使用
    gap-*
    ，绝不使用
    space-x-*
    /
    space-y-*
    。
  • 当宽高相等时，使用
    size-*
    而非
    w-N h-N
    ，使用
    truncate
    而非三属性的完整写法。
  • 使用
    cn()
    处理条件类    ——绝不使用字符串拼接，这会破坏冲突解决机制。
  • 不要手动设置覆盖层的
    z-index
    。Dialog、Sheet、Popover和Dropdown会自行管理堆叠顺序；手动设置z-index会导致某个组件被其他组件遮挡。
  • 表单按
    FieldGroup
    → 
    Field
    组合    ，项位于对应的组内（如
    SelectItem
    在
    SelectGroup
    内，以此类推）。
  • 使用
    asChild
    （Radix）或
    render
    （Base UI）作为触发器    ——绝不在触发器内嵌套按钮。
  • Dialog、Sheet和Drawer都需要标题，若设计不显示则设置为视觉隐藏。屏幕阅读器播报未命名的对话框会导致用户困惑。
  • 卡片需完整组合——包含header、title、content、footer——而非仅使用裸
    Card
    并在内部添加标记。

Self-critique

自我批判

The written pre-flight — always runs

书面预检查——始终执行

The default, and the one that actually fires in headless CI and locked-down VMs. Check the output against:
  1. The catalog, filtered to the declared surface.
  2. The accessibility floor, all of it.
  3. The two signature checks — exactly one signature exists, and its materials are legal at the declared rung.
  4. The remove-one-accessory pass. Before shipping, look at what you built and take one thing away. There is nearly always one decoration that doesn't serve the brief, and it is nearly always easier to see at the end than at the start.
Report what you fixed and what you're leaving, with a reason. This is a critique, not a gate — it never blocks the build.
默认模式，在无头CI和锁定VM中实际触发。检查输出是否符合：
  1. 反模板目录，按声明的界面类型过滤。
  2. 无障碍底线，全部要求。
  3. 两个标志性元素检查——恰好存在一个标志性元素，且其物料符合当前层级的规则。
  4. 移除一个装饰项。发布前，查看构建内容并移除一个装饰项。几乎总有一个不符合需求的装饰项，且在项目结束时比开始时更容易发现。
报告修复的内容和保留的内容及原因。这是批判，而非准入门槛——绝不会阻止构建。

The pixel pass — opt-in

像素检查——可选

Only on an explicit ask ("look at it", "screenshot it and check"). A picture is worth a thousand tokens when a picture is available.
Use what is already present, in this order: a browser-automation tool the environment provides · an installed headless browser or an existing test-automation setup already in the project. Point it at whatever renders cheapest — a static file, a component preview route, a running dev server the user started.
Never install a browser. Never start a dev server you weren't told to start. Never seed data. uikit needs strictly less than a full end-to-end tool does: rendered output, not a driven authenticated flow.
仅在明确请求时执行（如“look at it”、“screenshot it and check”）。当有图片可用时，图片胜过千言万语。
使用已存在的工具，按以下顺序：环境提供的浏览器自动化工具 · 已安装的无头浏览器或项目中已有的测试自动化设置。指向最易渲染的内容——静态文件、组件预览路由、用户启动的开发服务器。
绝不安装浏览器。绝不启动未被要求启动的开发服务器。绝不填充测试数据。uikit所需的资源远少于完整的端到端工具：仅需渲染输出，无需驱动认证流程。

Degrade loudly

降级提示

No browser, no rendering, no filesystem — these are normal conditions, not errors. Name the gap in the same breath as the result, and never frame the written pre-flight as a failed screenshot:
Built 
SettingsPanel.tsx
and 
SettingsRow.tsx
. Pre-flight clean against the product catalog and the a11y floor. No visual check — no browser automation available in this environment.
Never claim a visual check that didn't happen. A UI reported as verified when nothing looked at it is worse than one reported as unverified.
No filesystem at all (a browser-based agent)? Print each component as a fenced block labelled with its intended path, state the design read as normal, and name the commands the user should run themselves.
无浏览器、无渲染、无文件系统——这些是正常情况，而非错误。在给出结果的同时说明缺失的环境，绝不要将书面预检查描述为失败的截图检查：
已构建
SettingsPanel.tsx
和
SettingsRow.tsx
。预检查通过产品目录和无障碍底线验证。未执行视觉检查——当前环境无浏览器自动化工具。
绝不要声称执行了未进行的视觉检查。报告为已验证但实际未查看的UI，比报告为未验证的UI更糟糕。
完全无文件系统（如基于浏览器的Agent）？将每个组件作为带目标路径标记的代码块输出，正常声明设计说明，并告知用户应自行执行的命令。

Notes

注意事项

  • The ladder outranks the taste. When the recorded system and your better idea disagree, the system wins and the better idea goes in the hand-off as a suggestion. Consistency compounds; a one-off improvement doesn't.
  • Composition outranks invention. The existing component, then an extension of it, then something new — in that order, with a reason at each step down.
  • Never invent data. A number, a name, a logo, or a quote that isn't real doesn't ship, even as a placeholder. Placeholder data has a way of surviving to production, and inventing a metric is the one tell that can embarrass someone.
  • Existing project convention wins. A repo with its own component patterns, file layout, or styling approach gets followed — and uikit says which convention it followed.
  • UI copy here, prose elsewhere. uikit governs the strings inside the interface. Repo prose, docs, and READMEs belong to a general prose pass — humankit when installed.
  • Does not commit. Changes are left unstaged for a commit step to group.
  • 层级优先于审美。当已记录的系统与你的更好想法冲突时，系统优先，更好的想法作为建议写入交付内容。一致性会积累价值；一次性改进不会。
  • 组合优先于创造。优先使用现有组件，然后扩展，最后新建——按此顺序，每一步都需说明原因。
  • 绝不虚构数据。非真实的数字、名称、Logo或引用绝不发布，即使作为占位符。占位符数据可能会保留到生产环境，虚构指标是可能导致尴尬的AI生成痕迹。
  • 现有项目约定优先。遵循仓库自身的组件模式、文件布局或样式方法——uikit需说明遵循的约定。
  • UI文案在此处理，散文在其他地方。uikit管理界面内的文案。仓库散文、文档和README属于通用散文处理——安装
    humankit
    后使用该工具。
  • 不执行提交。变更内容保持未暂存状态，由提交步骤统一处理。