该规范用于指导使用 Tailwind CSS 4 主题令牌和获批的工具类模式为 Canvas 组件编写样式，适用于创建新组件、为组件添加颜色或样式等场景。
技术栈：样式使用 Tailwind CSS 4.1+；组件变体使用 class-variance-authority（CVA）；类名合并通过 cn() 实现（基于 clsx 与 tailwind-merge）。规范要求仅使用这些依赖进行样式处理，不得添加第三方 CSS 库或创建新的样式工具。
样式约定：使用 global.css 中定义的 Tailwind 主题颜色（primary-、gray-）；避免硬编码颜色值，改用主题令牌；遵循示例中已有的 focus、hover、active 状态模式。
cn() 工具：用于合并 Tailwind 类，结合 clsx 处理条件类与 tailwind-merge 解决冲突工具类。可从 "@/lib/utils" 或 "drupal-canvas" 导入。示例：const Button = ({ variant, className, children }) => (<button className={cn("rounded px-4 py-2", variant === "primary" && "bg-primary-600 text-white", variant === "secondary" && "bg-gray-200 text-gray-800", className)}>{children}</button>);
className 属性：每个组件应接受 className 属性以允许样式覆盖，将其作为最后一个参数传给 cn() 使调用方类优先。className 是实现/组合属性，而非编辑器属性，不要加入 component.yml，不要标记为必填，也不要在 Canvas 元数据中暴露。示例：const Card = ({ colorScheme, className, children }) => (<div className={cn(cardVariants({ colorScheme }), className)}>{children}</div>);
Tailwind 4 主题变量：Canvas 项目使用 Tailwind CSS 4 的 @theme 指令在 global.css 中定义设计令牌，@theme { } 内定义的变量会自动成为可用的 Tailwind 工具类。应始终检查 global.css 中可用的设计令牌，@theme 块是颜色、字体、断点等设计令牌的唯一来源。
主题变量与工具类的映射：在 @theme 中定义 CSS 变量后，Tailwind 4 会根据变量命名空间前缀自动生成对应工具类。模式为 --{namespace}-{name} 变成 {utility}-{name}。示例：--color-primary-600: #xxx 生成 bg-primary-600、text-primary-600、border-primary-600；--font-sans 生成 font-sans；--breakpoint-md: 48rem 生成 md: 响应式前缀。正确用法：<button className="bg-primary-600 hover:bg-primary-700 text-white">Click me</button>；错误用法：<button className="bg-[#1899cb] text-white hover:bg-[#1487b4]">Click me</button>。任意值（如 bg-[#xxx]）可接受用于极少一次性场景；但若颜色出现在多处或代表品牌/设计系统值，应加入 @theme。
语义别名：主题变量可引用其他变量创建语义别名，如 --color-primary-dark: var(--color-primary-700);，bg-primary-700 与 bg-primary-dark 均可用。当语义别名更好表达意图时使用。
添加或更新主题变量：当设计需要主题中尚未定义的颜色、字体或其他值时，应将其加入 global.css 的 @theme 块，而非在组件中硬编码。添加新变量的时机：设计引入新品牌色或色阶、需要现有值的语义别名、设计重复使用特定间距/字体/断点值。更新现有变量的时机：品牌色变化、设计令牌需全系统调整。示例：@theme { --color-primary-600: #1899cb; --color-success: #22c55e; --color-success-dark: #16a34a; }。添加后即可使用 bg-success、text-success-dark 等。应保持主题组织有序，用注释分组说明用途，遵循 global.css 现有命名约定（如 primary-100 至 primary-900 编号色阶、primary-dark 等语义名称）。
颜色属性必须使用变体而非颜色代码：绝不创建允许用户传入颜色代码（十六进制、RGB、HSL 或任何原始颜色字符串）的属性。应使用 CVA 定义一小组人类可读的变体，映射到 global.css 中的设计令牌。应始终检查 global.css 中可用的设计令牌，其中的令牌（如 primary-、gray-）是颜色值的唯一来源。错误做法：props: properties: backgroundColor: title: Background Color, type: string, examples: - "#3b82f6"；或 const Card = ({ backgroundColor }) => (<div style={{ backgroundColor }}>{/* ... */}</div>)。正确做法：props: properties: colorScheme: title: Color Scheme, type: string, enum: - default - primary - muted - dark, meta:enum: default: Default (White), primary: Primary (Blue), muted: Muted (Light Gray), dark: Dark, examples: - default；const cardVariants = cva("rounded-lg p-6", { variants: { colorScheme: { default: "bg-white text-black", primary: "bg-primary-600 text-white", muted: "bg-gray-100 text-gray-700", dark: "bg-gray-900 text-white" } }, defaultVariants: { colorScheme: "default" } }); const Card = ({ colorScheme, children }) => (<div className={cardVariants({ colorScheme })}>{children}</div>); 此方法确保设计系统颜色一致、用户从精选有意义选项中选择、通过修改 global.css 令牌轻松更新主题、以及经过测试的颜色组合带来更好可访问性。