accelint-design-foundation

Accelint Design Foundation

使用 @accelint/design-foundation 和 @accelint/design-toolkit 进行样式设计的专家知识 —— 一套带有明确主张的 Tailwind 约定，不同于原生实现。

使用 Design Foundation 设置样式时的禁止事项

• 切勿将数字间距类作为首选 - 强烈建议优先使用语义化尺度：p-xxs、gap-m、m-l。像 p-4、gap-6 这样的数字类采用 1:1 的关系（p-1 = 1px，而不是像原生 Tailwind 那样等于 4px），但只应在实现不符合设计规范的罕见情况下使用。语义化尺度可提供设计系统的一致性。
• 切勿使用原始颜色值手动处理主题 - 避免使用 dark:bg-gray-900 或 className={theme === 'dark' ? 'bg-black' : 'bg-white'}。请使用诸如 bg-surface-default 和 fg-primary-bold 之类的语义化颜色类，它们会自动适配浅色/深色主题。
• 切勿使用边框来确定元素尺寸 - 使用 outline 而非 border 类。边框会增加元素尺寸（破坏布局），而轮廓叠加在元素上且不影响尺寸。元素应仅根据内容和内边距来确定一致的尺寸。
• 切勿使用任意 Tailwind 变体 - 像 hover:[&>svg]:opacity-50 这样的任意值会破坏设计系统。请使用受支持的 React Aria 变体或配合 clsx 进行条件类名渲染。
• 为组件设置样式时切勿绕过 CSS 层 - 使用 @layer components.l1、@layer components.l2 来实现层叠层级。绕过层会导致优先级之争，并使覆盖变得困难。
• 切勿将 primitive/domain 令牌作为首选 - 在样式中强烈建议优先使用语义化令牌（bg-surface-default、fg-primary-bold）。工具类（bg-*、fg-*、icon-*、outline-*）为超出设计系统的罕见设计情况提供了对 domain-* 和 primitive-* 令牌的访问，但这应该是例外情况。语义化令牌可提供主题灵活性和设计系统的一致性。
• 切勿使用内联 Tailwind 类为组件设置样式 - 组件样式应放在 CSS modules 中，而不是内联 className 属性中。内联仅应用于次要的一次性覆盖。使用内联类为所有组件设置样式会导致代码难以维护，并失去 CSS modules 的优势（作用域、组织性、可复用性）。
• 切勿在单个 CSS 规则中使用多个 @apply 指令 - 将所有 Tailwind 类合并到单个 @apply 语句中。多个 @apply 指令会阻止 Tailwind IDE 插件对类进行排序和识别问题。应写 @apply bg-surface-default outline-1 outline-interactive p-m; 而不是分开的 @apply 行。
• 切勿在 CSS modules 中使用属性选择器实现变体 - 使用 @variant 指令块，而不是像 [data-size="small"] 这样的属性选择器。应写 @variant size-small { @apply p-s; } 而不是 .button[data-size="small"] { @apply p-s; }。当匹配的 data 属性存在时，@variant 指令会自动应用样式。
• 切勿使用 Tailwind 的默认主题值 - Design Foundation 会移除并替换 Tailwind 的默认值。依赖默认的阴影、字体大小或颜色将会出错。只使用设计系统提供的语义化类。
• 切勿在 CSS modules 中省略 @reference 指令 - 每个 CSS module 文件都必须在顶部包含 @reference '#globals';（如果存在自定义入口点）或 @reference '@accelint/design-foundation/styles';。否则，语义化令牌和 @variant 块将未定义，导致构建错误。
• 切勿跳过 PostCSS 配置 - postcss.config.mjs 中需要 @accelint/postcss-tailwind-css-modules 插件。否则，命名分组选择器（如 group-hover/button:）和 @variant 选择器将无法在 CSS modules 中解析。
• 切勿直接从 'clsx' 包导入 clsx - 请始终从 @accelint/design-foundation/lib/utils 导入：import { clsx } from '@accelint/design-foundation/lib/utils';。Design Foundation 重新导出了 clsx，并附加了类型支持和设计系统集成。直接导入会绕过这些增强功能。

为组件设置样式前，请先自问

应用以下检查，确保样式与设计系统保持一致：

主题兼容性

• 这在浅色和深色主题下都能正常工作吗？ 使用可自动适配的语义化颜色 token。通过在 @variant light 和 @variant dark 之间切换进行测试。
• 我是否在使用原始颜色值？ 如果是，请替换为语义化 token。原始值不支持主题化。

