css-coder

CSS 编码者

编写 CSS 的指南，优先考虑 Web 标准、无障碍性、性能和可维护性。

核心原则

1. Web 标准优先 — 使用库或框架之前，先采用原生 CSS 功能。除非明确要求，否则不要使用 Tailwind 或 CSS-in-JS。
2. 无障碍性是基本要求 — 确保样式支持辅助技术，而不是妨碍它们。尊重用户偏好（动画、配色方案、对比度）。
3. 性能很重要 — 尽量减少重绘，避免布局抖动，使用高效的选择器。
4. 易读胜过耍巧 — 未来的维护者（包括作者）应该一眼就能理解代码。
5. 明确胜过隐含 — 避免使用魔法数字和未说明的值。共享值应使用自定义属性。

工作流

1. 先查阅参考资料 — 编写 CSS 前，先查看 references/patterns.md 中已有的模式和代码片段。
2. 依据规范验证 — 不确定时，参考 MDN Web Docs 或 CSS 规范。
3. 提出替代方案 — 适当时，提出技能中模式之外的方案，但始终遵循上述核心原则。

编写指南

选择器

• 样式设置优先使用类选择器，而非元素选择器或 ID 选择器。
• 保持低且可预测的优先级。
• 避免深层嵌套（最多 2–3 层）。

自定义属性

• 使用 -- 前缀的自定义属性定义颜色、间距、排版和其他重复值。
• 在 :root 或适当的作用域中定义。
• 使用描述性名称：--color-primary、--spacing-md、--font-size-body。

逻辑属性

• 始终使用逻辑属性（margin-inline、padding-block、inset-inline-start、block-size 等），而非物理属性（margin-left、padding-top、left、height 等）。
• 逻辑属性会自动支持国际化和不同的书写模式。
• 仅在尚无对应逻辑属性时，才回退到物理属性。

单位

• 字体排版和间距使用 rem（遵循用户对字号的偏好）。
• 适当时使用 em 设置相对于组件的尺寸。
• 谨慎使用视口单位（vw、vh、dvh），并在需要时提供回退方案。
• 避免用 px 设置字号；边框、阴影和细节部分可以使用。

颜色

• 所有颜色函数（rgb()、hsl()、oklch()）都使用现代的空格分隔语法。
• 对于鲜艳或广色域颜色，建议使用 oklch()。
• 使用相对颜色语法，根据现有变量派生悬停状态或透明变体。
• 语法示例请参阅 references/patterns.md。

布局

• 对于二维布局，或需要纵向流动且不希望增加额外声明的布局，使用 CSS Grid。
• 对于一维对齐，使用 Flexbox，并注意其默认方向为 row。
• 避免使用浮动布局（仅用于旧式场景）。

媒体查询

• 使用现代范围语法：@media (width < 48rem)、@media (width >= 48rem)。
• 优先采用 Shared First，而非移动优先：在查询条件之外定义共享样式，并通过有界查询指定视口特定的样式。
• 尽量减少断点数量——只有明确需要时才增加断点。
• 详细示例请参阅 references/patterns.md。

无障碍性

• 切勿使用 display: none 或 visibility: hidden 隐藏应对屏幕阅读器保持可访问的内容。请使用参考资料中的适当技巧。
• 尊重 prefers-reduced-motion、prefers-color-scheme 和 prefers-contrast。
• 确保颜色对比度充足（至少达到 WCAG AA，最好达到 AAA）。
• 保持焦点指示器可见——移除 :focus 样式时，必须提供替代样式。

性能

• 避免在动画中使用开销较大的属性（优先使用 transform 和 opacity）。
• 谨慎使用 will-change，且仅在需要时使用。
• 尽量减少 * 选择器的使用。
• 在较大的代码库中管理层叠时，优先使用 @layer。

参考资料

请查阅 references/patterns.md，了解：

• 视觉隐藏工具类
• 用户偏好查询（动态效果、配色方案、对比度）
• 现代颜色语法和相对颜色
• Shared First 响应式模式
• 项目专属约定

随着添加更多模式，此文件会不断扩展。如果缺少所需模式，请提出一个符合核心原则的建议。