Theming & Customization

Make Specra your own. This guide covers everything from simple color changes to complete custom styling.

Quick Customization

The fastest way to customize your docs is through specra.config.json.

Brand Colors

Set your primary color to match your brand:

Code

json

1{
2  "theme": {
3    "primaryColor": "#3b82f6"
4  }
5}

Specra automatically generates all color variations (hover states, focus rings, etc.) from this single value.

Dark Mode Settings

Control how dark mode works:

Code

json

1{
2  "theme": {
3    "defaultMode": "system",
4    "respectPrefersColorScheme": true
5  }
6}

Options for defaultMode:

"system" - Respect user's OS preference (recommended)
"light" - Always start in light mode
"dark" - Always start in dark mode

Set respectPrefersColorScheme to false to ignore OS settings and only use your default.

Logos

Add your logo for light and dark modes:

Code

json

1{
2  "site": {
3    "logo": {
4      "light": "/logo-light.svg",
5      "dark": "/logo-dark.svg"
6    }
7  }
8}

Or use a single logo for both:

Code

json

1{
2  "site": {
3    "logo": "/logo.svg"
4  }
5}

Place logo files in the public/ directory.

Custom CSS

For deeper customization, add custom CSS.

Method 1: Custom CSS File

Create a CSS file and reference it in config:

1. Create /public/custom.css:

Code

css