Token 系统

• 我使用的 token 类型正确吗？ 强烈优先使用语义化 token（bg-surface-default、fg-primary-bold）。仅在设计超出系统的特殊情况下，才使用 domain-* 或 primitive-* 作为回退。
• 是否存在适用于此的语义化 token？ 先查看 token 目录。如果不存在语义化 token 且设计确实需要，回退到 domain-* 或 primitive-* 是可以接受的，但这种情况很少见。

Token 选择框架

选择 token 时，请遵循以下决策树：

1. 确定元素用途 —— 这是表面、文本、图标还是轮廓？
2. 确定层级 —— 主要、次要还是三级强调？
3. 考虑状态 —— 默认、悬停、激活还是禁用？
4. 检查状态类型 —— 信息、成功、警告还是危险？

示例：“我需要主要标题的文本颜色” → 用途：文本（fg-*） → 层级：带强调的主要（primary-bold） → 结果：fg-primary-bold

示例：“我需要交互式按钮在悬停状态下的背景色” → 用途：背景（bg-*） → 状态：交互式悬停（interactive-bold-hover） → 结果：bg-interactive-bold-hover

间距系统

• 此间距值是否存在于语义化尺度中？ 使用 xxs/xs/s/m/l/xl/xxl/oversized 尺度。如果某个值不在尺度中，请质疑它是否必要，或使用最接近的语义化值。
• 需要非标准间距值？ 数值类（p-1、m-12）按 1:1 关系生效（p-1 = 1px，而非 4px），但仅用于罕见的非规范设计情况。为保持一致性，强烈优先使用语义化尺度。

变体用法

• 这能否用 data 属性表达？ 使用 data-color="info" 搭配支持的变体，而不是任意类。
• 我是否正确覆盖了 Design Toolkit 组件？ 使用 className 或 classNames prop，而不是自定义 CSS 文件。

布局影响

• 轮廓在这里能生效，还是我需要边框？ 轮廓在大多数情况下都能生效。仅当边框必须影响布局尺寸时才需要边框。

样式实现方式

• 这应该放在 CSS 模块中还是内联？ 组件样式应放在 CSS 模块（.module.css）中。仅对次要的一次性覆盖或调整使用内联 Tailwind 类。
• 这是可复用组件还是一次性实例？ 可复用组件需要 CSS 模块。一次性实例可以使用内联类进行小幅调整。

配置验证

• PostCSS 配置正确吗？ 检查 postcss.config.mjs 中是否包含 @accelint/postcss-tailwind-css-modules 插件。没有它，命名分组和 @variant 选择器将无法在 CSS 模块中生效。
• 每个 CSS 模块都有 @reference 吗？ 每个 .module.css 文件都必须在顶部引用 '#globals'（自定义入口点）或 '@accelint/design-foundation/styles'。
• CSS 入口点是否最先导入？ 自定义 globals.css（或 design-foundation/styles）必须是根布局中的第一个导入。

配置要求

关键：设计基础需要特定的 PostCSS 和 CSS 模块配置才能正确工作。

PostCSS 配置

在项目根目录创建或更新 postcss.config.mjs：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
    '@accelint/postcss-tailwind-css-modules': {}, // Required for CSS modules
  },
};

原因： @accelint/postcss-tailwind-css-modules 插件修复了 CSS 模块选择器中的命名分组解析（例如 group-hover/button:）以及 @variant 选择器。没有它，这些选择器将无法在 CSS 模块文件中正确解析。

Package.json Imports（如果存在自定义 CSS 入口点）

如果项目为 token/工具类配置实现了自定义 CSS 入口点：

{
  "imports": {
    "#globals": "./src/styles/globals.css"
  }
}

目的： 允许 CSS 模块通过 @reference '#globals'; 引用自定义入口点。

CSS 模块引用模式

每个 CSS 模块文件都必须包含引用指令：

/* If project has custom CSS entrypoint (defined in package.json imports): */
@reference '#globals';

@layer components.l1 {
  .button {
    @apply px-m py-xs;
  }
}

/* If NO custom CSS entrypoint, reference design-foundation directly: */
@reference '@accelint/design-foundation/styles';

@layer components.l1 {
  .button {
    @apply px-m py-xs;
  }
}

原因： @reference 指令会导入设计系统的 token、工具类和变体定义。没有它，语义 token 和 @variant 块将处于未定义状态。

