Back to Details

epic-ui-guidelines

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Epic Stack: UI Guidelines

Epic Stack：UI规范

When to use this skill

何时使用本技能

Use this skill when you need to:
  • Create accessible UI components
  • Follow Epic Stack design patterns
  • Use Tailwind CSS effectively
  • Implement semantic HTML
  • Add ARIA attributes correctly
  • Create responsive layouts
  • Ensure proper form accessibility
  • Follow Epic Stack's UI component conventions
当你需要以下操作时，可使用本技能：
  • 创建无障碍UI组件
  • 遵循Epic Stack设计模式
  • 高效使用Tailwind CSS
  • 实现语义化HTML
  • 正确添加ARIA属性
  • 创建响应式布局
  • 确保表单具备无障碍访问性
  • 遵循Epic Stack的UI组件约定

Patterns and conventions

设计模式与约定

UI Philosophy

UI设计理念

Following Epic Web principles:
Software is built for people, by people - Accessibility isn't about checking boxes or meeting standards. It's about creating software that works for real people with diverse needs, abilities, and contexts. Every UI decision should prioritize the human experience over technical convenience.
Accessibility is not optional - it's how we ensure our software serves all users, not just some. When you make UI accessible, you're making it better for everyone: clearer labels help all users, keyboard navigation helps power users, and semantic HTML helps search engines.
Example - Human-centered approach:
typescript
// ✅ Good - Built for people
function NoteForm() {
	return (
		<Form method="POST">
			<Field
				labelProps={{
					htmlFor: fields.title.id,
					children: 'Note Title', // Clear, human-readable label
				}}
				inputProps={{
					...getInputProps(fields.title),
					placeholder: 'Enter a descriptive title', // Helpful guidance
					autoFocus: true, // Saves time for users
				}}
				errors={fields.title.errors} // Clear error messages
			/>
		</Form>
	)
}

// ❌ Avoid - Technical convenience over user experience
function NoteForm() {
	return (
		<Form method="POST">
			<input name="title" /> {/* No label, no guidance, no accessibility */}
		</Form>
	)
}
遵循Epic Web原则：
软件由人构建，为人服务 - 无障碍设计不是勾选框或满足标准，而是打造能满足不同需求、能力和场景的真实用户的软件。每一个UI决策都应优先考虑用户体验，而非技术便利性。
无障碍设计并非可选项 - 它是确保软件服务所有用户而非部分用户的方式。当你让UI具备无障碍性时，你是在让它对所有人更友好：清晰的标签帮助所有用户，键盘导航帮助高级用户，语义化HTML帮助搜索引擎。
示例 - 以人为中心的方法：
typescript
// ✅ 良好示例 - 为用户构建
function NoteForm() {
	return (
		<Form method="POST">
			<Field
				labelProps={{
					htmlFor: fields.title.id,
					children: 'Note Title', // 清晰、易懂的标签
				}}
				inputProps={{
					...getInputProps(fields.title),
					placeholder: 'Enter a descriptive title', // 实用的引导提示
					autoFocus: true, // 为用户节省时间
				}}
				errors={fields.title.errors} // 清晰的错误提示
			/>
		</Form>
	)
}

// ❌ 避免示例 - 优先技术便利性而非用户体验
function NoteForm() {
	return (
		<Form method="POST">
			<input name="title" /> {/* No label, no guidance, no accessibility */}
		</Form>
	)
}

Semantic HTML

语义化HTML

✅ Good - Use semantic elements:
typescript
function UserCard({ user }: { user: User }) {
	return (
		<article>
			<header>
				<h2>{user.name}</h2>
			</header>
			<p>{user.bio}</p>
			<footer>
				<time dateTime={user.createdAt}>{formatDate(user.createdAt)}</time>
			</footer>
		</article>
	)
}
❌ Avoid - Generic divs:
typescript
// ❌ Don't use divs for everything
<div>
	<div>{user.name}</div>
	<div>{user.bio}</div>
	<div>{formatDate(user.createdAt)}</div>
</div>
✅ 良好示例 - 使用语义化元素：
typescript
function UserCard({ user }: { user: User }) {
	return (
		<article>
			<header>
				<h2>{user.name}</h2>
			</header>
			<p>{user.bio}</p>
			<footer>
				<time dateTime={user.createdAt}>{formatDate(user.createdAt)}</time>
			</footer>
		</article>
	)
}
❌ 避免示例 - 滥用通用div：
typescript
// ❌ 不要所有元素都用div
<div>
	<div>{user.name}</div>
	<div>{user.bio}</div>
	<div>{formatDate(user.createdAt)}</div>