1:root {
2  --font-heading: 'Inter', system-ui, sans-serif;
3  --border-radius: 12px;
4}
5 
6.doc-content h1 {
7  font-size: 3rem;
8  color: var(--color-primary);
9}
10 
11.sidebar {
12  background: linear-gradient(to bottom, #f8f9fa, #ffffff);
13}

2. Reference in config:

Code

json

1{
2  "theme": {
3    "customCss": "/custom.css"
4  }
5}

Method 2: Global Styles

Edit app/globals.css directly for more control:

Code

css

1@tailwind base;
2@tailwind components;
3@tailwind utilities;
4 
5@layer base {
6  :root {
7    /* Your custom properties */
8    --radius: 0.75rem;
9  }
10}
11 
12@layer components {
13  /* Your custom component styles */
14  .custom-card {
15    @apply rounded-lg border border-gray-200 p-4;
16  }
17}

CSS Variables Reference

Specra uses CSS variables for theming. Override these to customize appearance:

Colors

Code

css

1:root {
2  /* Primary brand color */
3  --color-primary: #3b82f6;
4  --color-primary-hover: #2563eb;
5  --color-primary-light: #dbeafe;
6 
7  /* Background colors */
8  --color-bg: #ffffff;
9  --color-bg-secondary: #f9fafb;
10  --color-bg-tertiary: #f3f4f6;
11 
12  /* Text colors */
13  --color-text: #111827;
14  --color-text-secondary: #6b7280;
15  --color-text-tertiary: #9ca3af;
16 
17  /* Border colors */
18  --color-border: #e5e7eb;
19  --color-border-hover: #d1d5db;
20 
21  /* Code block colors */
22  --color-code-bg: #f3f4f6;
23  --color-code-text: #1f2937;
24}
25 
26.dark {
27  --color-bg: #111827;
28  --color-bg-secondary: #1f2937;
29  --color-bg-tertiary: #374151;
30 
31  --color-text: #f9fafb;
32  --color-text-secondary: #d1d5db;
33  --color-text-tertiary: #9ca3af;
34 
35  --color-border: #374151;
36  --color-border-hover: #4b5563;
37 
38  --color-code-bg: #1f2937;
39  --color-code-text: #f9fafb;
40}

Typography

Code

css

1:root {
2  /* Font families */
3  --font-sans: system-ui, -apple-system, sans-serif;
4  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
5  --font-heading: var(--font-sans);
6 
7  /* Font sizes */
8  --text-xs: 0.75rem;
9  --text-sm: 0.875rem;
10  --text-base: 1rem;
11  --text-lg: 1.125rem;
12  --text-xl: 1.25rem;
13  --text-2xl: 1.5rem;
14  --text-3xl: 1.875rem;
15  --text-4xl: 2.25rem;
16 
17  /* Line heights */
18  --leading-tight: 1.25;
19  --leading-normal: 1.5;
20  --leading-relaxed: 1.75;
21}

Spacing

Code

css

1:root {
2  /* Border radius */
3  --radius-sm: 0.25rem;
4  --radius: 0.5rem;
5  --radius-md: 0.75rem;
6  --radius-lg: 1rem;
7  --radius-xl: 1.5rem;
8 
9  /* Shadows */
10  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
11  --shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
12  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
13  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
14}

Custom Fonts

Using Google Fonts

1. Add font to your layout:

Code

tsx

1// app/layout.tsx
2// Use @fontsource packages for fonts in SvelteKit
3 
4const inter = Inter({ subsets: ['latin'] })
5const jetbrainsMono = JetBrains_Mono({ subsets: ['latin'] })
6 
7export default function RootLayout({ children }) {
8  return (
9    <html lang="en" className={`${inter.className}`}>
10      <body>{children}</body>
11    </html>
12  )
13}

2. Update CSS variables:

Code

css

1:root {
2  --font-sans: 'Inter', system-ui, sans-serif;
3  --font-mono: 'JetBrains Mono', monospace;
4}

Using Local Fonts

Place font files in public/fonts/ and load them:

Code

css

1@font-face {
2  font-family: 'CustomFont';
3  src: url('/fonts/custom-font.woff2') format('woff2');
4  font-weight: 400;
5  font-style: normal;
6  font-display: swap;
7}
8 
9:root {
10  --font-sans: 'CustomFont', system-ui, sans-serif;
11}

Layout Customization

Adjust sidebar width in your custom CSS:

Code

css

1.sidebar {
2  width: 280px; /* Default is 260px */
3}
4 
5@media (min-width: 1280px) {
6  .sidebar {
7    width: 320px;
8  }
9}

Content Width

Change maximum content width:

Code

css

1.doc-content {
2  max-width: 850px; /* Default is 800px */
3}

Table of Contents Position

Control TOC position via config:

Code

json

1{
2  "navigation": {
3    "tocPosition": "right",
4    "showTableOfContents": true
5  }
6}

Options: "left" or "right"

Component Styling

Callout Styles

Customize callout appearance:

Code

css

1.callout {
2  border-left-width: 4px;
3  border-radius: var(--radius-lg);
4  padding: 1rem 1.5rem;
5}
6 
7.callout-info {
8  background: #dbeafe;
9  border-color: #3b82f6;
10  color: #1e3a8a;
11}
12 
13.callout-warning {
14  background: #fef3c7;
15  border-color: #f59e0b;
16  color: #92400e;
17}
18 
19.dark .callout-info {
20  background: #1e3a8a;
21  color: #dbeafe;
22}

Code Block Styling

Customize syntax highlighting:

Code

css

1.code-block {
2  border-radius: var(--radius-lg);
3  font-size: 0.9rem;
4  line-height: 1.7;
5}
6 
7.code-block-title {
8  background: #374151;
9  color: #f9fafb;
10  font-family: var(--font-mono);
11  padding: 0.5rem 1rem;
12  border-radius: var(--radius-lg) var(--radius-lg) 0 0;
13}

Card Styling

Style card components:

Code

css

1.card {
2  border: 1px solid var(--color-border);
3  border-radius: var(--radius-lg);
4  padding: 1.5rem;
5  transition: all 0.2s;
6}
7 
8.card:hover {
9  border-color: var(--color-primary);
10  box-shadow: var(--shadow-md);
11  transform: translateY(-2px);
12}

Tailwind Configuration

Extend Tailwind for custom utilities:

Code

typescript

1// tailwind.config.ts
2import type { Config } from 'tailwindcss'
3 
4const config: Config = {
5  content: [
6    './app/**/*.{ts,tsx}',
7    './components/**/*.{ts,tsx}',
8    './docs/**/*.{md,mdx}',
9  ],
10  theme: {
11    extend: {
12      colors: {
13        brand: {
14          50: '#f0f9ff',
15          100: '#e0f2fe',
16          500: '#0ea5e9',
17          600: '#0284c7',
18          700: '#0369a1',
19        },
20      },
21      fontFamily: {
22        sans: ['Inter', 'system-ui', 'sans-serif'],
23        mono: ['JetBrains Mono', 'monospace'],
24      },
25      borderRadius: {
26        '4xl': '2rem',
27      },
28    },
29  },
30  plugins: [],
31}
32 
33export default config

Use custom utilities in your CSS or MDX:

Code

mdx

1<div className="bg-brand-50 dark:bg-brand-900 rounded-4xl p-6">
2  Custom styled content
3</div>

Add custom navigation links:

Code

json

1{
2  "navigation": {
3    "links": [
4      { "label": "Home", "href": "/" },
5      { "label": "Docs", "href": "/docs" },
6      { "label": "Blog", "href": "/blog" },
7      { "label": "GitHub", "href": "https://github.com/..." }
8    ]
9  }
10}

Display social icons in header:

Code

json

1{
2  "social": {
3    "github": "https://github.com/yourusername",
4    "twitter": "https://twitter.com/yourusername",
5    "discord": "https://discord.gg/invite",
6    "custom": [
7      {
8        "label": "YouTube",
9        "url": "https://youtube.com/@channel",
10        "icon": "youtube"
11      }
12    ]
13  }
14}

Customize footer content and links:

Code

json

1{
2  "footer": {
3    "copyright": "© 2024 Your Company. All rights reserved.",
4    "links": [
5      {
6        "title": "Product",
7        "items": [
8          { "label": "Features", "href": "/features" },
9          { "label": "Pricing", "href": "/pricing" }
10        ]
11      },
12      {
13        "title": "Resources",
14        "items": [
15          { "label": "Documentation", "href": "/docs" },
16          { "label": "API Reference", "href": "/api" }
17        ]
18      }
19    ],
20    "branding": {
21      "showBranding": true,
22      "logo": "/footer-logo.svg",
23      "title": "Your Brand",
24      "url": "https://yoursite.com"
25    }
26  }
27}

Advanced Customization

Custom Components

Create custom MDX components:

Code

tsx

1// components/custom/feature-grid.tsx
2interface FeatureGridProps {
3  children: React.ReactNode
4}
5 
6export function FeatureGrid({ children }: FeatureGridProps) {
7  return (
8    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
9      {children}
10    </div>
11  )
12}

Use in MDX:

Code

mdx

1import { FeatureGrid } from '@/components/custom/feature-grid'
2 
3<FeatureGrid>
4  <Card title="Feature 1" />
5  <Card title="Feature 2" />
6  <Card title="Feature 3" />
7</FeatureGrid>

Custom Layout

Override the default doc layout:

Code

tsx

1// app/docs/[...slug]/layout.tsx
2import { CustomDocLayout } from '@/components/layouts/custom-doc-layout'
3 
4export default function DocsLayout({ children }) {
5  return <CustomDocLayout>{children}</CustomDocLayout>
6}

Custom Search UI

Replace the default search component:

Code

tsx

1// components/search/custom-search.tsx
2export function CustomSearch() {
3  return (
4    <div className="search-container">
5      {/* Your custom search implementation */}
6    </div>
7  )
8}

Examples

Minimal Clean Theme

Code

css

1:root {
2  --color-primary: #000000;
3  --radius: 0.25rem;
4  --font-sans: 'Helvetica Neue', Arial, sans-serif;
5}
6 
7.doc-content {
8  max-width: 700px;
9  font-size: 1.125rem;
10  line-height: 1.8;
11}
12 
13.sidebar {
14  border-right: 1px solid #e5e7eb;
15  background: #ffffff;
16}

Vibrant Modern Theme

Code

css

1:root {
2  --color-primary: #8b5cf6;
3  --color-primary-hover: #7c3aed;
4  --radius-lg: 1.5rem;
5  --font-heading: 'Outfit', system-ui, sans-serif;
6}
7 
8.card {
9  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
10  color: white;
11  border: none;
12}
13 
14.callout {
15  background: linear-gradient(to right, #fef3c7, #fed7aa);
16  border: 2px solid #f59e0b;
17}

Dark-First Theme

Code

css

1:root {
2  --color-bg: #0a0a0a;
3  --color-bg-secondary: #141414;
4  --color-text: #fafafa;
5  --color-border: #262626;
6  --color-primary: #10b981;
7}
8 
9.sidebar {
10  background: #0a0a0a;
11  border-right: 1px solid #262626;
12}
13 
14.doc-content {
15  color: #d4d4d4;
16}
17 
18code {
19  background: #1a1a1a;
20  color: #10b981;
21}

Best Practices

Start small. Begin with config-based customization before writing custom CSS.

Use CSS variables. They make theme switching and maintenance easier.

Test dark mode. Always test your customizations in both light and dark modes.

Keep it accessible. Ensure sufficient color contrast (4.5:1 for body text, 3:1 for large text).

Optimize fonts. Use font-display: swap and subset fonts to improve load times.

Mobile first. Test your customizations on mobile devices.

Next Steps

Components

Build custom MDX components

Configuration

Full configuration reference

Documentation

Theming & Customization

Theming & Customization

Quick Customization

Brand Colors

Dark Mode Settings

Logos

Custom CSS

Method 1: Custom CSS File

Method 2: Global Styles

CSS Variables Reference

Colors

Typography

Spacing

Custom Fonts

Using Google Fonts

Using Local Fonts

Layout Customization

Sidebar Width

Content Width

Table of Contents Position

Component Styling

Callout Styles

Code Block Styling

Card Styling

Tailwind Configuration

Navigation Customization

Top Navigation Links

Social Links

Footer Customization

Advanced Customization

Custom Components

Custom Layout

Custom Search UI

Examples

Minimal Clean Theme

Vibrant Modern Theme

Dark-First Theme

Best Practices

Next Steps

Components

Configuration