@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/standards/README.md

@@ -0,0 +1,35 @@
+# 📚 PACE Standards — Master README
+
+## Purpose
+This document is the single source of truth for all engineering standards for pace-core and consuming apps.
+
+## pace-core Standards
+- 01-architecture-standard.md
+- 02-api-and-rpc-standard.md
+- 03-component-standard.md
+- 04-code-style-standard.md
+- 05-security-standard.md
+- 06-testing-and-docs-standard.md
+
+## Consuming App Standards
+- 01-app-architecture.md
+- 02-pace-core-integration.md
+- 03-domain-model.md
+- 04-app-security-and-rbac.md
+- 05-testing-strategy.md
+- 06-ai-collaboration.md
+
+## Precedence
+1. Security
+2. API/RPC
+3. Components
+4. Code Style
+5. Testing
+6. Documentation
+7. Consuming App Standards
+
+## AI Rules
+- Read relevant standards
+- Apply Cursor Checklists
+- Prefer pace-core for reusable logic
+- Update docs on API changes

package/docs/styles/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T18:30:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # PACE Core Styling Guide
@@ -386,6 +386,19 @@ import './app.css'; // Import app-specific colors second
 /* ... other pace-core source directives */
 ```
 
+### Colors Not Appearing
+
+- Ensure you've imported `@jmruthers/pace-core/src/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 dynamic theming state
+
 ## Best Practices
 
 1. **Create app.css** - Always create `src/app.css` with your brand colors and source directives
@@ -395,18 +408,86 @@ import './app.css'; // Import app-specific colors second
 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
 
