@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/styles/README.md

@@ -1,83 +1,190 @@
 # PACE Core Styling Guide
 
-This guide explains how to properly style PACE Core components using our clean 3-file CSS architecture with Tailwind v4 and native utilities.
+This guide explains how to properly style PACE Core components using our two-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 **clean 3-file CSS architecture** that provides:
+PACE Core uses a **two-file CSS architecture** that provides:
 
-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
+1. **Core Foundation** - Fonts, resets, typography, semantic tokens, and component styles
+2. **App-Specific Colors** - Each consuming app defines its own main/sec/acc color palettes
+3. **Native Utilities** - Native Tailwind utilities (bg-main-600, text-sec-700, etc.)
+4. **Content Scanning** - Each app handles its own Tailwind content scanning
+5. **No Conflicts** - Clean separation between core styles and app-specific theming
 
-> **💡 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.
+> **💡 Why This Architecture?** This approach provides maximum flexibility while maintaining consistency. Apps own their brand colors and content scanning, while pace-core provides the complete styling foundation and semantic token system.
 
-## The 3-File CSS Architecture
+## The Two-File CSS Architecture
 
-PACE Core ships with exactly 3 CSS files that work together:
+PACE Core uses a clean separation of concerns with two CSS files:
 
-### 1. `styles/base.css` - Foundation
+### `styles/core.css` - Core Foundation (from pace-core package)
 - **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
-- **Neutral tokens**: Background, foreground, muted colors that don't change with themes
+- **Semantic color mappings**: Maps main/sec/acc palettes to semantic tokens
 - **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
+- **Component styles**: All pace-core component styling
+- **NO color palettes**: Apps define their own main/sec/acc colors
+- **NO source directives**: Apps handle their own content scanning
+
+### `src/app.css` - App-Specific Configuration (in each consuming app)
+- **Color palettes**: Main, secondary, and accent palettes with all shades (50-950)
+- **Source directives**: Tailwind v4 `@source` directives for content scanning
+- **App-specific theming**: Any additional app-specific CSS variables
+
 
-### 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-Specific Color Palettes
 
-## App-Owned Color Palettes
+Each consuming app must define its own color palettes in `src/app.css`. This provides complete control over branding while maintaining consistency through the semantic token system.
 
-Each consuming app defines its own brand colors in `app.css`:
+### Required Color Palette Structure
+
+Every app must define three color palettes with complete shade ranges (50-950):
 
 ```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 */
+  /* Main palette - Primary brand color */
+  --color-main-raw: oklch(0.58 0.23 300);
+  --color-main-50: oklch(0.98 0.003 300);
+  --color-main-100: oklch(0.96 0.014 300);
+  /* ... continue through 950 */
+  
+  /* Secondary palette - Supporting color */
+  --color-sec-raw: oklch(0.675 0.169 244.75);
+  --color-sec-50: oklch(0.98 0.003 244.75);
+  /* ... continue through 950 */
+  
+  /* Accent palette - Highlight color */
+  --color-acc-raw: oklch(0.64 0.23 7.385);
+  --color-acc-50: oklch(0.98 0.003 7.385);
+  /* ... continue through 950 */
 }
 ```
 
 ### Benefits
 
