Agent Skills › alinaqi/maggy › ui-testing

ui-testing

GitHub

用于验证UI组件的无障碍标准，检查按钮可见性、对比度、触控目标大小及响应式布局，提供快速修复方案。

skills/ui-testing/SKILL.md alinaqi/maggy

Trigger Scenarios

创建新的UI组件后检查UI可访问性合规性解决视觉设计缺陷如对比度不足或按钮不可见

Install

npx skills add alinaqi/maggy --skill ui-testing -g -y

More Options

Use without installing

npx skills use alinaqi/maggy@ui-testing

指定 Agent (Claude Code)

npx skills add alinaqi/maggy --skill ui-testing -a claude-code -g -y

安装 repo 全部 skill

npx skills add alinaqi/maggy --all -g -y

预览 repo 内 skill

npx skills add alinaqi/maggy --list

SKILL.md

Frontmatter

{
    "name": "ui-testing",
    "paths": [
        "**\/*.test.tsx",
        "**\/*.spec.tsx",
        "**\/*.stories.*"
    ],
    "effort": "medium",
    "description": "Visual testing - catch invisible buttons, broken layouts, contrast",
    "when-to-use": "When writing visual or accessibility tests for UI components",
    "user-invocable": false
}

UI Verification Skill

Load with: ui-web.md or ui-mobile.md

Purpose

Quick verification that generated UI meets accessibility standards. Run these checks after creating any new UI components.

Pre-Flight Checklist

Before Shipping ANY UI:

## Visibility Check
- [ ] All buttons have visible background OR border
- [ ] No text is same color as its background
- [ ] All text meets 4.5:1 contrast ratio
- [ ] Ghost/text buttons have visible borders

## Touch/Click Targets
- [ ] All buttons are minimum 44px height
- [ ] Icon buttons are minimum 44x44px
- [ ] Adequate spacing between clickable elements

## States
- [ ] Hover states visible (web)
- [ ] Pressed states visible (mobile)
- [ ] Focus rings on keyboard navigation
- [ ] Disabled states visually distinct (opacity 0.5)
- [ ] Loading states show indicators

## Dark Mode (if applicable)
- [ ] Text readable on dark backgrounds
- [ ] Borders visible in dark mode
- [ ] No gray-400 text on dark backgrounds

## Responsive (web)
- [ ] No horizontal scroll on mobile (320px)
- [ ] Content readable at all breakpoints
- [ ] Touch targets adequate on mobile

Quick Contrast Check

Use Browser DevTools

1. Right-click element → Inspect
2. In Styles panel, click on color value
3. Look for contrast ratio display
4. Must show ✓ for AA compliance (4.5:1 for text)

Online Tools

Tailwind Safe Combinations

LIGHT MODE (on white bg):
✓ text-gray-900  (#111827) = 16:1
✓ text-gray-800  (#1F2937) = 12:1
✓ text-gray-700  (#374151) = 9:1
✓ text-gray-600  (#4B5563) = 6:1
✗ text-gray-500  (#6B7280) = 4.6:1 (barely)
✗ text-gray-400  (#9CA3AF) = 2.6:1 (FAILS)

DARK MODE (on gray-900 bg):
✓ text-white     (#FFFFFF) = 16:1
✓ text-gray-100  (#F3F4F6) = 13:1
✓ text-gray-200  (#E5E7EB) = 11:1
✓ text-gray-300  (#D1D5DB) = 8:1
✗ text-gray-400  (#9CA3AF) = 5:1 (barely)
✗ text-gray-500  (#6B7280) = 3:1 (FAILS)

Common Fixes

Invisible Button

// PROBLEM: No visible boundary
<button className="text-gray-500">Click</button>

// FIX: Add background OR border
<button className="bg-gray-100 text-gray-900 px-4 py-3 rounded-lg">
  Click
</button>
// OR
<button className="border border-gray-300 text-gray-700 px-4 py-3 rounded-lg">
  Click
</button>

Low Contrast Text

// PROBLEM: Light gray on white
<p className="text-gray-400">Secondary text</p>

// FIX: Use darker gray
<p className="text-gray-600">Secondary text</p>

Missing Focus State

// PROBLEM: Focus removed without replacement
<button className="outline-none">Submit</button>

// FIX: Add visible focus ring
<button className="outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2">
  Submit
</button>

Small Touch Target

// PROBLEM: Too small for fingers
<button className="p-1 text-sm">×</button>

// FIX: Minimum 44px
<button className="w-11 h-11 flex items-center justify-center">×</button>

Dark Mode Broken

// PROBLEM: Same colors in both modes
<p className="text-gray-400">Text</p>

// FIX: Adjust for dark mode
<p className="text-gray-600 dark:text-gray-300">Text</p>

Automated Checks (Optional)

ESLint Plugin

npm install -D eslint-plugin-jsx-a11y

// .eslintrc
{
  "extends": ["plugin:jsx-a11y/recommended"]
}

Playwright Quick Test

// e2e/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('no accessibility violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});