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,但不应借此重写组件的核心尺寸和状态语义。

tsx
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>
  );
}

预期结果

text
页面显示三个高度一致的按钮:蓝色“保存”、白底描边“取消”和禁用的红色“删除”。使用 Tab 聚焦时出现清晰焦点环,禁用按钮降低透明度且不响应点击。

变体名称应表达用途而不是具体颜色。danger 可以在未来更换色值而不影响调用代码;若业务直接传入 red,视觉实现就会泄漏到组件接口中。

统一状态与响应式规则

交互状态建议按默认、hover、focus-visible、active、disabled 的顺序设计,并保证键盘焦点不是悬停样式的附属品。禁用状态还应通过原生 disabled 属性阻止交互,而不是只降低透明度。

响应式规则遵循移动优先:无前缀类定义最小视口,只有布局确实需要变化时再增加 sm:、md: 或更大断点。组件内部负责自身尺寸变化,页面容器负责排列方式,避免两层同时控制同一属性。

用评审清单维持一致性

每次新增组件或变体时,检查参数是否有明确语义、基础规则是否被重复、状态是否覆盖键盘与禁用场景、响应式覆盖是否从小屏开始。调用方若连续多次追加相同 className,通常说明它应升级为正式变体。

规范还应保留一个受控逃生口。className 适合补充页面上下文中的外边距或宽度,但不适合长期覆盖颜色、圆角和焦点规则;后者应回到组件定义中统一修改。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立组件样式规范

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通