+## Visual Testing
+
+For visual regression testing and component verification, see the [Visual Testing Guide](./visual-testing.md).
+
 ## Support
 
 If you're having trouble with PACE Core styling:
 
 1. Check the [troubleshooting section](#troubleshooting) above
-2. Review the [usage guide](../usage.md) for complete examples
-3. Check the [visual testing guide](../visual-testing.md) for component verification
+2. Review the examples in this guide
+3. Check the [visual testing guide](./visual-testing.md) for component verification
 4. Open an issue on our GitHub repository
 
+## ♿ Accessibility
+
+Styling implementations should maintain accessibility:
+
+- **Color contrast** - All color combinations meet WCAG 2.1 AA contrast requirements
+- **Focus indicators** - Accessible focus styles are included in core.css
+- **Semantic color tokens** - Use semantic tokens (bg-primary, text-foreground) for better accessibility
+- **High contrast support** - Color palettes support high contrast modes
+- **Screen reader compatibility** - Styling doesn't interfere with screen reader functionality
+
+### Accessibility Best Practices
+
+1. **Test color contrast** - Verify all text/background combinations meet WCAG standards
+2. **Use semantic tokens** - Prefer `bg-primary` over `bg-main-600` for better maintainability
+3. **Ensure focus visibility** - Focus indicators are included, but verify they're visible
+4. **Test with assistive technologies** - Verify styling works with screen readers
+5. **Maintain color independence** - Don't rely solely on color to convey information
+
+## ⚠️ Edge Cases
+
+### Missing app.css Configuration
+
+When `app.css` is missing or incomplete:
+- Components will appear unstyled
+- Colors won't work (will show as gray/default)
+- Verify `app.css` exists and includes complete color palettes
+- Check import order (core.css first, then app.css)
+- Verify all `@source` directives are present
+
+### Tailwind v4 Content Scanning Issues
+
+When Tailwind classes are missing:
+- Verify `@source` directives include pace-core paths
+- Check that all pace-core component paths are scanned
+- Ensure Tailwind v4 is properly configured
+- Review content scanning configuration
+- See [troubleshooting guide](../troubleshooting/styling-issues.md) for detailed help
+
+### Dynamic Theming Conflicts
+
+When dynamic theming conflicts with app colors:
+- Verify palette structure matches expected format
+- Check that dynamic theming is properly cleared when needed
+- Ensure app.css colors are defined before dynamic theming
+- Test with both static and dynamic theming scenarios
+- Review dynamic theming implementation
+
+### Color Palette Inconsistencies
+
+When colors don't match expectations:
+- Verify all shades (50-950) are defined for each palette
+- Check OKLCH color format is correct
+- Ensure color values are within valid ranges
+- Test color rendering across different browsers
+- Verify semantic token mappings in core.css
+
+### Import Order Issues
+
+When styles don't apply correctly:
+- Verify core.css is imported before app.css
+- Check that both files are imported in entry point
+- Ensure no conflicting CSS imports
+- Review import statements for correctness
+- Test with minimal configuration
+
 ## Next Steps
 
-- [Usage Guide](../usage.md) - Complete integration guide
-- [Visual Testing Guide](../visual-testing.md) - Component verification
 - [Component Documentation](../api-reference/components.md) - Individual component docs
-- [Migration Guide](../migration-guide.md) - Detailed migration instructions
+- [Visual Testing Guide](./visual-testing.md) - Component verification
+- [Implementation Guides](../implementation-guides/component-styling.md) - Component styling guide

package/docs/testing/README.md

@@ -1,14 +1,14 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T19:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Testing Guide
 
 This guide covers testing strategies, patterns, and best practices for applications built with PACE Core.
 
-> 📖 **For comprehensive testing standards and patterns**, see the [Testing Standard](../../src/__tests__/TEST_STANDARD.md) - the authoritative guide for writing world-class tests in pace-core.
+> 📖 **For comprehensive testing standards and patterns**, see the [Testing Standard](../standards/testing-standard.md) - the authoritative guide for writing world-class tests in pace-core.
 
 ## Overview
 
@@ -590,7 +590,32 @@ describe('Keyboard Navigation', () => {
 
 ## Visual Regression Testing
 
-### 1. Component Snapshots
+Visual regression testing ensures visual parity after styling changes and helps catch unintended visual changes.
+
+### Testing Approach
+
+1. **Component Snapshots**: Each component should be tested with visual snapshots
+2. **Color Variations**: Test with different palette combinations
+3. **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
+
+### Component Snapshots
 
 ```tsx
 import { render } from '@testing-library/react';
@@ -628,29 +653,90 @@ describe('Visual Regression Tests', () => {
 });
 ```
 
-### 2. Theme Testing
+### Visual Testing Setup
 
-```tsx
-import { render } from '@testing-library/react';
-import { Button } from '@jmruthers/pace-core';
-
-describe('Component Tests', () => {
-  test('Button renders correctly', () => {
-    const { container } = render(
-      <Button>Test Button</Button>
-    );
-    expect(container.firstChild).toMatchSnapshot();
-  });
+```bash
+# Install visual testing tools
+npm install --save-dev @storybook/react @storybook/addon-storyshots
 
-  test('Button renders correctly', () => {
-    const { container } = render(
-      <Button>Test Button</Button>
-    );
-    expect(container.firstChild).toMatchSnapshot();
-  });
-});
+# 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
+
+2. **Dynamic Palette Replacement**
+   - Apply different organisation palettes
+   - Verify all components update correctly
+   - Test palette switching
+   - Check no hue shifts occur
+
+3. **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
+
 ## Performance Testing
 
 ### 1. Component Performance Tests
@@ -880,3 +966,68 @@ module.exports = {
 - **Test accessibility** and performance
 
 This testing guide provides comprehensive coverage of testing strategies for PACE Core applications. Follow these patterns and best practices to ensure your applications are well-tested and maintainable.
+
+## ♿ Accessibility
+
+Testing should include accessibility considerations:
+
+- **Accessibility testing tools** - Use jest-axe for automated accessibility testing
+- **Keyboard navigation testing** - Verify all interactive elements are keyboard accessible
+- **Screen reader compatibility** - Test with assistive technologies
+- **Color contrast verification** - Ensure all color combinations meet WCAG standards
+- **Focus management testing** - Verify focus indicators and focus order
+
+### Accessibility Best Practices
+
+1. **Include accessibility tests** - Add accessibility tests to your test suite
+2. **Test keyboard navigation** - Verify all interactive elements are keyboard accessible
+3. **Test with screen readers** - Use assistive technologies to verify functionality
+4. **Verify color contrast** - Test color combinations meet WCAG standards
+5. **Test focus management** - Ensure focus indicators are visible and logical
+
+## ⚠️ Edge Cases
+
+### Test Environment Issues
+
+When tests fail due to environment issues:
+- Verify test setup files are correctly configured
+- Check that all required mocks are in place
+- Ensure test utilities are properly imported
+- Review test configuration for correctness
+- Test with minimal configuration
+
+### Mock Data Inconsistencies
+
+When mocks don't match actual API responses:
+- Update mocks to match current API structure
+- Verify mock data matches production data structure
+- Test with realistic data scenarios
+- Review mock implementations for accuracy
+- Test with different data variations
+
+### Visual Regression False Positives
+
+When visual tests fail incorrectly:
+- Verify screenshot comparison thresholds
+- Check for environment-specific differences
+- Review test configuration for consistency
+- Test with different browsers and devices
+- Verify color rendering across platforms
+
+### Performance Test Flakiness
+
+When performance tests are inconsistent:
+- Use appropriate performance thresholds
+- Account for system load variations
+- Test in consistent environments
+- Review performance test methodology
+- Consider using statistical analysis
+
+### Integration Test Timing Issues
+
+When integration tests fail due to timing:
+- Use proper wait conditions
+- Account for async operations
+- Test with realistic network delays
+- Review test timeout settings
+- Verify proper cleanup between tests

package/docs/troubleshooting/README.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T15:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Troubleshooting Guide
@@ -870,6 +870,53 @@ function DebugInfo() {
 - [ ] Update error handling if needed
 - [ ] Consider adding monitoring for similar issues
 
+## ♿ Accessibility
+
+Troubleshooting should consider accessibility:
+
+- **WCAG 2.1 AA compliance** - Ensure fixes maintain accessibility standards
+- **Screen Reader Support** - Verify solutions don't break screen reader functionality
+- **Keyboard Navigation** - Ensure fixes don't affect keyboard accessibility
+- **Error Announcements** - Ensure error messages are accessible
+- **Focus Management** - Verify focus handling remains correct
+
+### Accessibility Best Practices
+
+1. **Test with screen readers** - Verify fixes work with assistive technologies
+2. **Check error announcements** - Ensure error messages are properly announced
+3. **Maintain keyboard access** - Verify all interactive elements remain keyboard accessible
+4. **Preserve semantic structure** - Don't break semantic HTML with workarounds
+5. **Test focus management** - Ensure focus handling remains correct
+
+## ⚠️ Edge Cases
+
+### Multiple Issues Occurring Simultaneously
+
+When multiple issues occur at once:
+- Address setup issues first (RBAC, providers, environment)
+- Fix authentication before permission issues
+- Resolve network/CORS before data fetching issues
+- Test each fix independently
+- Use systematic debugging approach
+
+### Issues That Only Occur in Production
+
+When issues only appear in production:
+- Verify environment variables are set correctly
+- Check build configuration matches development
+- Ensure all dependencies are included in build
+- Verify API endpoints are accessible from production
+- Check for environment-specific configuration differences
+
+### Intermittent Issues
+
+When issues occur intermittently:
+- Check for race conditions in async operations
+- Verify cache invalidation is working correctly
+- Check for timing issues in provider setup
+- Monitor network conditions
+- Review error logs for patterns
+
 ## Related Documentation
 
 - [Common Issues](./common-issues.md) - Specific problem solutions