mcpField
D
design-system

design-system

github.com/community-access设计与 UI431259 次安装1 天前更新
代码仓库

关于 design-system

供设计系统审查使用的无障碍参考资料，供 design-system-auditor.agent.md 使用。内容涵盖设计令牌对比度计算、焦点环要求、框架令牌路径及间距审计相关检查。

主要功能

  1. 01WCAG 对比度计算参考
  2. 02文本与 UI 对比度阈值
  3. 03常见设计令牌路径
  4. 04焦点环合规检查项
  5. 05令牌风险与修正示例

适用场景

  1. 01审查设计令牌的颜色对比度
  2. 02检查焦点指示器是否符合要求
  3. 03定位常见框架中的颜色令牌

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/community-access/accessibility-agents --skill design-system

安装后在 Claude Code 中输入/design-system确认已加载。

详细介绍

设计系统无障碍技能

此技能提供设计令牌对比度验证、焦点环合规性和间距审计的参考数据。供 design-system-auditor.agent.md 使用。

WCAG 对比度 - 计算参考

步骤 1：线性化 sRGB 通道
c = C / 255
c_lin = c / 12.92              if c <= 0.04045
c_lin = ((c + 0.055) / 1.055)^2.4   otherwise
步骤 2：相对亮度
L = 0.2126 * R_lin + 0.7152 * G_lin + 0.0722 * B_lin
步骤 3：对比度
ratio = (L_lighter + 0.05) / (L_darker + 0.05)
JavaScript 快速实现
function relativeLuminance(hex) {
  const c = hex.replace('#', '').match(/.{2}/g)
    .map(h => parseInt(h, 16) / 255)
    .map(c => c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4));
  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
}

function contrastRatio(hex1, hex2) {
  const L1 = relativeLuminance(hex1);
  const L2 = relativeLuminance(hex2);
  const lighter = Math.max(L1, L2);
  const darker = Math.min(L1, L2);
  return (lighter + 0.05) / (darker + 0.05);
}

// Example
contrastRatio('#6B7280', '#FFFFFF'); // 5.74:1 - PASSES AA (was a common misconception)
contrastRatio('#9CA3AF', '#FFFFFF'); // 2.85:1 - FAILS AA
HSL 转 Hex（用于 CSS 变量令牌）

许多设计系统会以 HSL 三元组存储颜色（例如 shadcn/ui、Radix）：

function hslToHex(h, s, l) {
  s /= 100; l /= 100;
  const a = s * Math.min(l, 1 - l);
  const f = n => {
    const k = (n + h / 30) % 12;
    return l - a * Math.max(Math.min(k - 3, 9 - k, 1), -1);
  };
  return '#' + [f(0), f(8), f(4)]
    .map(x => Math.round(x * 255).toString(16).padStart(2, '0'))
    .join('');
}

// shadcn/ui: --muted-foreground: 215.4 16.3% 46.9%
hslToHex(215.4, 16.3, 46.9); // -> approximately #6B7280

WCAG 对比度阈值

用例AAAAA说明
正文（< 18pt / < 14pt 粗体）4.5:17:1大多数正文文本
大号文本（>= 18pt / >= 14pt 粗体）3:14.5:1标题、展示文本
UI 组件（边框、图标）3:1-输入框边框、图标按钮
焦点指示器（WCAG 2.4.13、2.2）3:1-与相邻颜色的对比度
占位符文本4.5:1-按正文文本计
禁用状态豁免豁免已记录的豁免情况
徽标 / 品牌豁免豁免无要求
装饰性内容豁免豁免必须标记为装饰性内容

框架令牌路径 - 完整参考

