frontend

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Design Skill

前端设计技能

This skill enforces a single principle: work WITH the framework, never against it. Use the component library natively. Use the CSS framework idiomatically. Let the design system do its job.

The user provides frontend requirements: a component, page, or interface to build or modify.

本技能遵循一个核心原则：与框架协同工作，永远不要对抗它。原生使用组件库，符合惯例地使用CSS框架，让设计系统发挥其应有的作用。

用户提供前端需求：需要构建或修改的组件、页面或界面。

Core Philosophy

核心理念

Don't fight the framework. Use it as it was designed to be used.

Every frontend framework and component library has an intended way to be used. The job of this skill is to ensure that every line of frontend code respects that intent. Customization happens through the channels the framework provides — not by bypassing them.

不要对抗框架。按照它的设计初衷来使用它。

每个前端框架和组件库都有其预设的使用方式。本技能的作用是确保每一行前端代码都符合这一预设。自定义功能要通过框架提供的渠道实现，而不是绕开这些渠道。

Step 1: Codebase Context Discovery (MANDATORY)

步骤1：代码库上下文探查（必填）

Before writing any code, scan the codebase. This step is non-negotiable.

编写任何代码之前，先扫描代码库。 这一步是必须执行的，不能跳过。

What to Detect

需要检测的内容

Frontend framework — Check

package.json

for:

react

vue

angular

svelte

next

nuxt

astro

solid-js

Component library — Check dependencies for: PrimeVue, shadcn/ui, Vuetify, MUI, Chakra UI, Ant Design, Radix, Mantine, Quasar, Element Plus, Headless UI
CSS framework — Check for: Tailwind (
```
tailwind.config.*
```
,
```
@tailwind
```
directives), SCSS, CSS Modules, etc.
Theme configuration — Find the theming mechanism:
- PrimeVue: theme preset in
```
main.ts
```
  (Aura, Lara, Nora), design token overrides
- Vuetify:
```
vuetify.ts
```
  theme config
- MUI:
```
createTheme()
```
  config
- Tailwind:
```
tailwind.config.*
```
  or
```
@theme
```
  block (v4)
Existing component patterns — Examine 2-3 existing components to understand how the library is used in practice

State your findings before proceeding. Example: "Detected: Vue 3 + PrimeVue (Aura preset) + Tailwind CSS. I will use PrimeVue components natively with Tailwind for layout only."

前端框架 —— 检查
```
package.json
```
中的依赖：
```
react
```
、
```
vue
```
、
```
angular
```
、
```
svelte
```
、
```
next
```
、
```
nuxt
```
、
```
astro
```
、
```
solid-js
```
组件库 —— 检查依赖中的组件库：PrimeVue、shadcn/ui、Vuetify、MUI、Chakra UI、Ant Design、Radix、Mantine、Quasar、Element Plus、Headless UI
CSS框架 —— 检查是否存在：Tailwind（
```
tailwind.config.*
```
、
```
@tailwind
```
指令）、SCSS、CSS Modules等
主题配置 —— 找到主题配置机制：
- PrimeVue：
```
main.ts
```
  中的主题预设（Aura、Lara、Nora）、设计令牌覆盖配置
- Vuetify：
```
vuetify.ts
```
  中的主题配置
- MUI：
```
createTheme()
```
  配置
- Tailwind：
```
tailwind.config.*
```
  或
```
@theme
```
  块（v4版本）
现有组件模式 —— 查看2-3个现有组件，了解实际项目中组件库的使用方式

在继续操作前说明你的探查结果。 示例："检测到：Vue 3 + PrimeVue（Aura预设） + Tailwind CSS。我将原生使用PrimeVue组件，仅使用Tailwind做布局。"

Step 2: Framework-Native Implementation

步骤2：框架原生实现

The Golden Rule

黄金规则

Use every component, utility, and API the way the framework documentation shows it. If the framework has a built-in way to do something, use it. Do not invent alternatives.

按照框架文档展示的方式使用所有组件、工具函数和API。 如果框架有内置的实现方式，就用它，不要自创替代方案。

Component Library Rules

组件库通用规则

These rules apply regardless of which component library the project uses (PrimeVue, MUI, Vuetify, shadcn/ui, etc.):

ALWAYS:

Use the library's components directly with their documented props and API
Customize appearance through the library's theming system (design tokens, theme presets, theme config)
Use the library's built-in variants, severities, and sizes (
```
severity="success"
```
,
```
size="small"
```
, etc.)
Use the library's slot system when you need to customize content areas
Follow the library's documented patterns for forms, dialogs, tables, etc.
Use the library's icons and icon integration as documented

NEVER:

Override component internals with CSS targeting internal class names or DOM structure
Create wrapper components that re-style library components from the outside
Use
```
!important
```
to override library styles
Duplicate functionality that already exists in the library (if it has a Tooltip, use it)
Mix components from multiple UI libraries in the same project

无论项目使用哪个组件库（PrimeVue、MUI、Vuetify、shadcn/ui等），都适用以下规则：

必须遵守：

直接使用组件库提供的组件，按照文档说明传递props、调用API
通过组件库的主题系统（设计令牌、主题预设、主题配置）自定义外观
使用组件库内置的变体、严重等级、尺寸配置（
```
severity="success"
```
、
```
size="small"
```
等）
需要自定义内容区域时使用组件库的插槽系统
遵循组件库文档中表单、弹窗、表格等功能的实现模式
按照文档说明使用组件库的图标和图标集成能力

禁止操作：

通过CSS targeting内部类名或DOM结构的方式覆盖组件内部样式
创建 wrapper 组件从外部重写组件库组件的样式
使用
```
!important
```
覆盖组件库样式
重复实现组件库中已经存在的功能（如果组件库已经有Tooltip，直接使用即可）
同一项目中混用多个UI库的组件

PrimeVue-Specific Rules

PrimeVue专属规则

PrimeVue v4 uses a design token system with presets (Aura, Lara, Nora). This is the ONLY supported customization path.

NEVER do this:

Use the PassThrough (
```
pt
```
) API to restyle components with Tailwind classes
Use
```
unstyled
```
mode to strip PrimeVue's styles and rebuild from scratch
Use
```
usePassThrough()
```
utility to override preset styling
Create wrapper components that apply
```
pt
```
overrides globally
Target PrimeVue's internal CSS classes (
```
.p-button-label
```
,
```
.p-datatable-header
```
, etc.) in your stylesheets
Add Tailwind utility classes to PrimeVue component root elements to override their appearance

DO this instead:

Pick a theme preset (Aura, Lara, Nora) and use it

Customize through PrimeVue's design token system in

main.ts

or theme config:

typescript

app.use(PrimeVue, {
  theme: {
    preset: Aura,
    options: {
      prefix: 'p',
      darkModeSelector: '.dark-mode',
      cssLayer: { name: 'primevue', order: 'tailwind-base, primevue, tailwind-utilities' }
    }
  }
})

Override design tokens at the theme level when you need different colors or spacing:

typescript

import { definePreset } from '@primevue/themes'
import Aura from '@primevue/themes/aura'

const MyPreset = definePreset(Aura, {
  semantic: {
    primary: {
      50: '{indigo.50}',
      // ...
      950: '{indigo.950}'
    }
  }
})

Use component props as documented:
```
severity
```
,
```
size
```
,
```
outlined
```
,
```
rounded
```
,
```
raised
```
,
```
text
```
, etc.
Use PrimeVue's built-in CSS layer ordering to ensure Tailwind and PrimeVue coexist cleanly

Why no
pt
? The PassThrough API fights the framework. It bypasses the theming system, creates maintenance burden when PrimeVue updates internal DOM structure, and produces code that is neither idiomatic PrimeVue nor idiomatic Tailwind. The design token system exists precisely so you don't need

pt

PrimeVue v4使用带预设的设计令牌系统（Aura、Lara、Nora），这是唯一受支持的自定义途径。

禁止以下操作：

使用PassThrough（
```
pt
```
）API为组件添加Tailwind类来重写样式
使用
```
unstyled
```
模式移除PrimeVue的样式后从零开始重写
使用
```
usePassThrough()
```
工具覆盖预设样式
创建全局应用
```
pt
```
覆盖的wrapper组件
在样式表中target PrimeVue的内部CSS类（
```
.p-button-label
```
、
```
.p-datatable-header
```
等）
为PrimeVue组件根元素添加Tailwind工具类来覆盖其外观

请使用以下替代方案：

选择一个主题预设（Aura、Lara、Nora）并直接使用

在

main.ts

或主题配置中通过PrimeVue的设计令牌系统自定义：

typescript

app.use(PrimeVue, {
  theme: {
    preset: Aura,
    options: {
      prefix: 'p',
      darkModeSelector: '.dark-mode',
      cssLayer: { name: 'primevue', order: 'tailwind-base, primevue, tailwind-utilities' }
    }
  }
})

需要自定义颜色或间距时在主题层级覆盖设计令牌：

typescript

import { definePreset } from '@primevue/themes'
import Aura from '@primevue/themes/aura'

const MyPreset = definePreset(Aura, {
  semantic: {
    primary: {
      50: '{indigo.50}',
      // ...
      950: '{indigo.950}'
    }
  }
})