</div>

Form Accessibility

表单无障碍设计

✅ Good - Always use labels:
typescript
import { Field } from '#app/components/forms.tsx'

<Field
	labelProps={{
		htmlFor: fields.email.id,
		children: 'Email',
	}}
	inputProps={{
		...getInputProps(fields.email, { type: 'email' }),
		autoFocus: true,
		autoComplete: 'email',
	}}
	errors={fields.email.errors}
/>
The 
Field
component automatically:
  • Associates labels with inputs using 
    htmlFor
    and 
    id
  • Adds 
    aria-invalid
    when there are errors
  • Adds 
    aria-describedby
    pointing to error messages
  • Ensures proper error announcement
❌ Avoid - Unlabeled inputs:
typescript
// ❌ Don't forget labels
<input type="email" name="email" />
✅ 良好示例 - 始终使用标签：
typescript
import { Field } from '#app/components/forms.tsx'

<Field
	labelProps={{
		htmlFor: fields.email.id,
		children: 'Email',
	}}
	inputProps={{
		...getInputProps(fields.email, { type: 'email' }),
		autoFocus: true,
		autoComplete: 'email',
	}}
	errors={fields.email.errors}
/>
Field
组件会自动处理以下内容：
  • 使用
    htmlFor
    和
    id
    关联标签与输入框
  • 当存在错误时添加
    aria-invalid
    属性
  • 添加指向错误提示的
    aria-describedby
    属性
  • 确保错误提示被正确播报
❌ 避免示例 - 无标签的输入框：
typescript
// ❌ 不要忘记添加标签
<input type="email" name="email" />

ARIA Attributes

ARIA属性

✅ Good - Use ARIA appropriately:
typescript
// Epic Stack's Field component handles this automatically
<Field
	inputProps={{
		...getInputProps(fields.email, { type: 'email' }),
		// aria-invalid and aria-describedby are added automatically
	}}
	errors={fields.email.errors} // Error messages are linked via aria-describedby
/>
✅ Good - ARIA for custom components:
typescript
function LoadingButton({ isLoading, children }: { isLoading: boolean; children: React.ReactNode }) {
	return (
		<button aria-busy={isLoading} disabled={isLoading}>
			{isLoading ? 'Loading...' : children}
		</button>
	)
}
✅ 良好示例 - 合理使用ARIA：
typescript
// Epic Stack的Field组件会自动处理这些
<Field
	inputProps={{
		...getInputProps(fields.email, { type: 'email' }),
		// aria-invalid和aria-describedby会自动添加
	}}
	errors={fields.email.errors} // 错误提示通过aria-describedby关联
/>
✅ 良好示例 - 为自定义组件添加ARIA：
typescript
function LoadingButton({ isLoading, children }: { isLoading: boolean; children: React.ReactNode }) {
	return (
		<button aria-busy={isLoading} disabled={isLoading}>
			{isLoading ? 'Loading...' : children}
		</button>
	)
}

Using Radix UI Components

使用Radix UI组件

Epic Stack uses Radix UI for accessible, unstyled components.
✅ Good - Use Radix primitives:
typescript
import * as Dialog from '@radix-ui/react-dialog'
import { Button } from '#app/components/ui/button.tsx'

function MyDialog() {
	return (
		<Dialog.Root>
			<Dialog.Trigger asChild>
				<Button>Open Dialog</Button>
			</Dialog.Trigger>
			<Dialog.Portal>
				<Dialog.Overlay className="fixed inset-0 bg-black/50" />
				<Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6">
					<Dialog.Title>Dialog Title</Dialog.Title>
					<Dialog.Description>Dialog description</Dialog.Description>
					<Dialog.Close asChild>
						<Button>Close</Button>
					</Dialog.Close>
				</Dialog.Content>
			</Dialog.Portal>
		</Dialog.Root>
	)
}
Radix components automatically handle:
  • Keyboard navigation
  • Focus management
  • ARIA attributes
  • Screen reader announcements
Epic Stack使用Radix UI来构建无障碍、无样式的组件。
✅ 良好示例 - 使用Radix基础组件：
typescript
import * as Dialog from '@radix-ui/react-dialog'
import { Button } from '#app/components/ui/button.tsx'