自定义 CSS 入口点（可选）

如果实现自定义 token 或工具类，请创建一个 CSS 入口点（例如 src/styles/globals.css）：

/* Import design foundation base */
@import "@accelint/design-foundation/styles";

/* Add custom token overrides or utilities here */
@theme {
  --custom-brand-color: #ff0000;
}

然后： 在根布局组件中将此文件作为第一个导入导入：

import './styles/globals.css'; // First import
import { ReactNode } from 'react';

export default function RootLayout({ children }: { children: ReactNode }) {
  return <html>{children}</html>;
}

如何使用

此技能使用渐进式披露来尽量减少上下文占用：

1. 从核心模式开始（SKILL.md）

遵循下方的样式模式和 token 用法，以实现一致的实现。

2. 参考 Token 目录（AGENTS.md）

加载 AGENTS.md，快速查阅可用的 token、间距比例和变体模式。

3. 按需加载详细参考

强制加载触发条件 - 在特定场景下加载这些参考：

首次设置设计基础：

• 强制：当用户说“设置设计基础”、“配置设计基础”、“安装设计基础”，或遇到诸如“undefined variable”或“@variant not found”之类的构建错误时，完整加载 references/setup.md（约 8.9K）
• 不要加载：token-reference.md、variant-system.md、spacing-scale.md、migration-guide.md

选择 token 或理解 token 层级：

• 强制：当不确定该使用哪个语义 token，或用户需要完整的 token 目录时，加载 references/token-reference.md（约 6.5K）
• 不要加载：setup.md（除非出现构建错误）、migration-guide.md（除非正在迁移）

使用 @variant 系统或组件变体：

• 强制：在实现 data attribute 变体或处理 React Aria 状态时，加载 references/variant-system.md（约 5.8K）
• 不要加载：setup.md（除非出现构建错误）、migration-guide.md（除非正在迁移）

理解间距比例或数字回退值：

• 强制：当对语义间距与数字间距感到困惑，或需要完整的间距目录时，加载 references/spacing-scale.md（约 8.5K）
• 不要加载：token-reference.md（除非同时处理颜色）、setup.md（除非出现构建错误）

从原生 Tailwind 迁移：

• 强制：在将现有 Tailwind 代码转换为设计基础约定时，加载 references/migration-guide.md（约 4.2K）
• 不要加载：其他参考，除非迁移后出现特定问题

排查构建错误或设置问题：

• 强制：当遇到诸如“undefined variable”、“@variant not found”、“group-hover/button: not working”之类的错误时，完整加载 references/setup.md
• 不要加载：其他参考，直到确认设置正常工作

样式模式

使用 CSS 模块进行组件样式设置

默认做法：在 CSS 模块中使用 @apply 指令编写组件样式。

user-card.module.css：

@layer components.l1 {
  /* ✅ Single @apply per rule - enables IDE plugin support */
  .card {
    @apply bg-surface-default outline-1 outline-interactive shadow-elevation-raised-muted p-m;
  }

  .header {
    @apply flex items-center justify-between mb-s;
  }

  .title {
    @apply fg-primary-bold text-body-l;
  }

  .content {
    @apply space-y-xs mb-m;
  }

  .email {
    @apply fg-primary-bold text-body-m;
  }

  .role {
    @apply fg-primary-muted text-body-s;
  }

  .actions {
    @apply flex gap-s;
  }
}

/* ❌ Wrong - multiple @apply directives break IDE plugins */
/*
.card {
  @apply bg-surface-default;
  @apply outline-1 outline-interactive;
  @apply shadow-elevation-raised-muted;
  @apply p-m;
}
*/

user-card.tsx：

import styles from './user-card.module.css';

export function UserCard({ name, email, role }) {
  return (
    <article className={styles.card}>
      <header className={styles.header}>
        <h3 className={styles.title}>{name}</h3>
      </header>
      <div className={styles.content}>
        <p className={styles.email}>{email}</p>
        <p className={styles.role}>{role}</p>
      </div>
    </article>
  );
}

仅在一次性覆盖时使用内联类：

// ✅ Correct - CSS module + inline override for specific instance
<UserCard className="mb-xl" /> {/* One-off spacing adjustment */}

// ❌ Wrong - all styling inline
<div className="bg-surface-default outline-1 outline-interactive shadow-elevation-raised-muted p-m">
  <h3 className="fg-primary-bold text-body-l">{name}</h3>
