@jmruthers/pace-core 0.2.4

package/docs/troubleshooting/tailwind-content-scanning.md

@@ -0,0 +1,213 @@
+# Tailwind v4 Content Scanning Solutions
+
+This guide provides comprehensive solutions for Tailwind v4 content scanning issues with pace-core components.
+
+## 🚨 The Core Problem
+
+Tailwind v4 needs to scan source files to detect utility classes, but published packages only contain compiled JavaScript. This results in:
+
+- ❌ Only ~292 CSS rules instead of 987+ needed
+- ❌ Missing component styles
+- ❌ Severely compromised UI
+
+## ✅ Solution 1: Use Source Files (Recommended)
+
+Pace-core v0.4.15+ includes source files in the published package for Tailwind scanning.
+
+### Updated Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        // Your app's source files
+        './src/**/*.{js,ts,jsx,tsx}',
+        // Pace-core source files (NEW)
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### Alternative: PostCSS Configuration
+
+```javascript
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+## ✅ Solution 2: Pre-built CSS (Fallback)
+
+If source file scanning doesn't work, use the pre-built CSS approach:
+
+### 1. Import Pre-built CSS
+
+```tsx
+// src/main.tsx
+import '@jmruthers/pace-core/styles/core.css';
+// Don't import your own Tailwind CSS
+```
+
+### 2. Disable Tailwind in Your App
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+// Don't include tailwindcss plugin
+
+export default defineConfig({
+  plugins: [react()],
+})
+```
+
+## ✅ Solution 3: Hybrid Approach
+
+Use both approaches for maximum compatibility:
+
+### 1. Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
+        // Fallback: also scan dist files
+        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### 2. CSS Import
+
+```tsx
+// src/main.tsx
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+## 🔍 Verification Steps
+
+### 1. Check CSS Output Size
+
+After building, your CSS should be:
+- **Expected**: 50-100+ kB (with all utility classes)
+- **Problem**: 20-30 kB (missing classes)
+
+### 2. Verify Component Styling
+
+Test with a simple component:
+
+```tsx
+import { Button, Card } from '@jmruthers/pace-core';
+
+function TestComponent() {
+  return (
+    <Card className="p-4">
+      <Button variant="primary" className="bg-main-600 text-main-50">
+        Test Button
+      </Button>
+    </Card>
+  );
+}
+```
+
+**Expected Result**: Properly styled components with PACE Core colors and spacing.
+
+### 3. Check Browser Dev Tools
+
+Inspect elements to verify:
+- ✅ `bg-main-600` class is applied
+- ✅ `text-main-50` class is applied
+- ✅ Component has proper padding and styling
+
+## 🛠️ Troubleshooting
+
+### Issue: Source files not found
+
+**Error**: `Cannot resolve './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'`
+
+**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files.
+
+### Issue: Still only 292 rules
+
+**Possible Causes**:
+1. Using old package version
+2. Incorrect content paths
+3. Cached build files
+
+**Solutions**:
+1. Update to latest pace-core: `npm install @jmruthers/pace-core@latest`
+2. Clear node_modules and reinstall: `rm -rf node_modules package-lock.json && npm install`
+3. Clear build cache: `rm -rf dist .vite`
+
+### Issue: Build errors with source files
+
+**Error**: TypeScript errors when scanning source files
+
+**Solution**: Add TypeScript configuration for node_modules:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  },
+  "include": [
+    "src/**/*",
+    "node_modules/@jmruthers/pace-core/src/**/*"
+  ]
+}
+```
+
+## 📊 Expected Results
+
+With proper configuration, you should see:
+
+- **CSS file size**: 50-100+ kB
+- **Utility classes**: 800+ rules
+- **Component styling**: Full PACE Core design system
+- **Colors working**: `bg-main-600`, `text-sec-700`, etc.
+- **Spacing working**: `p-4`, `m-2`, `space-y-4`, etc.
+
+## 🆘 Still Having Issues?
+
+If none of these solutions work:
+
+1. **Check package version**: `npm list @jmruthers/pace-core`
+2. **Verify source files**: Check if `node_modules/@jmruthers/pace-core/src/` exists
+3. **Try pre-built CSS**: Use Solution 2 as a fallback
+4. **Contact support**: This may be a deeper compatibility issue
+
+## 📚 Related Documentation
+
+- [Installation Guide](../getting-started/installation.md)
+- [Vite Configuration](../consuming-app-vite-config.md)
+- [Troubleshooting Guide](./styling-issues.md)