function MyDialog() {
	return (
		<Dialog.Root>
			<Dialog.Trigger asChild>
				<Button>Open Dialog</Button>
			</Dialog.Trigger>
			<Dialog.Portal>
				<Dialog.Overlay className="fixed inset-0 bg-black/50" />
				<Dialog.Content className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6">
					<Dialog.Title>Dialog Title</Dialog.Title>
					<Dialog.Description>Dialog description</Dialog.Description>
					<Dialog.Close asChild>
						<Button>Close</Button>
					</Dialog.Close>
				</Dialog.Content>
			</Dialog.Portal>
		</Dialog.Root>
	)
}
Radix组件会自动处理：
  • 键盘导航
  • 焦点管理
  • ARIA属性
  • 屏幕阅读器播报

Tailwind CSS Patterns

Tailwind CSS模式

✅ Good - Use Tailwind utility classes:
typescript
function Card({ children }: { children: React.ReactNode }) {
	return (
		<div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm">
			{children}
		</div>
	)
}
✅ Good - Use Tailwind responsive utilities:
typescript
<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
	{items.map(item => (
		<Card key={item.id}>{item.name}</Card>
	))}
</div>
✅ Good - Use Tailwind dark mode:
typescript
<div className="bg-white text-gray-900 dark:bg-gray-800 dark:text-gray-100">
	{content}
</div>
✅ 良好示例 - 使用Tailwind工具类：
typescript
function Card({ children }: { children: React.ReactNode }) {
	return (
		<div className="rounded-lg border border-gray-200 bg-white p-6 shadow-sm">
			{children}
		</div>
	)
}
✅ 良好示例 - 使用Tailwind响应式工具类：
typescript
<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">
	{items.map(item => (
		<Card key={item.id}>{item.name}</Card>
	))}
</div>
✅ 良好示例 - 使用Tailwind深色模式：
typescript
<div className="bg-white text-gray-900 dark:bg-gray-800 dark:text-gray-100">
	{content}
</div>

Error Handling in Forms

表单错误处理

✅ Good - Display errors accessibly:
typescript
import { Field, ErrorList } from '#app/components/forms.tsx'

<Field
	labelProps={{ htmlFor: fields.email.id, children: 'Email' }}
	inputProps={getInputProps(fields.email, { type: 'email' })}
	errors={fields.email.errors} // Errors are displayed below input
/>

<ErrorList errors={form.errors} id={form.errorId} /> // Form-level errors
Errors are automatically:
  • Associated with inputs via 
    aria-describedby
  • Announced to screen readers
  • Visually distinct with error styling
✅ 良好示例 - 无障碍地展示错误：
typescript
import { Field, ErrorList } from '#app/components/forms.tsx'

<Field
	labelProps={{ htmlFor: fields.email.id, children: 'Email' }}
	inputProps={getInputProps(fields.email, { type: 'email' })}
	errors={fields.email.errors} // 错误提示显示在输入框下方
/>

<ErrorList errors={form.errors} id={form.errorId} /> // 表单级别的错误提示
错误提示会自动：
  • 通过
    aria-describedby
    与输入框关联
  • 被屏幕阅读器播报
  • 以醒目的错误样式显示

Focus Management

焦点管理

✅ Good - Visible focus indicators:
typescript
// Tailwind's default focus:ring handles this
<button className="focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">
	Click me
</button>
✅ Good - Focus on form errors:
typescript
import { useEffect, useRef } from 'react'

function FormWithErrorFocus() {
	const firstErrorRef = useRef<HTMLInputElement>(null)

	useEffect(() => {
		if (actionData?.errors && firstErrorRef.current) {
			firstErrorRef.current.focus()
		}
	}, [actionData?.errors])

	return <Field inputProps={{ ref: firstErrorRef, ... }} />
}
✅ 良好示例 - 可见的焦点指示器：
typescript
// Tailwind默认的focus:ring会处理这个
<button className="focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">
	Click me
</button>
✅ 良好示例 - 焦点定位到表单错误：
typescript
import { useEffect, useRef } from 'react'

function FormWithErrorFocus() {
	const firstErrorRef = useRef<HTMLInputElement>(null)

	useEffect(() => {
		if (actionData?.errors && firstErrorRef.current) {
			firstErrorRef.current.focus()
		}
	}, [actionData?.errors])

	return <Field inputProps={{ ref: firstErrorRef, ... }} />
}

