🌏 閱讀中文版本
The confirmation dialog animation was 600ms too slow.
Something happened on the team recently.
A junior dev used AI to build a settings page. It worked. The UI looked clean.
Then he clicked Delete Account. The confirmation dialog faded in — 600ms too slow.
The senior glanced at it and said nothing. Just moved the mouse to the Cancel button, tabbed through — and found the focus order was backwards.
The junior was excited about the speed: “Look how fast the AI wrote this.”
The senior finally spoke: “It’s not that it wrote slowly. Nobody told it what good looks like.”
This is normal.
It’s not that the junior doesn’t know how, and it’s not that the senior is too picky. The AI just wasn’t told what good means.
AI doesn’t have taste. It predicts the next token. Without a definition of “good,” it regresses toward the average of its training data. The average is mediocre.
That’s why we need UI Skills.
Not suggestions. Constraints.
What Are UI Skills?
Let’s clarify something first — the terminology gets confusing.
UI Skills is a directory of constraint documents designed for AI agents. The most representative one is baseline-ui — a concrete set of Skill files. Claude Code is the mechanism that loads them.
Think of it this way:
- UI Skills is the menu.
- baseline-ui is one recipe.
- Claude Code is the chef who follows it.
Its role is clear: Not a suggestion. A constraint.
Definition: UI Skills refers to a set of opinionated constraints designed for AI agents to generate consistent and high-quality UI code.
Key Terms
| Term | Meaning | Why It Matters |
|---|---|---|
| Opinionated | Makes explicit trade-offs | Not afraid to offend; takes a clear stance, reducing model drift |
| Constraints | Rules | Explicit and verifiable |
| AI Agent | AI agents | Built for tools like Claude or Cursor |
Six Constraint Domains
Using baseline-ui as the example, it covers six core areas of UI development:
- Stack: Must use Tailwind CSS (tokenized utilities) and motion/react (animation abstraction)
- Component system: Must use accessible component foundations (Base UI, React Aria, Radix)
- Interaction design: Destructive actions must use alert dialogs; blocking paste is prohibited
- Animation: Interaction feedback must not exceed 200ms; don’t add animations unless explicitly requested
- Typography: Headings use text-balance; numbers use tabular-nums
- Performance: No animation on large blur or backdrop filters
Why does this work?
Because it’s specific.
| Vague Best Practice | UI Skills Constraint |
|---|---|
| “Animation should be fast” | “Interaction feedback must not exceed 200ms” |
| “Consider accessibility” | “Must use React Aria or Base UI” |
| “Performance should be good” | “No animation on large blur filters” |
| “Interactions should be safe” | “Destructive actions must have a confirmation dialog” |
Specific numbers (200ms), not adjectives (fast). Named tools (Tailwind), not directions (use utility-first). Explicit prohibitions, not “try to avoid.”
I’ve seen plenty of teams think a Style Guide counts as governance. It works for humans. For AI, it needs to be a loadable constraint. Skill constraints are live — embedded directly in the AI’s prompt.
From Vague to Specific: The Pattern Shift
You might think: “Isn’t this just writing documentation?”
Not quite.
A Worked Example
Scenario: Animation
Vague rule: “Animation should be smooth and not too long.”
UI Skills constraint: “Interaction feedback must not exceed 200ms.”
Why does this work?
Because it’s verifiable.
When rules are written as “no more than 200ms” or “must use React Aria,” reviewers can spot violations at a glance. Pair them with linting or tests and you can catch issues at the CI stage.
The value of a constraint is verifiability. Once a rule can be checked, it’s no longer a suggestion — it’s a standard.
Usage: From Prompt to Review
Using UI Skills is straightforward.
1. Embed in the Prompt
Add the UI Skills constraints to your AI agent’s system prompt.
You are an expert UI developer.
Follow these constraints strictly:
## Animation
- Duration must be <= 200ms
- Only animate composite properties
## Accessibility
- Use React Aria or Base UI
- No manual ARIA attributes unless necessary2. Load the Skill via Claude Code
If you’re using Claude Code, load baseline-ui as a Skill. Claude will then review a file against the constraint checklist item by item.
One thing to clarify: this is not a traditional linter. There’s no deterministic AST parsing, no exhaustive rule engine. It’s essentially Claude reading your code with a constraint document in hand.
That’s why the output looks more like a review note:
## Potential Constraint Violations
1. **Animation Duration**
- File: `src/components/Button.tsx`
- Observation: Animation duration is set to 300ms, exceeding the 200ms constraint.
- Suggestion: Change `duration={300}` to `duration={200}`.
2. **Accessibility**
- File: `src/components/Input.tsx`
- Observation: Input is missing an `aria-label`.
- Suggestion: Add `aria-label="Search"`.Note: Claude outputs “judgments and suggestions based on the constraints” — it won’t automatically modify files and doesn’t guarantee it catches every violation. To enforce at the PR stage, wire the programmable parts to ESLint or test hooks separately.
How It Differs from Internal Docs
You might be thinking: “We already have internal documentation. How is this different from a Style Guide?”
The difference isn’t whether you have one. It’s who it’s written for.
Where They Diverge
| Dimension | UI Skills | Typical Internal Docs |
|---|---|---|
| Role | Constraint / rule | Reference / guide |
| Tone | “Must” / “Prohibited” | “Recommended” / “Suggested” |
| Verifiability | High (auto-checkable) | Medium (requires human judgment) |
| Technology binding | Tailwind, React Aria | More general |
| Usage | Loaded into AI agent prompt | Read by human engineers |
UI Skills is opinionated. It makes explicit trade-offs. It picks a side and holds it.
Typical internal docs are reference material. They try to cover all cases. Human review works fine, but for AI agents, they need to be converted into executable constraints.
To be specific: if you want AI-generated UI to meet your team’s standard, you need constraints, not references.
Opinionated is the key to Skill design. Take a side, even if it steps on toes — that’s the only way to ensure consistency.
Design Principles Worth Extracting
UI Skills surfaces a few design principles that go beyond UI — they apply to any Skill.
Opinionated + Specific Numbers
“Neutral” rules have lower enforceability. If a rule says “you can use A or B,” the AI picks randomly. Result: inconsistent code.
If your team uses Tailwind, say “must use Tailwind.” Not “Tailwind is recommended.”
“Fast” is subjective. “200ms” is objective. If you want fast animations, say “no more than 200ms.” Not “animations should be fast.”
Tool Binding + Prohibition Lists
Name the tool, don’t say “pick a good one.” “Pick a good one” requires judgment. AI judgment depends on context; explicit team rules reduce model drift between similar options.
If you want accessible components, say “use React Aria.” Not “use accessible components.”
“Try to avoid” means “can do.” “Prohibited” means “can’t.” If you want to avoid performance issues, say “no animation on large blur filters.” Not “try to avoid large blur filters.”
Verifiable
A rule needs three things: clarity, checkability, and a process to enforce it. Once a rule can be checked, it’s no longer a suggestion.
When constraints have concrete thresholds (200ms, must use library X), you can wire the programmable parts to linting or tests, and leave the non-programmable parts to AI-assisted human review.
How to Apply This to Your Own Skill
Step 1: Surface Your Team’s Unwritten Rules
What CSS framework do we use? How long do animations usually run? When does something need a confirmation dialog?
Run a quick meeting. Have the team list the most common UI optimization opportunities, risk scenarios, or review checkpoints they catch repeatedly.
Step 2: Convert Unwritten Rules into Constraints
“We usually use Tailwind” → “Must use Tailwind” “Keep animations short” → “Animation must not exceed 200ms” “Destructive actions should have confirmation” → “Destructive actions must have a confirmation dialog”
Unwritten rules are vague. Constraints are specific.
Step 3: Add a Verification Mechanism
Two paths here.
Path 1: Adopt baseline-ui directly Add the public baseline-ui Skill to your project. Claude Code gives constraint-based suggestions during review; the team makes the final call.
Path 2: Build your own Skill Fork baseline-ui or create your own SKILL.md with your team’s rules and review checkpoints. Wire the programmable parts (duration limits, forbidden properties) to ESLint or test hooks. Leave the non-programmable parts (like “destructive actions need a confirmation dialog”) to AI-assisted review.
Trade-offs and Limitations
Does over-constraining kill creativity? Or does it teach the AI “freedom within bounds”?
Limitation 1: The market signal isn’t clear yet
UI Skills is an emerging concept. The ecosystem is still developing. More standardized approaches may appear.
If you fully adopt UI Skills today, you may face rewrite costs when the ecosystem converges on a standard. When that happens, realignment takes effort.
Limitation 2: Not for every framework
baseline-ui leans React/Tailwind, though the catalog covers multiple platforms.
If you’re on Vue or Angular, some adjustments are needed. The design principles still apply; just swap out the technology-specific bindings.
Limitation 3: Today’s constraints aren’t permanent
AI models are evolving. Today’s constraints may not be needed tomorrow.
Five years from now, most of these constraints will probably be internalized by newer tools. But today, models haven’t learned to take your side for you. The constraints still have to come from you.
What does your team give the AI — constraints or luck?
Building explicit constraints is the first step to integrating AI into a professional development workflow.
The evidence base is still building. For now, I’m using verifiable constraints to reduce variance in generated quality.
Next time the AI generates a component for you, pause for 5 seconds and ask: did it make that choice because you taught it to — or was it guessing?
Sources
- baseline-ui SKILL.md — Baseline UI — constraint rules
- Claude Code Skills Documentation — Official guide to creating and sharing skills
- React Aria Documentation — Accessible component API docs and examples
- Base UI Documentation — Unstyled accessible React components