Copy page

Configuration

Colors & Theme

Zudoku provides flexible theming options allowing you to customize colors, import themes from shadcn registries, and add custom CSS. You can create cohesive light and dark mode experiences that match your brand.

The theme system is built on shadcn/ui theming and Tailwind v4, giving us a great foundation to build upon:

• CSS variables match shadcn/ui conventions
• Tailwind v4 CSS variable system for modern styling
• Theme editors like tweakcn work out of the box
• Shadcn registries are supported

Custom Colors

You can manually define colors for both light and dark modes, either by extending the default theme or creating a completely custom theme. Colors can be specified as hex values, RGB, HSL, OKLCH, etc. - basically anything that is supported by Tailwind CSS:

zudoku.config.ts
const config = {
  theme: {
    light: {
      background: "#ffffff",
      foreground: "#020817",
      card: "#ffffff",
      cardForeground: "#020817",
      popover: "#ffffff",
      popoverForeground: "#020817",
      primary: "#0284c7",
      primaryForeground: "#ffffff",
      secondary: "#f1f5f9",
      secondaryForeground: "#020817",
      muted: "#f1f5f9",
      mutedForeground: "#64748b",
      accent: "#f1f5f9",
      accentForeground: "#020817",
      destructive: "#ef4444",
      destructiveForeground: "#ffffff",
      border: "#e2e8f0",
      input: "#e2e8f0",
      ring: "#0284c7",
      radius: "0.5rem",
    },
    dark: {
      background: "#020817",
      foreground: "#f8fafc",
      card: "#020817",
      cardForeground: "#f8fafc",
      popover: "#020817",
      popoverForeground: "#f8fafc",
      primary: "#0ea5e9",
      primaryForeground: "#f8fafc",
      secondary: "#1e293b",
      secondaryForeground: "#f8fafc",
      muted: "#1e293b",
      mutedForeground: "#94a3b8",
      accent: "#1e293b",
      accentForeground: "#f8fafc",
      destructive: "#ef4444",
      destructiveForeground: "#f8fafc",
      border: "#1e293b",
      input: "#1e293b",
      ring: "#0ea5e9",
      radius: "0.5rem",
    },
  },
};

Available Theme Variables

Variable	Description
background	Main background color
foreground	Main text color
card	Card background color
cardForeground	Card text color
popover	Popover background color
popoverForeground	Popover text color
primary	Primary action color
primaryForeground	Text color on primary backgrounds
secondary	Secondary action color
secondaryForeground	Text color on secondary backgrounds
muted	Muted/subtle background color
mutedForeground	Text color for muted elements
accent	Accent color for highlights
accentForeground	Text color on accent backgrounds
destructive	Color for destructive actions
destructiveForeground	Text color on destructive backgrounds
border	Border color
input	Input field border color
ring	Focus ring color
radius	Border radius value

shadcn Registry Integration

The easiest way to customize your theme is by using a Shadcn registry theme. For example you can use the great tweakcn visual theme editor.

Using tweakcn Themes

You can still override specific values if needed:

zudoku.config.ts
const config = {
  theme: {
    registryUrl: "https://tweakcn.com/api/registry/theme/xyz123",
    // Override specific colors
    light: {
      primary: "#0066cc",
    },
    dark: {
      primary: "#3399ff",
    },
  },
};

Alternatively, paste the copied CSS into a stylesheet and import it from your config:

styles.css
/* Copied CSS code */

zudoku.config.ts
import "./styles.css";

Custom CSS

The recommended way to add custom styles is to write a .css file alongside your config and import it. This gives you HMR during development, syntax highlighting, autocompletion, and lets you split styles across files as your site grows.

styles.css
.custom {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

zudoku.config.ts
import "./styles.css";

const config = {
  // ...
};

If TypeScript reports Cannot find module './styles.css', add zudoku/client to your tsconfig types so CSS side-effect imports are recognized:

tsconfig.json
{
  "compilerOptions": {
    "types": ["zudoku/client"]
  }
}

Projects created with create-zudoku include this by default.

Inline alternatives (deprecated)

The theme.customCss option is deprecated and will be removed in a future release. It still accepts a CSS string or object for backwards compatibility, but every change requires restarting the dev server and you lose syntax highlighting, autocompletion, and HMR. Migrate to an imported .css file.

zudoku.config.ts
const config = {
  theme: {
    customCss: `
      .custom {
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
      }
    `,
  },
};

Enabling Code Ligatures

Zudoku disables ligatures in code blocks by default to avoid unwanted glyph joining in fonts like Geist Mono (e.g. ---, ###, |--|). If you're using a coding font designed around ligatures (Fira Code, JetBrains Mono, etc.), re-enable them in your CSS file:

styles.css
code,
pre,
kbd,
samp,
.shiki,
.shiki span {
  font-variant-ligatures: normal;
  font-feature-settings: normal;
}

Default Theme

Zudoku comes with a built-in default theme based on shadcn/ui zinc base colors. If you want to start completely from scratch without any default styling, you can disable the default theme:

zudoku.config.ts
const config = {
  theme: {
    noDefaultTheme: true,
    // Your custom theme configuration
  },
};

When noDefaultTheme is set to true, no default colors or styling will be applied, giving you complete control over your theme. Changing this requires to restart the development server.

Complete Example

Here's a comprehensive example combining multiple theming approaches:

zudoku.config.ts
const config = {
  theme: {
    // Import base theme from registry
    registryUrl: "https://tweakcn.com/api/registry/theme/modern-blue",

    // Override specific colors
    light: {
      primary: "#0066cc",
      accent: "#f0f9ff",
    },
    dark: {
      primary: "#3399ff",
      accent: "#0c1b2e",
    },

    // Custom fonts
    fonts: {
      sans: "Inter",
      mono: "JetBrains Mono",
    },

    // Additional custom styling
    customCss: {
      ".hero-section": {
        background: "var(--primary)",
        color: "var(--primary-foreground)",
        padding: "2rem",
        "border-radius": "var(--radius)",
      },
    },
  },
};

This configuration imports a base theme, customizes colors for both light and dark modes, sets fonts, and adds custom component styling.