构建或审查组件库时如何保证按钮、输入框…

当你构建或审查组件库、设计系统或任何一组 UI 组件时，用共享设计 DNA 让所有交互组件看起来属于同一产品。

适用场景

解决思路

1. 新建组件前先审计已有组件：优先复用现成组件；若几乎合适就通过 prop 或 variant 扩展，而不是克隆（一个灵活的 Button 胜过 PrimaryButton、BigButton、CtaButton 并存）。
2. 若代码库中有接近的一次性实现，将其泛化：提升到共享库，把硬编码部分（label、颜色、尺寸）参数化为 props/tokens，去掉页面特定假设，而不是再写一个近似重复品。
3. 只有当没有现成组件可用且无法合理泛化时才新建，并且必须基于共享 DNA 构建，使其干净地加入组件家族。
4. 当某个视觉处理独立出现在 2–3 处时，应将其命名并提升为共享组件或 token，防止第四份副本出现。
5. 当不同设计时代的页面冲突时，将旧组件迁移向新组件；最新组件是当前意图的最佳证据，但弃用某样式前先确认。
6. 定义统一的 border-radius token：--radius-base 用于按钮/输入框/选择框，--radius-sm 用于复选框/小徽章，--radius-lg 用于卡片/模态框，--radius-full 用于胶囊/标签/头像芯片；同一表单中的按钮和输入框半径必须相同。
7. 嵌套圆角必须同心：外层半径 = 内层半径 + 两者间距；用 calc() 推导而非硬编码，例如卡片 padding 12px 包 8px 按钮时半径应为 calc(var(--radius-base) + var(--space-3)) = 20px。
8. 边框宽度遵循 2-Step 规则：最多两种选项（如 1px 和 4px），不要用 1px、2px、3px、4px 的递增刻度；定义 --border-width-thin 和 --border-width-thick。
9. 统一边框颜色 token：--border-color 用于静止态，--border-color-focus 用于聚焦，--border-color-error 用于错误；输入框和选择框静止态边框完全一致，聚焦和错误态在所有组件中一致。
10. 组件在同一视觉尺度共享高度和内边距：定义 --component-height-md/sm/lg、--component-padding-x-md/sm/lg、--component-padding-y-md/sm/lg；高度和文字内边距用 rem，边框和阴影用 px。
11. 并排的按钮和输入框必须高度相同；显式设置高度（用 min-height）而非由 padding 推导，避免描边变体比无边框变体高 2px、流体字号改变行盒、内容为头像或图标时固有高度不同等问题。
12. 在盒模型层面解决高度问题：使用 box-sizing: border-box，让边框被吸收进高度；无边框变体保留 border: 1px solid transparent，使内部尺寸在有边框和无边框时完全一致。
13. 用「一个类拥有整行」的方式：所有行内控件共用一个类，该类拥有盒模型、内容槽和所有状态；实例只能设置颜色，不能设置高度、内边距、字号、圆角或状态。
14. 该类必须放在框架的组件层（如 @layer components）并使用 longhand 属性，避免简写（如 border、background、padding、font、transition）重置工具类已设置的值；必须引用现有 token 而非复制其字面值。
15. 为控件内容定义统一的内容槽高度（如 .control-slot），让头像、标签、图标、计数都放在同一槽内；图标可在槽内用不同尺寸（如 16px 图标、12px 箭头）仍保持行齐平。
16. 图标的质量中心不在其盒子中心：用 alpha 通道质心测量每个图标的偏移量，将结果作为每个图标的独立偏移写入标记并注释测量依据，换图标时重新测量；不要在一组图标间共享同一个微调值。
17. 为控件类设置 cursor: pointer，因为浏览器默认给 button 是 cursor: default，Tailwind v4 preflight 也不修复；用 grep -n "cursor" node_modules/tailwindcss/preflight.css 验证。
18. 当控件边缘相接成组时，圆角应用于组而非每个子元素：外角保留 --radius-base，内部接缝变直角；合并相邻边框为一条线，避免 2px 接缝。
19. 当下拉面板从控件展开时，触发器保留顶部圆角、底部变直角，面板顶部直角、底部保留家族圆角，使展开控件读作一个更高的形状；面板边框是触发器边框的延续，宽度和颜色相同。
20. 对于包裹多个控件的共享表面（余额+头像、分段控件、输入框+附加按钮），在 wrapper 上固定高度并同时在子元素上设置，不要只靠拉伸。
21. 引入共享类后必须重新测量：用无头浏览器针对应用真实编译样式表、在两个视口宽度下读取每个控件的 getBoundingClientRect 和 getComputedStyle，比较 height、top、fontSize、padLeft；相等 height 证明盒子匹配，相等 top 证明基线一致，fontSize 或 padLeft 不同即范式不匹配。
22. 检查构建该行的每个外壳：同一工具栏通常在多处组装，屏幕上显示的可能不是你打开的那个文件；修复后无变化说明改错了文件。
23. 当工具栏需要放置非按钮项（余额、状态、头像、计数）时，用共同区域（common region）分组：默认用 2–8% 中性背景色，或边框、内阴影、渐变（最不推荐）；匹配按钮的 border-radius 和高度，只选一种处理，子元素保持朴素，wrapper 使用静态边框和分隔色避免子元素 hover 重绘整组，每组最多一个图标。
24. 凹陷表面需要三部分：渐变从上到下由深到浅、顶部内阴影、底部浅色细线；两个主题分别调参，因为同一 alpha 值在浅色主题读作微妙凹陷、在深色主题读作污迹。
25. 统一阴影逻辑：静止态无阴影或 --shadow-xs（浮动组件触发器），聚焦态用 outline 焦点环（或一致地用 box-shadow），浮层（下拉、弹出）用 --shadow-md。
26. 统一颜色角色：静止边框 --color-border，聚焦边框/环 --color-primary，错误边框 --color-error，禁用 --color-text-secondary 降低不透明度，选中/激活填充 --color-primary，hover 背景 --color-primary 8–12% 不透明度。
27. 只保留一种交互语言：一种 hover 响应、一种 active/pressed 响应、一种焦点环、一种选中处理、一种动效签名（相同缓动和时长），不要在产品内混用 3–4 种模式。
28. 确保角色在交互前可读：按钮=可点击（实心填充或明确边框、cursor: pointer、hover 响应），徽章/标签=只读（柔和填充、更小字号、绝无 hover 响应和指针光标），输入框=可编辑（边框+空内部、占位符、文本光标）；至少通过两个视觉通道区分，不能只靠颜色。
29. 用语义化 chip 组件替代通用 Badge：每种含义一个组件（Tag 用于分类标签/状态/筛选，Code 用于内联字面量/路径/键，Kbd 用于键盘快捷键，Metric 用于测量值），每个组件只编码一种含义，调用方不传颜色或形状 props。
30. chip 组件使用 em 相对内边距（如 text-[0.85em] px-[0.6em] py-[0.25em]），使其在标题、正文、说明等任意文本上下文中自动适配尺寸。
31. 将 chip 的每种语义颜色放在 CSS 类中（如 .chip-tag、.chip-code）集中在一个文件，不要内联颜色 props，以便亮/暗模式集中管理并一眼审计整个 chip 调色板。
32. 若现有调用点使用通用 Badge，将最常见的语义变体作为默认重新导出，使旧导入无需迁移即可工作。
33. 行内混排时保持同一字号和中心线：文字旁的徽章或 chip 共享周围字体大小，使用 leading-none 和 align-middle；状态指示点（红/黄/绿）垂直居中于其标注文字的大写字母高度中心而非基线。
34. 小尺寸组件保持克制：避免多层边框嵌套（边框 chip 套边框单元格套边框卡片），最多一个图标，卡片套卡片套卡片应扁平化，改用留白和标题分组。
35. 若品牌使用渐变，所有按钮变体保持一致：主按钮渐变使用与产品其他渐变相同的角度和色标，hover 时微调渐变亮度而非色相，不要某些变体用渐变、某些用纯色。
36. 用审查清单逐项检查：同表单按钮和输入框高度是否相同、高度是否显式设置、行内控件是否来自一个共享类、该类是否在组件层且用 longhand、是否引用现有 token、每个子元素是否在同一内容槽、所有状态是否定义在该类上、是否用真实样式表在多视口测量、边框宽度是否最多两种、焦点态和错误态是否一致、是否只有一种交互语言、圆角是否都来自同一基础 token、胶囊和标签是否一致用 --radius-full、按钮/徽章/输入框能否仅凭外观区分、渐变使用是否一致、新建前是否检查过现有库、新组件能否只用现有 token 加入、内联标签/状态/代码/键盘提示/度量是否为独立组件、chip 是否用 em 相对尺寸、chip 颜色是否在 CSS 类中、混排行是否共享字号和中心线、状态指示是否垂直居中、小组件是否避免嵌套边框、小组件是否最多一个图标、卡片嵌套是否已扁平化。

适用边界 · 注意事项

• 当项目只有单个页面或极少量组件、不存在组件库或设计系统时，过度建立 token 体系可能得不偿失。
• 当产品有意采用多种视觉风格（如营销页与后台管理区刻意区分）时，不应强行统一所有组件。
• 当团队尚未确定品牌方向或正在快速原型探索阶段时，过早固化 token 会限制迭代。