@alliance-droid/svelte-docs-system 0.0.1

package/docs/en/config/theme-and-colors.md

@@ -0,0 +1,395 @@
+---
+title: Theme and Colors Configuration
+description: Customize colors, fonts, and appearance
+author: Andrew
+date: 2026-02-05
+---
+
+# Theme and Colors Configuration
+
+Learn how to customize the theme colors and appearance of your documentation site.
+
+## Quick Start
+
+The SvelteKit Documentation System comes with the Claude Code color palette built-in. To customize colors, edit your `tailwind.config.ts`:
+
+```typescript
+import type { Config } from 'tailwindcss';
+
+export default {
+  theme: {
+    extend: {
+      colors: {
+        'claude-bg': '#FFFFFF',           // Light background
+        'claude-bg-secondary': '#F7F6F3', // Light secondary background
+        'claude-text': '#1A1A1A',         // Light text
+        'claude-text-secondary': '#565656', // Light secondary text
+        'claude-border': '#ECECEC',       // Light borders
+        'claude-accent': '#0066CC',       // Light accent (blue)
+        'claude-accent-hover': '#0052A3', // Light accent hover
+
+        'claude-dark-bg': '#1A1A1A',      // Dark background
+        'claude-dark-bg-secondary': '#2D2D2D', // Dark secondary background
+        'claude-dark-text': '#FFFFFF',    // Dark text
+        'claude-dark-text-secondary': '#B0B0B0', // Dark secondary text
+        'claude-dark-border': '#3A3A3A',  // Dark borders
+        'claude-dark-accent': '#4D94FF',  // Dark accent (blue)
+        'claude-dark-accent-hover': '#6BA3FF', // Dark accent hover
+      },
+    },
+  },
+  darkMode: 'class',
+  plugins: [],
+} satisfies Config;
+```
+
+## Color Palette Reference
+
+### Light Mode Colors
+
+| Color | Usage | Default Value |
+|-------|-------|---------------|
+| `claude-bg` | Main background | `#FFFFFF` |
+| `claude-bg-secondary` | Secondary background (sidebar, cards) | `#F7F6F3` |
+| `claude-text` | Primary text | `#1A1A1A` |
+| `claude-text-secondary` | Secondary text (muted) | `#565656` |
+| `claude-border` | Borders and dividers | `#ECECEC` |
+| `claude-accent` | Links, buttons, highlights | `#0066CC` |
+| `claude-accent-hover` | Hover state for accent | `#0052A3` |
+
+### Dark Mode Colors
+
+| Color | Usage | Default Value |
+|-------|-------|---------------|
+| `claude-dark-bg` | Main background | `#1A1A1A` |
+| `claude-dark-bg-secondary` | Secondary background (sidebar, cards) | `#2D2D2D` |
+| `claude-dark-text` | Primary text | `#FFFFFF` |
+| `claude-dark-text-secondary` | Secondary text (muted) | `#B0B0B0` |
+| `claude-dark-border` | Borders and dividers | `#3A3A3A` |
+| `claude-dark-accent` | Links, buttons, highlights | `#4D94FF` |
+| `claude-dark-accent-hover` | Hover state for accent | `#6BA3FF` |
+
+## Customizing Your Palette
+
+### Example: Using Your Brand Colors
+
+If you want to use your own brand colors instead of Claude Code blue:
+
+```typescript
+export default {
+  theme: {
+    extend: {
+      colors: {
+        // Light mode - Warm brand palette
+        'claude-bg': '#FAFAF8',
+        'claude-bg-secondary': '#F3F0E6',
+        'claude-text': '#2C2416',
+        'claude-text-secondary': '#6B6457',
+        'claude-border': '#E8E3D3',
+        'claude-accent': '#D97706',      // Amber
+        'claude-accent-hover': '#B45309',
+
+        // Dark mode - Dark with amber accent
+        'claude-dark-bg': '#1F1812',
+        'claude-dark-bg-secondary': '#2D2620',
+        'claude-dark-text': '#FDF6EE',
+        'claude-dark-text-secondary': '#D1CFC4',
+        'claude-dark-border': '#3D3530',
+        'claude-dark-accent': '#FBBF24',  // Lighter amber
+        'claude-dark-accent-hover': '#FCD34D',
+      },
+    },
+  },
+} satisfies Config;
+```
+
+### Example: Green/Teal Theme
+
+```typescript
+export default {
+  theme: {
+    extend: {
+      colors: {
+        'claude-bg': '#FFFFFF',
+        'claude-bg-secondary': '#F0FFFE',
+        'claude-text': '#0F4C4F',
+        'claude-text-secondary': '#4A7C7E',
+        'claude-border': '#D1E8E7',
+        'claude-accent': '#059669',       // Emerald
+        'claude-accent-hover': '#047857',
+
+        'claude-dark-bg': '#0F4C4F',
+        'claude-dark-bg-secondary': '#1A6B6E',
+        'claude-dark-text': '#ECFDF5',
+        'claude-dark-text-secondary': '#A7D8CC',
+        'claude-dark-border': '#2D7A76',
+        'claude-dark-accent': '#6EE7B7',  // Light emerald
+        'claude-dark-accent-hover': '#A7F3D0',
+      },
+    },
+  },
+} satisfies Config;
+```
+
+## Global Styling
+
+Edit `src/app.css` to customize global styles:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  /* Custom font sizes */
+  h1 {
+    @apply text-4xl font-bold mb-4;
+  }
+
+  h2 {
+    @apply text-2xl font-bold mt-8 mb-3;
+  }
+
+  p {
+    @apply text-lg leading-7 mb-4;
+  }
+
+  /* Custom link styling */
+  a {
+    @apply text-claude-accent hover:text-claude-accent-hover;
+  }
+
+  /* Code block styling */
+  code {
+    @apply bg-claude-bg-secondary px-2 py-1 rounded;
+    font-family: 'Monaco', 'Courier New', monospace;
+  }
+}
+
+@layer components {
+  /* Custom components */
+  .doc-container {
+    @apply max-w-4xl mx-auto px-4 py-8;
+  }
+
+  .doc-section {
+    @apply mb-8 pb-8 border-b border-claude-border;
+  }
+}
+```
+
+## Dark Mode Configuration
+
+The documentation system uses Tailwind's `class` strategy for dark mode. This means:
+
+1. **Automatic detection:** Respects user's system preference
+2. **Manual override:** Users can toggle with the theme button
+3. **Persistence:** Theme preference is saved to localStorage
+
+### How Dark Mode Works
+
+The `theme` store in `src/lib/stores/theme.ts` manages the theme state:
+
+```typescript
+import { writable } from 'svelte/store';
+
+type Theme = 'light' | 'dark' | 'system';
+
+function createThemeStore() {
+  // Load from localStorage or default to 'system'
+  const stored = typeof localStorage !== 'undefined' 
+    ? localStorage.getItem('theme')
+    : 'system';
+
+  const { subscribe, set } = writable<Theme>(stored as Theme || 'system');
+
+  return {
+    subscribe,
+    set: (theme: Theme) => {
+      if (typeof document !== 'undefined') {
+        if (theme === 'dark') {
+          document.documentElement.classList.add('dark');
+        } else if (theme === 'light') {
+          document.documentElement.classList.remove('dark');
+        } else {
+          // System preference
+          if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+            document.documentElement.classList.add('dark');
+          } else {
+            document.documentElement.classList.remove('dark');
+          }
+        }
+      }
+      localStorage.setItem('theme', theme);
+      set(theme);
+    },
+  };
+}
+```
+
+## Typography
+
+The default typography uses system fonts for best performance:
+
+```css
+/* In src/app.css */
+@layer base {
+  :root {
+    --font-sans: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
+      'Helvetica Neue', Arial, 'Noto Sans', sans-serif;
+    --font-mono: 'Menlo', 'Monaco', 'Courier New', monospace;
+  }
+
+  body {
+    @apply font-sans;
+  }
+
+  code,
+  pre {
+    @apply font-mono;
+  }
+}
+```
+
+### Using Custom Fonts
+
+To use Google Fonts or other custom fonts:
+
+1. Add to `src/app.html`:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link
+  rel="preconnect"
+  href="https://fonts.gstatic.com"
+  crossorigin
+/>
+<link
+  href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;600;700&display=swap"
+  rel="stylesheet"
+/>
+```
+
+2. Configure in `tailwind.config.ts`:
+
+```typescript
+export default {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['Poppins', 'system-ui', 'sans-serif'],
+      },
+    },
+  },
+} satisfies Config;
+```
+
+## Spacing and Layout
+
+Customize spacing in `tailwind.config.ts`:
+
+```typescript
+export default {
+  theme: {
+    extend: {
+      spacing: {
+        '128': '32rem',
+        '144': '36rem',
+      },
+      maxWidth: {
+        'prose': '65ch',
+        'full': '100%',
+      },
+    },
+  },
+} satisfies Config;
+```
+
+## Component-Level Customization
+
+### Customizing DocLayout
+
+Edit `src/lib/components/DocLayout.svelte` to change:
+- Sidebar width
+- Navbar height
+- Footer content
+- Overall grid layout
+
+Example modification:
+
+```svelte
+<div class="grid grid-cols-1 lg:grid-cols-4 gap-8">
+  <!-- Change sidebar width from col-span-3 to col-span-4 -->
+  <aside class="lg:col-span-1">
+    <Sidebar {sections} {currentPath} />
+  </aside>
+  <main class="lg:col-span-3">
+    <!-- Content -->
+  </main>
+</div>
+```
+
+### Customizing Navbar
+
+Edit `src/lib/components/Navbar.svelte` to change:
+- Logo size
+- Button styles
+- Navigation items
+- Color scheme
+
+## CSS Variables
+
+For even more control, use CSS custom properties:
+
+```css
+:root {
+  --color-bg: #ffffff;
+  --color-bg-secondary: #f7f6f3;
+  --color-text: #1a1a1a;
+  --color-border: #ececec;
+  --color-accent: #0066cc;
+
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 1rem;
+}
+
+.dark {
+  --color-bg: #1a1a1a;
+  --color-bg-secondary: #2d2d2d;
+  --color-text: #ffffff;
+  --color-border: #3a3a3a;
+  --color-accent: #4d94ff;
+}
+```
+
+Then use in your components:
+
+```svelte
+<div class="bg-[var(--color-bg)] text-[var(--color-text)]">
+  Content
+</div>
+```
+
+## Testing Your Changes
+
+After updating colors:
+
+1. **Check dev server:** `npm run dev`
+2. **Test both themes:** Toggle dark mode in the UI
+3. **Check contrast:** Ensure text is readable on all backgrounds
+4. **Test on mobile:** Verify colors look good on small screens
+
+## Accessibility Considerations
+
+When customizing colors, ensure:
+
+- **WCAG AA compliance:** Text contrast ratio of at least 4.5:1
+- **WCAG AAA compliance:** Text contrast ratio of at least 7:1 (recommended)
+
+Use tools like [Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your colors.
+
+Example accessible combination:
+- Light background: `#FFFFFF`
+- Dark text: `#1A1A1A` (contrast ratio: 21:1)
+- Accent: `#0066CC` (meets WCAG AAA)