good-css

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Good CSS

优秀的 CSS

One declaration that adapts on its own beats a set of breakpoints, and a CSS feature beats a script. Use JavaScript only where it makes a result nicer that already works without it.

Each technique is a set of properties and values, so it works in any authoring system. Class names in the examples are placeholders. Write the declarations in what the project already uses, whether that is a stylesheet, Tailwind utilities or StyleX objects. Where that system has no shorthand for a declaration, write it the long way, as a Tailwind arbitrary property or a rule in the project's CSS file. Do not swap the technique for a breakpoint.

一个能够自动适配的声明胜过一组断点，一个 CSS 特性胜过一段脚本。只有在 JavaScript 能让原本已经可以正常工作的结果体验更好时，才使用 JavaScript。

每种技术都由一组 CSS 属性和值构成，因此适用于任何编写体系。示例中的 class 名称均为占位符。应按照项目已经使用的体系编写声明，无论它使用的是样式表、Tailwind utilities 还是 StyleX objects。如果该体系没有某个声明的简写形式，就使用完整写法，例如 Tailwind arbitrary property 或项目 CSS 文件中的 rule。不要用断点替换这些技术。

In all CSS

适用于所有 CSS 的规则

These need no file.

Write
```
inline
```
and
```
block
```
properties in place of left, right, top and bottom. Tailwind has them too, as in
```
mbs-
```
,
```
pe-
```
and
```
inset-bs-
```
, so never write
```
mt-
```
,
```
pr-
```
or
```
top-
```
.
Write colors in
```
oklch()
```
, with
```
none
```
as the hue of a gray, white or black. Derive a hover, tint or transparent version with
```
color-mix(in oklch, …)
```
.
Put sizes that grow with the screen in one
```
clamp()
```
token.

Put every

:hover

rule inside

@media (hover: hover) and (pointer: fine)

Style focus with
```
:focus-visible
```
and
```
outline
```
. Never write
```
outline: none
```
.
Give everything pressable an
```
:active
```
state.
Put a transition that moves or scales something inside
```
@media (prefers-reduced-motion: no-preference)
```
. Name its properties, never
```
all
```
, and never use
```
ease-in
```
.
Cut off overflow with
```
overflow: clip
```
. Keep
```
hidden
```
for an element a script scrolls.

这些规则不需要任何文件。

使用
```
inline
```
和
```
block
```
方向的属性来代替
```
left
```
、
```
right
```
、
```
top
```
和
```
bottom
```
。Tailwind 也提供这类工具类，例如
```
mbs-
```
、
```
pe-
```
和
```
inset-bs-
```
，因此绝不写
```
mt-
```
、
```
pr
```
或
```
top-
```
。
使用
```
oklch()
```
编写颜色，以
```
none
```
作为灰色、白色或黑色的色相。通过
```
color-mix(in oklch, …)
```
派生 hover、淡色或透明版本。
将随屏幕尺寸增长的尺寸集中到一个
```
clamp()
```
token 中。

将所有

:hover

规则放在

@media (hover: hover) and (pointer: fine)

内。

使用
```
:focus-visible
```
和
```
outline
```
设置焦点样式。绝不写
```
outline: none
```
。
为所有可按压元素添加
```
:active
```
状态。
将移动或缩放元素的 transition 放在
```
@media (prefers-reduced-motion: no-preference)
```
内。明确指定参与 transition 的属性，绝不使用
```
all
```
，也不使用
```
ease-in
```
。
使用
```
overflow: clip
```
截断溢出。仅对由脚本滚动控制的元素使用
```
hidden
```
。

Read the entry before you write

编写前先阅读对应条目

Each file holds entries with the CSS and its rules. The rules are the conditions the CSS needs to work, so keep all of them. Read only the files whose row matches what you are about to write. One component matches two or three, and a whole page matches most of them.