Tailwind CSS
// tailwind.config.js / tailwind.config.ts
module.exports = {
  theme: {
    // Base colors (Tailwind default palette)
    colors: {
      // All color scales: slate, gray, zinc, neutral, stone, red, orange, amber,
      // yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet,
      // purple, fuchsia, pink, rose
      // Each scale: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
    },
    extend: {
      colors: {
        // Custom semantic colors - CHECK ALL PAIRS
        brand: { primary: '#...', secondary: '#...' },
        background: '#...',
        foreground: '#...',
        muted: '#...',
        'muted-foreground': '#...',
        accent: '#...',
        'accent-foreground': '#...',
        destructive: '#...',
        'destructive-foreground': '#...',
        card: '#...',
        'card-foreground': '#...',
        popover: '#...',
        'popover-foreground': '#...',
        border: '#...',    // UI component - check 3:1 against background
        input: '#...',     // UI component - check 3:1 against background
        ring: '#...',      // Focus ring - check 3:1 against background
        primary: '#...',
        'primary-foreground': '#...',
        secondary: '#...',
        'secondary-foreground': '#...',
      },
      ringColor: { DEFAULT: '...' },  // Focus state
      ringWidth: { DEFAULT: '2px' },  // Must be >= 2px for WCAG 2.4.13
    }
  }
}
shadcn/ui / Radix CSS 变量
/* globals.css - HSL triplets without hsl() wrapper */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --card: 0 0% 100%;
  --card-foreground: 222.2 84% 4.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;     /* HIGH RISK - check on --background */
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;               /* HIGH RISK - red on white */
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;               /* UI component - check 3:1 */
  --input: 214.3 31.8% 91.4%;                /* UI component - check 3:1 */
  --ring: 222.2 84% 4.9%;                    /* Focus ring - check 3:1 */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... all dark mode variants */
}
Material UI (MUI) v5+
// Token paths in createTheme()
palette: {
  primary: {
    main: '#1976d2',            // text-on-white: 4.56:1 
    light: '#42a5f5',           // text-on-white: 2.86:1  (do not use as text color)
    dark: '#1565c0',            // text-on-white: 5.91:1 
    contrastText: '#fff',       // check on main
  },
  secondary: {
    main: '#9c27b0',            // text-on-white: 4.56:1  (barely)
    light: '#ba68c8',           // text-on-white: 2.55:1 
    dark: '#7b1fa2',
    contrastText: '#fff',
  },
  error: {
    main: '#d32f2f',            // text-on-white: 5.08:1 
    light: '#ef5350',           // text-on-white: 3.04:1 
  },
  warning: {
    main: '#ed6c02',            // text-on-white: 2.94:1  COMMON FAILURE
    light: '#ff9800',           // text-on-white: 2.02:1 
    dark: '#e65100',            // text-on-white: 3.84:1  (still fails!)
    contrastText: 'rgba(0, 0, 0, 0.87)',  // check on warning.main
  },
  info: {
    main: '#0288d1',            // text-on-white: 4.54:1  (barely)
    light: '#03a9f4',           // text-on-white: 2.88:1 
  },
  success: {
    main: '#2e7d32',            // text-on-white: 7.24:1 
    light: '#4caf50',           // text-on-white: 2.52:1 
  },
  text: {
    primary: 'rgba(0,0,0,0.87)',   // -> ~#212121: 16.07:1 on white 
    secondary: 'rgba(0,0,0,0.6)', // -> ~#666: 5.74:1 on white 
    disabled: 'rgba(0,0,0,0.38)', // -> ~#9E9E9E: 2.34:1  (exempt when disabled)
  },
  background: { paper: '#fff', default: '#fafafa' },
  action: {
    active: 'rgba(0,0,0,0.54)',   // ~4.48:1  for small icons
    disabled: 'rgba(0,0,0,0.26)', // exempt when disabled
  }
}
Chakra UI v2/v3
// Token paths in extendTheme()
const theme = extendTheme({
  colors: {
    // Direct palette values
    brand: { 50: '#f5f3ff', 500: '#7C3AED', 600: '#6D28D9', 700: '#5B21B6', 900: '#2E1065' },
    gray: { 50: '#F9FAFB', 100: '#F3F4F6', 200: '#E5E7EB', 300: '#D1D5DB',
            400: '#9CA3AF',  // text-on-white: 2.85:1 
            500: '#6B7280',  // text-on-white: 4.48:1  (near-miss)
            600: '#4B5563',  // text-on-white: 7.44:1 
            700: '#374151', 800: '#1F2937', 900: '#111827' },
  },
  semanticTokens: {
    colors: {
      'chakra-body-text': { default: 'gray.800', _dark: 'whiteAlpha.900' },
      'chakra-body-bg': { default: 'white', _dark: 'gray.800' },
      'chakra-placeholder-color': { default: 'gray.400', _dark: 'whiteAlpha.400' },
      // gray.400 on white = 2.85:1  - placeholder fails AA
    }
  },
  components: {
    Button: {
      variants: {
        solid: (props) => ({
          bg: `${props.colorScheme}.500`,  // check colorScheme.500 on white
          color: 'white',                  // white on colorScheme.500 - check 3:1
        }),
        ghost: (props) => ({
          color: `${props.colorScheme}.600`,  // text-on-white variant
        }),
      }
    }
  }
});
Style Dictionary（W3C 设计令牌）
{
  "color": {
    "text": {
      "primary": { "$value": "#111827", "$type": "color" },
      "secondary": { "$value": "#6B7280", "$type": "color" },   // 4.48:1 on white 
      "muted": { "$value": "#9CA3AF", "$type": "color" },       // 2.85:1 on white 
      "inverse": { "$value": "#FFFFFF", "$type": "color" },
      "on-primary": { "$value": "#FFFFFF", "$type": "color" }
    },
    "background": {
      "default": { "$value": "#FFFFFF", "$type": "color" },
      "subtle": { "$value": "#F9FAFB", "$type": "color" },
      "primary": { "$value": "#1D4ED8", "$type": "color" }
    },
    "status": {
      "error": { "$value": "#DC2626", "$type": "color" },
      "warning": { "$value": "#D97706", "$type": "color" },     // 3:1 on white  for normal text
      "success": { "$value": "#16A34A", "$type": "color" },
      "info": { "$value": "#2563EB", "$type": "color" }
    },
    "border": {
      "default": { "$value": "#D1D5DB", "$type": "color" },     // 1.44:1 on white  UI component
      "focus": { "$value": "#2563EB", "$type": "color" }        // focus ring
    }
  }
}

