candidate for release

PRPs/ai_docs/UI_STANDARDS.md

@@ -77,22 +77,27 @@
 ## 2) Tailwind CSS (v4)
 
 **Rules**
-- **Define tokens properly**: Variables in `:root` and `.dark`, then map to Tailwind with `@theme inline`.
+- **CRITICAL: Define custom dark variant FIRST** - Required for `dark:` utilities to work in v4.
+- **Define tokens properly**: Variables in `:root` and `.dark` with **bare HSL values** (NO hsl() wrapper), then map to Tailwind with `@theme inline`.
 ```css
 @import "tailwindcss";
 
+@custom-variant dark (&:where(.dark, .dark *));  /* REQUIRED for dark: utilities */
+
 :root {
-  --background: hsl(0 0% 98%);
+  /* Bare HSL values - Tailwind adds hsl() wrapper automatically */
-  --foreground: hsl(240 10% 3.9%);
+  --background: 0 0% 98%;
-  --border: hsl(240 5.9% 90%);
+  --foreground: 240 10% 3.9%;
+  --border: 240 5.9% 90%;
   --radius: 0.5rem;
   color-scheme: light;
 }
 
 .dark {
-  --background: hsl(0 0% 0%);
+  /* Bare HSL values - redefine same variables */
-  --foreground: hsl(0 0% 100%);
+  --background: 0 0% 0%;
-  --border: hsl(240 3.7% 15.9%);
+  --foreground: 0 0% 100%;
+  --border: 240 3.7% 15.9%;
   color-scheme: dark;
 }
 
@@ -593,6 +598,7 @@ Then use generated utilities (e.g., `bg-brand-500`, `border-border`) or token re
 Before committing any UI component, verify ALL of these:
 
 ### Tailwind v4 Rules
+- [ ] **@custom-variant dark defined** (`@custom-variant dark (&:where(.dark, .dark *));` in index.css)
 - [ ] **No dynamic class construction** (`bg-${color}-500`, template literals with variables)
 - [ ] **CSS variables allowed in arbitrary values** (static utility names: `bg-[var(--accent)]`)
 - [ ] **Static class lookup objects** for discrete variants (e.g., `const colorClasses = { cyan: "...", ... }`)
@@ -600,7 +606,8 @@ Before committing any UI component, verify ALL of these:
 - [ ] **Conditional classes are complete strings** (use `cn()` with full class names)
 - [ ] **Arbitrary values are static** (written as complete strings in source code)
 - [ ] **Inline style ONLY for CSS variables** (`style={{ "--accent": token }}`), never direct visual CSS
-- [ ] **Variables in `:root` and `.dark`**, mapped with `@theme inline`
+- [ ] **Variables in `:root` and `.dark` with bare HSL values** (NO hsl() wrapper)
+- [ ] **Variables mapped with `@theme inline`**
 - [ ] **`@layer` and `@apply` used properly** (base styles and component classes)
 
 ### Responsive Layout Rules
@@ -667,6 +674,14 @@ Use these patterns to programmatically detect violations in `.tsx` files.
 
 ### Critical Violations (Breaking Changes)
 
+**Missing @custom-variant dark (DARK MODE WON'T WORK)**
+```bash
+grep -n "@custom-variant dark" [path]/index.css
+```
+**Rule**: Section 2 - @custom-variant dark REQUIRED for Tailwind v4
+**Symptom**: dark: utilities don't apply, theme toggle appears to work but nothing changes visually
+**Fix**: Add `@custom-variant dark (&:where(.dark, .dark *));` immediately after `@import "tailwindcss";`
+
 **Dynamic Tailwind Class Construction (NO CSS GENERATED)**
 ```bash
 grep -rn "className={\`.*\${.*}.*\`}" [path] --include="*.tsx"