-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 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
+1. **Brand Control**: Each app defines its own unique color palette
+2. **Semantic Consistency**: All apps use the same semantic token system
+3. **Native Utilities**: Use standard Tailwind classes (`bg-main-600`, `text-sec-700`)
+4. **Easy Maintenance**: Colors are managed per app, not centrally
+5. **Future-Proof**: New features work with any color palette
+
+## ⚠️ CRITICAL: Required App Configuration
+
+**IMPORTANT**: Each consuming app must create a `src/app.css` file with proper color palettes and source directives. Without this configuration, components will be unstyled.
+
+### Required App CSS File
+
+**You MUST create `src/app.css` in your consuming app with the following structure:**
+
+```css
+@import "tailwindcss";
+
+/* @source directives for Tailwind v4 content scanning */
+@source "./src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/components/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/providers/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/hooks/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/utils/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/types/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/validation/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/rbac/**/*.{js,ts,jsx,tsx}";
+
+/* This file is only to contain the color palette for the app. NEVER ADD ANY CSS OVERRIDES TO THIS FILE!! */
+@theme static {
+  /* Main palette - Primary brand color */
+  --color-main-raw: oklch(0.58 0.23 300);
+  --color-main-50: oklch(0.98 0.003 300);
+  --color-main-100: oklch(0.96 0.014 300);
+  --color-main-200: oklch(0.927 0.033 300);
+  --color-main-300: oklch(0.881 0.059 300);
+  --color-main-400: oklch(0.822 0.093 300);
+  --color-main-500: oklch(0.75 0.133 300);
+  --color-main-600: oklch(0.665 0.182 300);
+  --color-main-700: oklch(0.58 0.23 300);
+  --color-main-800: oklch(0.456 0.158 300);
+  --color-main-900: oklch(0.332 0.099 300);
+  --color-main-950: oklch(0.195 0.047 300);
+
+  /* Secondary palette - Supporting color */
+  --color-sec-raw: oklch(0.675 0.169 244.75);
+  --color-sec-50: oklch(0.98 0.003 244.75);
+  --color-sec-100: oklch(0.96 0.014 244.75);
+  --color-sec-200: oklch(0.927 0.032 244.75);
+  --color-sec-300: oklch(0.881 0.057 244.75);
+  --color-sec-400: oklch(0.822 0.089 244.75);
+  --color-sec-500: oklch(0.75 0.128 244.75);
+  --color-sec-600: oklch(0.675 0.169 244.75);
+  --color-sec-700: oklch(0.567 0.134 244.75);
+  --color-sec-800: oklch(0.456 0.101 244.75);
+  --color-sec-900: oklch(0.332 0.068 244.75);
+  --color-sec-950: oklch(0.195 0.037 244.75);
+
+  /* Accent palette - Highlight color */
+  --color-acc-raw: oklch(0.64 0.23 7.385);
+  --color-acc-50: oklch(0.98 0.003 7.385);
+  --color-acc-100: oklch(0.96 0.017 7.385);
+  --color-acc-200: oklch(0.927 0.039 7.385);
+  --color-acc-300: oklch(0.881 0.069 7.385);
+  --color-acc-400: oklch(0.822 0.109 7.385);
+  --color-acc-500: oklch(0.75 0.157 7.385);
+  --color-acc-600: oklch(0.64 0.23 7.385);
+  --color-acc-700: oklch(0.567 0.193 7.385);
+  --color-acc-800: oklch(0.456 0.142 7.385);
+  --color-acc-900: oklch(0.332 0.092 7.385);
+  --color-acc-950: oklch(0.195 0.047 7.385);
+}
+```
+
+### Required Import Order
+
+**You MUST import both CSS files in the correct order:**
+
+```tsx
+// In your app's entry point (e.g., main.tsx)
+import '@jmruthers/pace-core/styles/core.css'; // Import core first
+import './app.css'; // Import app-specific colors second
+```
+
+### Why This Configuration is Critical
+
+Without proper app.css configuration:
+- ❌ 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
+
+### 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. **Defines Color Palettes**: Provides the main/sec/acc color values that core.css references
+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 app.css configuration.
 
 ## Quick Start
 
@@ -87,19 +194,38 @@ Each consuming app defines its own brand colors in `app.css`:
 npm install @jmruthers/pace-core
 ```
 
-### 2. Import the 3 CSS Files
+### 2. Create Your App CSS File
 
-```tsx
-// In your app's entry point (e.g., main.tsx)
-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
+Create `src/app.css` in your consuming app with your brand colors and source directives:
+
+```css
+@import "tailwindcss";
+
+/* @source directives for Tailwind v4 content scanning */
+@source "./src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/components/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/providers/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/hooks/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/utils/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/types/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/validation/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/rbac/**/*.{js,ts,jsx,tsx}";
+
+/* Define your brand color palettes */
+@theme static {
+  /* Your main, secondary, and accent color palettes here */
+  /* See the example above for the complete structure */
+}
 ```
 
