clean-css

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Clean CSS: Index And Review Guide

规范CSS：索引与审查指南

CSS should express design intent through the project's styling system, keep layout relationships predictable, and preserve accessibility across states and viewport sizes.

CSS应通过项目的样式系统传达设计意图，保持布局关系可预测，并在不同状态和视口尺寸下确保可访问性。

First Check Project Conventions

首先检查项目约定

Before reviewing or editing styles, identify the local styling approach:

CSS files or CSS Modules
CSS variables, design tokens, theme objects, or utility classes
Tailwind or another utility framework
styled-components, Emotion, StyleX, or inline
```
style={{}}
```
props
existing spacing, color, typography, radius, shadow, z-index, and breakpoint conventions

Prefer the project's established tokens and patterns. Do not invent a new token scale or styling abstraction for a narrow change.

在审查或编辑样式之前，先确定本地的样式方案：

CSS文件或CSS Modules
CSS变量、设计令牌、主题对象或工具类
Tailwind或其他工具框架
styled-components、Emotion、StyleX或内联
```
style={{}}
```
属性
已有的间距、颜色、排版、圆角、阴影、z-index和断点约定

优先使用项目已确立的令牌和模式。不要为局部修改创建新的令牌尺度或样式抽象。

Core Rules (CSS1-CSS8)

核心规则（CSS1-CSS8）

CSS1: Use design tokens or existing utilities for repeated design values.
CSS2: Keep CSS declarations purposeful; remove defaults, overrides, and no-op properties.
CSS3: Prefer layout primitives over manual spacing and positioning.
CSS4: Keep selectors shallow and specificity low.
CSS5: Preserve visible focus, contrast, reduced motion, and disabled states.
CSS6: Avoid static inline styles and arbitrary class strings.
CSS7: Keep responsive behavior explicit and stable.
CSS8: Avoid duplicated style knowledge.

CSS1：重复的设计值使用设计令牌或现有工具类。
CSS2：CSS声明需具备明确用途；移除默认值、覆盖项和无效属性。
CSS3：优先使用布局原语，而非手动设置间距和定位。
CSS4：选择器层级要浅，特异性要低。
CSS5：保留可见焦点、对比度、减少动效和禁用状态。
CSS6：避免静态内联样式和任意类名字符串。
CSS7：保持响应式行为明确且稳定。
CSS8：避免重复的样式逻辑。

CSS1: Tokens For Design Values

CSS1：设计值使用令牌

Use theme tokens, CSS variables, or established utilities for colors, spacing, type, radius, shadows, z-index, and reusable transition values.

css

/* Bad */
.card {
  color: #374151;
  padding: 1.875rem;
  border-radius: 13px;
  z-index: 100;
}

/* Good */
.card {
  color: var(--color-text-muted);
  padding: var(--space-lg);
  border-radius: var(--radius-md);
  z-index: var(--z-popover);
}

Hardcoded values are acceptable when they are intrinsic geometry or genuinely dynamic:

1px

hairlines, SVG coordinates,

clip-path

points, transform offsets, measured canvas values, animation keyframe coordinates, and one-off media query breakpoints that match project convention.

颜色、间距、字体、圆角、阴影、z-index和可复用过渡值，应使用主题令牌、CSS变量或已有的工具类。

css

/* Bad */
.card {
  color: #374151;
  padding: 1.875rem;
  border-radius: 13px;
  z-index: 100;
}

/* Good */
.card {
  color: var(--color-text-muted);
  padding: var(--space-lg);
  border-radius: var(--radius-md);
  z-index: var(--z-popover);
}

硬编码值在以下场景是可接受的：固有几何属性、真正的动态值，例如

、

1px

细线、SVG坐标、

clip-path

点、变换偏移量、测量的画布值、动画关键帧坐标，以及符合项目约定的一次性媒体查询断点。

CSS2: Purposeful Declarations

CSS2：声明需具备明确用途

Every declaration should have a visible effect in context.

Remove declarations that:

