@brainfish-ai/devdoc 0.1.36 → 0.1.38

package/ai-agents/.cursor/rules/devdoc-whisk-theme.mdc

@@ -0,0 +1,301 @@
+---
+description: Analyze repository branding and generate custom theme for documentation
+globs: ["**/theme.json", "**/custom.css", "**/tailwind.config.*", "**/*.css", "**/*.scss"]
+---
+
+# Whisk Theme - Brand Analysis & Theme Generation
+
+When asked to "whisk theme", "generate theme", "customize branding", or "match brand":
+
+## Step 1: Scan for Brand Colors
+
+Search these sources in order of priority:
+
+### 1a. Tailwind Config (highest priority)
+```javascript
+// tailwind.config.js or tailwind.config.ts
+theme: {
+  colors: {
+    primary: '#xxx',      // → primary
+    secondary: '#xxx',    // → accent
+    brand: '#xxx',        // → primary
+  }
+}
+```
+
+### 1b. CSS Variables
+```css
+/* Look in: globals.css, variables.css, theme.css, app.css */
+:root {
+  --primary: #xxx;
+  --brand-color: #xxx;
+  --accent: #xxx;
+  --color-primary: #xxx;
+}
+```
+
+### 1c. SCSS Variables
+```scss
+/* Look in: _variables.scss, _colors.scss */
+$primary: #xxx;
+$brand-color: #xxx;
+$accent-color: #xxx;
+```
+
+### 1d. UI Framework Themes
+```javascript
+// Chakra UI: theme.js
+colors: { brand: { 500: '#xxx' } }
+
+// MUI: theme.js  
+palette: { primary: { main: '#xxx' } }
+
+// shadcn: globals.css
+--primary: 220 90% 56%;
+```
+
+### 1e. Package.json / Brand Files
+```json
+// package.json (rare but check)
+{ "brand": { "color": "#xxx" } }
+
+// brand.json, colors.json
+{ "primary": "#xxx" }
+```
+
+## Step 2: Scan for Logo
+
+Search for logo files:
+```
+public/logo.svg, public/logo.png
+assets/logo.*, images/logo.*
+src/assets/logo.*
+favicon.svg, favicon.ico
+```
+
+**If SVG logo found:**
+- Extract fill colors as potential brand colors
+- Note path for docs.json update
+
+## Step 3: Scan for Fonts
+
+```javascript
+// tailwind.config.js
+fontFamily: {
+  sans: ['CustomFont', ...],
+}
+
+// CSS
+--font-family: 'CustomFont';
+font-family: 'CustomFont', sans-serif;
+
+// Next.js fonts
+import { Inter } from 'next/font/google'
+```
+
+## Step 4: Present Findings
+
+Show user what was discovered:
+
+```
+🎨 Brand Analysis Complete
+
+Colors detected:
+  Primary:   #3B82F6 ████ (from tailwind.config.js)
+  Secondary: #10B981 ████ (from tailwind.config.js)
+  
+Logo found:
+  public/logo.svg
+  
+Font detected:
+  Inter (from next/font)
+
+Apply these to your docs theme?
+1. **Yes** - Update theme.json and custom.css
+2. **Customize** - Let me adjust the colors
+3. **Cancel** - Keep current theme
+```
+
+## Step 5: Generate Theme Files
+
+### 5a. Update theme.json
+
+```json
+{
+  "$schema": "https://devdoc.sh/theme.json",
+  "name": "{Product Name} Docs",
+  "description": "Custom theme matching {Product Name} branding",
+  "colors": {
+    "primary": "{detected_primary}",
+    "primaryLight": "{lighten_15%}",
+    "primaryDark": "{darken_15%}"
+  },
+  "typography": {
+    "fontFamily": "{detected_font}, system-ui, sans-serif",
+    "headingFontFamily": "{detected_font}, system-ui, sans-serif",
+    "codeFontFamily": "'JetBrains Mono', 'Fira Code', monospace"
+  },
+  "header": {
+    "showSearch": true,
+    "showThemeToggle": true,
+    "showAskAI": true
+  },
+  "layout": {
+    "sidebarWidth": 280,
+    "contentMaxWidth": 768
+  },
+  "defaultTheme": "system"
+}
+```
+
+### 5b. Update custom.css with Branded Components
+
+Generate comprehensive component styles based on brand:
+
+```css
+/* {Product Name} Documentation Theme */
+/* Generated by DevDoc whisk-theme */
+
+/* === 1. CSS Variables === */
+:root {
+  --devdoc-primary: {primary};
+  --devdoc-primary-light: {primaryLight};
+  --devdoc-primary-dark: {primaryDark};
+  --devdoc-primary-rgb: {primaryRGB};
+  --devdoc-font-family: '{fontFamily}', system-ui, sans-serif;
+  --devdoc-code-font-family: 'JetBrains Mono', monospace;
+}
+
+/* === 2. Base === */
+* { transition: background-color 0.2s, border-color 0.2s, color 0.2s; }
+::selection { background-color: var(--devdoc-primary); color: white; }
+
+/* === 3. Links === */
+.docs-content a:not([class]) { color: var(--devdoc-primary); text-decoration: underline; }
+.docs-content a:not([class]):hover { color: var(--devdoc-primary-dark); }
+
+/* === 4. Navigation === */
+.nav-link:hover { color: var(--devdoc-primary); }
+.nav-link.active { color: var(--devdoc-primary); font-weight: 500; }
+.nav-tab.active { color: var(--devdoc-primary); border-bottom: 2px solid var(--devdoc-primary); }
+.toc-link:hover, .toc-link.active { color: var(--devdoc-primary); }
+.toc-indicator { background-color: var(--devdoc-primary); }
+
+/* === 5. Buttons === */
+.btn-primary { background-color: var(--devdoc-primary); color: white; }
+.btn-primary:hover { background-color: var(--devdoc-primary-dark); }
+.btn-secondary { border: 1px solid var(--devdoc-primary); color: var(--devdoc-primary); }
+.btn-secondary:hover { background-color: var(--devdoc-primary); color: white; }
+
+/* === 6. Cards === */
+.card:hover { border-color: var(--devdoc-primary); box-shadow: 0 4px 12px rgba(var(--devdoc-primary-rgb), 0.15); }
+.card-icon { color: var(--devdoc-primary); }
+
+/* === 7. Callouts === */
+.callout { border-left: 4px solid var(--devdoc-primary); }
+.callout-info { border-left-color: var(--devdoc-primary); }
+.callout-tip { border-left-color: #10b981; }
+.callout-warning { border-left-color: #f59e0b; }
+.callout-danger { border-left-color: #ef4444; }
+
+/* === 8. Tabs === */
+.tabs-trigger[data-state="active"] { color: var(--devdoc-primary); border-bottom-color: var(--devdoc-primary); }
+.tabs-trigger:hover { color: var(--devdoc-primary-dark); }
+
+/* === 9. Accordions === */
+.accordion-trigger:hover { color: var(--devdoc-primary); }
+.accordion-trigger[data-state="open"] { color: var(--devdoc-primary); }
+.accordion-trigger[data-state="open"] svg { color: var(--devdoc-primary); }
+
+/* === 10. Steps === */
+.step-number { background-color: var(--devdoc-primary); color: white; border-radius: 50%; }
+.step-completed .step-connector { background-color: var(--devdoc-primary); }
+
+/* === 11. Code === */
+pre code { font-family: var(--devdoc-code-font-family); font-size: 0.875rem; line-height: 1.7; }
+:not(pre) > code { background-color: var(--muted); padding: 0.125rem 0.375rem; border-radius: 0.25rem; }
+.code-block .copy-button:hover { color: var(--devdoc-primary); }
+
+/* === 12. Search === */
+.search-input:focus { border-color: var(--devdoc-primary); box-shadow: 0 0 0 2px rgba(var(--devdoc-primary-rgb), 0.2); }
+.search-result-title mark { background-color: rgba(var(--devdoc-primary-rgb), 0.2); color: var(--devdoc-primary-dark); }
+
+/* === 13. API Reference === */
+.api-method-get { background-color: #10b981; }
+.api-method-post { background-color: var(--devdoc-primary); }
+.api-method-put { background-color: #f59e0b; }
+.api-method-delete { background-color: #ef4444; }
+.try-it-button { background-color: var(--devdoc-primary); }
+.try-it-button:hover { background-color: var(--devdoc-primary-dark); }
+.schema-property:hover { border-left-color: var(--devdoc-primary); }
+
+/* === 14. Features (Product Docs) === */
+.feature-card:hover { border-color: var(--devdoc-primary); }
+.feature-icon { color: var(--devdoc-primary); }
+```
+
+### 5c. Copy Logo (if found and not already in docs)
+
+```
+1. Copy logo to docs/public/logo.svg
+2. If dark variant exists, copy to docs/public/logo-dark.svg
+3. Update docs.json:
+
+{
+  "logo": {
+    "light": "/logo.svg",
+    "dark": "/logo-dark.svg"  // or same as light
+  }
+}
+```
+
+## Step 6: Confirm Changes
+
+```
+✅ Theme updated!
+
+Files modified:
+  - theme.json (colors, fonts)
+  - custom.css (brand variables, styles)
+  - docs.json (logo paths)
+  - public/logo.svg (copied from source)
+
+Preview your docs with `devdoc dev` to see the changes.
+```
+
+## Color Utilities
+
+When generating lighter/darker variants:
+
+```
+Primary: #3B82F6
+  → primaryLight: lighten by 15% → #60A5FA
+  → primaryDark: darken by 15% → #2563EB
+```
+
+**HSL method (preferred):**
+- Light: increase L by 10-15%
+- Dark: decrease L by 10-15%
+
+## Common Brand Patterns
+
+| Framework | Primary Color Location |
+|-----------|----------------------|
+| Tailwind | `theme.colors.primary` or `theme.extend.colors` |
+| Chakra UI | `theme.colors.brand.500` |
+| MUI | `palette.primary.main` |
+| shadcn/ui | `--primary` in HSL format |
+| Bootstrap | `$primary` SCSS variable |
+| Ant Design | `@primary-color` |
+
+## Fallback Defaults
+
+If no brand colors detected:
+```
+Primary: #10b981 (DevDoc green)
+Font: Inter, system-ui, sans-serif
+```
+
+Ask user: "No brand colors found. Would you like to:
+1. Enter your brand color (hex)
+2. Use DevDoc defaults"