ui-ux-pro-max-skill 设计系统组件规格完全指南Button、Input、Card 等七大组件的变体、尺寸与状态规范落地【免费下载链接】ui-ux-pro-max-skillAn AI skill that provides design intelligence for building professional UI/UX across multiple platforms.项目地址: https://gitcode.com/gh_mirrors/ui/ui-ux-pro-max-skill本篇指南围绕 ui-ux-pro-max-skill 开源仓库中 design-system 技能 的组件规格文档component-specs.md展开完整解读 Button、Input、Card、Badge、Alert、Dialog、Table 七大核心组件的变体Variants、尺寸Sizes、状态States与解剖结构Anatomy规范并结合仓库中的三层 Token 架构、状态模式文档与 Tailwind 集成脚本讲清楚规格如何落地为可复用的设计 Token 与 CSS 变量。读完本文你将掌握一套可直接复制到项目中的组件规范表、对应 CSS 变量实现以及生成与校验 Token 的命令行工作流。一、组件规格在 design-system 技能中的位置在 ui-ux-pro-max-skill 中design-system技能承担设计 Token 架构、组件规格定义、系统化设计与幻灯片生成四类职责见 SKILL.md。组件规格文档 component-specs.md 是其中的核心参考之一它回答一个关键问题一个组件在界面上到底长什么样、有多少种用法、每个交互时刻如何变化。该技能的全部参考资料形成了一个闭环参考文档作用token-architecture.md三层 Token 总体架构Primitive → Semantic → Componentprimitive-tokens.md原始值颜色阶、间距、字号、圆角、阴影、动效、z-indexsemantic-tokens.md语义别名primary、muted、destructive 等支持暗黑模式component-tokens.md组件级 Token--button-bg、--input-border等component-specs.md本文主体组件的变体 / 尺寸 / 状态 / 解剖结构规格states-and-variants.md交互状态与变体的通用模式、无障碍要求tailwind-integration.mdToken 到 Tailwind / shadcn/ui 的映射从源码结构看三者的依赖关系是组件规格定义要什么变体、尺寸、状态Component Tokens 定义用什么变量实现--button-bg等Primitive/Semantic Tokens 定义变量的值从哪来var(--color-primary)→var(--color-blue-600)→#2563EB。这正是规范可被机器执行的关键——规格表里的每一行都能在 CSS 变量层找到一一对应。二、Button从 6 种变体到完整状态机Button 是组件规格中信息量最大的一项其规范覆盖变体、尺寸、状态、解剖结构四个维度。2.1 变体Variants变体背景文字边框使用场景defaultprimarywhitenone主要操作Primary actionssecondarygray-100gray-900none次要操作Secondary actionsoutlinetransparentforegroundborder三级操作Tertiary actionsghosttransparentforegroundnone弱化操作Subtle actionslinktransparentprimarynone导航Navigationdestructivered-600whitenone危险操作Dangerous actions设计意图清晰操作重要性越高背景填充越实。从 default 到 ghost 是一条实底 → 描边 → 透明的降级链路destructive 用红色阶red-600单独隔离危险语义避免与主操作混淆。在 Token 层这 6 种变体对应 component-tokens.md 中 Button 的一组变量:root { /* Default (Primary) */ --button-bg: var(--color-primary); --button-fg: var(--color-primary-foreground); --button-hover-bg: var(--color-primary-hover); --button-active-bg: var(--color-primary-active); /* Secondary */ --button-secondary-bg: var(--color-secondary); --button-secondary-fg: var(--color-secondary-foreground); /* Outline */ --button-outline-border: var(--color-border); --button-outline-fg: var(--color-foreground); --button-outline-hover-bg: var(--color-accent); /* Ghost */ --button-ghost-fg: var(--color-foreground); --button-ghost-hover-bg: var(--color-accent); /* Destructive */ --button-destructive-bg: var(--color-destructive); --button-destructive-fg: var(--color-destructive-foreground); }注意 outline/ghost 的 hover 都落到--color-accent语义层中为 gray-100这保证了弱操作悬停时轻量提亮、不喧宾夺主的视觉一致。2.2 尺寸Sizes尺寸高度水平内边距垂直内边距字号图标尺寸sm32px12px6px14px16pxdefault40px16px8px14px18pxlg48px24px12px16px20pxicon40px00-18px尺寸体系建立在 4px 基础网格之上参考 primitive-tokens.md 的--space-*变量32/40/48 是 4px 的整数倍12/16/24px 内边距分别对应--space-3/--space-4/--space-6。icon 尺寸专门服务纯图标按钮高度与 default 一致40px以保证相邻排列时的对齐。对应 Token:root { --button-padding-x: var(--space-4); --button-padding-y: var(--space-2); --button-padding-x-sm: var(--space-3); --button-padding-y-sm: var(--space-1-5); --button-padding-x-lg: var(--space-6); --button-padding-y-lg: var(--space-3); --button-radius: var(--radius-md); --button-font-size: var(--font-size-sm); --button-font-weight: var(--font-weight-medium); }2.3 状态States状态背景文字不透明度光标defaulttokentoken1pointerhoverdarkertoken1pointeractivedarkesttoken1pointerfocustokentoken1pointerdisabledmutedmuted-fg0.5not-allowedloadingtokentoken0.7wait状态表中背景列使用token/darker/darkest这类相对描述词表示状态在变体基色上做明度递进hover 更深一档、active 最深而不是写死具体色值——这正是 Token 化设计的核心状态由语义驱动颜色由 Token 解析。在 semantic-tokens.md 中可看到实现--color-primary-hover: var(--color-blue-700)、--color-primary-active: var(--color-blue-800)即 hover/active 是同一色阶上的明度爬升。disabled 与 loading 是两条特殊状态disabled 降为 50% 不透明度并禁用指针cursor: not-allowedloading 保持 70% 不透明度内容加 spinner 占位并显示wait光标。两者不可点击pointer-events: none详见 states-and-variants.md。2.4 解剖结构Anatomy┌─────────────────────────────────────┐ │ [icon] Label Text [icon] │ └─────────────────────────────────────┘ ↑ ↑ leading icon trailing iconButton 内容区由可选的前导图标、标签文本、尾部图标三段组成。spinner加载时的推荐位置是替换图标或居中见 states-and-variants.md 的加载状态表。三、Input文本输入的全谱系3.1 变体Variants变体描述default标准文本输入textarea多行文本select下拉选择checkbox布尔开关radio单选switch切换开关Input 变体实际上覆盖了文本类、选择类、开关类三类控件规格文档统一用同一套尺寸与状态体系约束它们从而保证表单视觉的一致性。3.2 尺寸Sizes尺寸高度内边距字号sm32px8px 12px14pxdefault40px8px 12px14pxlg48px12px 16px16px与 Button 对齐sm/default/lg 同样为 32/40/48px 三档横向内边距对应--input-padding-x: var(--space-3)12px、--input-padding-y: var(--space-2)8px字号默认 14px--font-size-smlg 升到 16px。3.3 状态States状态边框背景环Ringdefaultgray-300whitenonehovergray-400whitenonefocusprimarywhiteprimary/20%errorred-500whitered/20%disabledgray-200gray-100noneInput 状态的设计要点focus 双保险边框切换到 primary 色的同时叠加primary/20%的焦点环视觉锚点明确error 与 focus 区分错误态边框为 red-500、焦点环为red/20%即便输入框获得焦点也通过红色语义提示校验失败而不是被主色掩盖disabled 整体降级背景 gray-100、边框 gray-200与可用态形成明确对比。对应 Tokencomponent-tokens.md:root { --input-bg: var(--color-background); --input-border: var(--color-input); --input-fg: var(--color-foreground); --input-placeholder: var(--color-muted-foreground); --input-focus-border: var(--color-ring); --input-focus-ring: var(--color-ring); --input-error-border: var(--color-error); --input-error-fg: var(--color-error); --input-disabled-bg: var(--color-muted); --input-disabled-fg: var(--color-muted-foreground); --input-padding-x: var(--space-3); --input-padding-y: var(--space-2); --input-radius: var(--radius-md); --input-font-size: var(--font-size-sm); }3.4 解剖结构AnatomyLabel (optional) ┌─────────────────────────────────────┐ │ [icon] Placeholder/Value [action] │ └─────────────────────────────────────┘ Helper text or error messageInput 结构包含可选的 Label、前导图标、占位符/值、尾部操作action如清除按钮、密码可见性切换以及下方的辅助文本或错误消息。错误消息的规范位置就在输入框正下方使用错误色并建议带图标以服务无障碍详见 states-and-variants.md 的错误状态章节。四、Card容器类组件的层次表达4.1 变体Variants变体阴影边框使用场景defaultsm1px标准卡片elevatedlgnone突出内容outlinenone1px弱化容器interactivesm→md1px可点击卡片Card 变体用阴影 边框的组合表达层次default 用细边框 小阴影做标准内容块elevated 去掉边框、改用 lg 大阴影实现悬浮突出outline 只用 1px 边框做最弱的容器划分interactive 则在悬停时阴影从 sm 过渡到 md用光影变化暗示可点击。对应 Token:root { --card-bg: var(--color-card); --card-fg: var(--color-card-foreground); --card-border: var(--color-border); --card-shadow: var(--shadow-default); --card-shadow-hover: var(--shadow-md); --card-padding: var(--space-6); --card-gap: var(--space-4); --card-radius: var(--radius-lg); }4.2 解剖结构与间距┌─────────────────────────────────────┐ │ Card Header │ │ Title │ │ Description │ ├─────────────────────────────────────┤ │ Card Content │ │ Main content area │ │ │ ├─────────────────────────────────────┤ │ Card Footer │ │ Actions │ └─────────────────────────────────────┘区域内边距header24px 24px 0content24pxfooter0 24px 24px区域间距 gap16pxCard 三段式结构Header / Content / Footer的内边距全部是 24px--space-6的变体header 去掉底部内边距、footer 去掉顶部内边距从而让区域间以 16px--card-gap: var(--space-4)的自然间距衔接而不是叠加双倍 padding。五、Badge轻量标签的 6 变体 3 尺寸5.1 变体Variants变体背景文字defaultprimarywhitesecondarygray-100gray-900outlinetransparentforegrounddestructivered-600whitesuccessgreen-600whitewarningyellow-500gray-900Badge 在 default/secondary/outline 之外额外引入了 successgreen-600、warningyellow-500两个语义变体。注意 warning 的文字色是 gray-900 而非白色——这是为了保证黄色底上的对比度黄色明度高白字对比不足与 states-and-variants.md 中正常文本对比度不低于 4.5:1的要求一致。对应 Token:root { --badge-bg: var(--color-primary); --badge-fg: var(--color-primary-foreground); --badge-secondary-bg: var(--color-secondary); --badge-secondary-fg: var(--color-secondary-foreground); --badge-outline-border: var(--color-border); --badge-outline-fg: var(--color-foreground); --badge-destructive-bg: var(--color-destructive); --badge-destructive-fg: var(--color-destructive-foreground); --badge-padding-x: var(--space-2-5); --badge-padding-y: var(--space-0-5); --badge-radius: var(--radius-full); --badge-font-size: var(--font-size-xs); }5.2 尺寸Sizes尺寸内边距字号高度sm4px 8px11px20pxdefault4px 10px12px24pxlg6px 12px14px28pxBadge 使用全圆角--radius-full胶囊造型字号使用 xs12px档甚至更小的 11px高度随内边距自然增长20/24/28px。六、Alert反馈信息的语义化表达6.1 变体Variants变体图标背景边框defaultinfogray-50gray-200destructivealertred-50red-200successcheckgreen-50green-200warningwarningyellow-50yellow-200Alert 是色彩语义化最典型的组件四个变体共享同一种布局仅通过图标、浅色背景与同色系边框区分语义。背景统一使用 50 级浅色red-50/green-50/yellow-50文字仍用前景色保证可读性这与 Badge 使用 600 级深色实底形成互补——Alert 需要大段可读文本因此用浅底深字而非深底白字。6.2 解剖结构Anatomy┌─────────────────────────────────────┐ │ [icon] Title [×]│ │ Description text │ └─────────────────────────────────────┘结构包括语义图标、标题、描述文本与可选的关闭按钮×。错误类提示应搭配rolealert供屏幕阅读器即时播报见 states-and-variants.md 的 ARIA 示例。对应 Token:root { --alert-bg: var(--color-background); --alert-fg: var(--color-foreground); --alert-border: var(--color-border); --alert-destructive-bg: var(--color-destructive); --alert-destructive-fg: var(--color-destructive-foreground); --alert-padding: var(--space-4); --alert-radius: var(--radius-lg); }七、Dialog五种尺寸的模态层级7.1 尺寸Sizes尺寸最大宽度使用场景sm384px简单确认default512px标准对话框lg640px复杂表单xl768px数据密集型对话框full100% - 32px移动端全屏Dialog 的五档尺寸对应从轻确认到重数据的递进sm 只承载一句话确认xl 用于表格/明细类内容full 在移动端占满屏幕两侧各留 16px。默认最大宽度 512px 对应 Token 中的--dialog-max-width: 32rem。7.2 解剖结构Anatomy┌───────────────────────────────────────┐ │ Dialog Header [×]│ │ Title │ │ Description │ ├───────────────────────────────────────┤ │ Dialog Content │ │ Scrollable if needed │ │ │ ├───────────────────────────────────────┤ │ Dialog Footer │ │ [Cancel] [Confirm]│ └───────────────────────────────────────┘结构含遮罩overlay、Header标题 描述 关闭按钮、可滚动的 Content、Footer操作区取消在左、确认在右。Dialog 相关 Token 特别定义了遮罩层的透明度:root { --dialog-overlay-bg: rgb(0 0 0 / 0.5); --dialog-bg: var(--color-background); --dialog-fg: var(--color-foreground); --dialog-border: var(--color-border); --dialog-shadow: var(--shadow-lg); --dialog-padding: var(--space-6); --dialog-radius: var(--radius-lg); --dialog-max-width: 32rem; }从 z-index 体系看primitive-tokens.mdModal 类浮层应使用--z-modal: 1200与 dropdown1000、popover1300、tooltip1400构成完整的浮层层级。八、Table数据展示的行状态与对齐规则8.1 行状态Row States状态背景使用场景defaultwhite普通行hovergray-50鼠标悬停selectedprimary/10%选中行stripedgray-50/white斑马纹交替Table 行状态用背景色 透明主色表达hover 用 gray-50 轻量提亮selected 用primary/10%10% 透明度的主色区分选中与悬停striped 用于长列表的视觉分组。对应 Token:root { --table-header-bg: var(--color-muted); --table-header-fg: var(--color-muted-foreground); --table-row-bg: var(--color-background); --table-row-hover-bg: var(--color-muted); --table-row-fg: var(--color-foreground); --table-border: var(--color-border); --table-cell-padding-x: var(--space-4); --table-cell-padding-y: var(--space-3); }8.2 单元格对齐Cell Alignment内容类型对齐方式文本左对齐数字右对齐状态/徽标居中操作右对齐对齐规则是表格可读性的关键文本左对齐符合阅读习惯数字右对齐便于纵向比较位数状态/徽标居中让状态列视觉整齐操作列右对齐贴近行尾便于点击。8.3 间距Spacing元素数值单元格内边距12px 16px表头内边距12px 16px行高紧凑40px行高默认48px行高舒适56px行高提供 compact / default / comfortable 三档40/48/56px分别对应数据密集、标准、宽松阅读三种场景配合 8.1 的行状态即可覆盖绝大多数数据表格需求。九、状态与变体的统一模式规格背后的通用规律在七个组件的规格之上states-and-variants.md 抽象出了跨组件通用的规则这才是规格可维护的根本1. 状态优先级当多个状态同时存在时按disabled loading active focus hover default决定最终表现。例如禁用中的按钮即使被 hover也必须显示禁用样式。2. 状态过渡颜色/背景类变化统一 150msease-in-outtransform/shadow 类变化 200msease-out对应 Token 中的--duration-fast: 150ms、--duration-normal: 200ms。3. 焦点环规格标准焦点环为 2px 主色环 2px 背景色偏移--ring-width: 2px; --ring-offset: 2px; --ring-color: var(--color-ring)实现时优先使用:focus-visible而非:focus避免鼠标点击也触发焦点环.focusable:focus-visible { outline: none; box-shadow: 0 0 0 var(--ring-offset) var(--color-background), 0 0 0 calc(var(--ring-offset) var(--ring-width)) var(--ring-color); }4. 变体实现模式颜色变体通过在组件根节点重写--component-bg/--component-fg两个局部变量实现尺寸变体通过重写--component-height/--component-padding/--component-font实现。这意味着新增一个变体只需新增一组变量赋值无需重写组件样式。5. 无障碍底线普通文本对比度 ≥ 4.5:1、大号文本/UI 组件/焦点指示 ≥ 3:1状态不得只依赖颜色表达需辅以图标、文本或图案禁用元素用aria-disabledtrue加载用aria-busytrue错误输入用aria-invalidtrue配合rolealert。十、规格到代码的落地CSS 变量与 Tailwind 集成规格表是设计契约最终要翻译成工程代码。仓库提供了两条落地路径路径一纯 CSS 变量。把第七节之前展示的组件级 Token--button-bg、--input-border等写入:root组件样式全部引用var()。这也是 SKILL.md 的硬性最佳实践Never use raw hex in components - always reference tokens组件中绝不使用裸 hex 值一律引用 Token。路径二Tailwind / shadcn 集成。tailwind-integration.md 给出了完整的映射方案CSS 变量以空格分隔的 HSL格式存储如--primary: 217 91% 60%从而获得 Tailwind 原生的透明度修饰能力div classNamebg-primary/50 // 50% 透明度 div classNametext-primary/80 // 80% 透明度 // 输出: background-color: hsl(217 91% 60% / 0.5);tailwind.config.ts中把语义变量映射为 Tailwind 颜色colors: { background: hsl(var(--background)), foreground: hsl(var(--foreground)), primary: { DEFAULT: hsl(var(--primary)), foreground: hsl(var(--primary-foreground)), }, // secondary / muted / accent / destructive / border / input / ring / card ... }, borderRadius: { lg: var(--radius), md: calc(var(--radius) - 2px), sm: calc(var(--radius) - 4px), },组件类示例与 2.1 的规格一一对应.btn-default { apply bg-primary text-primary-foreground hover:bg-primary/90; } .btn-secondary { apply bg-secondary text-secondary-foreground hover:bg-secondary/80; } .btn-outline { apply border border-input bg-background hover:bg-accent hover:text-accent-foreground; } .btn-ghost { apply hover:bg-accent hover:text-accent-foreground; } .btn-destructive { apply bg-destructive text-destructive-foreground hover:bg-destructive/90; } .btn-sm { apply h-8 px-3 text-xs; } /* 32px 高对应 sm 尺寸 */ .btn-md { apply h-10 px-4 text-sm; } /* 40px 高对应 default 尺寸 */ .btn-lg { apply h-12 px-6 text-base; } /* 48px 高对应 lg 尺寸 */由于该配置与 shadcn/ui 采用相同的变量命名、相同的 HSL 格式与相同的色阶结构可以直接兼容npx shadcnlatest add button card input等命令让 shadcn 组件自动消费这套 Token。十一、工具链生成与校验组件 Token规格与 Token 的维护由两个 Node 脚本支撑见 SKILL.md 的脚本表# 从 JSON Token 配置生成 CSS 变量文件 node scripts/generate-tokens.cjs --config tokens.json -o tokens.css # 校验代码中是否存在硬编码色值应一律使用 Token node scripts/validate-tokens.cjs --dir src/其中 validate-tokens.cjs 用于扫描指定目录揪出违反组件中不使用裸 hex 值规则的代码配套的 Python 测试 test_validate_tokens.py 覆盖了校验器的核心逻辑。仓库还提供了模板 design-tokens-starter.json内含三层 Token 结构可作为新项目引入这套组件规格的起点。典型工作流依据本文的组件规格表确定需要的变体与状态在tokens.json中按 Primitive → Semantic → Component 三层定义变量值运行generate-tokens.cjs产出tokens.css组件样式引用var(--xxx)并通过validate-tokens.cjs防止硬编码回潮需要 Tailwind 时按第十节的映射生成tailwind.config.ts。十二、最佳实践总结综合组件规格文档与仓库配套资料落地这套组件体系时有几条核心纪律组件内禁止裸色值所有颜色、间距、字号一律走 Token 引用var()否则暗黑模式切换与主题换肤会失效语义层是主题开关暗黑模式只需覆盖语义变量.dark { --color-background: ... }组件层零改动即可完成明暗切换组件 Token 提供定制点想要某个组件局部差异化如圆角更小只改对应组件级变量不动全局语义HSL 优于 HEX使用空格分隔的 HSL 格式存储才能获得 Tailwind 的透明度修饰能力bg-primary/50状态表达不依赖单一通道颜色、图标、文字、ARIA 属性多通道协同满足对比度与屏幕阅读器要求每个 Token 都要有用途说明规格表本身就是最好的文档让 Token 与规格一一对应避免孤儿变量。这套规格表 三层 Token 生成/校验脚本的组合正是 ui-ux-pro-max-skill 中 design-system 技能的核心价值让组件规范从文档走向可执行、可校验、可换肤的工程资产。读者可以直接以 component-specs.md 为基准表、以 component-tokens.md 为变量清单在自己的项目中复现这套组件体系。【免费下载链接】ui-ux-pro-max-skillAn AI skill that provides design intelligence for building professional UI/UX across multiple platforms.项目地址: https://gitcode.com/gh_mirrors/ui/ui-ux-pro-max-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考