better-layout

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Layout that communicates structure

传递结构信息的布局

Layout communicates before a single word is read: position, spacing, and alignment carry hierarchy on their own, and generous space beats decoration. A good layout also survives stress: resize it, translate it, mirror it for RTL, and it should still hold together. Apply these principles when building or reviewing UI code, and express every change in the project's existing styling system (Tailwind, plain CSS, CSS-in-JS); never introduce a second styling approach.

Hit-area sizes and focus behavior are covered by the

better-accessibility

skill; visual polish (radius, shadows, animation) by the

better-ui

skill; line length and text spacing by the

better-typography

skill.

布局在用户阅读任何文字之前就传递了信息：位置、间距和对齐方式本身就承载着层级关系，充足的留白比装饰更有效。优秀的布局还能应对各种场景变化：调整尺寸、翻译内容、镜像为RTL布局后，仍能保持结构完整。在构建或审核UI代码时应用这些原则，并且所有修改都要基于项目现有的样式系统（Tailwind、纯CSS、CSS-in-JS）；切勿引入第二种样式方案。

点击区域尺寸和焦点行为由

better-accessibility

技能覆盖；视觉优化（圆角、阴影、动画）由

better-ui

技能覆盖；行宽和文本间距由

better-typography

技能覆盖。

Quick Reference

快速参考

Category	When to Use
Grouping & Alignment	Space vs separators, alignment edges, logical properties, importance ordering
Spacing & Adaptivity	Spacing between targets, layout margins, progressive disclosure, full-bleed content, breakpoints, i18n growth

类别	适用场景
分组与对齐	留白 vs 分隔符、对齐边缘、逻辑属性、重要性排序
间距与适应性	目标元素间的间距、布局边距、渐进式展示、全屏内容、断点、国际化内容扩展

Core Principles

核心原则

1. Group with Space, Not Lines

1. 用留白分组，而非线条

Negative space is the primary grouping tool; background shapes second; separator lines last, only where space alone can't carry the structure. The gap between groups must be at least 2× the gap within a group (

8px

intra-group →

16px

+ inter-group), or the grouping reads as noise.

负空间是主要的分组工具；背景形状次之；分隔线仅在留白无法传递结构时使用。组与组之间的间距至少应为组内间距的2倍（组内

8px

→ 组间

16px

及以上），否则分组会显得杂乱无章。

2. Keep Controls Distinct from Content

2. 区分控件与内容

Interactive elements must look interactive: a background shape, a border, or a consistent placement zone. Never style a control identically to adjacent static text.

交互元素必须具备交互视觉特征：背景形状、边框或固定的放置区域。切勿将控件设计成与相邻静态文本完全一致的样式。

3. Align to Shared Edges

3. 对齐到共享边缘

Pick alignment edges and stick to them; every stray edge reads as noise. Indent exactly one step (

16px

) to signal subordination. Use logical properties (

padding-inline-start

margin-inline-end

), never physical left/right, so RTL mirrors for free.

选定对齐边缘并保持一致；任何偏离的边缘都会显得杂乱。通过精确缩进一级（

16px

）来表示从属关系。使用逻辑属性（

padding-inline-start

、

margin-inline-end

），切勿使用物理方向的left/right，这样RTL布局可自动适配镜像效果。

4. Order by Importance

4. 按重要性排序

The most important content sits near the top and the leading edge; reading order flows top-to-bottom, leading-to-trailing. Think in leading/trailing, not left/right.

最重要的内容应位于顶部和起始边缘附近；阅读顺序遵循从上到下、从起始到末尾的逻辑。思考时使用起始/末尾，而非左/右。

5. Hint at Hidden Content

5. 提示隐藏内容

Progressive disclosure needs a visible affordance: let the next item peek

16–32px

past the scroll edge, or show a disclosure control. Content hidden with zero cue may as well not exist.

渐进式展示需要可见的提示：让下一个元素露出

16–32px

超出滚动边缘，或显示展开控件。没有任何提示的隐藏内容等同于不存在。