高风险令牌组合 - 已知问题

令牌组合常见值白色背景上的对比度状态说明
MUI warning.main#ed6c022.94:1失败橙色搭配白色 - 始终不合格
MUI warning.light#ff98002.02:1失败浅橙色 - 严重不合格
Tailwind amber-400#FBBF241.73:1失败绝不可将 amber-400 用作文本
Tailwind yellow-400#FACC151.60:1失败黄色搭配白色始终不合格
gray-400 (Tailwind)#9CA3AF2.85:1失败常见的占位符颜色
gray-500 (Tailwind)#6B72804.48:1失败非常接近合格 - 十分常见
Chakra gray.400#9CA3AF2.85:1失败Chakra 默认占位符颜色
MUI text.disabledrgba(0,0,0,0.38)~2.34:1（豁免）根据 WCAG，禁用状态可豁免
MUI action.activergba(0,0,0,0.54)~4.48:1失败白色背景上的图标颜色
shadcn --muted-foregroundhsl(215.4 16.3% 46.9%)~4.48:1失败shadcn 默认主题
shadcn --destructivehsl(0 84.2% 60.2%)~3.13:1失败白色背景上的红色徽标
Style Dictionary text.secondary#6B72804.48:1失败无处不在 - 务必检查
合规替代方案
不合格令牌替代方案新对比度说明
#9CA3AF (gray-400)#6B7280 (gray-500)4.48:1仍接近不合格；为确保安全，请使用 #595959
#6B7280 (gray-500)#4B5563 (gray-600)7.44:1最安全的选项
#ed6c02 (MUI warning)#b45309 (amber-700)4.57:1刚好合格
#ff9800 (MUI warning.light)#b45309 (amber-700)4.57:1
#FBBF24 (amber-400)#92400e (amber-800)8.80:1用作背景，不要用作文本
#FACC15 (yellow-400)#713f12 (yellow-900)12.04:1用作背景，不要用作文本
hsl(0 84.2% 60.2%) (shadcn destructive)#b91c1c (red-700)5.56:1

Storybook addon-a11y 配置

npm install --save-dev @storybook/addon-a11y

// .storybook/main.js
module.exports = {
  addons: ['@storybook/addon-a11y'],
};

// .storybook/preview.js - global configuration
export const parameters = {
  a11y: {
    config: {
      rules: [
        { id: 'color-contrast', enabled: true },
        { id: 'button-name', enabled: true },
        { id: 'image-alt', enabled: true },
        { id: 'focus-visible', enabled: true },    // Requires axe-core 4.4+
        { id: 'target-size', enabled: true },       // WCAG 2.5.5 / 2.5.8
      ],
    },
    // Disable for specific stories (use sparingly)
    disable: false,
  },
};

