Customization

Last updated on 2026-04-14

The A11y Starter Kit is designed to be customized. This guide covers theming, layout changes, adding pages, and extending the component library.

Rebranding

1. Update Colors

Open app/globals.css and modify the oklch tokens in the @theme block:

@theme {
    --color-primary: oklch(0.45 0.2 260);       /* Your brand hue */
    --color-primary-foreground: oklch(0.985 0.01 260);
}

Verify contrast ratios with the Color Contrast Checker or the Tailwind Theme Preview.

2. Update Fonts

Fonts are configured in app/layout.tsx via next/font:

import { Inter, DM_Sans, JetBrains_Mono } from 'next/font/google';

const inter = Inter({ subsets: ['latin'], variable: '--font-inter' });
const dmSans = DM_Sans({ subsets: ['latin'], variable: '--font-dm-sans' });

Replace with your brand fonts while keeping the CSS variable names consistent.

3. Update Metadata

Edit app/layout.tsx to set your app name, description, and Open Graph tags:

export const metadata: Metadata = {
    title: 'Your App Name',
    description: 'Your app description',
};

4. Replace Logo

The logo is rendered in the sidebar component at components/layout/sidebar.tsx. Replace the SVG or image with your own.

Adding New Pages

Create a new route in app/:

app/
├── your-page/
│   └── page.tsx

Follow the component hierarchy:
- Use primitives from components/ui/
- Create domain composites in components/your-domain/
- Wire them together in the page
Add the page to the sidebar navigation in components/layout/sidebar.tsx.
Include accessibility patterns:
- Set <main id="main-content"> for skip link targeting
- Use useAnnounce() for dynamic status updates
- Ensure all interactive elements are keyboard accessible

Adding Components

Using shadcn/ui

Add new shadcn/ui components via the CLI:

npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu

Components are installed to components/ui/ and come with built-in keyboard navigation and ARIA attributes.

Custom Components

When building custom components, follow these accessibility patterns:

// 1. Use semantic HTML
<nav aria-label="Main navigation">

// 2. Add ARIA attributes where needed
<button aria-expanded={isOpen} aria-controls="menu-panel">

// 3. Handle keyboard events
onKeyDown={(e) => {
    if (e.key === 'Escape') close();
}}

// 4. Announce dynamic changes
const announce = useAnnounce();
announce('Item added to cart');

The sidebar is in components/layout/sidebar.tsx. To add or remove navigation items, edit the items array:

const navItems = [
    { label: 'Dashboard', href: '/dashboard', icon: LayoutDashboardIcon },
    { label: 'Your Page', href: '/your-page', icon: YourIcon },
    // Add or remove items here
];

Dark Mode

Dark mode is handled by next-themes and configured in app/layout.tsx:

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
    {children}
</ThemeProvider>

The toggle is in the settings page. All color tokens automatically swap between light and dark values via the .dark class in globals.css.

Removing Pages You Don't Need

Delete the route folder from app/
Remove the entry from the sidebar navigation
Remove any related seed data from data/seed.ts
Remove unused components from components/

The kit is modular -- removing a page won't break other pages.

Deployment

The kit deploys like any Next.js app:

# Build for production
npm run build

# Start production server
npm start

Works with Vercel, Netlify, AWS, Docker, or any Node.js hosting platform.

Design Tokens

FAQ