package/docs/usage.md

@@ -0,0 +1,175 @@
+# PACE Core Styling Usage Guide
+
+This guide explains how to integrate PACE Core's new styling system into your application.
+
+## Quick Start
+
+### 1. Install PACE Core
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### 2. Import Required CSS Files
+
+In your app's entry point (e.g., `main.tsx` or root layout):
+
+```tsx
+// Import the core CSS file (includes default palettes)
+import '@jmruthers/pace-core/styles/core.css';
+
+// Optional: Override with your own palettes
+// import './app.css'; // Define your custom main/sec/acc palettes
+```
+
+### 3. Use the Built-in Color Palette
+
+PACE Core comes with a beautiful default color palette (silver, violet, blood orange) that works out of the box. No additional configuration needed! You can optionally override these by defining your own palettes in `app.css`.
+
+### 4. Use Components
+
+Now you can use PACE Core components with native Tailwind utilities:
+
+```tsx
+import { Button, Card, DataTable } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  return (
+    <Card className="bg-main-50 border-main-200">
+      <h2 className="text-main-900">Welcome</h2>
+      <p className="text-sec-700">This uses your brand colors!</p>
+      <Button className="bg-main-600 hover:bg-main-700">
+        Click me
+      </Button>
+    </Card>
+  );
+}
+```
+
+## Dynamic Theming
+
+### Organisation/Event Colors
+
+Apply dynamic colors from your database:
+
+```tsx
+import { applyPalette, clearPalette } from '@jmruthers/pace-core/theming/runtime';
+
+// Apply organisation colors
+function applyOrganisationColors(orgData: any) {
+  applyPalette({
+    main: orgData.colors.main,
+    sec: orgData.colors.sec,
+    acc: orgData.colors.acc
+  });
+}
+
+// Clear dynamic theming (return to app defaults)
+function resetToAppColors() {
+  clearPalette();
+}
+```
+
+### SSR Support
+
+For server-side rendering, generate the theme CSS:
+
+```tsx
+import { generateSSRThemeCSS } from '@jmruthers/pace-core/theming/runtime';
+
+// In your SSR setup
+const themeCSS = generateSSRThemeCSS(paletteData);
+// Inject into your HTML head
+```
+
+## Available Utilities
+
+### Color Utilities
+
+- `bg-main-50` through `bg-main-950`
+- `text-main-50` through `text-main-950`
+- `border-main-200`, `border-main-300`
+- `ring-main-500`, `ring-sec-500`, `ring-acc-500`
+
+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
+- `font-serif` - Open Sans (serif fallback)
+- `font-mono` - Reddit Mono
+
+### Other Utilities
+
+- `rounded-sm` through `rounded-2xl`
+- `shadow-sm` through `shadow-2xl`
+- Custom utilities: `.pace-text-balance`, `.pace-scrollbar-hide`
+
+## Migration from Old System
+
+### Before (Old System)
+```tsx
+// Old app-* classes
+<div className="bg-main-500 text-main-50">
+  <Button className="bg-sec-600 hover:bg-sec-700">
+    Click me
+  </Button>
+</div>
+```
+
+### After (New System)
+```tsx
+// New native utilities
+<div className="bg-main-500 text-main-50">
+  <Button className="bg-sec-600 hover:bg-sec-700">
+    Click me
+  </Button>
+</div>
+```
+
+## Constraints
+
+- **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`
+
+## Troubleshooting
+
+### Colors Not Appearing
+- Ensure you've imported `@jmruthers/pace-core/styles/core.css`
+- If using custom palettes, check that your `app.css` defines the complete palette
+- Verify Tailwind v4 is installed
+- Check that font files are available in your `/fonts` directory
+
+
+### Dynamic Theming Issues
+- Verify palette data has correct structure (main/sec/acc with 50-950 shades)
+- Check browser console for errors
+- Use `isDynamicThemingActive()` to debug
+
+## Visual Testing
+
+For visual regression testing and component verification, see the [Visual Testing Guide](./visual-testing.md).
+
+## Support
+
+For issues or questions:
+- Check the [GitHub repository](https://github.com/jmruthers/pace-core)
+- Review component documentation
+- See [Visual Testing Guide](./visual-testing.md) for visual regression testing
+- Open an issue with reproduction steps

package/docs/visual-testing.md

@@ -0,0 +1,114 @@
+# Visual Testing Guide
+
+This document outlines the visual testing approach for pace-core components to ensure visual parity after the styling refactor.
+
+## Before/After Visual Testing
+
+### Testing Approach
+
+1. **Component Snapshots**: Each component should be tested with visual snapshots
+2. **Color Variations**: Test with different palette combinations
+4. **Responsive**: Test at different screen sizes
+
+### Key Components to Test
+
+#### Button Component
+- **Variants**: default, destructive, outline, secondary, ghost, link
+- **Sizes**: sm, default, lg, icon
+- **States**: normal, hover, active, disabled, focus
+
+#### Card Component  
+- **Variants**: default, outline, ghost
+- **Sizes**: default, sm, lg
+- **Content**: with/without header, footer, actions
+
+#### DataTable Component
+- **States**: empty, loading, with data
+- **Features**: sorting, filtering, pagination
+- **Responsive**: mobile, tablet, desktop
+
+### Visual Regression Testing
+
+#### Setup
+```bash
+# Install visual testing tools
+npm install --save-dev @storybook/react @storybook/addon-storyshots
+
+# Run visual tests
+npm run test:visual
+```
+
+#### Test Cases
+
+1. **Light Mode Default Palette**
+   - Use default main/sec/acc colors
+   - Verify all components render correctly
+   - Check color contrast ratios
+
+   - Check no hue shifts occur
+
+3. **Dynamic Palette Replacement**
+   - Apply different organisation palettes
+   - Verify all components update correctly
+   - Test palette switching
+
+4. **Custom App Palettes**
+   - Test with different brand colors
+   - Verify OKLCH format works correctly
+   - Check all shade variations (50-950)
+
+### Visual Parity Checklist
+
+- [ ] Button variants maintain same visual appearance
+- [ ] Card shadows and borders unchanged
+- [ ] DataTable styling consistent
+- [ ] Typography hierarchy preserved
+- [ ] Focus states work correctly
+- [ ] Hover effects unchanged
+- [ ] Spacing and layout identical
+- [ ] Color contrast maintained
+- [ ] Dynamic theming works
+
+### Screenshot Comparison
+
+#### Before (Legacy System)
+- Components using `app-*` classes
+- CVA-based styling
+- Complex theming system
+
+#### After (New System)
+- Components using native utilities (`main-*`, `sec-*`, `acc-*`)
+- No CVA dependency
+- Simple runtime theming
+
+### Testing Tools
+
+1. **Chromatic** - Visual regression testing
+2. **Percy** - Cross-browser visual testing  
+3. **Storybook** - Component isolation and testing
+4. **Playwright** - Automated visual testing
+
+### Manual Testing Checklist
+
+- [ ] All components render without errors
+- [ ] Colors display correctly in light mode
+- [ ] Dynamic palette switching works
+- [ ] No visual regressions detected
+- [ ] Performance is maintained or improved
+- [ ] Accessibility features work correctly
+
+### Reporting Issues
+
+If visual regressions are found:
+
+1. Document the specific component and variant
+2. Note the expected vs actual appearance
+3. Check if it's a color mapping issue
+4. Verify the palette values are correct
+5. Test with different color combinations
+
+### Maintenance
+
+- Update visual tests when adding new components
+- Re-run tests after palette changes
+- Test dynamic theming with new palettes