Repeat browser defaults without intent.
Are overridden later in the same rule.
Are nullified by display mode, positioning, or cascade.
Duplicate a shorthand already present.

Prefer shorthand when it keeps intent clear and the project's styling system supports it. This applies to

margin

padding

border

background

transition

font

, and

inset

css

/* Bad */
.button {
  display: flex;
  flex-direction: row;
  background: none;
  background-color: transparent;
}

.badge {
  z-index: 2;
}

.panel {
  padding-top: var(--space-sm);
  padding-right: var(--space-md);
  padding-bottom: var(--space-sm);
  padding-left: var(--space-md);
}

/* Good */
.button {
  display: flex;
  background: none;
}

.badge {
  position: relative;
  z-index: var(--z-raised);
}

.panel {
  padding: var(--space-sm) var(--space-md);
}

Be careful with framework resets, browser normalization, and CSS-in-JS constraints. A value that looks like a default may still be intentional if it counters a reset, inherited style, or third-party component. Some systems, such as StyleX, may restrict shorthand support; treat shorthand as a suggestion in those cases.

每个声明在上下文环境中都应产生可见效果。

移除以下声明：

无意图重复浏览器默认值的声明。
在同一规则中被后续代码覆盖的声明。
被显示模式、定位或层叠规则抵消的声明。
已存在简写形式的重复声明。

当简写能明确传达意图且项目样式系统支持时，优先使用简写。这适用于

margin

、

padding

、

border

、

background

、

transition

、

font

和

inset

。

css

/* Bad */
.button {
  display: flex;
  flex-direction: row;
  background: none;
  background-color: transparent;
}

.badge {
  z-index: 2;
}

.panel {
  padding-top: var(--space-sm);
  padding-right: var(--space-md);
  padding-bottom: var(--space-sm);
  padding-left: var(--space-md);
}

/* Good */
.button {
  display: flex;
  background: none;
}

.badge {
  position: relative;
  z-index: var(--z-raised);
}

.panel {
  padding: var(--space-sm) var(--space-md);
}

注意框架重置、浏览器归一化和CSS-in-JS的限制。如果某个值看似默认值，但用于抵消重置样式、继承样式或第三方组件样式，则可能是有意为之。部分系统（如StyleX）可能限制简写支持，这种情况下将简写视为建议即可。

CSS3: Layout Primitives Over Manual Spacing

CSS3：优先使用布局原语而非手动间距

Use flexbox,

gap

, alignment, and intrinsic sizing before margins, absolute positioning, or magic offsets. Prefer flexbox for layout when possible; reserve grid for cases that truly need two-dimensional row and column control.

css

/* Bad */
.item {
  margin-bottom: var(--space-md);
}

.item:last-child {
  margin-bottom: 0;
}

/* Good */
.list {
  display: flex;
  flex-direction: column;
  gap: var(--space-md);
}

Margins between unrelated sections are fine. This rule targets repeated sibling spacing, manual alignment, and offsets that encode layout relationships in children.

Reserve

position: absolute

and

position: fixed

for overlays, anchored UI, measured placement, decorative layers, and intentionally removed-from-flow elements. If

top

right

bottom

, or

left

are used to align ordinary siblings, prefer flexbox or grid.

在使用外边距、绝对定位或魔术偏移量之前，优先使用flexbox、

gap

、对齐和固有尺寸。尽可能用flexbox实现布局；仅在真正需要二维行列控制时使用grid。

css

/* Bad */
.item {
  margin-bottom: var(--space-md);
}

.item:last-child {
  margin-bottom: 0;
}

/* Good */
.list {
  display: flex;
  flex-direction: column;
  gap: var(--space-md);
}

不相关区块之间的外边距是允许的。本规则针对的是重复的同级间距、手动对齐，以及将布局关系编码在子元素中的偏移量。

position: absolute

和

position: fixed

仅用于覆盖层、锚定UI、精准定位、装饰层，以及有意脱离文档流的元素。如果使用

