Community编程与开发github.com

jakubkrehel/better-layout

有助于分组、对齐、阅读顺序、渐进式展示以及其他打造优秀布局的细节。

better-layout 是什么?

该技能专注于构建用户界面的结构和层级关系,确保布局在视觉上清晰、符合逻辑,并且能够适应不同的阅读方向(如 RTL)和屏幕尺寸。它提供了一套详细的规则,指导开发者通过间距而非线条来分组元素、保持控件与内容的视觉区分、遵循对齐边线、按重要性排序内容,并为隐藏内容提供可见的提示。该技能明确了哪些布局细节属于其他技能(如 `better-accessibility` 处理点击区域和焦点行为,`better-ui` 处理圆角、阴影和动画,`better-typography` 处理行高和字间距),从而保持职责的清晰划分。它还包含一套可以发现布局问题的结构化报告系统,用于验证布局在不同视口、200% 缩放以及 RTL 镜像下的表现,并要求检查逻辑属性、物理属性以及 DOM 顺序。最终,该技能帮助团队在设计系统的约束内实现一致、可访问且健壮的布局。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/jakubkrehel/skills/tree/main/skills/better-layout

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

布局

位置、间距和对齐在文字被阅读之前就传递了层级信息。该技能构建这种结构,并对其进行压力测试:调整大小、翻译、镜像以适配 RTL。

所有修复请在项目自身的样式系统中完成。以下数字是针对尚未建立密度系统的界面的起点;如果项目已有密度系统,请直接使用,而非挑选一个看起来熟悉的替代值。保留特意使用的平台界面元素、紧凑的专业工具以及在通过压力测试后仍适用的项目设计令牌。

点击区域和焦点行为属于 better-accessibility。圆角、阴影和动画属于 better-ui。行长和字间距属于 better-typography。

用间距分组,而非线条

优先使用间距进行分组,其次使用背景形状,最后才使用分隔线——仅当间距本身无法清晰传达结构时才使用分隔线。组与组之间的间距必须至少是组内间距的 2 倍(例如组内 8px,组间 16px 或更多),否则分组会被视为噪声。对齐边线和重要性排序的详细信息请参考 grouping-and-alignment.md。

保持控件与内容的区分

为每个可交互元素赋予背景形状、边框或一致的放置区域。如果控件与旁边的静态文本样式相似,用户将无法将其识别为控件。

对齐到共享边线

选择对齐边线并保持一致;任何偏离的边线都会被视为噪声。每层子级关系使用一个项目的精细间距步长,16px 是一个有用的默认值。

对于方向相关的布局,请使用逻辑属性:padding-inline-start、margin-inline-end。仅当描述真正的几何形状时才保留物理上的左和右。

按重要性排序

最重要的内容靠近顶部和起始边缘。阅读顺序为从上到下,从起始边到结束边。思考时使用起始和结束,而不是左和右。

提示隐藏的内容

渐进式展示需要可见的提示。使用项目已有的提示方式,或者让下一个元素在滚动边缘露出 16–32px,或者显示一个展开控件。没有任何提示的隐藏内容等同于不存在。

目标之间的呼吸空间

在没有既定密度系统的情况下,相邻的带边框或填充的控件之间起始间距为 12px,无边框的纯文本或图标控件之间为 24px。紧凑布局可以使用更小的间距,前提是 better-accessibility 定义的点击区域不重叠,且控件仍然易于区分。布局边距和断点设置的详细信息请参考 spacing-and-adaptivity.md。

按钮内缩进边缘

在内容布局中,保持全宽按钮位于布局边距内部,并带有可见的圆角,在移动端从接近 16px 的内联间距开始。边缘到边缘的操作仅在其遵循平台用户界面惯例、考虑了安全区域并且与系统 UI 可区分时方可使用。

内容可溢出,控件需悬浮

背景和媒体可以延伸到视口边缘。控件和文本保持在布局边距和安全区域(env(safe-area-inset-*))内部。粘性定位的界面元素悬浮在内容层之上,而不是遮挡它。

保持布局直到它真正失效

断点应基于内容,而非设备预设。只要布局能真正适配,就保持展开状态,并尽可能晚地折叠。优先使用容器查询进行组件级别的适配,并首先测试最小和最大尺寸。

为文本增长和裁剪做好规划

翻译后的字符串会变长,短的字符串增长比例更大,因此单字按钮的标签是屏幕上风险最高的元素。不要在文本容器上设置固定的宽度或高度,让行可以换行。使用伪本地化测试和一个有代表性的语言环境进行测试,而不是预留一个百分比的空间。

切勿将关键操作放置在调整大小或滚动时会裁剪的位置。将其放在正常流中,或者放在适合产品的稳定界面元素中。

完成前检查

错误修复
在可本地化的布局中使用 margin-left / padding-right使用 margin-inline-start / padding-inline-end
内容布局中的按钮接触视口边缘在项目边距内缩进;保留特意使用的平台界面元素
断点设置为默认的 768/1024在内容实际不再适配的地方设置断点
为某一种语言固定了文本容器的宽度使用 max-width 和换行;使用伪本地化测试
主操作位于面板底部容易被裁剪的位置使用粘性定位或稳定界面元素,并添加安全区域内边距

报告

严重程度。 HIGH 表示在支持的视口中阻止了内容或操作。MEDIUM 表示损害了层级关系、阅读顺序或适配性。LOW 表示孤立的对齐或间距微调。

验证。 无浏览器时:检查是否使用逻辑属性替代物理属性;容器查询和媒体查询是否针对支持的视口列表;DOM 顺序是否符合预期的阅读顺序。有浏览器时:测试每个支持的宽度、200% 缩放以及 RTL 镜像。对于无法执行的检查,请报告为 未验证。

格式。 按违反的原则分组发现的问题,按严重程度排序,每个根本原因对应一行,列出其出现的所有位置:

严重程度位置修改前修改后原因

位置 为 路径/文件:行号。原因 说明违反的原则以及用户影响。

如果仍有任何 HIGH 问题未解决,则以 阻止 结尾;否则以 批准 结尾,并将剩余的待办事项留在表格中。切勿对未审查的覆盖范围给出 批准。如无任何发现,则说明“无需要处理的布局问题”,并报告验证情况。

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

相关技能