Keyboard Navigation

键盘导航

✅ Good - Keyboard accessible components:
typescript
// Radix components handle keyboard navigation automatically
<Dialog.Trigger asChild>
	<Button>Open</Button>
</Dialog.Trigger>

// Custom components should support keyboard
<button
	onKeyDown={(e) => {
		if (e.key === 'Enter' || e.key === ' ') {
			handleClick()
		}
	}}
>
	Custom Button
</button>
✅ 良好示例 - 支持键盘导航的组件：
typescript
// Radix组件会自动处理键盘导航
<Dialog.Trigger asChild>
	<Button>Open</Button>
</Dialog.Trigger>

// 自定义组件应支持键盘操作
<button
	onKeyDown={(e) => {
		if (e.key === 'Enter' || e.key === ' ') {
			handleClick()
		}
	}}
>
	Custom Button
</button>

Color Contrast

颜色对比度

✅ Good - Use accessible color combinations:
typescript
// Use Tailwind's semantic colors that meet WCAG AA
<div className="bg-white text-gray-900"> // High contrast
<div className="text-blue-600 hover:text-blue-700"> // Accessible links
❌ Avoid - Low contrast text:
typescript
// ❌ Don't use low contrast
<div className="bg-gray-100 text-gray-200"> // Very low contrast
✅ 良好示例 - 使用无障碍的配色组合：
typescript
// 使用符合WCAG AA标准的Tailwind语义化颜色
<div className="bg-white text-gray-900"> // 高对比度
<div className="text-blue-600 hover:text-blue-700"> // 无障碍链接
❌ 避免示例 - 低对比度文本：
typescript
// ❌ 不要使用低对比度配色
<div className="bg-gray-100 text-gray-200"> // 对比度极低

Responsive Design

响应式设计

✅ Good - Mobile-first approach:
typescript
<div className="
	flex flex-col gap-4
	md:flex-row md:gap-8
	lg:gap-12
">
	{/* Content */}
</div>
✅ Good - Responsive typography:
typescript
<h1 className="text-2xl md:text-3xl lg:text-4xl">
	Responsive Heading
</h1>
✅ 良好示例 - 移动端优先的设计方法：
typescript
<div className="
	flex flex-col gap-4
	md:flex-row md:gap-8
	lg:gap-12
">
	{/* 内容 */}
</div>
✅ 良好示例 - 响应式排版：
typescript
<h1 className="text-2xl md:text-3xl lg:text-4xl">
	响应式标题
</h1>

Loading States

加载状态

✅ Good - Accessible loading indicators:
typescript
import { useNavigation } from 'react-router'

function SubmitButton() {
	const navigation = useNavigation()
	const isSubmitting = navigation.state === 'submitting'

	return (
		<button
			type="submit"
			disabled={isSubmitting}
			aria-busy={isSubmitting}
		>
			{isSubmitting ? 'Saving...' : 'Save'}
		</button>
	)
}
✅ 良好示例 - 无障碍的加载指示器：
typescript
import { useNavigation } from 'react-router'

function SubmitButton() {
	const navigation = useNavigation()
	const isSubmitting = navigation.state === 'submitting'

	return (
		<button
			type="submit"
			disabled={isSubmitting}
			aria-busy={isSubmitting}
		>
			{isSubmitting ? 'Saving...' : 'Save'}
		</button>
	)
}

Icon Usage

图标使用

✅ Good - Decorative icons:
typescript
import { Icon } from '#app/components/ui/icon.tsx'

<button aria-label="Delete note">
	<Icon name="trash" />
	<span className="sr-only">Delete note</span>
</button>
✅ Good - Semantic icons:
typescript
<button>
	<Icon name="check" aria-hidden="true" />
	Save
</button>
✅ 良好示例 - 装饰性图标：
typescript
import { Icon } from '#app/components/ui/icon.tsx'

<button aria-label="Delete note">
	<Icon name="trash" />
	<span className="sr-only">Delete note</span>
</button>
✅ 良好示例 - 语义化图标：
typescript
<button>
	<Icon name="check" aria-hidden="true" />
	Save
</button>

Skip Links

跳转链接

✅ Good - Add skip to main content:
typescript
// In your root layout
<a href="#main-content" className="sr-only focus:not-sr-only focus:absolute focus:top-0 focus:left-0 focus:z-50 focus:p-4 focus:bg-blue-600 focus:text-white">
	Skip to main content
