How to use UI Skills: Load front-end design rules by task for Codex and Claude Code

UI Skills is a set of rules for design engineers that can hand over appropriate UI specifications to agents such as Codex and Claude Code based on the current task. It is different from a single large and comprehensive design prompt: identify the task first, and then load the corresponding category, which can reduce irrelevant context.

Project address: ibelick/ui-skills

Quick Answer

The project provides a direct run CLI:

1

npx ui-skills start

This command will route the Agent to the appropriate UI Skill based on the task. You can also query categories and specific rules:

1
2
3

npx ui-skills categories
npx ui-skills list --category motion
npx ui-skills get baseline-ui

If it is only used occasionally, there is no need to install it globally first; teams using fixed versions should lock the version in package.json to prevent CLI updates from causing changes in the output of the same prompt word.

Which tasks are suitable for

• Determine basic visual rules before creating a new page;
• Supplement dynamic effects to existing interfaces;
• Unify spacing, layout and component status;
• Review mobile and responsive layout;
• Establish minimum acceptance criteria when design drafts are incomplete.

It is not responsible for understanding the business data, nor does it automatically know whether the project uses Tailwind, CSS Modules, or a component library. Before calling, you still need to tell the Agent the technology stack, target files, and unchangeable interfaces.

Recommended prompt words

1

使用 UI Skills 为当前设置页面选择合适的规则。先说明加载了哪些类别，再检查现有组件。只修改布局和样式，不改变表单字段、接口和路由。

Add constraints when animation is involved:

1

加载 motion 类别，但必须支持 prefers-reduced-motion。动效不能阻塞点击、键盘操作或页面首次渲染。

Why load on demand?

Stuffing all the design rules into the context at once will create three problems: rules conflict with each other, the model ignores really important project constraints, and context costs increase. After loading by category, it is easier to know which rules are affected by this change, and it also facilitates code review.

The recommended order is:

1. Read the existing design system of the project;
2. Query the UI Skills category;
3. Only load the Skills required for the current task;
4. Let the Agent give the modification scope;
5. Check the mobile, keyboard and reduce motion settings.

What problems do CLI commands solve?

View all categories

1

npx ui-skills categories

Run this command first when you don’t know what rules the repository has. Don’t guess the category based on the name, and don’t ask for a skill that doesn’t exist in the prompt word.

View a category

1

npx ui-skills list --category motion

This is suitable for scenarios where the task type is already clear. For example, when you are making up for page transitions, you only query motion instead of loading all layout, form, and marketing page rules.

Get specific rules

1

npx ui-skills get baseline-ui

After obtaining the rules, read the content first and then decide to hand it over to the Agent. Teams can organize the final constraints into their own design documents, rather than relying on the remote current version for each task.

Automatic routing tasks

1

npx ui-skills start

start is suitable for situations where you are not sure which Skill to choose. It is responsible for selecting rules but cannot replace the business brief. Page goals, technology stack, modifiable table of contents, and acceptance criteria should still be provided.

How to write prompt words for different tasks

Create a new settings page

1
2
3
4

使用 UI Skills 选择适合后台设置页的规则。
项目使用 React、TypeScript 和现有 Form 组件。
保留字段、接口、验证逻辑和测试选择器。
先输出将加载的 Skill 和修改计划，确认后再编辑。

Review responsive layout

1
2

只使用与 responsive 和 baseline UI 有关的规则，检查 360px、768px 和 1440px。
列出溢出、固定宽度、触控目标和文字换行问题，不改业务逻辑。

Add animation

1
2

加载 motion 类别，为抽屉打开、列表插入和保存成功设计动效。
支持 prefers-reduced-motion；不得延迟交互、阻塞焦点或修改状态逻辑。

Improve data-intensive pages

1
2

选择适合数据表格和信息密度的 UI Skills。
不要把每一项改成大卡片。保留批量操作、键盘选择和列宽逻辑。

What to do if there is a conflict with the project specification?

UI Skills are external suggestions, and project specifications are the final constraints. It is recommended to handle conflicts according to the following priority:

1. Legal, privacy and security requirements;
2. Business process and interface contract;
3. Accessibility and browser compatibility;
4. Project design token and component API;
5. The UI Skill loaded this time;
6. Agent’s default aesthetic preference.