按照文档说明使用组件props：
```
severity
```
、
```
size
```
、
```
outlined
```
、
```
rounded
```
、
```
raised
```
、
```
text
```
等
使用PrimeVue内置的CSS层排序机制保证Tailwind和PrimeVue可以正常共存

为什么禁止使用
pt
？ PassThrough API会与框架逻辑产生冲突。它绕开了主题系统，在PrimeVue更新内部DOM结构时会增加维护负担，产出的代码既不符合PrimeVue的使用惯例，也不符合Tailwind的使用惯例。设计令牌系统的存在正是为了让你不需要使用

pt

。

CSS Framework Rules (Tailwind)

CSS框架规则（Tailwind）

When the project uses Tailwind CSS, follow these rules on every frontend change:

ALWAYS:

Use Tailwind utility classes directly in templates — this is the primary styling mechanism
Follow mobile-first responsive design: base styles first, then
```
sm:
```
,
```
md:
```
,
```
lg:
```
,
```
xl:
```
Use consistent class ordering: layout > positioning > box model > typography > visual > interactive
Use the project's Tailwind config tokens (
```
text-primary-500
```
, not
```
text-[#3b82f6]
```
)
Use complete class strings — never concatenate (
```
bg-${color}-500
```
breaks the compiler)
Use computed properties or lookup objects for dynamic classes
Use
```
prettier-plugin-tailwindcss
```
for automatic class sorting if available
Use Tailwind for layout, spacing, and typography on YOUR elements (not library components)

NEVER:

Write custom CSS when a Tailwind utility exists for it
Use
```
@apply
```
excessively — prefer Vue components for abstraction instead of CSS classes
Use arbitrary values (
```
text-[14px]
```
) when a Tailwind scale value exists (
```
text-sm
```
)
Concatenate class names dynamically (breaks purging in production)
Mix CSS methodologies — if the project uses Tailwind, don't add CSS Modules or styled-components
Use Tailwind utilities to override component library styles

Tailwind + Component Library coexistence:

Tailwind handles: page layout, spacing between components, custom elements, typography on non-library elements
Component library handles: component appearance, component spacing internals, interactive states
They do NOT overlap: don't use Tailwind to restyle library components, don't use library classes for page layout

当项目使用Tailwind CSS时，每一次前端变更都要遵循以下规则：

必须遵守：

在模板中直接使用Tailwind工具类——这是主要的样式实现方式
遵循移动端优先的响应式设计：先写基础样式，再添加
```
sm:
```
、
```
md:
```
、
```
lg:
```
、
```
xl:
```
断点样式
保持统一的类名顺序：布局 > 定位 > 盒模型 > 排版 > 视觉效果 > 交互效果
使用项目Tailwind配置中的设计令牌（用
```
text-primary-500
```
，不要用
```
text-[#3b82f6]
```
）
使用完整的类名字符串——不要拼接类名（
```
bg-${color}-500
```
会破坏编译器功能）
动态类使用计算属性或查找对象实现
如果项目配置了
```
prettier-plugin-tailwindcss
```
，使用该插件自动排序类名
Tailwind仅用于你自己编写的元素的布局、间距、排版（不要用于组件库组件）

禁止操作：

如果Tailwind已经有对应的工具类，就不要写自定义CSS
过度使用
```
@apply
```
——优先使用Vue组件做抽象，而不是CSS类
如果Tailwind存在对应的刻度值，不要使用任意值（用
```
text-sm
```
，不要用
```
text-[14px]
```
）
动态拼接类名（会破坏生产环境的Tree Shaking）
混用CSS方法论——如果项目使用Tailwind，就不要添加CSS Modules或styled-components
使用Tailwind工具类覆盖组件库的样式

Tailwind与组件库共存规则：

Tailwind负责：页面布局、组件之间的间距、自定义元素、非组件库元素的排版
组件库负责：组件外观、组件内部间距、交互状态
二者功能不重叠：不要用Tailwind重写组件库样式，不要用组件库的类做页面布局

Tailwind Best Practices Checklist

Tailwind最佳实践检查清单

Apply this checklist on every frontend change:

Mobile-first: base styles are mobile, breakpoints add complexity
No arbitrary values when a scale value exists
No
```
@apply
```
— use Vue components for repeated patterns
No class concatenation — use lookup objects for dynamic classes
Consistent class ordering (use Prettier plugin)
Dark mode uses
```
dark:
```
prefix consistently
Interactive states use
```
hover:
```
,
```
focus:
```
,
```
active:
```
,
```
disabled:
```
variants
Focus styles are visible for accessibility (
```
focus:ring-2
```
,
```
focus:outline-none
```
)
Design tokens from
```
tailwind.config
```
are used, not hardcoded values
No conflicting utilities on the same element