</a>

<main id="main-content">
	{/* Main content */}
</main>
✅ 良好示例 - 添加跳转到主内容的链接：
typescript
// 在根布局中
<a href="#main-content" className="sr-only focus:not-sr-only focus:absolute focus:top-0 focus:left-0 focus:z-50 focus:p-4 focus:bg-blue-600 focus:text-white">
	跳转到主内容
</a>

<main id="main-content">
	{/* 主内容 */}
</main>

Progressive Enhancement

渐进式增强

✅ Good - Forms work without JavaScript:
typescript
// Conform forms work without JavaScript
<Form method="POST" {...getFormProps(form)}>
	<Field {...props} />
	<StatusButton type="submit">Submit</StatusButton>
</Form>
Forms automatically:
  • Submit via native HTML forms if JavaScript is disabled
  • Validate server-side
  • Show errors appropriately
✅ 良好示例 - 表单在无JavaScript环境下仍可工作：
typescript
// Conform表单在无JavaScript环境下仍可工作
<Form method="POST" {...getFormProps(form)}>
	<Field {...props} />
	<StatusButton type="submit">Submit</StatusButton>
</Form>
表单会自动：
  • 如果JavaScript被禁用，通过原生HTML表单提交
  • 在服务端进行验证
  • 正确显示错误提示

Screen Reader Best Practices

屏幕阅读器最佳实践

✅ Good - Use semantic HTML first:
typescript
// ✅ Semantic HTML provides context automatically
<nav aria-label="Main navigation">
	<ul>
		<li><a href="/">Home</a></li>
		<li><a href="/about">About</a></li>
	</ul>
</nav>
✅ Good - Announce dynamic content:
typescript
import { useNavigation } from 'react-router'

function SearchResults({ results }: { results: Result[] }) {
	const navigation = useNavigation()
	const isSearching = navigation.state === 'loading'

	return (
		<div
			role="status"
			aria-live="polite"
			aria-atomic="true"
			className="sr-only"
		>
			{isSearching ? 'Searching...' : `${results.length} results found`}
		</div>
	)
}
✅ Good - Live regions for important updates:
typescript
function ToastContainer({ toasts }: { toasts: Toast[] }) {
	return (
		<div aria-live="assertive" aria-atomic="true" className="sr-only">
			{toasts.map(toast => (
				<div key={toast.id} role="alert">
					{toast.message}
				</div>
			))}
		</div>
	)
}
ARIA live region options:
  • aria-live="polite"
    - For non-critical updates (search results, status messages)
  • aria-live="assertive"
    - For critical updates (errors, confirmations)
  • aria-atomic="true"
    - Screen reader reads entire region on update
  • aria-atomic="false"
    - Screen reader reads only changed parts
✅ 良好示例 - 优先使用语义化HTML：
typescript
// ✅ 语义化HTML会自动提供上下文
<nav aria-label="Main navigation">
	<ul>
		<li><a href="/">Home</a></li>
		<li><a href="/about">About</a></li>
	</ul>
</nav>
✅ 良好示例 - 播报动态内容：
typescript
import { useNavigation } from 'react-router'

function SearchResults({ results }: { results: Result[] }) {
	const navigation = useNavigation()
	const isSearching = navigation.state === 'loading'

	return (
		<div
			role="status"
			aria-live="polite"
			aria-atomic="true"
			className="sr-only"
		>
			{isSearching ? 'Searching...' : `${results.length} results found`}
		</div>
	)
}
✅ 良好示例 - 为重要更新使用实时区域：
typescript
function ToastContainer({ toasts }: { toasts: Toast[] }) {
	return (
		<div aria-live="assertive" aria-atomic="true" className="sr-only">
			{toasts.map(toast => (
				<div key={toast.id} role="alert">
					{toast.message}
				</div>
			))}
		</div>
	)
}
ARIA实时区域选项：
  • aria-live="polite"
    - 用于非关键更新（搜索结果、状态提示）
  • aria-live="assertive"
    - 用于关键更新（错误提示、确认信息）
  • aria-atomic="true"
    - 屏幕阅读器会播报整个区域的内容
  • aria-atomic="false"
    - 屏幕阅读器仅播报变化的部分

Keyboard Navigation Patterns

键盘导航模式

✅ Good - Tab order follows visual order:
typescript
// Elements appear in logical tab order
<nav>
	<a href="/">Home</a>
	<a href="/about">About</a>
	<a href="/contact">Contact</a>