Read	Before you write
`references/foundations.md`	a reset or base stylesheet, a set of color tokens, dark mode, a type or spacing scale
`references/layout.md`	a page container or wrapper, a grid of cards, cards whose parts line up, a sidebar, a component placed in slots of different widths, overlapping layers, centered content that can overflow
`references/spacing-and-shape.md`	spacing between sections, elements stacked one above another, one item pushed to the far end of a row or column, nested rounded corners
`references/text-and-media.md`	text or images that come from a user or a CMS, such as names, titles, excerpts, thumbnails, avatars and embeds, an icon next to a label, a label that looks off-center, numbers in a column
`references/interaction.md`	the focus, hover and press states of a button, link, input or card, a small tap target, a clickable card, form validation, a textarea, a parent styled by what it contains, page scroll locked behind a modal
`references/motion.md`	easing and duration tokens, one state change that drives several values, a shadow that changes on hover, a transition between pages, the indicator under an active tab
`references/show-and-hide.md`	a dialog, popover, dropdown menu or accordion
`references/scroll-and-viewport.md`	a carousel, a row that may overflow, a modal body, chat list or drawer that scrolls between a header and a footer, in-page links under a sticky header, an app shell on desktop or on a phone

每个文件都包含 CSS 及其适用规则的条目。这些规则是 CSS 正常发挥作用所需的条件，因此必须全部保留。只读取表格中“编写前”场景与当前任务匹配的行所对应的文件。一个组件通常会匹配两三项，而整个页面会匹配其中大多数。

阅读	编写前
`references/foundations.md`	重置样式或基础样式表、一组颜色 token、深色模式、排版或间距尺度
`references/layout.md`	页面容器或包装器、卡片网格、内部各部分对齐的卡片、侧边栏、放置在不同宽度插槽中的组件、相互重叠的图层、可能溢出的居中内容
`references/spacing-and-shape.md`	区块之间的间距、纵向堆叠的元素、被推到一行或一列最末端的单个项目、嵌套的圆角
`references/text-and-media.md`	来自用户或 CMS 的文本或图像，例如名称、标题、摘要、缩略图、头像和嵌入内容；位于标签旁的图标；看起来未居中的标签；一列数字
`references/interaction.md`	按钮、链接、input 或 card 的 focus、hover 和 press 状态；较小的点击目标；可点击的 card；表单验证；textarea；根据所含内容设置样式的父元素；模态框后方的页面滚动被锁定
`references/motion.md`	缓动和时长 token；一个状态变化同时驱动多个值；hover 时变化的阴影；页面之间的 transition；活动 tab 下方的指示器
`references/show-and-hide.md`	dialog、popover、dropdown menu 或 accordion
`references/scroll-and-viewport.md`	carousel、可能溢出的行、在 header 和 footer 之间滚动的 modal body、chat list 或 drawer、位于 sticky header 下方的页内链接、桌面端或手机端的 app shell

Left out on purpose

有意省略的内容

Never add

text-box

trim on

text-rendering: optimizeLegibility

, or a reset that puts

display: contents

or one shared grid cell on every element.

references/foundations.md

has the reasons.

绝不要对

添加

text-box: trim

，也不要使用

text-rendering: optimizeLegibility

，或采用会让每个元素都使用

display: contents

或共用同一个 grid cell 的 reset。

references/foundations.md

中说明了原因。

Browser support

浏览器支持

Most entries end with a

Support:

line. This skill sets no browser floor. Weigh the line against the browsers the project targets, and tell the user when something you used is missing from one of them.

大多数条目末尾都有

Support:

行。本 skill 不设浏览器支持下限。根据项目面向的浏览器权衡该行内容；如果所使用的某项功能在目标浏览器中缺失，应告知用户。

Motion

Whether something should animate, the design or review of motion, springs, gestures and drag, and checks on a real phone belong to Emil Kowalski's skills

animate

review-animations

improve-animations

find-animation-opportunities

and

mobile-native

. When they are installed, use them for those jobs, and where one disagrees with a value here, use its value. When they are not, use the entries as written and add no motion beyond what an entry or the task calls for.

是否应该添加动画、motion 的设计或审查、spring、gesture 和 drag，以及在真实手机上的检查，均应交由 Emil Kowalski 的 skills

animate

、

review-animations

、

improve-animations

、

find-animation-opportunities

和

mobile-native

处理。安装这些 skill 后，应将相关工作交给它们；如果其中某个 skill 的取值与此处不一致，以该 skill 的取值为准。如果尚未安装，则按条目原文使用，并且不添加条目或任务未要求的 motion。