DEV Community

Gaurav Guha
Gaurav Guha

Posted on Originally published at thefrontkit.com

How to customize UI kits without breaking accessibility

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)",
        },
      },
    },
  },
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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>
  )
}
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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>
  )
}
Enter fullscreen mode Exit fullscreen mode

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}
    />
  )
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)