@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/styles/README.md

@@ -1,138 +1,83 @@
 # PACE Core Styling Guide
 
-This guide explains how to properly style PACE Core components using our simplified single-file CSS architecture with Tailwind v4 and native utilities.
+This guide explains how to properly style PACE Core components using our clean 3-file CSS architecture with Tailwind v4 and native utilities.
 
 > **🎨 New to PACE Core?** Start with the [Quick Start Guide](./getting-started/quick-start.md) to get up and running in 5 minutes.
 
 ## Overview
 
-PACE Core uses a **simplified single-file CSS architecture** that provides:
+PACE Core uses a **clean 3-file CSS architecture** that provides:
 
-1. **Complete Foundation** - Fonts, resets, typography, neutral tokens, and theme mappings
-2. **Native Utilities** - Native Tailwind utilities (bg-main-600, text-sec-700, etc.)
-3. **Default Palettes Included** - Sensible default main/sec/acc colors with option to override
-4. **No Conflicts** - Safe to import into any consuming application
-5. **Simplified Imports** - Single CSS file reduces import complexity and order issues
+1. **Base Styles** - Fonts, resets, typography, and neutral tokens
+2. **Theme Mappings** - Native Tailwind utilities (bg-main-600, text-sec-700, etc.)
+3. **Dark Mode** - Automatic shade remap for dark mode
+4. **App-Owned Palettes** - Each app defines its own main/sec/acc colors
+5. **No Conflicts** - Safe to import into any consuming application
 
-> **💡 Why This Architecture?** This approach provides maximum flexibility while maintaining consistency. Apps own their brand colors, while pace-core provides the complete styling foundation in a single file.
+> **💡 Why This Architecture?** This approach provides maximum flexibility while maintaining consistency. Apps own their brand colors, while pace-core provides the styling foundation and component styles.
 
-## The Single-File CSS Architecture
+## The 3-File CSS Architecture
 
-PACE Core ships with exactly 1 CSS file that contains everything:
+PACE Core ships with exactly 3 CSS files that work together:
 
-### `styles/core.css` - Complete Foundation
+### 1. `styles/base.css` - Foundation
 - **Fonts**: Georama, Open Sans, Reddit Mono with `font-display: swap`
 - **Base element styles**: h1-h6, p, a, lists, code, etc.
 - **Resets**: CSS resets and normalization
-- **Complete color palettes**: Main, secondary, and accent palettes with all shades (50-950) and semantic tokens
+- **Neutral tokens**: Background, foreground, muted colors that don't change with themes
 - **Focus styles**: Accessible focus indicators
+
+### 2. `styles/theme.css` - Native Utilities
 - **Color mappings**: Maps main/sec/acc palettes to native Tailwind utilities
 - **Typography**: Font family mappings (font-sans, font-serif, font-mono)
 - **Shadows & radii**: Named theme tokens for consistent styling
 - **Ring colors**: Focus ring color mappings
-- **Automatic scanning**: Uses `@source` directives to scan both pace-core and consuming app files
-
-
-## Built-in Color Palettes
 
-PACE Core comes with a beautiful default color palette that works out of the box:
-
-- **Main palette**: Silver tones for primary elements
-- **Secondary palette**: Violet tones for secondary elements  
-- **Accent palette**: Blood orange tones for highlights and accents
-
-The color palettes are defined in `core.css` and provide a complete set of shades from 50 to 950, giving you access to utilities like `bg-main-600`, `text-sec-700`, `border-acc-500`, etc.
+### 3. `styles/dark.css` - Dark Mode
+- **Shade remap**: Reverses lightness (50⇄950, 100⇄900, etc.)
+- **No hue shifts**: Only lightness changes, colors stay true to brand
+- **Neutral updates**: Updates background/foreground for dark mode
+
+## App-Owned Color Palettes
+
+Each consuming app defines its own brand colors in `app.css`:
+
+```css
+/* app.css - Your app's brand colors */
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-raw: oklch(0.7 0.057 252.02);
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  --color-main-200: oklch(0.927 0.012 252.02);
+  --color-main-300: oklch(0.881 0.021 252.02);
+  --color-main-400: oklch(0.822 0.032 252.02);
+  --color-main-500: oklch(0.75 0.047 252.02);
+  --color-main-600: oklch(0.7 0.057 252.02);
+  --color-main-700: oklch(0.567 0.044 252.02);
+  --color-main-800: oklch(0.456 0.034 252.02);
+  --color-main-900: oklch(0.332 0.024 252.02);
+  --color-main-950: oklch(0.195 0.014 252.02);
+
+  /* SEC palette - your secondary brand color */
+  --color-sec-raw: oklch(0.58 0.23 280.75);
+  --color-sec-50: oklch(0.98 0.003 280.75);
+  /* ... complete palette for sec */
+
+  /* ACC palette - your accent brand color */
+  --color-acc-raw: oklch(0.64 0.21 37.76);
+  --color-acc-50: oklch(0.98 0.003 37.76);
+  /* ... complete palette for acc */
+}
+```
 
 ### Benefits
 
