Theming

Sona UI is built with Tailwind CSS, making theming straightforward and flexible. Components use semantic CSS variables and work with any light/dark mode strategy. This documentation site uses next-themes, while Vite projects can use the same tokens with their preferred theme provider.

Sona theme foundation

Most components use the standard semantic tokens created by shadcn, including background, foreground, primary, muted, accent, popover, border, and ring.

Components that need Sona-specific tokens declare sona-theme as a registry dependency. The shadcn CLI merges those CSS variables into the consumer's Tailwind CSS v4 theme automatically. The foundation is intentionally small and currently adds the Sona radius plus danger-state colors; it does not copy the documentation site's full stylesheet into consumer projects.

You can override these values after installation. Components continue to reference semantic names, so custom themes do not require editing component internals.

Dark Mode

Sona UI components are designed to look great in both light and dark modes. We use CSS variables (custom properties) to handle color schemes, which makes it easy to switch themes without rewriting styles.

Setting up next-themes

For a Next.js application using next-themes, install the package and wrap your application in a ThemeProvider. This step is not required for Vite projects using a different theme strategy.

npm install next-themes

src/app/providers.tsx

// src/app/providers.tsx
"use client";
 
import type * as React from "react";
import { ThemeProvider as NextThemesProvider } from "next-themes";
 
export function ThemeProvider({
children,
...props
}: React.ComponentProps<typeof NextThemesProvider>) {
return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
}

Then use it in your layout:

src/app/layout.tsx

// src/app/layout.tsx
import { ThemeProvider } from "./providers";
 
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
  <html lang="en" suppressHydrationWarning>
    <body>
      <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
        {children}
      </ThemeProvider>
    </body>
  </html>
);
}

Customizing Colors

You can customize the color palette by overriding the CSS variables in your Tailwind CSS entry file, usually src/app/globals.css in a Next.js app. Sona UI uses standard semantic variable names like --background, --foreground, --primary, and --border.

css

src/app/globals.css

@theme {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--radius-lg: var(--radius);
}
 
:root {
--radius: 0.75rem;
--background: oklch(0.98 0 0);
--foreground: oklch(0.18 0 0);
--card: oklch(1 0 0);
--card-foreground: oklch(0.27 0 0);
--popover: oklch(1 0 0);
--popover-foreground: oklch(0.27 0 0);
--primary: oklch(0.6 0.2 250);
--primary-foreground: oklch(1 0 0);
--secondary: oklch(0.95 0 0);
--secondary-foreground: oklch(0.32 0 0);
--muted: oklch(0.95 0 0);
--muted-foreground: oklch(0.5 0 0);
--accent: oklch(0.91 0 0);
--accent-foreground: oklch(0.22 0 0);
--destructive: oklch(0.53 0.19 25);
--destructive-foreground: oklch(0.98 0 0);
--border: oklch(0 0 0 / 8%);
--input: oklch(0.95 0 0);
--ring: oklch(0.55 0.2 250);
}
 
.dark {
--background: oklch(0.19 0 0);
--foreground: oklch(0.94 0 0);
--card: oklch(0.21 0 0);
--card-foreground: oklch(0.94 0 0);
--popover: oklch(0.21 0 0);
--popover-foreground: oklch(0.94 0 0);
--secondary: oklch(0.28 0 0);
--secondary-foreground: oklch(0.94 0 0);
--muted: oklch(0.26 0 0);
--muted-foreground: oklch(0.73 0 0);
--accent: oklch(0.31 0 0);
--accent-foreground: oklch(0.95 0 0);
--destructive: oklch(0.5 0.22 25);
--destructive-foreground: oklch(1 0 0);
--border: oklch(1 0 0 / 10%);
--input: oklch(1 0 0 / 15%);
}

When you use next-themes with attribute="class", prefer explicit :root and .dark values like the example above. That keeps theme switching controlled by the .dark class instead of depending on the browser's color-scheme.

Styling Components

Since Sona UI gives you the source code, you can style individual components directly in the TSX files using standard Tailwind classes.

// Example: Changing the background color of an Accordion item
<AccordionItem className="bg-blue-50 dark:bg-blue-900" ... />