</nav>
✅ Good - Keyboard shortcuts:
typescript
import { useEffect } from 'react'

function SearchDialog({ onClose }: { onClose: () => void }) {
	useEffect(() => {
		function handleKeyDown(e: KeyboardEvent) {
			if (e.key === 'Escape') {
				onClose()
			}
		}

		window.addEventListener('keydown', handleKeyDown)
		return () => window.removeEventListener('keydown', handleKeyDown)
	}, [onClose])

	return <Dialog>{/* content */}</Dialog>
}
✅ Good - Focus trap in modals:
typescript
// Radix Dialog automatically handles focus trap
<Dialog.Root>
	<Dialog.Content>
		{/* Focus is trapped inside dialog */}
		<Dialog.Close>Close</Dialog.Close>
	</Dialog.Content>
</Dialog.Root>
✅ 良好示例 - Tab顺序遵循视觉顺序：
typescript
// 元素按逻辑Tab顺序排列
<nav>
	<a href="/">Home</a>
	<a href="/about">About</a>
	<a href="/contact">Contact</a>
</nav>
✅ 良好示例 - 键盘快捷键：
typescript
import { useEffect } from 'react'

function SearchDialog({ onClose }: { onClose: () => void }) {
	useEffect(() => {
		function handleKeyDown(e: KeyboardEvent) {
			if (e.key === 'Escape') {
				onClose()
			}
		}

		window.addEventListener('keydown', handleKeyDown)
		return () => window.removeEventListener('keydown', handleKeyDown)
	}, [onClose])

	return <Dialog>{/* 内容 */}</Dialog>
}
✅ 良好示例 - 模态框中的焦点陷阱：
typescript
// Radix Dialog会自动处理焦点陷阱
<Dialog.Root>
	<Dialog.Content>
		{/* 焦点被限制在模态框内 */}
		<Dialog.Close>Close</Dialog.Close>
	</Dialog.Content>
</Dialog.Root>

Focus Management for React Router

React Router的焦点管理

✅ Good - Focus on route changes:
typescript
import { useEffect } from 'react'
import { useNavigation } from 'react-router'

function RouteComponent() {
	const navigation = useNavigation()
	const mainRef = useRef<HTMLElement>(null)

	useEffect(() => {
		if (navigation.state === 'idle' && mainRef.current) {
			mainRef.current.focus()
		}
	}, [navigation.state])

	return (
		<main ref={mainRef} tabIndex={-1}>
			{/* Content */}
		</main>
	)
}
✅ Good - Focus on errors:
typescript
import { useEffect, useRef } from 'react'

function FormWithErrorFocus({ actionData }: Route.ComponentProps) {
	const firstErrorRef = useRef<HTMLInputElement>(null)

	useEffect(() => {
		if (actionData?.errors && firstErrorRef.current) {
			// Focus first error field
			firstErrorRef.current.focus()
			// Announce error
			firstErrorRef.current.setAttribute('aria-invalid', 'true')
		}
	}, [actionData?.errors])

	return <Field inputProps={{ ref: firstErrorRef, ... }} />
}
✅ 良好示例 - 路由切换时的焦点定位：
typescript
import { useEffect } from 'react'
import { useNavigation } from 'react-router'

function RouteComponent() {
	const navigation = useNavigation()
	const mainRef = useRef<HTMLElement>(null)

	useEffect(() => {
		if (navigation.state === 'idle' && mainRef.current) {
			mainRef.current.focus()
		}
	}, [navigation.state])

	return (
		<main ref={mainRef} tabIndex={-1}>
			{/* 内容 */}
		</main>
	)
}
✅ 良好示例 - 焦点定位到错误：
typescript
import { useEffect, useRef } from 'react'

function FormWithErrorFocus({ actionData }: Route.ComponentProps) {
	const firstErrorRef = useRef<HTMLInputElement>(null)

	useEffect(() => {
		if (actionData?.errors && firstErrorRef.current) {
			// 焦点定位到第一个错误输入框
			firstErrorRef.current.focus()
			// 播报错误
			firstErrorRef.current.setAttribute('aria-invalid', 'true')
		}
	}, [actionData?.errors])

	return <Field inputProps={{ ref: firstErrorRef, ... }} />
}

Typography and Readability

排版与可读性