-1. **Consistent Design**: All apps use the same beautiful color palette
+1. **Brand Ownership**: Each app controls its own visual identity
 2. **Native Utilities**: Use standard Tailwind classes (`bg-main-600`, `text-sec-700`)
-3. **No Configuration**: Works out of the box with no setup required
-4. **Easy Maintenance**: Colors are centrally managed in the core package
-5. **Future-Proof**: New features work with the existing color system
-
-## ⚠️ CRITICAL: File Scanning Configuration
-
-**IMPORTANT**: Pace-core components contain Tailwind classes that MUST be scanned during the build process. Without proper configuration, components will be unstyled.
-
-### Required Vite Configuration
-
-**You MUST include pace-core in your content scanning configuration:**
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      // CRITICAL: Include pace-core components for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-### Why This Configuration is Critical
-
-Without proper content scanning:
-- ❌ Pace-core component styles will be missing
-- ❌ Colors, spacing, and typography won't work
-- ❌ The UI will be severely compromised
-- ❌ The entire point of using this UI library is undermined
-
-### Alternative Configuration (if needed)
-
-If you're still having issues with component scanning:
-
-```ts
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: {
-        files: [
-          './src/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-        ]
-      }
-    })
-  ],
-})
-```
-
-### What This Configuration Does
-
-1. **Scans Your Source Files**: Detects Tailwind classes in your app's source code
-2. **Scans Pace-Core Components**: Ensures all Tailwind classes used in pace-core components are included
-3. **Generates Complete CSS**: Creates a CSS file with all necessary utility classes
-4. **Enables Proper Styling**: Allows pace-core components to render with correct styles
-
-### Verification
-
-After configuration, test with a simple component:
-
-```tsx
-import { Button, Card } from '@jmruthers/pace-core';
-
-function TestComponent() {
-  return (
-    <Card className="p-4">
-      <Button variant="primary">Test Button</Button>
-    </Card>
-  );
-}
-```
-
-The component should render with proper PACE Core styling. If it appears unstyled, check your Vite configuration.
+3. **No Conflicts**: Clean separation between app colors and component styles
+4. **Easy Updates**: Change colors in one file, everything updates
+5. **Future-Proof**: New features work with your existing colors
 
 ## Quick Start
 
@@ -142,16 +87,21 @@ The component should render with proper PACE Core styling. If it appears unstyle
 npm install @jmruthers/pace-core
 ```
 
-### 2. Import the Core CSS File
+### 2. Import the 3 CSS Files
 
 ```tsx
 // In your app's entry point (e.g., main.tsx)
-import '@jmruthers/pace-core/styles/core.css';
+import '@jmruthers/pace-core/styles/base.css';
+import '@jmruthers/pace-core/styles/theme.css';
+import '@jmruthers/pace-core/styles/dark.css';
+import './app.css'; // Your app's color palette
 ```
 
-**That's it!** No additional CSS files needed - everything is included.
+### 3. Define Your App's Colors
 
-### 3. Use Native Tailwind Utilities
+Create `app.css` with your brand colors (see example above).
+
+### 4. Use Native Tailwind Utilities
 
 ```tsx
 import { Button, Card, DataTable } from '@jmruthers/pace-core';
@@ -169,6 +119,33 @@ function MyComponent() {
 }
 ```
 
+## Dark Mode
+
+### Enable Dark Mode
+
+Add a dark mode toggle to your app:
+
+```tsx
+function DarkModeToggle() {
+  const toggleDarkMode = () => {
+    document.documentElement.toggleAttribute('data-mode', true);
+  };
+
+  return (
+    <button onClick={toggleDarkMode}>
+      Toggle Dark Mode
+    </button>
+  );
+}
+```
+
+### Dark Mode Behavior
+
+- Dark mode automatically reverses all color shades (50⇄950, 100⇄900, etc.)
+- No hue changes - only lightness reversal
+- All components automatically adapt to dark mode
+- Uses `[data-mode="dark"]` selector
+
 ## Dynamic Theming
 
 ### Organisation/Event Colors
@@ -216,19 +193,6 @@ const themeCSS = generateSSRThemeCSS(paletteData);
 
 Same patterns for `sec-*` and `acc-*` palettes.
 
-### Semantic Color Utilities
-
-PACE Core also provides semantic color utilities that automatically map to your palettes:
-
-- `bg-background`, `text-foreground` - Main background and text
-- `bg-primary`, `text-primary-foreground` - Primary actions
-- `bg-secondary`, `text-secondary-foreground` - Secondary elements
-- `bg-destructive`, `text-destructive-foreground` - Destructive actions
-- `bg-muted`, `text-muted-foreground` - Muted content
-- `bg-accent`, `text-accent-foreground` - Accent elements
-- `bg-card`, `text-card-foreground` - Card backgrounds
-- `bg-popover`, `text-popover-foreground` - Popover backgrounds
-
 ### Typography
 
 - `font-sans` - Open Sans
@@ -246,8 +210,8 @@ PACE Core also provides semantic color utilities that automatically map to your
 ### Before (Old System)
 ```tsx
 // Old app-* classes
