HTML / CSS / 系统课时
建立组件样式规范
建立组件样式规范
本课把零散的工具类用法整理为可执行的组件规范,统一类名组织、尺寸与视觉变体、交互状态和响应式边界。完成后,同类组件能够保持一致,同时仍保留明确的扩展入口。
学习目标
- 制定可评审、可复用的类名组织顺序。
- 用稳定基础样式和有限变体表达组件差异。
- 统一交互状态、响应式覆盖和自定义扩展边界。
把规范写成可执行约定
样式规范不能只写“保持统一”,而要明确谁负责什么。基础层负责结构与可访问状态,尺寸层负责高度和内边距,变体层负责颜色与边框,调用方只传语义化参数,不直接复制整串类名。

这套分工会减少两类漂移:一类是多个页面各自调整圆角、间距和焦点样式;另一类是调用方用临时类名覆盖组件内部规则,导致同名变体表现不一致。
固定类名组织顺序
Tailwind 对大多数工具类没有阅读顺序要求,但团队需要稳定的书写顺序。建议按“布局与定位 → 尺寸与间距 → 边框与背景 → 文字 → 阴影与过渡 → 交互状态 → 响应式与主题覆盖”排列。
| 分组 | 负责内容 | 示例 |
|---|---|---|
| 结构 | display、对齐、定位 | inline-flex items-center justify-center |
| 盒模型 | 高宽、内外边距 | h-10 px-4 |
| 外观 | 圆角、边框、背景、文字 | rounded-lg bg-sky-600 text-white |
| 效果 | 阴影、过渡、变换 | shadow-sm transition-colors |
| 状态 | hover、focus、disabled | hover:bg-sky-700 disabled:opacity-50 |
| 覆盖 | 断点、暗色或容器条件 | md:px-5 dark:bg-sky-500 |
顺序的目标是降低审查成本,而不是改变 CSS 优先级。出现冲突时,应先确认变体职责和覆盖条件,不要依赖移动某个类名的位置来“修复”结果。
用组件变体收口差异
下面的 React 与 TypeScript 示例把稳定规则集中到 base,把尺寸和视觉差异限制为联合类型。调用方可以追加少量 className,但不应借此重写组件的核心尺寸和状态语义。
import type {
ButtonHTMLAttributes,
PropsWithChildren,
} from "react";
type ButtonVariant = "primary" | "secondary" | "danger";
type ButtonSize = "sm" | "md";
type ButtonProps = PropsWithChildren<
ButtonHTMLAttributes<HTMLButtonElement> & {
variant?: ButtonVariant;
size?: ButtonSize;
fullWidth?: boolean;
}
>;
const base = [
"inline-flex items-center justify-center rounded-lg font-medium",
"transition-colors focus-visible:outline-none focus-visible:ring-2",
"focus-visible:ring-sky-500 focus-visible:ring-offset-2",
"disabled:pointer-events-none disabled:opacity-50",
].join(" ");
const variants: Record<ButtonVariant, string> = {
primary: "bg-sky-600 text-white hover:bg-sky-700",
secondary:
"border border-slate-300 bg-white text-slate-900 hover:bg-slate-50",
danger: "bg-rose-600 text-white hover:bg-rose-700",
};
const sizes: Record<ButtonSize, string> = {
sm: "h-8 px-3 text-sm",
md: "h-10 px-4 text-sm",
};
export function Button({
variant = "primary",
size = "md",
fullWidth = false,
className = "",
children,
...props
}: ButtonProps) {
// 每个维度只贡献自己负责的类名,避免变体之间互相覆盖。
const classes = [
base,
sizes[size],
variants[variant],
fullWidth && "w-full",
className,
]
.filter(Boolean)
.join(" ");
return (
<button className={classes} {...props}>
{children}
</button>
);
}
export default function App() {
return (
<div className="flex flex-wrap gap-3 p-6">
<Button>保存</Button>
<Button variant="secondary">取消</Button>
<Button variant="danger" disabled>
删除
</Button>
</div>
);
}预期结果
页面显示三个高度一致的按钮:蓝色“保存”、白底描边“取消”和禁用的红色“删除”。使用 Tab 聚焦时出现清晰焦点环,禁用按钮降低透明度且不响应点击。变体名称应表达用途而不是具体颜色。danger 可以在未来更换色值而不影响调用代码;若业务直接传入 red,视觉实现就会泄漏到组件接口中。
统一状态与响应式规则
交互状态建议按默认、hover、focus-visible、active、disabled 的顺序设计,并保证键盘焦点不是悬停样式的附属品。禁用状态还应通过原生 disabled 属性阻止交互,而不是只降低透明度。
响应式规则遵循移动优先:无前缀类定义最小视口,只有布局确实需要变化时再增加 sm:、md: 或更大断点。组件内部负责自身尺寸变化,页面容器负责排列方式,避免两层同时控制同一属性。
用评审清单维持一致性
每次新增组件或变体时,检查参数是否有明确语义、基础规则是否被重复、状态是否覆盖键盘与禁用场景、响应式覆盖是否从小屏开始。调用方若连续多次追加相同 className,通常说明它应升级为正式变体。
规范还应保留一个受控逃生口。className 适合补充页面上下文中的外边距或宽度,但不适合长期覆盖颜色、圆角和焦点规则;后者应回到组件定义中统一修改。