S
Specra Docs
You are viewing the v1.0.0 documentation.
Specra Docs Comprehensive documentation for your project

Documentation

Theming & Customization

Customize colors, fonts, layouts, and styles to match your brand

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"

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}

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

Edit this page Report an issue
Previous
Search Setup
Next
Tab Groups