如何自訂 UI kit,同時保留無障礙功能
How to customize UI kits without breaking accessibility
文章説明如何透過設計 token、重設焦點樣式及包裝既有元件,自訂 UI kit 外觀而不破壞無障礙功能。作者建議檢查主要文字、按鈕和焦點環的對比,並在亮色與暗色主題下測試;互動元素應保留語義,避免把原始元件改寫成普通 <div>。合併前可用鍵盤測試登入、設定及聊天流程,並至少在一個平台進行螢幕閲讀器快速測試,例如 NVDA 或 VoiceOver。
The problem
You pull in a UI kit to move fast, then customize colors and spacing and suddenly focus states vanish, contrast fails in dark mode, and semantic buttons become plain <div>s.
Start with tokens, not components
The fastest way to rebrand without breaking things is to work at the token level: colors, spacing, radius, typography. Both the SaaS Starter Kit and AI UX Kit use CSS custom properties plus Tailwind tokens.
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
primary: {
50: "var(--color-primary-50)",
100: "var(--color-primary-100)",
600: "var(--color-primary-600)",
},
secondary: {
100: "var(--color-secondary-100)",
200: "var(--color-secondary-200)",
},
},
},
},
}
You customize the variables, not every component:
/* theme.css */
:root {
--color-primary-50: #f5f3ff;
--color-primary-100: #e0ddff;
--color-primary-600: #5b21ff; /* your brand color */
--color-secondary-100: #f4f4f5;
--color-secondary-200: #e4e4e7;
}
Because components consume tokens, they inherit your brand automatically while keeping spacing, hierarchy, and focus styling intact.
Keep contrast in check
Changing colors is the number one way to accidentally break accessibility.
Safe pattern:
- Change tokens in one place.
- Check contrast for key pairs:
-
primary-600on white - text on
secondary-100/secondary-200 - focus rings vs. backgrounds
-
- Test both light and dark themes if enabled.
Tools like @axe-core/react, browser devtools, or design tools can help, but the kits already start from WCAG-conscious defaults: you're adjusting from a good baseline.
Don't remove focus, restyle it
It's tempting to remove focus outlines completely. Instead, restyle them to match your brand. The kits ship components that already handle focus states; you just adjust tokens or utility classes.
import { Button, ButtonLabel } from "@/components/ui/primitives/button"
export function PrimaryAction() {
return (
<Button
action="primary"
className="focus-visible:ring-2 focus-visible:ring-primary-300 focus-visible:ring-offset-2"
>
<ButtonLabel>Save changes</ButtonLabel>
</Button>
)
}
If you want global customization, do it in one place:
/* globals.css */
:root {
--focus-ring-color: rgba(91, 33, 255, 0.35);
}
button:focus-visible,
input:focus-visible,
[role="button"]:focus-visible {
outline: 2px solid var(--focus-ring-color);
outline-offset: 2px;
}
This keeps keyboard navigation intact while still feeling on-brand.
Wrap, don't rewrite primitives
The fastest way to break accessibility is to copy-paste internal component code and start editing. Better pattern: wrap the existing primitive.
// app/components/BrandButton.tsx
import { Button, ButtonProps, ButtonLabel } from "@/components/ui/primitives/button"
type BrandButtonProps = ButtonProps & {
icon?: React.ReactNode
}
export function BrandButton({ children, icon, ...props }: BrandButtonProps) {
return (
<Button
action="primary"
className="rounded-full px-5 py-2 text-sm shadow-sm"
{...props}
>
{icon && <span className="mr-2">{icon}</span>}
<ButtonLabel>{children}</ButtonLabel>
</Button>
)
}
Now your app uses BrandButton everywhere, but all the underlying ARIA attributes, focus behavior, and disabled state handling still come from the original primitive.
Customizing complex components
Components like PromptInput (AI UX Kit) or MainSidebar (SaaS Starter Kit) are composed from primitives. To customize them safely:
- Identify what should be configurable props (labels, placeholder, icons, badges, etc.).
- Use Tailwind
classNameoverrides, not structural rewrites.
Example: customizing PromptInput styling and copy:
import {
PromptInput,
type PromptInputProps,
} from "@/components/ui/composites/prompt-input"
export function BrandedPromptInput(props: PromptInputProps) {
return (
<PromptInput
placeholder="Ask our assistant anything about your workspace..."
outlined
className="bg-basic-white border border-primary-100 shadow-sm"
{...props}
/>
)
}
You've changed the look and feel without touching semantic structure, keyboard handling, or file attachment and audio logic.
Anti-patterns to avoid
Common customization mistakes that break accessibility:
-
Turning everything into
<div>s: AvoidonClickon plaindivwithout role/keyboard handlers. Instead, use<button>,<a>, or wrap the existingButton/Linkcomponents. -
Removing focus outlines completely: Avoid
outline-noneorfocus-visible:outline-nonewith no replacement. Instead, restyle focus outlines via tokens or utilities. -
Hardcoding colors inside components: Avoid
className="text-[#888]"scattered across files. Instead, use token-driven classes liketext-secondary-600. -
Copy-pasting core components: Avoid duplicating internal primitives just to tweak spacing. Instead, wrap in your own component and override via
className.
Safe customization checklist
Before merging major visual changes:
Tokens
- All brand color changes go through design tokens / CSS variables.
- Contrast is checked for primary text, buttons, and focus rings.
Focus
- Focus styles are visible on all interactive elements.
- No global
outline: nonewithout a replacement.
Semantics
- Interactive elements use
<button>,<a>, or components that wrap them. - Icons used as buttons include accessible labels or are decorative only.
Structure
- Heavier customizations are done via wrappers, not internal rewrites.
- Layout changes don't hide or detach focusable elements.
Regression
- Key flows (auth, settings, chat) are tested with keyboard only.
- Screen reader smoke test on at least one platform (NVDA/VoiceOver).
This is a shorter version of a guide I wrote at Frontkit Studio. The full post has the complete walkthrough.
來源:DEV Community · dev.to