-<div className="bg-main-500 text-main-50">
-  <Button className="bg-sec-600 hover:bg-sec-700">
+<div className="bg-app-main-500 text-app-main-50">
+  <Button className="bg-app-sec-600 hover:bg-app-sec-700">
     Click me
   </Button>
 </div>
@@ -268,8 +232,7 @@ PACE Core also provides semantic color utilities that automatically map to your
 - **No arbitrary values**: Use only standard utilities like `bg-main-600`, not `bg-[oklch(...)]`
 - **No CVA**: Components use native Tailwind utilities, not class-variance-authority
 - **No utility aliases**: Use standard Tailwind class names
-- **Default palettes included**: pace-core provides sensible defaults, but you can override with `app.css`
-- **Tailwind v4 only**: Uses CSS-first approach with `@theme` blocks, no `tailwind.config.js`
+- **App owns palettes**: Only define main/sec/acc in your `app.css`
 
 ## Troubleshooting
 
@@ -277,30 +240,41 @@ PACE Core also provides semantic color utilities that automatically map to your
 
 **Problem**: Components appear unstyled or with default browser styling.
 
-**Solution**: Ensure you've imported the core CSS file:
+**Solution**: Ensure you've imported all 3 CSS files:
 ```tsx
-import '@jmruthers/pace-core/styles/core.css';
+import '@jmruthers/pace-core/styles/base.css';
+import '@jmruthers/pace-core/styles/theme.css';
+import '@jmruthers/pace-core/styles/dark.css';
 ```
 
 **Problem**: Colors don't work (bg-main-600 shows as gray).
 
-**Solution**: The color palettes are built into core.css. If colors aren't working, check that:
-1. You've imported the core CSS file
-2. Tailwind v4 is properly configured
-3. Your build tool is processing the CSS correctly
+**Solution**: Ensure you've defined your color palettes in `app.css`:
+```css
+@theme static {
+  --color-main-600: oklch(0.7 0.057 252.02);
+  /* ... other shades */
+}
+```
+
+**Problem**: Dark mode doesn't work.
 
+**Solution**: Ensure you've imported `dark.css` and added the `data-mode="dark"` attribute:
+```tsx
+document.documentElement.setAttribute('data-mode', 'dark');
+```
 
 **Problem**: Fonts don't load correctly.
 
-**Solution**: Fonts are included in the package. Ensure you're importing `core.css` which contains the font definitions.
+**Solution**: Fonts are included in the package. Ensure you're importing `base.css` which contains the font definitions.
 
 ## Best Practices
 
-1. **Import CSS file** - Just core.css (no additional files needed)
-2. **Use native utilities** - Stick to standard Tailwind classes like `bg-main-600`
-3. **Configure content scanning** - Include pace-core in your Vite config for proper styling
-4. **Use built-in palettes** - All color palettes are included in core.css
-5. **Use semantic tokens** - Prefer `bg-primary` over `bg-main-600` for better maintainability
+1. **Import all 3 CSS files** - base.css, theme.css, and dark.css
+2. **Define complete palettes** - Include all shades (50-950) for main, sec, and acc
+3. **Use native utilities** - Stick to standard Tailwind classes like `bg-main-600`
+4. **Test dark mode** - Always test your app in both light and dark modes
+5. **Keep colors in app.css** - Don't define colors in component files
 
 ## Support
 

package/docs/testing/README.md

@@ -624,19 +624,23 @@ describe('Visual Regression Tests', () => {
 
 ```tsx
 import { render } from '@testing-library/react';
-import { Button } from '@jmruthers/pace-core';
+import { ThemeProvider, Button } from '@jmruthers/pace-core';
 
-describe('Component Tests', () => {
-  test('Button renders correctly', () => {
+describe('Theme Tests', () => {
+  test('Button renders with light theme', () => {
     const { container } = render(
-      <Button>Test Button</Button>
+      <ThemeProvider theme="light">
+        <Button>Light Theme Button</Button>
+      </ThemeProvider>
     );
     expect(container.firstChild).toMatchSnapshot();
   });
 
-  test('Button renders correctly', () => {
+  test('Button renders with dark theme', () => {
     const { container } = render(
-      <Button>Test Button</Button>
+      <ThemeProvider theme="dark">
+        <Button>Dark Theme Button</Button>
+      </ThemeProvider>
     );
     expect(container.firstChild).toMatchSnapshot();
   });