</div>

使用 clsx 实现条件类：

// ✅ Correct - import clsx from design foundation
import { clsx } from '@accelint/design-foundation/lib/utils';
import styles from './Button.module.css';

export function Button({ variant, isActive }) {
  return (
    <button className={clsx(styles.button, isActive && styles.active)}>
      Click me
    </button>
  );
}

// ❌ Wrong - importing directly from clsx package
import clsx from 'clsx';

Token 类别

背景 Token（bg-*）：

• bg-surface-default - 主表面（页面/卡片背景）
• bg-surface-raised - 抬升/悬浮表面
• bg-interactive-bold - 主要操作背景
• bg-info-muted - 信息消息背景
• bg-advisory-muted - 警告消息背景
• bg-critical-muted - 错误/危险消息背景
• bg-normal-muted - 成功消息背景

前景 Token（fg-*）：

• fg-primary-bold - 主要文本（标题、正文）
• fg-primary-muted - 次要文本（说明文字、次要内容）
• fg-inverse-bold - 深色/彩色背景上的文本
• fg-accent-primary-bold - 交互文本/链接
• fg-critical-bold - 错误/危险文本

轮廓 Token（outline-*）：

• outline-interactive - 交互轮廓（按钮、输入框）
• outline-static - 静态轮廓（边框、分隔线）
• outline-info-bold - 信息状态轮廓
• outline-advisory-bold - 警告状态轮廓
• outline-critical-bold - 错误/危险状态轮廓

Token 回退模式：

// ✅ Preferred - semantic tokens
<div className="bg-surface-default fg-primary-bold">Content</div>

// ⚠️  Acceptable but rare - domain/primitive fallback for edge cases
<div className="bg-domain-brand fg-primitive-blue-500">
  {/* Use only when design exceeds system */}
</div>

// ❌ Wrong - using fallbacks when semantic tokens exist
<div className="bg-primitive-neutral-100 fg-primitive-neutral-900">
  {/* Should use bg-surface-default fg-primary-bold */}
</div>

间距刻度

八级语义刻度：xxs → xs → s → m → l → xl → xxl → oversized

思考语义含义，而不是像素。m 表示“此上下文中的中等”，而不是某个具体的像素值。

CSS module 用法：

.button {
  @apply px-m py-xs; /* ✅ Semantic spacing - preferred */
}

.card {
  @apply p-m space-y-s; /* ✅ Semantic scale for consistency */
}

/* ⚠️  Acceptable but rare - numeric fallback for edge cases */
.nonStandardLayout {
  @apply p-13; /* 13px exactly - use only for non-conforming designs */
  /* Note: p-1 = 1px (not 4px like vanilla Tailwind) */
}

间距回退模式：

• 首选：使用语义刻度（p-m、gap-s、mb-l）
• 回退：数值类可用，与像素 1:1 对应（p-1 = 1px，p-12 = 12px）
• 何时使用数值：仅用于语义刻度不适用的非规范设计

轮廓与边框

优先使用轮廓 - 它们不影响元素尺寸。

/* ✅ Correct - outline doesn't impact layout */
.card {
  @apply outline-1 outline-interactive;
}

/* ❌ Wrong - border adds to dimensions */
.card {
  @apply border-2 border-gray-300;
}

仅在以下情况使用边框：

• 边框必须参与布局（表格单元格）
• 明确希望影响尺寸

变体系统

使用 data 属性实现组件变体：

Button.module.css：

@layer components.l1 {
  .button {
    @apply px-m py-xs;
  }
}

@layer components.l2 {
  /* ✅ Use @variant blocks for conditional styling */
  .button {
    @variant color-info {
      @apply bg-interactive-bold fg-inverse-bold;
    }

    @variant color-critical {
      @apply outline-2 outline-critical-bold fg-critical-bold;
    }

    @variant size-large {
      @apply px-l py-s;
    }
  }
}

/* ❌ Wrong - attribute selectors */
/*
.button[data-color="primary"] {
  @apply bg-interactive-bold;
}
*/

Button.tsx：

import styles from './Button.module.css';

export function Button({ children, color = 'primary', size = 'medium' }) {
  return (
    <button
      className={styles.button}
      data-color={color}
      data-size={size}
    >
      {children}
    </button>
  );
}

常见变体：

• data-color：info、success、warning、danger
• data-size：small、medium、large
• data-state：active、disabled、loading

CSS 层级

