@happyvertical/smrt-ui 0.30.0

package/dist/themes/CUSTOM_THEME_GUIDE.md

@@ -0,0 +1,341 @@
+# Custom Theme Guide
+
+This guide shows how to create and use custom themes in your own project repository.
+
+## Project Structure
+
+```
+my-project/
+├── src/
+│   ├── lib/
+│   │   └── themes/
+│   │       ├── brand.ts          # TypeScript theme definition
+│   │       ├── brand.css         # CSS override file
+│   │       └── index.ts          # Export and registration
+│   ├── routes/
+│   │   └── +layout.svelte        # Use your theme
+│   └── app.html                  # Set data attributes
+├── static/
+│   └── themes/                   # Static CSS files (optional)
+└── package.json
+```
+
+## Method 1: TypeScript Theme (Recommended)
+
+### 1. Create Theme Definition
+
+```typescript
+// src/lib/themes/brand.ts
+import { createTheme, registerTheme } from '@happyvertical/smrt-ui/themes';
+import type { Theme } from '@happyvertical/smrt-ui/themes';
+
+export const brandTheme: Theme = createTheme({
+  id: 'brand',
+  name: 'My Brand',
+  
+  // Start from Material as a base
+  extend: 'material',
+  
+  // Define your brand colors
+  light: {
+    primary: '#6366f1',        // Indigo
+    secondary: '#8b5cf6',      // Purple
+    tertiary: '#ec4899',       // Pink
+    background: '#fafafa',
+    surface: '#ffffff',
+    error: '#ef4444',
+    success: '#10b981',
+    warning: '#f59e0b',
+  },
+  
+  // Define dark mode (or let it auto-generate)
+  dark: {
+    primary: '#818cf8',
+    secondary: '#a78bfa',
+    tertiary: '#f472b6',
+    background: '#0f172a',
+    surface: '#1e293b',
+  },
+  
+  // Use your brand font
+  fontFamily: '"Inter var", "Inter", system-ui, sans-serif',
+  
+  // Optional: Custom border radius
+  borderRadius: {
+    none: '0',
+    sm: '0.25rem',
+    md: '0.5rem',
+    lg: '0.75rem',
+    xl: '1rem',
+    '2xl': '1.25rem',
+    '3xl': '1.5rem',
+    full: '9999px',
+  },
+});
+
+// Auto-register when imported
+registerTheme(brandTheme);
+```
+
+### 2. Export Theme
+
+```typescript
+// src/lib/themes/index.ts
+export { brandTheme } from './brand.js';
+```
+
+### 3. Use in Layout
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+  // Import to register the theme
+  import '$lib/themes';
+  
+  // Import base CSS
+  import '@happyvertical/smrt-ui/themes/styles/all.css';
+  
+  // Your custom theme CSS (optional overrides)
+  import '$lib/themes/brand.css';
+  
+  import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
+</script>
+
+<ThemeProvider preset="brand" colorScheme="system" persist={true}>
+  {@render children()}
+</ThemeProvider>
+```
+
+### 4. Optional CSS Overrides
+
+```css
+/* src/lib/themes/brand.css */
+/* Fine-tune specific components */
+
+[data-theme="brand"] {
+  /* Custom component styles */
+  --my-brand-header-height: 64px;
+  --my-brand-sidebar-width: 240px;
+}
+
+[data-theme="brand"] .my-brand-button {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## Method 2: CSS-Only Theme
+
+For simpler cases, you can define a theme entirely in CSS:
+
+```css
+/* src/styles/my-theme.css */
+
+/* Import base structure */
+@import '@happyvertical/smrt-ui/themes/styles/material.css';
+
+/* Define light mode */
+[data-theme="mybrand"][data-color-scheme="light"] {
+  /* Primary palette */
+  --smrt-color-primary: #0ea5e9;
+  --smrt-color-on-primary: #ffffff;
+  --smrt-color-primary-container: #e0f2fe;
+  --smrt-color-on-primary-container: #075985;
+  
+  /* Secondary palette */
+  --smrt-color-secondary: #64748b;
+  --smrt-color-on-secondary: #ffffff;
+  --smrt-color-secondary-container: #f1f5f9;
+  --smrt-color-on-secondary-container: #334155;
+  
+  /* Surfaces */
+  --smrt-color-surface: #ffffff;
+  --smrt-color-surface-variant: #f8fafc;
+  --smrt-color-background: #f1f5f9;
+  --smrt-color-on-surface: #0f172a;
+  
+  /* Semantic colors */
+  --smrt-color-error: #ef4444;
+  --smrt-color-success: #22c55e;
+  --smrt-color-warning: #f59e0b;
+  
+  /* Custom typography */
+  --smrt-font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
+  
+  /* Custom spacing (optional) */
+  --smrt-spacing-1: 0.25rem;
+  --smrt-spacing-2: 0.5rem;
+  --smrt-spacing-4: 1rem;
+  --smrt-spacing-8: 2rem;
+}
+
+/* Define dark mode */
+[data-theme="mybrand"][data-color-scheme="dark"] {
+  --smrt-color-primary: #38bdf8;
+  --smrt-color-on-primary: #0c4a6e;
+  --smrt-color-primary-container: #075985;
+  --smrt-color-on-primary-container: #e0f2fe;
+  
+  --smrt-color-surface: #0f172a;
+  --smrt-color-surface-variant: #1e293b;
+  --smrt-color-background: #020617;
+  --smrt-color-on-surface: #f1f5f9;
+  
+  --smrt-color-error: #f87171;
+  --smrt-color-success: #4ade80;
+  --smrt-color-warning: #fbbf24;
+}
+```
+
+## Method 3: Hybrid Approach
+
+Combine TypeScript definition with extensive CSS customization:
+
+```typescript
+// src/lib/themes/hybrid.ts
+import { createTheme, registerTheme } from '@happyvertical/smrt-ui/themes';
+
+export const hybridTheme = createTheme({
+  id: 'hybrid',
+  name: 'Hybrid Brand',
+  extend: 'material',
+  light: {
+    primary: '#8b5cf6',
+    background: '#fafafa',
+  },
+  // Let dark mode auto-generate
+});
+
+registerTheme(hybridTheme);
+```
+
+```css
+/* src/lib/themes/hybrid.css */
+@import '@happyvertical/smrt-ui/themes/styles/material.css';
+
+[data-theme="hybrid"] {
+  /* All the CSS customizations */
+  --smrt-typography-display-large-size: 4rem;
+  --smrt-typography-display-large-weight: 800;
+  
+  /* Custom animations */
+  --smrt-duration-slow: 400ms;
+  --smrt-easing-emphasized: cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+/* Component-specific overrides */
+[data-theme="hybrid"] .card {
+  border: 1px solid var(--smrt-color-outline);
+  transition: transform var(--smrt-duration-normal) var(--smrt-easing-standard);
+}
+
+[data-theme="hybrid"] .card:hover {
+  transform: translateY(-4px);
+}
+```
+
+## Sharing Themes Between Projects
+
+### As a Local Package
+
+```bash
+# In your theme package
+mkdir packages/my-brand-theme
+cd packages/my-brand-theme
+npm init
+```
+
+```json
+// packages/my-brand-theme/package.json
+{
+  "name": "@mycompany/brand-theme",
+  "main": "./index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./styles": "./styles.css"
+  }
+}
+```
+
+```typescript
+// packages/my-brand-theme/index.ts
+import { createTheme, registerTheme } from '@happyvertical/smrt-ui/themes';
+
+export const myBrandTheme = createTheme({
+  id: 'mycompany',
+  name: 'MyCompany Brand',
+  // ... theme definition
+});
+
+registerTheme(myBrandTheme);
+export { myBrandTheme as default };
+```
+
+```css
+/* packages/my-brand-theme/styles.css */
+/* CSS version of the theme */
+```
+
+Then in your main project:
+
+```bash
+npm install ./packages/my-brand-theme
+```
+
+```svelte
+<script>
+  import '@mycompany/brand-theme';
+  import '@mycompany/brand-theme/styles';
+</script>
+```
+
+## Theme Switching with Custom Themes
+
+```svelte
+<script>
+  import { getThemeContext, ThemeSwitcher } from '@happyvertical/smrt-ui/themes';
+  
+  // Import your custom themes to register them
+  import '$lib/themes/brand';
+  import '$lib/themes/corporate';
+  
+  const theme = getThemeContext();
+  
+  // Switch between built-in and custom
+  function useBrandTheme() {
+    theme.setPreset('brand');
+  }
+  
+  function useCorporateTheme() {
+    theme.setPreset('corporate');
+  }
+</script>
+
+<!-- UI shows all available themes including custom ones -->
+<ThemeSwitcher variant="segmented" />
+```
+
+## Best Practices
+
+1. **Extend a base theme**: Start with `extend: 'material'` or another base to get sensible defaults
+2. **Define both modes**: Always provide both light and dark colors, or let the system auto-generate dark mode
+3. **Test contrast**: Ensure your colors meet WCAG contrast requirements
+4. **Use semantic naming**: Map your brand colors to semantic tokens (primary, secondary, error, etc.)
+5. **Document your theme**: Create a demo page showing all colors and components
+
+## Troubleshooting
+
+### Theme not appearing in ThemeSwitcher
+Make sure you import the file that calls `registerTheme()` before using the component.
+
+### Colors not applying
+Check that you've imported the base CSS files and your custom CSS.
+
+### TypeScript errors
+Ensure your custom theme implements the full `Theme` type or use `createTheme()` which handles this.
+
+### Flash of unstyled content
+Use server-side rendering or inline critical CSS in your `app.html`.