top

、

right

、

bottom

或

left

对齐普通同级元素，优先选择flexbox或grid。

CSS4: Low Specificity

CSS4：低特异性

Keep selectors shallow and local. Prefer one clear class over descendant chains.

css

/* Bad */
.page .content .sidebar .nav .item .link {
  color: var(--color-link);
}

/* Good */
.navLink {
  color: var(--color-link);
}

Avoid

!important

. It usually means the cascade boundary, selector ownership, or component API is wrong. Only tolerate it for documented third-party overrides where the project already uses that escape hatch.

选择器层级要浅且本地化。优先使用单一清晰的类名，而非后代选择器链。

css

/* Bad */
.page .content .sidebar .nav .item .link {
  color: var(--color-link);
}

/* Good */
.navLink {
  color: var(--color-link);
}

避免使用

!important

。它通常意味着层叠边界、选择器归属或组件API存在问题。仅在项目已明确允许的第三方样式覆盖场景下容忍它。

CSS5: Visual Accessibility

CSS5：视觉可访问性

Interactive elements need visible states:

```
:focus-visible
```
for keyboard focus
hover and active states where the component uses pointer affordance
disabled styles that do not rely on color alone
sufficient text and UI contrast
reduced-motion behavior for large motion or continuous animation

css

/* Bad */
.trigger:focus {
  outline: none;
}

/* Good */
.trigger:focus-visible {
  outline: 2px solid var(--color-focus-ring);
  outline-offset: 2px;
}

Do not remove focus outlines without replacing them. If animation is more than a small transition, check

prefers-reduced-motion

交互元素需要可见状态：

键盘聚焦时的
```
:focus-visible
```
状态
组件使用指针交互时的hover和active状态
不单独依赖颜色的禁用样式
足够的文本与UI对比度
大型动效或连续动画的减少动效行为

css

/* Bad */
.trigger:focus {
  outline: none;
}

/* Good */
.trigger:focus-visible {
  outline: 2px solid var(--color-focus-ring);
  outline-offset: 2px;
}

不要移除聚焦轮廓而不替换它。如果动画不仅仅是小过渡，需检查

prefers-reduced-motion

。

CSS6: Avoid Static Inline Styles

CSS6：避免静态内联样式

Static style values belong in the styling system, not

style={{}}

tsx

// Bad
<button style={{ padding: "0.5rem 1rem", borderRadius: "8px" }} />

// Good
<button className={styles.button} />

Inline styles are acceptable for values computed at runtime: measured overlay coordinates, user-selected colors, chart dimensions, CSS custom property bridges, and canvas or animation values that cannot be known statically.

For Tailwind or utility classes, avoid long arbitrary-value strings when an existing utility or tokenized class communicates the same intent.

静态样式值应放在样式系统中，而非

style={{}}

内。

tsx

// Bad
<button style={{ padding: "0.5rem 1rem", borderRadius: "8px" }} />

// Good
<button className={styles.button} />

内联样式适用于运行时计算的值：测量的覆盖层坐标、用户选择的颜色、图表尺寸、CSS自定义属性桥接，以及无法静态确定的画布或动画值。

对于Tailwind或工具类，当已有工具类或令牌化类能传达相同意图时，避免使用冗长的任意值字符串。

CSS7: Responsive Stability

CSS7：响应式稳定性

Styles should survive real content and common viewport sizes.

Check for:

Text that can overflow buttons, cards, table cells, tabs, and narrow columns.
Fixed widths or heights where content should determine size.
```
100vh
```
on mobile without accounting for dynamic browser chrome.
Viewport-scaled font sizes that make text too small or too large.
Layout shifts caused by hover, focus, loading, or validation states.
Images, canvases, and iframes without stable dimensions or aspect ratios.

Prefer

minmax

clamp

for dimensions,

max-width

min-width: 0

overflow-wrap

aspect-ratio

, and container-aware layouts. Do not scale font size directly with viewport width unless the project already has a carefully bounded typography utility.

