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…
Customizing UI kits without compromising accessibility requires a methodical approach. Begin by working with tokens instead of individual components. This allows you to change colors, spacing, radius, and typography at the source, rather than modifying each component individually. Both the SaaS Starter Kit and AI UX Kit employ CSS custom properties along with Tailwind tokens, making this approach feasible.
Modify the variables instead of every component. In your CSS file, define your brand colors:
```css
:root {
--color-primary-50: #f5f3ff;
--color-primary-100: #e0ddff;
--color-primary-600: #5b21ff;
--color-secondary-100: #f4f4f5;
--color-secondary-200: #e4e4e7;
}
```
Components consume these tokens, inheriting your brand while preserving spacing, hierarchy, and focus styling. When altering colors, adhere to safe practices to avoid breaking accessibility. Adjust tokens in a single location and verify contrast for pivotal pairs, such as primary-600 on white text, secondary-100 or secondary-200. Utilize tools like @axe-core/react, browser developer tools, or design software to assist, but recognize that the kits initiate from WCAG-compliant defaults.
Avoid removing focus outlines; rather, style them to align with your brand. Most kits already include components that manage focus states, so your task is to adjust token values or utility classes. Import the necessary button component and apply focus-visible styles:
```jsx
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>Saving changes</ButtonLabel>
</Button>
);
}
```
For global customization, implement it in one place. Define global styles in a CSS file:
```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 method preserves keyboard navigation while maintaining an on-brand appearance. Instead of copying internal component code and editing it, wrap the existing primitive component. This preserves accessibility attributes like ARIA and focus behavior:
```jsx
// 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>
);
}
```
By wrapping the primitive, you utilize its existing ARIA attributes, focus behavior, and disabled state handling while customizing its appearance. This approach effectively customizes complex components, like PromptInput from the AI UX Kit or MainSidebar from the SaaS Starter Kit, without compromising accessibility. Identify which aspects should be customizable props (labels, placeholders, icons, badges, etc.) and employ Tailwind className overrides instead of structural modifications.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.