每一次前端变更都应用以下检查项：

移动端优先：基础样式适配移动端，断点仅增加更复杂的适配逻辑
存在对应刻度值时不使用任意值
不使用
```
@apply
```
——重复模式使用Vue组件抽象
不拼接类名——动态类使用查找对象实现
类名顺序统一（使用Prettier插件自动处理）
深色模式统一使用
```
dark:
```
前缀
交互状态使用
```
hover:
```
、
```
focus:
```
、
```
active:
```
、
```
disabled:
```
变体
为了可访问性，聚焦样式可见（
```
focus:ring-2
```
、
```
focus:outline-none
```
）
使用
```
tailwind.config
```
中的设计令牌，不写硬编码值
同一元素上不存在冲突的工具类

Step 3: What This Skill is NOT

步骤3：本技能不涵盖的内容

This skill does NOT cover:

Aesthetic direction or creative design — it enforces framework discipline, not visual creativity
Framework-specific API patterns — defer to
```
vue-best-practices
```
,
```
react-best-practices
```
for those
Greenfield design system creation — use
```
create-design-system-rules
```
for that

本技能不覆盖以下场景：

美学方向或创意设计 —— 它强制推行框架使用规范，不涉及视觉创意
特定框架的API模式 —— 请参考
```
vue-best-practices
```
、
```
react-best-practices
```
获取相关规范
全新设计系统创建 —— 请使用
```
create-design-system-rules
```
完成该工作

What to AVOID — Summary

需要避免的内容 —— 总结

Anti-pattern	Why it's wrong	What to do instead
`pt` API on PrimeVue components	Fights the framework's theming system	Use design tokens and `definePreset()`
`unstyled` mode + Tailwind rebuild	Re-implements PrimeVue from scratch	Use a theme preset
Wrapper components with style overrides	Unnecessary abstraction, breaks on updates	Use components directly with props
`!important` overrides	Specificity wars, unmaintainable	Fix the root cause through theme config
Tailwind classes on library components	Two systems fighting for control	Let the library own its components
Custom CSS for things Tailwind does	Mixed methodologies	Use Tailwind utilities
`@apply` everywhere	Defeats utility-first purpose	Extract Vue components instead
Arbitrary values ( `text-[14px]` )	Bypasses design token system	Use scale values ( `text-sm` )
Class concatenation ( `bg-${x}-500` )	Breaks Tailwind compiler purging	Use lookup objects
Targeting internal library classes	Breaks on library updates	Use library's theming API

反模式	错误原因	替代方案
PrimeVue组件上使用 `pt` API	与框架的主题系统冲突	使用设计令牌和 `definePreset()`
`unstyled` 模式 + Tailwind重写样式	相当于从零重新实现PrimeVue	使用官方主题预设
带样式覆盖的wrapper组件	不必要的抽象，组件更新时容易失效	直接使用组件并传递props
`!important` 样式覆盖	会导致优先级冲突，难以维护	通过主题配置从根源解决问题
给组件库组件添加Tailwind类	两个样式系统会产生冲突	让组件库自己控制组件样式
为Tailwind已经支持的功能写自定义CSS	混用方法论会提升维护成本	使用Tailwind工具类
到处使用 `@apply`	违背了工具优先的设计初衷	提取为Vue组件
使用任意值（ `text-[14px]` ）	绕开了设计令牌系统	使用刻度值（ `text-sm` ）
拼接类名（ `bg-${x}-500` ）	破坏Tailwind编译器的Tree Shaking功能	使用查找对象
Target组件库内部类	组件库更新时容易失效	使用组件库的主题API

Complementary Skills

互补技能

vue-best-practices / react-best-practices — Framework-specific API patterns and component architecture
create-design-system-rules — For projects without an established design system
web-design-guidelines — For auditing accessibility and UI quality

vue-best-practices / react-best-practices —— 特定框架的API模式和组件架构规范
create-design-system-rules —— 适用于还没有建立成熟设计系统的项目
web-design-guidelines —— 用于可访问性和UI质量审计

Remember

请牢记

The best frontend code is invisible. It uses the tools the project chose — the component library, the CSS framework, the theme system — exactly as they were meant to be used. No overrides. No workarounds. No cleverness that the next developer has to reverse-engineer.

Use the framework. Trust the framework. Don't fight the framework.

最好的前端代码是无感知的。它完全按照设计初衷使用项目选择的工具——组件库、CSS框架、主题系统。没有样式覆盖，没有临时变通方案，不需要下一个开发者反向推导才能理解的奇技淫巧。

使用框架，信任框架，不要对抗框架。 ",