// Per-story override
export const MyStory = {
  parameters: {
    a11y: {
      config: {
        rules: [{ id: 'color-contrast', enabled: false }],  // Document WHY
      }
    }
  }
};
在 CI 中运行 Storybook a11y 检查
# Install storybook test runner
npm install --save-dev @storybook/test-runner

# package.json scripts
{
  "scripts": {
    "storybook:test": "test-storybook",
    "storybook:test:a11y": "test-storybook --ci"
  }
}

# Run in CI
npx storybook dev --port 6006 &
npx wait-on tcp:6006
npx test-storybook --ci

WCAG 2.4.13 焦点外观要求（AAA，高于 AA 基线）

WCAG 2.4.13 焦点外观（WCAG 2.2 中的 AAA 级）——高于 2.4.7 焦点可见（AA）基线，但建议作为最佳实践：

  1. **面积：**焦点指示器包围组件，或其周长不小于组件周长 × 2px
  2. **对比度变化：**焦点指示器区域在聚焦和未聚焦状态之间的对比度变化必须 ≥ 3:1
  3. **不被遮挡：**焦点指示器不得被作者创建的内容完全隐藏
最低合规的焦点环实现
/* Minimum WCAG 2.4.13 compliant focus ring */
:focus-visible {
  outline: 2px solid #0054B3;      /* >= 2px width */
  outline-offset: 2px;             /* Separates from component edge */
  /* #0054B3 on #FFF = 8.28:1 -> passes 3:1 for UI components */
}

/* Dark mode variant */
@media (prefers-color-scheme: dark) {
  :focus-visible {
    outline-color: #7CAFFF;        /* lighter blue on dark background */
    /* #7CAFFF on #1E1E1E = 5.74:1  */
  }
}

/* VIOLATION patterns to detect */
:focus { outline: none; }                           /* Hard fail */
:focus { outline: 0; }                              /* Hard fail */
:focus-visible { box-shadow: none; outline: none; } /* Hard fail */
button:focus { outline: none; }                     /* Hard fail */
*:focus { outline-color: transparent; }             /* Hard fail */
焦点环 Token 验证清单
检查项要求工具
outline-width >= 2pxWCAG 2.4.13 面积要求CSS 审计
焦点颜色对比度 >= 3:1与相邻背景相比对比度计算器
焦点状态与未聚焦状态不同必须有可见变化视觉检查
没有未替换的 outline: none不适用grep / CSS 审计
在浅色和深色模式下均存在保持一致视觉检查

设计 Token 文件发现命令

# Find all token files in a project
find . -type f \( \
  -name "tokens.json" \
  -o -name "design-tokens.json" \
  -o -name "colors.json" \
  -o -name "variables.css" \
  -o -name "tokens.css" \
  -o -name "_variables.scss" \
  -o -name "theme.ts" \
  -o -name "theme.js" \
  -o -name "tailwind.config.*" \
\) \
-not -path "*/node_modules/*" \
-not -path "*/.next/*" \
-not -path "*/dist/*"

# PowerShell equivalent
Get-ChildItem -Recurse -File -Include tokens.json,design-tokens.json,colors.json,`
  variables.css,tokens.css,_variables.scss,theme.ts,theme.js,tailwind.config.js,tailwind.config.ts `
  | Where-Object { $_.FullName -notmatch 'node_modules|\.next|dist' }

严重程度分类

发现项严重程度
文本 Token 低于 3:1严重
文本 Token 为 3:1-4.49:1（普通文本）错误
文本 Token 为 4.5:1-6.99:1，AAA 目标警告
UI 组件 Token 低于 3:1错误
焦点环完全缺失严重
焦点环小于 2px错误
焦点环对比度低于 3:1错误
触控目标 Token 小于 24 x 24px（WCAG 2.5.8）错误
触控目标 Token 小于 44 x 44px（WCAG 2.5.5）警告
未重置 prefers-reduced-motion警告
占位符颜色对比度低于 4.5:1错误
禁用状态 Token 低于 3:1信息（已记录的豁免，需注明以保持透明度）

评论

支持 Markdown