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.
Top comments (0)