-### 3. Define Your App's Colors
+### 3. Import Both CSS Files
 
-Create `app.css` with your brand colors (see example above).
+```tsx
+// In your app's entry point (e.g., main.tsx)
+import '@jmruthers/pace-core/styles/core.css'; // Import core first
+import './app.css'; // Import app-specific colors second
+```
 
 ### 4. Use Native Tailwind Utilities
 
@@ -119,33 +245,6 @@ 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
@@ -193,6 +292,19 @@ 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
@@ -210,8 +322,8 @@ Same patterns for `sec-*` and `acc-*` palettes.
 ### Before (Old System)
 ```tsx
 // Old app-* classes
-<div className="bg-app-main-500 text-app-main-50">
-  <Button className="bg-app-sec-600 hover:bg-app-sec-700">
+<div className="bg-main-500 text-main-50">
+  <Button className="bg-sec-600 hover:bg-sec-700">
     Click me
   </Button>
 </div>
@@ -232,7 +344,10 @@ Same patterns for `sec-*` and `acc-*` palettes.
 - **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
-- **App owns palettes**: Only define main/sec/acc in your `app.css`
+- **App-specific palettes required**: Each app must define its own main/sec/acc color palettes in `app.css`
+- **Tailwind v4 only**: Uses CSS-first approach with `@theme` blocks, no `tailwind.config.js`
+- **Two-file architecture**: Must use both `core.css` and `app.css` files
+- **Source directives required**: Each app must include `@source` directives for pace-core scanning
 
 ## Troubleshooting
 
@@ -240,41 +355,41 @@ Same patterns for `sec-*` and `acc-*` palettes.
 
 **Problem**: Components appear unstyled or with default browser styling.
 
-**Solution**: Ensure you've imported all 3 CSS files:
+**Solution**: Ensure you've imported both CSS files in the correct order:
 ```tsx
-import '@jmruthers/pace-core/styles/base.css';
-import '@jmruthers/pace-core/styles/theme.css';
-import '@jmruthers/pace-core/styles/dark.css';
+import '@jmruthers/pace-core/styles/core.css'; // Import core first
+import './app.css'; // Import app-specific colors second
 ```
 
 **Problem**: Colors don't work (bg-main-600 shows as gray).
 
-**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 */
-}
-```
+**Solution**: Check that you've created `src/app.css` with your color palettes. If colors aren't working, verify that:
+1. You've created `src/app.css` with complete color palettes (main, sec, acc)
+2. You've imported both CSS files in the correct order
+3. Your color palettes include all shades (50-950)
+4. Tailwind v4 is properly configured
 
-**Problem**: Dark mode doesn't work.
+**Problem**: Fonts don't load correctly.
 
-**Solution**: Ensure you've imported `dark.css` and added the `data-mode="dark"` attribute:
-```tsx
-document.documentElement.setAttribute('data-mode', 'dark');
-```
+**Solution**: Fonts are included in the core.css file. Ensure you're importing `core.css` which contains the font definitions.
 
-**Problem**: Fonts don't load correctly.
+**Problem**: Tailwind classes from pace-core components are missing.
 
-**Solution**: Fonts are included in the package. Ensure you're importing `base.css` which contains the font definitions.
+**Solution**: Check that your `src/app.css` includes the proper `@source` directives for pace-core:
+```css
+@source "./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}";
+@source "./node_modules/@jmruthers/pace-core/src/components/**/*.{js,ts,jsx,tsx}";
+/* ... other pace-core source directives */
+```
 
 ## Best Practices
 
-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
+1. **Create app.css** - Always create `src/app.css` with your brand colors and source directives
+2. **Import both CSS files** - Import core.css first, then app.css
 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
+4. **Complete color palettes** - Always define all shades (50-950) for main, sec, and acc palettes
+5. **Use semantic tokens** - Prefer `bg-primary` over `bg-main-600` for better maintainability
+6. **Keep app.css clean** - Only put color palettes and source directives in app.css, no other CSS
 
 ## Support
 

package/docs/testing/README.md

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