✅ Good - Readable text sizes:
typescript
// Use Tailwind's text size scale
<p className="text-base md:text-lg">Readable body text</p>
<h1 className="text-2xl md:text-3xl lg:text-4xl">Clear headings</h1>
✅ Good - Sufficient line height:
typescript
// Tailwind defaults provide good line height
<p className="leading-relaxed">Comfortable reading</p>
❌ Avoid - Small or hard-to-read text:
typescript
// ❌ Don't use very small text
<p className="text-xs">Hard to read</p>
✅ 良好示例 - 易读的文本尺寸：
typescript
// 使用Tailwind的文本尺寸比例
<p className="text-base md:text-lg">易读的正文文本</p>
<h1 className="text-2xl md:text-3xl lg:text-4xl">清晰的标题</h1>
✅ 良好示例 - 足够的行高：
typescript
// Tailwind默认值提供了良好的行高
<p className="leading-relaxed">舒适的阅读体验</p>
❌ 避免示例 - 过小或难以阅读的文本：
typescript
// ❌ 不要使用过小的文本
<p className="text-xs">难以阅读</p>

Touch Target Sizes

触摸目标尺寸

✅ Good - Sufficient touch targets:
typescript
// Buttons should be at least 44x44px (touch target size)
<button className="min-h-[44px] min-w-[44px] px-4 py-2">
	Click me
</button>
✅ Good - Spacing between interactive elements:
typescript
<div className="flex gap-4">
	<Button>Save</Button>
	<Button>Cancel</Button>
</div>
✅ 良好示例 - 足够的触摸目标：
typescript
// 按钮的触摸目标尺寸至少应为44x44px
<button className="min-h-[44px] min-w-[44px] px-4 py-2">
	Click me
</button>
✅ 良好示例 - 交互元素间的间距：
typescript
<div className="flex gap-4">
	<Button>Save</Button>
	<Button>Cancel</Button>
</div>

Internationalization (i18n) Considerations

国际化（i18n）注意事项

✅ Good - Use semantic HTML for dates/times:
typescript
<time dateTime={note.createdAt.toISOString()}>
	{formatDate(note.createdAt)}
</time>
✅ Good - Use semantic HTML for numbers:
typescript
// Screen readers can pronounce numbers correctly
<p>Total: <span aria-label={`${count} items`}>{count}</span></p>
✅ Good - Language attributes:
typescript
// In root.tsx
<html lang="en">
	<body>
		{/* Content */}
	</body>
</html>
✅ 良好示例 - 为日期/时间使用语义化HTML：
typescript
<time dateTime={note.createdAt.toISOString()}>
	{formatDate(note.createdAt)}
</time>
✅ 良好示例 - 为数字使用语义化HTML：
typescript
// 屏幕阅读器可以正确读取数字
<p>Total: <span aria-label={`${count} items`}>{count}</span></p>
✅ 良好示例 - 语言属性：
typescript
// 在root.tsx中
<html lang="en">
	<body>
		{/* 内容 */}
	</body>
</html>

Dark Mode Accessibility

深色模式无障碍设计

✅ Good - Maintain contrast in dark mode:
typescript
// Ensure sufficient contrast in both modes
<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">
	{content}
</div>
✅ Good - Respect user preference:
typescript
// Epic Stack automatically handles theme preference
// Use semantic colors that work in both modes
<button className="bg-blue-600 text-white hover:bg-blue-700 dark:bg-blue-500 dark:hover:bg-blue-600">
	Button
</button>
✅ 良好示例 - 在深色模式下保持对比度：
typescript
// 确保在两种模式下都有足够的对比度
<div className="bg-white text-gray-900 dark:bg-gray-900 dark:text-gray-100">
	{content}
</div>
✅ 良好示例 - 尊重用户偏好：
typescript
// Epic Stack会自动处理主题偏好
// 使用在两种模式下都适用的语义化颜色
<button className="bg-blue-600 text-white hover:bg-blue-700 dark:bg-blue-500 dark:hover:bg-blue-600">
	Button
</button>

Animation and Motion

动画与动效

✅ Good - Respect reduced motion:
typescript
// Tailwind automatically respects prefers-reduced-motion
<div className="transition-transform duration-200 hover:scale-105 motion-reduce:transition-none">
	{/* Animations disabled for users who prefer reduced motion */}
</div>
✅ Good - Use CSS for animations:
typescript
// ✅ CSS animations can be disabled via prefers-reduced-motion
<div className="animate-fade-in">
	{/* Content */}