@@ -932,14 +947,17 @@ export function GlassCard({ color = "cyan", customAccent }: Props) {
 
 ### Critical Reminders
 
-1. **NO dynamic class construction** - `bg-${color}-500` will NOT generate CSS
+1. **@custom-variant dark REQUIRED** - First line after `@import "tailwindcss";` or dark: won't work!
-2. **CSS variables ARE allowed** - `bg-[var(--accent)]` works (utility name is static)
+2. **Bare HSL values** - Variables must be `0 0% 98%` NOT `hsl(0 0% 98%)`
-3. **Inline style ONLY for CSS variables** - `style={{ "--accent": token }}`, never direct visual CSS
+3. **NO dynamic class construction** - `bg-${color}-500` will NOT generate CSS
-4. **Proper @theme pattern** - Variables in `:root`/`.dark`, map with `@theme inline`
+4. **CSS variables ARE allowed** - `bg-[var(--accent)]` works (utility name is static)
-5. **`@layer` and `@apply` still work** - Valid in v4 for base/component styles
+5. **Inline style ONLY for CSS variables** - `style={{ "--accent": token }}`, never direct visual CSS
-6. **Constrain scroll containers** - `overflow-x-auto` parent needs `w-full`
+6. **Proper @theme pattern** - Variables in `:root`/`.dark`, map with `@theme inline`
-7. **Responsive grids always** - Never fixed `grid-cols-4` without breakpoints
+7. **`@layer` and `@apply` still work** - Valid in v4 for base/component styles
-8. **Use primitives** - Card, PillNavigation, Radix UI components
+8. **Constrain scroll containers** - `overflow-x-auto` parent needs `w-full`
-9. **Desktop-primary** - Optimize for desktop, add responsive breakpoints for smaller screens
+9. **Flex parent with scroll needs min-w-0** - Prevents page expansion
-10. **Text truncation** - Always handle long text explicitly
+10. **Responsive grids always** - Never fixed `grid-cols-4` without breakpoints
-11. **Dark mode** - Every visible color needs `dark:` variant
+11. **Use primitives** - Card, PillNavigation, Radix UI components
+12. **Desktop-primary** - Optimize for desktop, add responsive breakpoints for smaller screens
+13. **Text truncation** - Always handle long text explicitly
+14. **Dark mode** - Every visible color needs `dark:` variant

archon-ui-main/src/contexts/ThemeContext.tsx

@@ -8,25 +8,22 @@ const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
 export const ThemeProvider: React.FC<{
   children: React.ReactNode;
 }> = ({ children }) => {
-  const [theme, setTheme] = useState<Theme>('dark');
+  // Read from localStorage immediately to avoid flash
-  useEffect(() => {
+  const [theme, setTheme] = useState<Theme>(() => {
-    // Check if theme is stored in localStorage
     const savedTheme = localStorage.getItem('theme') as Theme | null;
-    if (savedTheme) {
+    return savedTheme || 'dark';
-      setTheme(savedTheme);
+  });
-    } else {
-      // Default to dark mode
-      setTheme('dark');
-      localStorage.setItem('theme', 'dark');
-    }
-  }, []);
   useEffect(() => {
     // Apply theme class to document element
     const root = window.document.documentElement;
-    // Remove both classes first
+
-    root.classList.remove('dark', 'light');
+    // Tailwind v4: Only toggle .dark class, don't add .light
-    // Add the current theme class
+    if (theme === 'dark') {
-    root.classList.add(theme);
+      root.classList.add('dark');
+    } else {
+      root.classList.remove('dark');
+    }
+
     // Save to localStorage
     localStorage.setItem('theme', theme);
   }, [theme]);

archon-ui-main/src/features/style-guide/layouts/NavigationExplanation.tsx

@@ -1,145 +1,75 @@
 import { ChevronRight } from "lucide-react";
-import { Card } from "@/features/ui/primitives/card";
 
 export const NavigationExplanation = () => {
   return (
-    <div className="space-y-6">
+    <div className="space-y-8">
-      <div>
+      {/* Navigation Hierarchy at Top */}
-        <h2 className="text-2xl font-bold mb-4 text-gray-900 dark:text-white">
+      <div className="bg-white/80 dark:bg-black/40 border border-gray-300 dark:border-gray-700 rounded-lg p-6">
-          Navigation Patterns
-        </h2>
-        <p className="text-gray-600 dark:text-gray-400 mb-6">
-          Archon uses a layered navigation approach with distinct patterns for different navigation levels.
-        </p>
-      </div>
-
-      <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
-        {/* Main Navigation */}
-        <Card className="p-6">
-          <div className="flex items-start gap-3 mb-4">
-            <div className="w-10 h-10 rounded-lg bg-cyan-500/20 flex items-center justify-center">
-              <span className="text-cyan-400 font-bold">1</span>
-            </div>
-            <div className="flex-1">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2">
-                Main Navigation
-              </h3>
-              <p className="text-sm text-gray-600 dark:text-gray-400">
-                Fixed left sidebar (72px wide) with icon-based navigation. Always visible across all pages.
-              </p>
-            </div>
-          </div>
-          <div className="bg-black/20 rounded-lg p-4 border border-white/10">
-            <code className="text-xs text-gray-300">
-              <div>position: fixed</div>
-              <div>left: 24px (left-6)</div>
-              <div>width: 72px</div>
-              <div>Icon-based with tooltips</div>
-            </code>
-          </div>
-        </Card>
-
-        {/* Content Area */}
-        <Card className="p-6">
-          <div className="flex items-start gap-3 mb-4">
-            <div className="w-10 h-10 rounded-lg bg-purple-500/20 flex items-center justify-center">
-              <span className="text-purple-400 font-bold">2</span>
-            </div>
-            <div className="flex-1">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2">
-                Content Area
-              </h3>
-              <p className="text-sm text-gray-600 dark:text-gray-400">
-                All page content lives in the content area with left padding to accommodate main nav.
-              </p>
-            </div>
-          </div>
-          <div className="bg-black/20 rounded-lg p-4 border border-white/10">
-            <code className="text-xs text-gray-300">
-              <div>padding-left: 100px (pl-[100px])</div>
-              <div>Gives space for 72px nav + 28px gap</div>
-              <div>All layouts exist INSIDE this area</div>
-            </code>
-          </div>
-        </Card>
-
-        {/* Page Navigation */}
-        <Card className="p-6">
-          <div className="flex items-start gap-3 mb-4">
-            <div className="w-10 h-10 rounded-lg bg-blue-500/20 flex items-center justify-center">
-              <span className="text-blue-400 font-bold">3</span>
-            </div>
-            <div className="flex-1">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2">
-                Page Navigation
-              </h3>
-              <p className="text-sm text-gray-600 dark:text-gray-400">
-                Top-level tabs or pills for page sections. Uses Radix Tabs primitive with glassmorphism.
-              </p>
-            </div>
-          </div>
-          <div className="bg-black/20 rounded-lg p-4 border border-white/10">
-            <code className="text-xs text-gray-300">
-              <div>{'<Tabs>'} with TabsList</div>
-              <div>Example: Docs/Tasks tabs</div>
-              <div>Color variants: cyan, blue, purple, orange</div>
-            </code>
-          </div>
-        </Card>
-
-        {/* View Controls */}
-        <Card className="p-6">
-          <div className="flex items-start gap-3 mb-4">
-            <div className="w-10 h-10 rounded-lg bg-green-500/20 flex items-center justify-center">
-              <span className="text-green-400 font-bold">4</span>
-            </div>
-            <div className="flex-1">
-              <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-2">
-                View Controls
-              </h3>
-              <p className="text-sm text-gray-600 dark:text-gray-400">
-                Toggle buttons for switching between view modes (grid/table/list).
-              </p>
-            </div>
-          </div>
-          <div className="bg-black/20 rounded-lg p-4 border border-white/10">
-            <code className="text-xs text-gray-300">
-              <div>Icon buttons with active state</div>
-              <div>Grid, List, Table icons</div>
-              <div>Glassmorphism background</div>
-            </code>
-          </div>
-        </Card>
-      </div>
-
-      {/* Visual Hierarchy */}
-      <Card className="p-6">
         <h3 className="text-lg font-semibold text-gray-900 dark:text-white mb-4">
           Navigation Hierarchy
         </h3>
-        <div className="flex items-center gap-2 text-sm text-gray-600 dark:text-gray-400">
+        <div className="flex items-center gap-2 text-sm flex-wrap">
-          <span className="px-3 py-1 bg-cyan-500/20 text-cyan-400 rounded border border-cyan-400/30">
+          <span className="px-3 py-1 bg-cyan-500/20 text-cyan-700 dark:text-cyan-400 rounded border border-cyan-400/30 font-medium">
             Main Nav
           </span>
-          <ChevronRight className="w-4 h-4" />
+          <ChevronRight className="w-4 h-4 text-gray-600 dark:text-gray-400" />
-          <span className="px-3 py-1 bg-purple-500/20 text-purple-400 rounded border border-purple-400/30">
+          <span className="px-3 py-1 bg-purple-500/20 text-purple-700 dark:text-purple-400 rounded border border-purple-400/30 font-medium">
             Content Area
           </span>
-          <ChevronRight className="w-4 h-4" />
+          <ChevronRight className="w-4 h-4 text-gray-600 dark:text-gray-400" />
-          <span className="px-3 py-1 bg-blue-500/20 text-blue-400 rounded border border-blue-400/30">
+          <span className="px-3 py-1 bg-blue-500/20 text-blue-700 dark:text-blue-400 rounded border border-blue-400/30 font-medium">
             Page Tabs
           </span>
-          <ChevronRight className="w-4 h-4" />
+          <ChevronRight className="w-4 h-4 text-gray-600 dark:text-gray-400" />
-          <span className="px-3 py-1 bg-green-500/20 text-green-400 rounded border border-green-400/30">
+          <span className="px-3 py-1 bg-green-500/20 text-green-700 dark:text-green-400 rounded border border-green-400/30 font-medium">
             View Controls
           </span>
         </div>
-      </Card>
+      </div>
+
+      {/* Wireframe Mockup */}
+      <div className="relative h-[500px]">
+        {/* Main Navigation - Floating Left (Centered Vertically) */}
+        <div className="absolute left-0 top-1/2 -translate-y-1/2 w-[72px] flex flex-col items-center gap-2">
+          <div className="text-xs font-semibold text-cyan-700 dark:text-cyan-400">Main Navigation</div>
+          <div className="w-full h-[250px] bg-cyan-200 dark:bg-cyan-900/30 rounded-lg border-2 border-cyan-500/50 flex items-center justify-center p-2">
+            <span className="text-[10px] text-cyan-700 dark:text-cyan-400 text-center">Floating</span>
+          </div>
+        </div>
+
+        {/* Content Area - Full Width (with left padding for nav) */}
+        <div className="pl-20 h-full flex flex-col gap-2">
+          <div className="text-xs font-semibold text-purple-700 dark:text-purple-400">Content Area</div>
+          <div className="flex-1 bg-purple-100 dark:bg-purple-900/20 rounded-lg border-2 border-purple-500/50 p-4 space-y-3">
+
+            {/* Page Tabs - Pill Shaped */}
+            <div className="space-y-1">
+              <div className="text-[10px] font-semibold text-blue-700 dark:text-blue-400">Page Navigation (Pill Tabs)</div>
+              <div className="h-10 w-48 mx-auto bg-blue-200 dark:bg-blue-900/30 rounded-full border-2 border-blue-500/50 flex items-center justify-center">
+                <span className="text-xs text-blue-700 dark:text-blue-400">Docs | Tasks</span>
+              </div>
+            </div>
+
+            {/* View Controls */}
+            <div className="flex items-center justify-end gap-2">
+              <div className="text-[10px] font-semibold text-green-700 dark:text-green-400">View Controls</div>
+              <div className="h-8 w-20 bg-green-200 dark:bg-green-900/30 rounded-lg border-2 border-green-500/50 flex items-center justify-center">
+                <span className="text-xs text-green-700 dark:text-green-400">Grid/List</span>
+              </div>
+            </div>
+
+            {/* Content Placeholder */}
+            <div className="flex-1 bg-gray-200 dark:bg-gray-800 rounded-lg border-2 border-gray-400 dark:border-gray-600 flex items-center justify-center">
+              <span className="text-sm text-gray-600 dark:text-gray-400">Page Content</span>
+            </div>
+          </div>
+        </div>
+      </div>
 
       {/* Key Point */}
-      <div className="bg-orange-500/10 border border-orange-400/30 rounded-lg p-4">
+      <div className="bg-orange-100 dark:bg-orange-500/10 border border-orange-400/50 rounded-lg p-4">
-        <p className="text-sm text-gray-700 dark:text-gray-300">
+        <p className="text-sm text-gray-800 dark:text-gray-200">
-          <strong className="text-orange-600 dark:text-orange-400">Important:</strong>{" "}
+          <strong className="text-orange-700 dark:text-orange-400">Important:</strong>{" "}
           Main navigation is OUTSIDE the content area (fixed position). All page layouts
           (including sidebar variants) exist INSIDE the content area and use relative positioning
           to avoid overlapping with the main nav.

archon-ui-main/src/index.css

@@ -1,58 +1,60 @@
 @import "tailwindcss";
 
+@custom-variant dark (&:where(.dark, .dark *));
+
 :root {
-  /* Light mode variables */
+  /* Light mode variables - bare HSL values (Tailwind adds hsl() wrapper) */
-  --background: hsl(0 0% 98%);
+  --background: 0 0% 98%;
-  --foreground: hsl(240 10% 3.9%);
+  --foreground: 240 10% 3.9%;
-  --muted: hsl(240 4.8% 95.9%);
+  --muted: 240 4.8% 95.9%;
-  --muted-foreground: hsl(240 3.8% 46.1%);
+  --muted-foreground: 240 3.8% 46.1%;
-  --popover: hsl(0 0% 100%);
+  --popover: 0 0% 100%;
-  --popover-foreground: hsl(240 10% 3.9%);
+  --popover-foreground: 240 10% 3.9%;
-  --border: hsl(240 5.9% 90%);
+  --border: 240 5.9% 90%;
-  --input: hsl(240 5.9% 90%);
+  --input: 240 5.9% 90%;
-  --card: hsl(0 0% 100%);
+  --card: 0 0% 100%;
-  --card-foreground: hsl(240 10% 3.9%);
+  --card-foreground: 240 10% 3.9%;
-  --primary: hsl(271 91% 65%);
+  --primary: 271 91% 65%;
-  --primary-foreground: hsl(0 0% 100%);
+  --primary-foreground: 0 0% 100%;
-  --secondary: hsl(240 4.8% 95.9%);
+  --secondary: 240 4.8% 95.9%;
-  --secondary-foreground: hsl(240 5.9% 10%);
+  --secondary-foreground: 240 5.9% 10%;
-  --accent: hsl(271 91% 65%);
+  --accent: 271 91% 65%;
-  --accent-foreground: hsl(0 0% 100%);
+  --accent-foreground: 0 0% 100%;
-  --destructive: hsl(0 84.2% 60.2%);
+  --destructive: 0 84.2% 60.2%;
-  --destructive-foreground: hsl(0 0% 98%);
+  --destructive-foreground: 0 0% 98%;
-  --ring: hsl(240 5.9% 10%);
+  --ring: 240 5.9% 10%;
   --radius: 0.5rem;
 
   /* Tron accent colors */
-  --purple-accent: hsl(271 91% 65%);
+  --purple-accent: 271 91% 65%;
-  --green-accent: hsl(160 84% 39%);
+  --green-accent: 160 84% 39%;
-  --pink-accent: hsl(330 90% 65%);
+  --pink-accent: 330 90% 65%;
-  --blue-accent: hsl(217 91% 60%);
+  --blue-accent: 217 91% 60%;
 
   color-scheme: light;
 }
 
 .dark {
-  /* Dark mode variables */
+  /* Dark mode variables - bare HSL values */
-  --background: hsl(0 0% 0%);
+  --background: 0 0% 0%;
-  --foreground: hsl(0 0% 100%);
+  --foreground: 0 0% 100%;
-  --muted: hsl(240 4% 16%);
+  --muted: 240 4% 16%;
-  --muted-foreground: hsl(240 5% 65%);
+  --muted-foreground: 240 5% 65%;
-  --popover: hsl(0 0% 0%);
+  --popover: 0 0% 0%;
-  --popover-foreground: hsl(0 0% 100%);
+  --popover-foreground: 0 0% 100%;
-  --border: hsl(240 3.7% 15.9%);
+  --border: 240 3.7% 15.9%;
-  --input: hsl(240 3.7% 15.9%);
+  --input: 240 3.7% 15.9%;
-  --card: hsl(0 0% 0%);
+  --card: 0 0% 0%;
-  --card-foreground: hsl(0 0% 100%);
+  --card-foreground: 0 0% 100%;
-  --primary: hsl(271 91% 65%);
+  --primary: 271 91% 65%;
-  --primary-foreground: hsl(0 0% 100%);
+  --primary-foreground: 0 0% 100%;
-  --secondary: hsl(240 3.7% 15.9%);
+  --secondary: 240 3.7% 15.9%;
-  --secondary-foreground: hsl(0 0% 98%);
+  --secondary-foreground: 0 0% 98%;
-  --accent: hsl(271 91% 65%);
+  --accent: 271 91% 65%;
-  --accent-foreground: hsl(0 0% 100%);
+  --accent-foreground: 0 0% 100%;
-  --destructive: hsl(0 84.2% 60.2%);
+  --destructive: 0 84.2% 60.2%;
-  --destructive-foreground: hsl(0 0% 98%);
+  --destructive-foreground: 0 0% 98%;
-  --ring: hsl(240 3.7% 15.9%);
+  --ring: 240 3.7% 15.9%;
 
   color-scheme: dark;
 }