跳到正文
DEV Community· Gaurav Guha·· 3 天前AI 評分52

如何自訂 UI kit,同時保留無障礙功能

How to customize UI kits without breaking accessibility

AI 導讀

文章説明如何透過設計 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:

  1. Change tokens in one place.
  2. Check contrast for key pairs:
    • primary-600 on white
    • text on secondary-100 / secondary-200
    • focus rings vs. backgrounds
  3. 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:

  1. Identify what should be configurable props (labels, placeholder, icons, badges, etc.).
  2. Use Tailwind className overrides, 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: Avoid onClick on plain div without role/keyboard handlers. Instead, use <button>, <a>, or wrap the existing Button/Link components.
  • Removing focus outlines completely: Avoid outline-none or focus-visible:outline-none with 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 like text-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: none without 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