</div>

// ❌ JavaScript animations may not respect user preferences
✅ 良好示例 - 尊重减少动效的偏好：
typescript
// Tailwind会自动尊重prefers-reduced-motion设置
<div className="transition-transform duration-200 hover:scale-105 motion-reduce:transition-none">
	{/* 对于偏好减少动效的用户，动画会被禁用 */}
</div>
✅ 良好示例 - 使用CSS实现动画：
typescript
// ✅ CSS动画可通过prefers-reduced-motion禁用
<div className="animate-fade-in">
	{/* 内容 */}
</div>

// ❌ JavaScript动画可能无法尊重用户偏好

Common mistakes to avoid

需避免的常见错误

  • ❌ Treating accessibility as a checklist: Accessibility is about serving real people, not just meeting standards
  • ❌ Missing form labels: Always use 
    Field
    component which includes labels - helps all users, not just screen reader users
  • ❌ Using divs for semantic elements: Use 
    <article>
    , 
    <header>
    , 
    <nav>
    , etc. - helps all users understand content structure
  • ❌ Ignoring keyboard navigation: Ensure all interactive elements are keyboard accessible - helps power users and those who can't use a mouse
  • ❌ Low color contrast: Test color combinations for WCAG AA compliance - helps users with visual impairments and in bright sunlight
  • ❌ Missing ARIA attributes: Use Epic Stack components which handle this automatically
  • ❌ Breaking focus management: Let Radix components handle focus
  • ❌ Not testing with screen readers: Test with VoiceOver, NVDA, or JAWS - understand how real users experience your UI
  • ❌ Hiding content from screen readers: Use 
    sr-only
    instead of 
    display: none
    for screen reader only content
  • ❌ Ignoring mobile users: Always test on mobile devices - many users only have mobile access
  • ❌ Not using Tailwind's responsive utilities: Use mobile-first responsive design
  • ❌ Not using live regions: Use 
    aria-live
    for dynamic content announcements
  • ❌ Small touch targets: Ensure interactive elements are at least 44x44px - helps users with motor impairments and on mobile
  • ❌ Ignoring reduced motion: Respect 
    prefers-reduced-motion
    media query - helps users with vestibular disorders
  • ❌ Poor focus indicators: Ensure focus is always visible - helps keyboard users navigate
  • ❌ Missing skip links: Add skip to main content links for keyboard users
  • ❌ 将无障碍设计视为勾选清单：无障碍设计是为真实用户服务，而非仅仅满足标准
  • ❌ 缺少表单标签：始终使用包含标签的
    Field
    组件 - 这对所有用户都有帮助，而不仅仅是屏幕阅读器用户
  • ❌ 使用div替代语义化元素：使用
    <article>
    、
    <header>
    、
    <nav>
    等元素 - 帮助所有用户理解内容结构
  • ❌ 忽略键盘导航：确保所有交互元素都支持键盘访问 - 帮助高级用户和无法使用鼠标的用户
  • ❌ 低颜色对比度：测试配色组合是否符合WCAG AA标准 - 帮助视障用户和在强光环境下的用户
  • ❌ 缺少ARIA属性：使用Epic Stack的组件，它们会自动处理这些
  • ❌ 破坏焦点管理：让Radix组件处理焦点
  • ❌ 未使用屏幕阅读器测试：使用VoiceOver、NVDA或JAWS进行测试 - 了解真实用户的UI体验
  • ❌ 向屏幕阅读器隐藏内容：对于仅屏幕阅读器可见的内容，使用
    sr-only
    而非
    display: none
  • ❌ 忽略移动端用户：始终在移动设备上进行测试 - 许多用户仅使用移动设备访问
  • ❌ 未使用Tailwind的响应式工具类：采用移动端优先的响应式设计
  • ❌ 未使用实时区域：使用
    aria-live
    播报动态内容
  • ❌ 过小的触摸目标：确保交互元素的尺寸至少为44x44px - 帮助行动不便的用户和移动端用户
  • ❌ 忽略减少动效的偏好：尊重
    prefers-reduced-motion
    媒体查询 - 帮助有前庭障碍的用户
  • ❌ 不清晰的焦点指示器：确保焦点始终可见 - 帮助键盘用户导航
  • ❌ 缺少跳转链接：为键盘用户添加跳转到主内容的链接

References

参考资料