设计与 UI
web-design-guidelines
Web design best practices, accessibility, responsive layout, color contrast. Use when auditing a UI for a11y compliance, designing responsive layouts, or establishing design standards across a web app.
sabahattink · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add sabahattink/antigravity-fullstack-hq --skill web-design-guidelines技能说明
name: web-design-guidelines description: Web design best practices, accessibility, responsive layout, color contrast. Use when auditing a UI for a11y compliance, designing responsive layouts, or establishing design standards across a web app.
Web Design Guidelines
Accessibility (WCAG 2.1 AA)
Color Contrast Requirements
- Normal text (< 18pt): minimum 4.5:1 contrast ratio
- Large text (≥ 18pt or 14pt bold): minimum 3:1
- UI components and graphical objects: minimum 3:1
// Use a utility to check contrast at runtime in dev
// Install: npm i color2k
import { parseToRgb, getLuminance } from 'color2k'
function getContrastRatio(fg: string, bg: string): number {
const l1 = getLuminance(fg)
const l2 = getLuminance(bg)
const lighter = Math.max(l1, l2)
const darker = Math.min(l1, l2)
return (lighter + 0.05) / (darker + 0.05)
}
// In Storybook stories or tests:
// expect(getContrastRatio('#2563eb', '#ffffff')).toBeGreaterThan(4.5)
Semantic HTML
// Good: semantic structure
export function PageLayout() {
return (
<>
<header role="banner">
<nav aria-label="Main navigation">
<ul role="list">
<li><a href="/">Home</a></li>
<li><a href="/about">About</a></li>
</ul>
</nav>
</header>
<main id="main-content" tabIndex={-1}>
<h1>Page Title</h1>
{/* Skip-to-main link target */}
</main>
<aside aria-label="Related content">
{/* Sidebar */}
</aside>
<footer role="contentinfo">
{/* Footer */}
</footer>
</>
)
}
// Skip link — must be the very first focusable element
function SkipToMain() {
return (
<a
href="#main-content"
className="sr-only focus:not-sr-only focus:absolute focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-white focus:text-blue-600 focus:rounded-lg focus:shadow-lg focus:outline-none focus:ring-2 focus:ring-blue-500"
>
Skip to main content
</a>
)
}
Keyboard Navigation
// All interactive elements must be keyboard-operable
function DropdownMenu({ items }: { items: MenuItem[] }) {
const [open, setOpen] = React.useState(false)
const [activeIndex, setActiveIndex] = React.useState(-1)
const handleKeyDown = (e: React.KeyboardEvent) => {
switch (e.key) {
case 'ArrowDown':
e.preventDefault()
setActiveIndex(i => Math.min(i + 1, items.length - 1))
break
case 'ArrowUp':
e.preventDefault()
setActiveIndex(i => Math.max(i - 1, 0))
break
case 'Escape':
setOpen(false)
break
case 'Enter':
case ' ':
if (activeIndex >= 0) items[activeIndex].action()
break
}
}
return (
<div role="navigation" aria-label="Actions menu">
<button
aria-haspopup="true"
aria-expanded={open}
onClick={() => setOpen(o => !o)}
>
Actions
</button>
{open && (
<ul
role="menu"
onKeyDown={handleKeyDown}
className="..."
>
{items.map((item, i) => (
<li key={item.id} role="menuitem" tabIndex={i === activeIndex ? 0 : -1}>
<button onClick={item.action}>{item.label}</button>
</li>
))}
</ul>
)}
</div>
)
}
ARIA Labels
// Always label icon-only buttons
<button aria-label="Close dialog" onClick={onClose}>
<XIcon aria-hidden="true" className="h-5 w-5" />
</button>
// Images
<img src={product.image} alt={`${product.name} — front view`} />
// Decorative images get empty alt
<img src="/divider.svg" alt="" role="presentation" />
// Live regions for dynamic content
<div aria-live="polite" aria-atomic="true" className="sr-only">
{statusMessage}
</div>
Responsive Layout
Mobile-First Approach
/* Write base styles for mobile, then progressively enhance */
.card {
padding: 1rem; /* mobile */
}
@media (min-width: 640px) { /* sm */
.card { padding: 1.5rem; }
}
@media (min-width: 1024px) { /* lg */
.card { padding: 2rem; }
}
// Tailwind mobile-first
<div className="px-4 sm:px-6 lg:px-8">
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
{items.map(item => <Item key={item.id} {...item} />)}
</div>
</div>
Fluid Typography
/* clamp(min, preferred, max) — scales smoothly between viewport sizes */
:root {
--text-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
--text-lg: clamp(1.125rem, 1rem + 0.75vw, 1.375rem);
--text-xl: clamp(1.25rem, 1rem + 1.5vw, 1.75rem);
--text-2xl: clamp(1.5rem, 1rem + 2.5vw, 2.25rem);
--text-4xl: clamp(2rem, 1rem + 5vw, 4rem);
}
Container Queries
/* Style based on parent width, not viewport width */
.card-grid {
container-type: inline-size;
container-name: card-grid;
}
@container card-grid (min-width: 480px) {
.product-card {
display: grid;
grid-template-columns: 140px 1fr;
}
}
Image Optimization
// Next.js Image — always use this over <img>
import Image from 'next/image'
// Known dimensions (static assets)
<Image
src="/hero.jpg"
alt="Dashboard overview showing key metrics"
width={1200}
height={630}
priority // LCP image: load eagerly
className="rounded-xl object-cover"
/>
// Unknown dimensions (user uploads)
<div className="relative aspect-video w-full overflow-hidden rounded-xl">
<Image
src={user.avatar}
alt={`${user.name}'s profile photo`}
fill
sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
className="object-cover"
/>
</div>
Touch Targets
Minimum touch target size: 44×44 px (Apple HIG) / 48×48 dp (Material).
// Expand click area without changing visual size
<button
className="
relative p-2 -m-2
/* visual size stays 24px, but hit area is 44px (24 + 2*8 = 40... close enough) */
b
阅读完整来源 ↗