@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/design-system/SKILL.md

@@ -0,0 +1,457 @@
+---
+name: design-system
+description: >
+  Build a new design system (tokens, variants, theming). Use when
+  "create a design system" or "component library from scratch". Drifted
+  existing system → housekeep-design. Plan-only unification →
+  plan-uiux-unification.
+license: MIT
+---
+
+# Design System Skill
+
+**Degree of freedom: MIXED.** Token taxonomy and variants `[HIGH freedom]`;
+existing `ui/` / token inventory `[LOW freedom — run exactly]`.
+
+Build scalable, maintainable design systems with consistent tokens, variants, and documentation.
+
+## How to reason
+
+1. **Inventory** — `components/ui`, tokens, `cva`, shadcn/Radix
+2. **Tokenize** — semantic tokens, not raw hex in components
+3. **Variant** — `cva` covers real states (default/destructive/disabled)
+4. **Document** — JSDoc, keyboard/focus, dark mode
+
+## Worked example
+
+> **Inventory:** shadcn `Button` exists; colors are raw `#3B82F6` in three pages; no `--primary`.
+> **Tokenize:** `--primary` / `--primary-foreground` in `globals.css`; Tailwind maps `hsl(var(--primary))`.
+> **Variant:** extend existing `buttonVariants` — do not add `components/Button2.tsx`.
+> **Document:** JSDoc lists variants/sizes; focus ring + dark `.dark` overrides.
+
+## Self-critique before reporting
+
+- **Did not fork** — existing primitives were extended, not recreated
+- **Semantic tokens** — components reference tokens, not primitives or hex
+- **A11y + dark** — focus, disabled, and dark variants exist
+- **Right owner** — drifted existing system → `housekeep-design`; plan-only unification → `plan-uiux-unification`
+
+## Check existing first  [LOW freedom — run exactly]
+
+**Before creating ANY design system components, verify:**
+
+1. **Check for existing design system:**
+```bash
+ls -la src/components/ui/
+cat package.json | grep -i "shadcn\|radix\|headless"
+cat components.json 2>/dev/null # shadcn config
+```
+
+2. **Check for existing tokens:**
+```bash
+cat tailwind.config.* | head -100
+cat src/styles/globals.css | head -50
+rg "var\(--" --type css | head -20
+```
+
+3. **Check for existing patterns:**
+```bash
+rg "cva\(|variants:" --type ts --type tsx | head -10
+rg "cn\(|clsx\(|twMerge" --type tsx | head -5
+```
+
+**Why:** Don't recreate existing primitives. Extend and enhance what exists.
+
+## Design Tokens  [HIGH freedom]
+
+Face and ground are choices, not defaults: Inter/Roboto/Arial, a cream/off-white page, and a purple-gradient primary are the fallbacks to name and avoid. Add `--font-sans` / `--font-display` tokens for the faces you pick.
+
+### CSS Custom Properties
+```css
+/* globals.css */
+:root {
+ /* Colors - Semantic */
+ --background: 0 0% 100%;
+ --foreground: 222.2 84% 4.9%;
+ --card: 0 0% 100%;
+ --card-foreground: 222.2 84% 4.9%;
+ --popover: 0 0% 100%;
+ --popover-foreground: 222.2 84% 4.9%;
+ --primary: 221.2 83.2% 53.3%;
+ --primary-foreground: 210 40% 98%;
+ --secondary: 210 40% 96.1%;
+ --secondary-foreground: 222.2 47.4% 11.2%;
+ --muted: 210 40% 96.1%;
+ --muted-foreground: 215.4 16.3% 46.9%;
+ --accent: 210 40% 96.1%;
+ --accent-foreground: 222.2 47.4% 11.2%;
+ --destructive: 0 84.2% 60.2%;
+ --destructive-foreground: 210 40% 98%;
+ --border: 214.3 31.8% 91.4%;
+ --input: 214.3 31.8% 91.4%;
+ --ring: 221.2 83.2% 53.3%;
+
+ /* Spacing */
+ --spacing-xs: 0.25rem;
+ --spacing-sm: 0.5rem;
+ --spacing-md: 1rem;
+ --spacing-lg: 1.5rem;
+ --spacing-xl: 2rem;
+
+ /* Border Radius */
+ --radius: 0.5rem;
+ --radius-sm: calc(var(--radius) - 4px);
+ --radius-lg: calc(var(--radius) + 4px);
+
+ /* Shadows */
+ --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+ --shadow: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1);
+ --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
+ --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+
+ /* Animation */
+ --duration-fast: 150ms;
+ --duration-normal: 200ms;
+ --duration-slow: 300ms;
+ --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+ --ease-in: cubic-bezier(0.4, 0, 1, 1);
+ --ease-out: cubic-bezier(0, 0, 0.2, 1);
+ --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
+}
+
+.dark {
+ --background: 222.2 84% 4.9%;
+ --foreground: 210 40% 98%;
+ /* ... dark mode overrides */
+}
+```
+
+### Tailwind Config Integration
+```ts
+// tailwind.config.ts
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+ content: ['./src/**/*.{ts,tsx}'],
+ darkMode: 'class',
+ theme: {
+ extend: {
+ colors: {
+ border: 'hsl(var(--border))',
+ input: 'hsl(var(--input))',
+ ring: 'hsl(var(--ring))',
+ background: 'hsl(var(--background))',
+ foreground: 'hsl(var(--foreground))',
+ primary: {
+ DEFAULT: 'hsl(var(--primary))',
+ foreground: 'hsl(var(--primary-foreground))',
+ },
+ secondary: {
+ DEFAULT: 'hsl(var(--secondary))',
+ foreground: 'hsl(var(--secondary-foreground))',
+ },
+ destructive: {
+ DEFAULT: 'hsl(var(--destructive))',
+ foreground: 'hsl(var(--destructive-foreground))',
+ },
+ muted: {
+ DEFAULT: 'hsl(var(--muted))',
+ foreground: 'hsl(var(--muted-foreground))',
+ },
+ accent: {
+ DEFAULT: 'hsl(var(--accent))',
+ foreground: 'hsl(var(--accent-foreground))',
+ },
+ },
+ borderRadius: {
+ lg: 'var(--radius-lg)',
+ md: 'var(--radius)',
+ sm: 'var(--radius-sm)',
+ },
+ boxShadow: {
+ sm: 'var(--shadow-sm)',
+ DEFAULT: 'var(--shadow)',
+ md: 'var(--shadow-md)',
+ lg: 'var(--shadow-lg)',
+ },
+ transitionDuration: {
+ fast: 'var(--duration-fast)',
+ normal: 'var(--duration-normal)',
+ slow: 'var(--duration-slow)',
+ },
+ },
+ },
+}
+
+export default config
+```
+
+## Component Variants with CVA
+
+```tsx
+// lib/utils.ts
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+ return twMerge(clsx(inputs))
+}
+```
+
+```tsx
+// components/ui/button.tsx
+import { cva, type VariantProps } from 'class-variance-authority'
+import { forwardRef } from 'react'
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+ // Base styles
+ 'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50',
+ {
+ variants: {
+ variant: {
+ default: 'bg-primary text-primary-foreground shadow hover:bg-primary/90',
+ destructive: 'bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90',
+ outline: 'border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground',
+ secondary: 'bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80',
+ ghost: 'hover:bg-accent hover:text-accent-foreground',
+ link: 'text-primary underline-offset-4 hover:underline',
+ },
+ size: {
+ default: 'h-9 px-4 py-2',
+ sm: 'h-8 rounded-md px-3 text-xs',
+ lg: 'h-10 rounded-md px-8',
+ icon: 'h-9 w-9',
+ },
+ },
+ defaultVariants: {
+ variant: 'default',
+ size: 'default',
+ },
+ }
+)
+
+export interface ButtonProps
+ extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+ VariantProps<typeof buttonVariants> {
+ asChild?: boolean
+}
+
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+ ({ className, variant, size, asChild = false, ...props }, ref) => {
+ const Comp = asChild ? Slot : 'button'
+ return (
+ <Comp
+ className={cn(buttonVariants({ variant, size, className }))}
+ ref={ref}
+ {...props}
+ />
+ )
+ }
+)
+Button.displayName = 'Button'
+
+export { Button, buttonVariants }
+```
+
+## Compound Components Pattern
+
+```tsx
+// components/ui/card.tsx
+import { cn } from '@/lib/utils'
+import { forwardRef } from 'react'
+
+const Card = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+ ({ className, ...props }, ref) => (
+ <div
+ ref={ref}
+ className={cn(
+ 'rounded-xl border bg-card text-card-foreground shadow',
+ className
+ )}
+ {...props}
+ />
+ )
+)
+Card.displayName = 'Card'
+
+const CardHeader = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+ ({ className, ...props }, ref) => (
+ <div
+ ref={ref}
+ className={cn('flex flex-col space-y-1.5 p-6', className)}
+ {...props}
+ />
+ )
+)
+CardHeader.displayName = 'CardHeader'
+
+const CardTitle = forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(
+ ({ className, ...props }, ref) => (
+ <h3
+ ref={ref}
+ className={cn('font-semibold leading-none tracking-tight', className)}
+ {...props}
+ />
+ )
+)
+CardTitle.displayName = 'CardTitle'
+
+const CardDescription = forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+ ({ className, ...props }, ref) => (
+ <p
+ ref={ref}
+ className={cn('text-sm text-muted-foreground', className)}
+ {...props}
+ />
+ )
+)
+CardDescription.displayName = 'CardDescription'
+
+const CardContent = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+ ({ className, ...props }, ref) => (
+ <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
+ )
+)
+CardContent.displayName = 'CardContent'
+
+const CardFooter = forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+ ({ className, ...props }, ref) => (
+ <div
+ ref={ref}
+ className={cn('flex items-center p-6 pt-0', className)}
+ {...props}
+ />
+ )
+)
+CardFooter.displayName = 'CardFooter'
+
+export { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }
+```
+
+## Accessible Components with Radix
+
+```tsx
+// components/ui/dialog.tsx
+'use client'
+
+import * as DialogPrimitive from '@radix-ui/react-dialog'
+import { X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+const Dialog = DialogPrimitive.Root
+const DialogTrigger = DialogPrimitive.Trigger
+const DialogPortal = DialogPrimitive.Portal
+const DialogClose = DialogPrimitive.Close
+
+const DialogOverlay = forwardRef<
+ React.ElementRef<typeof DialogPrimitive.Overlay>,
+ React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(({ className, ...props }, ref) => (
+ <DialogPrimitive.Overlay
+ ref={ref}
+ className={cn(
+ 'fixed inset-0 z-50 bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+ className
+ )}
+ {...props}
+ />
+))
+
+const DialogContent = forwardRef<
+ React.ElementRef<typeof DialogPrimitive.Content>,
+ React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+ <DialogPortal>
+ <DialogOverlay />
+ <DialogPrimitive.Content
+ ref={ref}
+ className={cn(
+ 'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-background p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg',
+ className
+ )}
+ {...props}
+ >
+ {children}
+ <DialogPrimitive.Close className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground">
+ <X className="h-4 w-4" />
+ <span className="sr-only">Close</span>
+ </DialogPrimitive.Close>
+ </DialogPrimitive.Content>
+ </DialogPortal>
+))
+
+export { Dialog, DialogTrigger, DialogContent, DialogClose }
+```
+
+## Component Documentation Pattern
+
+```tsx
+// components/ui/button.stories.tsx (or docs)
+/**
+ * Button Component
+ *
+ * A versatile button component with multiple variants and sizes.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="default" size="md">Click me</Button>
+ * <Button variant="outline" size="sm">Small</Button>
+ * <Button variant="destructive" disabled>Disabled</Button>
+ * ```
+ *
+ * ## Variants
+ * - `default` - Primary action button
+ * - `secondary` - Secondary actions
+ * - `destructive` - Dangerous actions (delete, remove)
+ * - `outline` - Less prominent actions
+ * - `ghost` - Minimal visual weight
+ * - `link` - Styled as a link
+ *
+ * ## Sizes
+ * - `sm` - 32px height
+ * - `default` - 36px height
+ * - `lg` - 40px height
+ * - `icon` - 36x36px square for icon-only buttons
+ *
+ * ## Accessibility
+ * - Uses native `<button>` element
+ * - Supports `disabled` attribute
+ * - Focus ring visible on keyboard navigation
+ * - Works with `asChild` prop for custom elements
+ */
+```
+
+## File Structure
+
+```
+src/
+├── components/
+│ └── ui/
+│ ├── button.tsx
+│ ├── card.tsx
+│ ├── dialog.tsx
+│ ├── input.tsx
+│ ├── label.tsx
+│ ├── select.tsx
+│ ├── textarea.tsx
+│ ├── toast.tsx
+│ └── index.ts # Barrel export
+├── lib/
+│ └── utils.ts # cn() helper
+├── styles/
+│ └── globals.css # CSS tokens
+└── tailwind.config.ts # Theme config
+```
+
+## Validation  [LOW freedom — do not skip]
+
+After creating design system components:
+
+1. **Consistency** → All components use same tokens
+2. **Variants** → Cover all needed use cases
+3. **Accessibility** → Keyboard nav, ARIA, focus states
+4. **Dark mode** → All components work in dark mode
+5. **Responsive** → Mobile-friendly by default
+6. **Documentation** → JSDoc comments, usage examples
+7. **Type safety** → Full TypeScript support with VariantProps

package/skills/design-theme/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: design-theme
+description: >
+  Apply one of 11 preset themes (colors, fonts) to slides, docs, or landing
+  pages. Use when "apply theme", "color palette", "brand colors", "styling
+  slides", "presentation design", "visual identity", or styling artifacts
+  consistently.
+license: MIT
+---
+
+# Theme Factory Skill
+
+**Degree of freedom: MIXED.** Custom-theme authoring `[HIGH freedom]`; wait-for-
+selection and existing-token inventory `[LOW freedom — run exactly]`.
+
+A curated collection of professional font and color themes. Once a theme is chosen, it can be applied to any artifact.
+
+## How to reason
+
+1. **Inventory** — existing tokens, fonts, and brand colors
+2. **Select** — show the catalog; wait for an explicit choice
+3. **Apply** — one palette + pairing everywhere on the artifact
+4. **Contrast** — 4.5:1 text; do not override the design system arbitrarily
+
+## Worked example
+
+> **Inventory:** slide deck uses mixed hex; `globals.css` already has `--primary`.
+> **Select:** user picks **Forest Canopy** after seeing the 11 options.
+> **Apply:** headings Merriweather / body Lato; `#276749` primary on `#f0fff4`.
+> **Contrast:** body text vs background ≥4.5:1; app chrome still uses existing tokens.
+
+## Self-critique before reporting
+
+- **Choice recorded** — a theme was not applied until the user picked one
+- **One pairing** — no leftover fonts or hex from a second theme
+- **Readable** — contrast checked, not assumed
+- **Right owner** — component library / tokens from scratch → `design-system`; drifted token SSOT → `housekeep-design`
+
+## Purpose
+
+To apply consistent, professional styling to presentation slide decks or other artifacts. Each theme includes:
+- A cohesive color palette with hex codes
+- Complementary font pairings for headers and body text
+- A distinct visual identity suitable for different contexts and audiences
+
+## Usage Instructions  [LOW freedom — run exactly]
+
+To apply styling to a slide deck or other artifact:
+
+1. **Show available themes**: Display the theme options to allow users to see all available themes
+2. **Ask for their choice**: Ask which theme to apply
+3. **Wait for selection**: Get explicit confirmation about the chosen theme
+4. **Apply the theme**: Apply the selected theme's colors and fonts
+
+## Themes Available
+
+The following 11 themes are available:
+
+### 1. Ocean Depths
+Professional and calming maritime theme
+- **Primary**: `#1a365d` (deep blue)
+- **Secondary**: `#2c5282`
+- **Accent**: `#63b3ed`
+- **Background**: `#ebf8ff`
+- **Heading Font**: Playfair Display
+- **Body Font**: Source Sans Pro
+
+### 2. Sunset Boulevard
+Warm and vibrant sunset colors
+- **Primary**: `#c05621` (burnt orange)
+- **Secondary**: `#dd6b20`
+- **Accent**: `#ed8936`
+- **Background**: `#fffaf0`
+- **Heading Font**: Poppins
+- **Body Font**: Open Sans
+
+### 3. Forest Canopy
+Natural and grounded earth tones
+- **Primary**: `#276749` (forest green)
+- **Secondary**: `#38a169`
+- **Accent**: `#9ae6b4`
+- **Background**: `#f0fff4`
+- **Heading Font**: Merriweather
+- **Body Font**: Lato
+
+### 4. Modern Minimalist
+Clean and contemporary grayscale
+- **Primary**: `#1a202c` (charcoal)
+- **Secondary**: `#4a5568`
+- **Accent**: `#718096`
+- **Background**: `#f7fafc`
+- **Heading Font**: Inter
+- **Body Font**: Inter
+
+### 5. Golden Hour
+Rich and warm autumnal palette
+- **Primary**: `#744210` (golden brown)
+- **Secondary**: `#b7791f`
+- **Accent**: `#ecc94b`
+- **Background**: `#fffff0`
+- **Heading Font**: Cormorant Garamond
+- **Body Font**: Work Sans
+
+### 6. Arctic Frost
+Cool and crisp winter-inspired theme
+- **Primary**: `#2b6cb0` (ice blue)
+- **Secondary**: `#4299e1`
+- **Accent**: `#90cdf4`
+- **Background**: `#ebf8ff`
+- **Heading Font**: Montserrat
+- **Body Font**: Nunito
+
+### 7. Desert Rose
+Soft and sophisticated dusty tones
+- **Primary**: `#97266d` (dusty rose)
+- **Secondary**: `#d53f8c`
+- **Accent**: `#ed64a6`
+- **Background**: `#fff5f7`
+- **Heading Font**: DM Serif Display
+- **Body Font**: DM Sans
+
+### 8. Tech Innovation
+Bold and modern tech aesthetic
+- **Primary**: `#2d3748` (slate)
+- **Secondary**: `#4c51bf`
+- **Accent**: `#667eea`
+- **Background**: `#edf2f7`
+- **Heading Font**: JetBrains Mono
+- **Body Font**: IBM Plex Sans
+
+### 9. Botanical Garden
+Fresh and organic garden colors
+- **Primary**: `#285e61` (teal)
+- **Secondary**: `#319795`
+- **Accent**: `#81e6d9`
+- **Background**: `#e6fffa`
+- **Heading Font**: Libre Baskerville
+- **Body Font**: Karla
+
+### 10. Midnight Galaxy
+Dramatic and cosmic deep tones
+- **Primary**: `#1a1a2e` (midnight)
+- **Secondary**: `#16213e`
+- **Accent**: `#e94560`
+- **Background**: `#0f0f23`
+- **Text**: `#edf2f7`
+- **Heading Font**: Orbitron
+- **Body Font**: Rajdhani
+
+### 11. Tsumagoi Ranch
+Neo-Brutalist "Cute-alism" - Japanese ranch/campground aesthetic
+- **Primary**: `#0c85f4` (mountain blue)
+- **Secondary**: `#10b981` (pine green)
+- **Accent**: `#ff6b35` (campfire orange)
+- **Accent Alt**: `#FF6D38` (navigate orange - CTAs)
+- **Premium**: `#8584FF` (navigate purple)
+- **Background Light**: `#faf7f2` (warm cream)
+- **Background Dark**: `#0c1424` (night sky)
+- **Border**: `#b8a080` (wood/sand tone)
+- **Text**: `#1a1a1a` (near black)
+- **Heading Font**: M PLUS Rounded 1c
+- **Body Font**: Inter
+- **Body JP**: Noto Sans JP
+- **Mono**: JetBrains Mono
+
+**Neo-Brutal Shadows**: Hard-edge `3px 3px 0 0 #b8a080` (no blur)
+**Border Style**: 3px solid with rounded-xl corners
+**Motion**: Bounce easing `cubic-bezier(0.34, 1.56, 0.64, 1)`
+
+See `themes/tsumagoi-ranch.md` for full specification including mobile patterns.
+
+## Application Process  [LOW freedom — run exactly]
+
+After a preferred theme is selected:
+1. Read the corresponding theme specifications
+2. Apply the specified colors and fonts consistently throughout
+3. Ensure proper contrast and readability
+4. Maintain the theme's visual identity across all elements
+
+## Create Your Own Theme  [HIGH freedom]
+
+To handle cases where none of the existing themes work, create a custom theme based on:
+- User's brand colors
+- Specific aesthetic direction
+- Industry or context requirements
+
+Generate a new theme with:
+- 5 color palette (primary, secondary, accent, background, text)
+- Font pairing (heading + body)
+- A descriptive name
+
+Name the fallbacks and avoid them: Inter/Roboto as the pairing, a cream or off-white background, a purple gradient — a custom theme that lands on those is the model's default, not the user's brand.
+
+After generating, show it for review before applying.
+
+## Check existing first  [LOW freedom — run exactly]
+
+**Before applying ANY theme, verify:**
+
+1. **Check for existing theme/design system:**
+```bash
+cat tailwind.config.* 2>/dev/null | grep -A30 "colors\|fontFamily"
+cat src/styles/globals.css docs/THEME_GUIDE.md 2>/dev/null
+```
+
+2. **Check for existing CSS variables:**
+```bash
+rg "var\(--" --type css --type tsx | head -20
+```
+
+3. **Check for existing brand colors:**
+- Look in `public/` for logos
+- Check existing components for color patterns
+
+**Why:** Themes must integrate with existing design systems, not override them arbitrarily.
+
+## Validation  [LOW freedom — do not skip]
+
+After applying a theme:
+
+1. **Visual consistency** → All components use theme colors
+2. **Contrast check** → Text readable on backgrounds (4.5:1 min)
+3. **Font loading** → Google Fonts load correctly
+4. **Dark mode** → If applicable, verify dark variant works
+5. **Mobile check** → Typography scales appropriately
+6. **Print preview** → If printable, colors work in print