在 CSS module 中始终使用层级：

/* ✅ Correct - layered for predictable specificity */
@layer components.l1 {
  .base-styles { /* Base component styles */ }
}

@layer components.l2 {
  .variant-styles { /* Variant styles */ }
}

@layer components.l3 {
  .state-styles { /* State styles */ }
}

/* ❌ Wrong - no layers causes specificity issues */
.component {
  background: var(--bg-surface-default);
}

**层级顺序：**l1（基础）< l2（变体）< l3（状态）

覆盖设计工具包组件

使用 className prop 进行覆盖：

// ✅ Correct - override with inline class
<DesignToolkitButton className="mb-l">
  Action
</DesignToolkitButton>

// ✅ Correct - use classNames prop for internal elements
<DesignToolkitButton classNames={{ icon: 'icon-override' }}>
  Action
</DesignToolkitButton>

常见问题

问题：“undefined variable --bg-surface-default”

**原因：**CSS module 中缺少 @reference 指令。

**修复：**在 CSS module 文件顶部添加 @reference '#globals'; 或 @reference '@accelint/design-foundation/styles';。

/* ✅ Correct */
@reference '@accelint/design-foundation/styles';

@layer components.l1 {
  .card {
    @apply bg-surface-default; /* Now defined */
  }
}

问题：“@variant directive not recognized”

**原因：**缺少 @reference 指令，或未配置 PostCSS 插件。

**修复 1：**确认 CSS module 顶部存在 @reference 指令。

**修复 2：**检查 postcss.config.mjs 是否包含 @accelint/postcss-tailwind-css-modules 插件：

export default {
  plugins: {
    '@tailwindcss/postcss': {},
    '@accelint/postcss-tailwind-css-modules': {}, // Add this
  },
};

问题：“group-hover/button: selector not working”

**原因：**缺少 @accelint/postcss-tailwind-css-modules 插件。

**修复：**将插件添加到 postcss.config.mjs（见上文）。

问题：样式未生效 / Token 显示为原始值

**原因：**CSS 入口文件未导入，或导入过晚。

**修复：**确保 globals.css（或 @accelint/design-foundation/styles）是根布局中的第一个导入：

// ✅ Correct order
import './styles/globals.css'; // First
import './other-styles.css';
import Component from './Component';

// ❌ Wrong order
import Component from './Component';
import './styles/globals.css'; // Too late

问题：“Cannot find module '#globals'”

**原因：**缺少 package.json imports 字段，或路径不正确。

**修复：**将 imports 添加到 package.json：

{
  "imports": {
    "#globals": "./src/styles/globals.css"
  }
}

或者将 @reference 改为直接路径：

@reference './styles/globals.css';

或者直接使用 design-foundation：

@reference '@accelint/design-foundation/styles';

重要说明

• Tailwind 默认值已被移除 - 设计基础会重置 Tailwind 的默认主题。不要依赖任何默认的颜色、间距、阴影或排版值。只使用设计系统中明确定义的内容。
• 语义 token 是 CSS 变量 - 所有语义 token 都会编译为 CSS 自定义属性，例如 var(--bg-surface-default)。当工具类不够用时，可以在自定义 CSS 中使用它们，但应优先使用工具类。
• 存在 token 回退链 - 工具类（bg-*、fg-*、icon-*、outline-*）会先检查语义 token，然后回退到 domain-* 和 primitive-* token。这种回退是有意为之，用于设计超出设计系统的罕见情况，但为了保持一致性和主题化，默认应选择语义 token。
• 间距尺度是语义化的，而非像素映射 - 不要想成“m = 16px”。要想成“m = 当前语境下的中等间距”。该尺度会适应不同语境（按钮内边距 vs 区块外边距）。数字类按 1:1 关系工作（p-1 = 1px，而不是 4px），但仅作为不符合规范设计的回退。
• 主题变体使用 @ 指令 - @theme static 和 @variant light/dark 语法是自定义的。不要与标准 CSS 媒体查询混淆。主题通过根元素上的 class/attribute 应用。
• Design Toolkit 组件基于 React Aria - 它们使用 React Aria 实现无障碍。不要对抗 React Aria 的状态管理或变体。请配合 className 和 classNames props 使用。
• 设置不是可选项 - PostCSS 插件和 @reference 指令是必需的，而不是便利项。缺少设置会导致晦涩的构建错误（“undefined variable”、“@variant not found”）。在调试样式问题之前，务必先验证设置。