6. Breathing Room Between Targets

6. 目标元素间保留呼吸空间

Keep at least

12px

between adjacent bordered or filled controls, and

24px

of clearance around borderless text- and icon-only controls. Hit-area sizes themselves are covered by the

better-accessibility

skill.

相邻带边框或填充的控件之间至少保留

12px

间距，无边框的纯文本和图标控件周围至少保留

24px

空白。点击区域尺寸本身由

better-accessibility

技能覆盖。

7. Inset Buttons from the Edges

7. 按钮与边缘保持间距

No edge-to-edge, full-width buttons pressed against the viewport. Keep buttons inside the layout margins (at least

16px

inline margin on mobile) with a visible radius.

不要使用紧贴视口边缘的全宽按钮。按钮应置于布局边距内（移动端至少保留

16px

的内联边距），并设置可见的圆角。

8. Content Bleeds, Controls Float

8. 内容全屏延伸，控件悬浮于内

Backgrounds and media extend to the viewport edges; controls and text stay inside the layout margins and safe areas (

env(safe-area-inset-*)

). Sticky chrome floats above the content layer, it doesn't dam it.

背景和媒体可延伸至视口边缘；控件和文本应保持在布局边距和安全区域（

env(safe-area-inset-*)

）内。粘性导航栏悬浮于内容层上方，不应遮挡内容。

9. Hold Structure Until It Breaks

9. 保持结构直至无法承载

Breakpoints come from the content, not device presets. Keep the expanded layout as long as it genuinely fits and collapse late; prefer container queries for component-level adaptation. Test the smallest and largest sizes first.

断点由内容决定，而非设备预设。尽可能保留展开布局，直到内容确实无法容纳再折叠；组件级适配优先使用容器查询（container queries）。优先测试最小和最大尺寸。

10. Plan for Growth and Clipping

10. 为内容扩展和溢出做好规划

Translated strings run 30–40% longer: no fixed widths or heights on text containers, and let rows wrap. Never park critical actions where resizing or scrolling clips them; keep primary actions in stable chrome.

翻译后的字符串长度会增加30–40%：文本容器不要设置固定宽高，允许换行。切勿将关键操作放在调整尺寸或滚动时会被遮挡的位置；将主要操作放在稳定的导航栏中。

Common Mistakes

常见错误

Mistake	Fix
Separator line where spacing would do	Remove the line, double the gap between groups
`margin-left` / `padding-right` in a localizable layout	`margin-inline-start` / `padding-inline-end`
Full-width edge-to-edge button	Inset within layout margins ( `mx-4` minimum on mobile)
Carousel/scroller that looks complete	Let the next item peek `16–32px` past the edge
Adjacent controls with no gap	`12px` minimum between bordered controls, `24px` around borderless ones
Breakpoints at 768/1024 because they're the defaults	Break where the content actually stops fitting
Fixed-width text container sized to English strings	`max-width` + wrapping; translations run 30–40% longer
Primary action at the clip-prone bottom of a pane	Sticky positioning or stable chrome with safe-area padding

错误	修复方案
可用留白却使用分隔线	删除线条，将组间间距加倍
可本地化布局中使用 `margin-left` / `padding-right`	替换为 `margin-inline-start` / `padding-inline-end`
全宽边缘到边缘按钮	缩进至布局边距内（移动端最小 `mx-4` ）
轮播/滚动容器看起来已完全展示	让下一个元素露出 `16–32px` 超出边缘
相邻控件无间距	带边框控件间至少保留 `12px` 间距，无边框控件周围至少保留 `24px` 空白
因默认值将断点设为768/1024	在内容确实无法容纳时设置断点
文本容器固定宽度适配英文内容	设置 `max-width` 并允许换行；翻译内容长度会增加30–40%
主要操作位于面板底部易被遮挡	使用粘性定位或带安全区域内边距的稳定导航栏

Review Output Format

审核输出格式

Present every review in two parts.

所有审核结果分为两部分呈现。

Findings

问题发现