样式应能适配真实内容和常见视口尺寸。

检查以下问题：

文本溢出按钮、卡片、表格单元格、标签页和窄列。
内容应决定尺寸的地方使用了固定宽高。
移动端使用
```
100vh
```
但未考虑动态浏览器栏。
视口缩放的字体大小导致文本过小或过大。
悬停、聚焦、加载或验证状态导致的布局偏移。
没有稳定尺寸或宽高比的图片、画布和iframe。

优先使用

minmax

、

clamp

设置尺寸，以及

max-width

、

min-width: 0

、

overflow-wrap

、

aspect-ratio

和容器感知布局。除非项目已有严格限定的排版工具类，否则不要直接根据视口宽度缩放字体大小。

CSS8: No Duplicated Style Knowledge

CSS8：避免重复的样式逻辑

If the same group of three or more declarations appears in multiple places, check whether the project has a shared primitive, mixin, token, utility, or component style that should own it.

Duplication across files matters too: inputs, cards, modals, focus rings, empty states, and form errors should usually share one source of design knowledge.

Do not extract prematurely when two blocks only look similar by coincidence. Extract when the repeated styles represent the same design concept.

如果同一组三个及以上的声明出现在多个地方，检查项目是否有应承载该逻辑的共享原语、混入、令牌、工具类或组件样式。

文件间的重复也需注意：输入框、卡片、模态框、聚焦环、空状态和表单错误通常应共享单一设计逻辑源。

当两个代码块只是偶然相似时，不要过早提取。仅当重复样式代表相同设计概念时再进行提取。

Review Process

审查流程

When reviewing a branch:

Determine the requested or default base branch, then run
```
git diff <base> --name-only
```
.
Inspect changed
```
.css
```
,
```
.module.css
```
,
```
.scss
```
,
```
.tsx
```
,
```
.jsx
```
, styled template literals,
```
stylex.create
```
, Tailwind class strings, and
```
style={{}}
```
props.
Read changed hunks in context before flagging a rule.
Report findings by severity and rule ID.

审查分支时：

确定请求的或默认的基础分支，然后运行
```
git diff <base> --name-only
```
。
检查已修改的
```
.css
```
、
```
.module.css
```
、
```
.scss
```
、
```
.tsx
```
、
```
.jsx
```
文件、styled模板字面量、
```
stylex.create
```
、Tailwind类字符串和
```
style={{}}
```
属性。
在标记规则违规前，结合上下文查看修改的代码块。
按严重程度和规则ID报告发现的问题。

Severity

严重程度

Block: Accessibility regression, broken responsive layout, unsafe
```
!important
```
, invisible focus, or likely user-visible breakage.
Fix: Token drift, no-op declarations, duplicated style knowledge, brittle positioning, static inline styles, or avoidable specificity.
Suggest: Shorthand, minor consistency, optional extraction, or style polish already near the changed code.

阻塞：可访问性退化、响应式布局损坏、不安全的
```
!important
```
、不可见焦点，或可能导致用户可见的故障。
修复：令牌偏离、无效声明、重复样式逻辑、脆弱定位、静态内联样式，或可避免的高特异性。
建议：简写形式、微小一致性优化、可选提取，或修改代码附近的样式打磨。

AI Behavior

AI行为

When reviewing code, identify violations by rule number, for example: "CSS5 violation: custom button removes focus outline without a replacement."

When editing code, preserve the existing styling system and report what changed, for example: "Fixed: replaced child margins with parent

gap

(CSS3)."

When unsure whether a value is arbitrary or project-standard, inspect nearby styles before flagging it.

审查代码时，按规则编号识别违规，例如：“CSS5违规：自定义按钮移除了聚焦轮廓但未替换。”

编辑代码时，保留现有样式系统并说明修改内容，例如：“已修复：将子元素外边距替换为父元素

gap

（CSS3）。”

不确定某个值是任意值还是项目标准值时，先查看附近样式再标记。