Writing priorities into tasks prevents Agents from destroying existing forms or components just to follow a visual rule.

How to implement it in the team repository

Fixed version

It is possible to get the current version by running npx ui-skills directly. Production teams should lock versions in development dependencies and update through the normal dependency upgrade process.

Record the adopted rules

Write the used Skill names into the PR description or design document, indicating which rules were adopted and which ones were rejected due to project constraints. This way reviewers can understand the basis for the changes.

Do not treat tool output as final specification

The external skill will be updated. Rules that are important to the team in the long term should be converted into their own tokens, components, lints, tests, or storybooks, rather than relying on cue word memorization forever.

How to cooperate with Hallmark and component library

A clear combination is:

1
2
3
4

Hallmark：决定页面宏观结构和差异化方向
UI Skills：为当前任务选择具体实现规则
组件库：提供可复用、经过测试的实际组件
视觉回归：验证最终输出没有意外变化

If the theme given by Hallmark requires adding new colors, but the component library only allows existing tokens, the tokens should be retained and let Hallmark adjust the structure rather than bypass the design system.

Acceptance checklist after completion

Vision

• Whether the font size and spacing come from the project token;
• Is the page hierarchy clear?
• Whether empty state, loading and error state exist;
• Whether long text and multiple languages overflow.

Interaction

• Can be operated by mouse, keyboard and touch;
• The focus sequence is reasonable;
• Animation effects will not block clicks;
• Form errors can be recognized by screen readers.

Engineering

• Existing components are not re-created;
• No unnecessary dependencies are introduced;
• No changes to interfaces and routing;
• Tests, lint and type checking pass.

Troubleshooting table

FAQ

What should I do if npx ui-skills cannot run?

Check whether Node.js and npm are available, and then confirm that the network can access npm. In corporate networks, it is recommended to use an internal registry and review package sources and versions first.

Can it be used with Hallmark?

Yes, but responsibilities must be divided. Hallmark prefers an overall structure and reduces the sense of AI templates, while UI Skills prefers to load specific rules according to tasks. Don’t have two Skills rewriting the same page at the same time without giving them priority.

Will UI Skills automatically modify the code?

Whether it is modified or not depends on the Agent and task instructions that host it. Obtaining a rule by itself does not equate to authorization to edit a file; it is better to require a schedule or audit before opening the scope for writing.

Can it be used offline?

Getting packages and rules for the first time through npm usually requires networking. Teams can lock and cache dependencies, but the specific offline method requires a combination of npm Registry and license management.

Is it suitable for non-React projects?

The rules themselves may be framework agnostic, but the agent must know the actual technology stack. Don’t directly apply React component writing to Vue, Svelte or native HTML projects.

A complete process from requirements to merge

Take “Add API Key management to the settings page” as an example:

1. First read the existing form, Dialog, Toast and Token;
2. Run categories to confirm the available rules;
3. Only load the form, baseline UI and necessary responsive rules;
4. Indicate the API Key default mask, copy prompt and deletion confirmation;
5. Require the Agent to first outline the plan and file scope;
6. After implementation, test null values, error keys, over-long names and network failures;
7. Use the keyboard to complete addition, editing and deletion;
8. Check the logs and DOM to ensure that the complete Key is not leaked;
9. Run type, unit, end-to-end and visual tests;
10. Document the skills adopted and suggestions covered by the project specifications in the PR.

This process illustrates that UI rules are only part of the implementation process. Data security, error conditions, and regression testing are still provided by project constraints.

When should rules be turned into code?

If a piece of UI advice is used repeatedly on multiple pages, it should not continue to rely on reminder words. For example, fixed focus styles should go into CSS Tokens, button minimum touch sizes should go into components, and form label checks should go into automated tests.

You can convert according to the following table:

UI Skills are used for discovery and guidance, and engineering rules are used to ensure long-term consistency.

Version upgrade verification

After upgrading the CLI, first run a read-only review of the same test page to compare rule names and output changes. If a category is renamed or a proposal changes significantly, update the team documentation first before letting the new version participate in production changes.

Summary

UI Skills are suitable for turning front-end design specifications into agent contexts that can be queried and loaded on demand. For actual use, read existing projects first, then select categories, and finally complete acceptance with accessibility and real devices.