Group findings by principle. Use a markdown table with Severity, Location, Before, After, and Why columns. Include every change made or proposed, not a subset. Never use separate "Before:" / "After:" lines.

Severity:
```
HIGH
```
blocks content or an action at a supported viewport;
```
MEDIUM
```
harms hierarchy, reading order, or adaptability;
```
LOW
```
is isolated alignment or spacing polish.
Location: cite
```
path/to/file:line
```
. If the artifact has no source files, cite the exact screen and component instead.
Before / After: show the current layout and an actionable replacement.
Why: name the violated principle and its effect on comprehension or adaptability.

Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.

按原则分组展示问题。使用Markdown表格，包含Severity、Location、Before、After和Why列。列出所有已修改或建议修改的内容，而非部分内容。切勿使用单独的“Before:” / “After:”行。

Severity：
```
HIGH
```
表示在支持的视口下阻塞内容或操作；
```
MEDIUM
```
表示损害层级、阅读顺序或适应性；
```
LOW
```
表示孤立的对齐或间距优化问题。
Location：引用
```
path/to/file:line
```
。如果没有源文件，则引用具体屏幕和组件。
Before / After：展示当前布局和可执行的整改方案。
Why：指出违反的原则及其对理解或适应性的影响。

将重复的系统性问题合并为一行，并列出所有受影响的位置。没有问题的原则可省略。

Example

示例

Group with space, not lines

用留白分组，而非线条

Severity	Location	Before	After	Why
LOW	`src/Settings.tsx:41`	`border-b` on every settings row	Remove borders; use `space-y-2` within groups and `space-y-8` between groups	Spacing communicates grouping with less visual noise
LOW	`src/ProfileForm.tsx:58`	`<hr>` between form sections	Replace with `mt-10` on each section heading	Section hierarchy should not depend on repeated rules

Severity	Location	Before	After	Why
LOW	`src/Settings.tsx:41`	每个设置行添加 `border-b`	删除边框；组内使用 `space-y-2` ，组间使用 `space-y-8`	留白分组视觉干扰更少
LOW	`src/ProfileForm.tsx:58`	表单区块间使用 `<hr>`	替换为每个区块标题添加 `mt-10`	区块层级不应依赖重复的分隔线

Align to shared edges

对齐到共享边缘

Severity	Location	Before	After	Why
LOW	`src/Card.tsx:24`	Card text at `pl-4` , card icon at `pl-3`	Align both to the same `pl-4` edge	Shared edges create a legible structure
MEDIUM	`src/Nav.css:19`	`margin-left: 16px`	`margin-inline-start: 16px`	Physical properties break direction-aware layouts

Severity	Location	Before	After	Why
LOW	`src/Card.tsx:24`	卡片文本 `pl-4` ，卡片图标 `pl-3`	两者均对齐到 `pl-4` 边缘	共享边缘可形成清晰的结构
MEDIUM	`src/Nav.css:19`	`margin-left: 16px`	`margin-inline-start: 16px`	物理属性会破坏方向感知布局

Verification and Verdict

验证与结论

After the findings:

Verification: list the exact checks run and their observed results across the relevant viewport widths, reading order, zoom, and RTL state. If a check was not run, state what still needs verification.
Verdict:
```
Block
```
if any
```
HIGH
```
finding remains,
```
Needs changes
```
if only
```
MEDIUM
```
or
```
LOW
```
findings remain, and
```
Approve
```
only when no actionable findings remain.

When there are no findings, omit the tables, state "No actionable layout findings", report verification, and end with

Approve

问题发现之后：

Verification：列出执行的具体检查及其在相关视口宽度、阅读顺序、缩放和RTL状态下的观察结果。如果未执行某项检查，说明仍需验证的内容。
Verdict：若存在未解决的
```
HIGH
```
问题则为
```
Block
```
；仅存在
```
MEDIUM
```
或
```
LOW
```
问题则为
```
Needs changes
```
；无待处理问题则为
```
Approve
```
。

若无问题，可省略表格，说明“无待处理布局问题”，报告验证情况，最后以

Approve

结尾。