@jmruthers/pace-core 0.5.74 → 0.5.76

package/docs/implementation-guides/component-styling.md

@@ -0,0 +1,410 @@
+# Component Styling Guide
+
+> **📚 Implementation Guide**: Component Customization | [← Back](../README.md) | [Styling Overview](../styles/README.md)
+
+Complete guide to customizing and styling PACE Core components.
+
+---
+
+**Last Updated**: 2025-02-08 | **Version**: v0.5.65+
+
+## Overview
+
+PACE Core components are fully customizable while maintaining design system consistency. This guide shows you how to:
+
+- Customize component appearance
+- Create custom themes
+- Override component styles
+- Maintain design system consistency
+- Build custom components using design tokens
+
+## Customizing Component Styles
+
+### 1. Using className Prop
+
+All PACE Core components accept a `className` prop for styling:
+
+```tsx
+import { Button, Card, Input } from '@jmruthers/pace-core';
+
+function CustomButton() {
+  return (
+    <Button 
+      className="bg-main-600 text-main-50 hover:bg-main-700 px-6"
+    >
+      Custom Styled Button
+    </Button>
+  );
+}
+
+function CustomCard() {
+  return (
+    <Card className="border-2 border-main-300 shadow-lg">
+      <p>Custom styled card</p>
+    </Card>
+  );
+}
+```
+
+### 2. Overriding Default Styles
+
+```tsx
+// Override specific styles while keeping defaults
+<Button 
+  variant="primary"
+  className="!bg-acc-500 hover:!bg-acc-600"
+>
+  Accent Colored Button
+</Button>
+```
+
+### 3. Responsive Styling
+
+```tsx
+<Card className="p-4 md:p-6 lg:p-8">
+  <h2 className="text-lg md:text-xl lg:text-2xl">Responsive Title</h2>
+</Card>
+```
+
+---
+
+## Creating Custom Themes
+
+### 1. Define Theme Variables
+
+Create a custom theme file:
+
+```css
+/* src/themes/my-theme.css */
+@theme {
+  /* Override design tokens */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 12px;
+  
+  --spacing-unit: 4px;
+  
+  /* Custom colors if needed */
+  --color-brand: oklch(0.58 0.23 300);
+}
+```
+
+### 2. Apply Theme
+
+```tsx
+import './themes/my-theme.css';
+import '@jmruthers/pace-core/src/styles/core.css';
+
+function App() {
+  return <YourApp />;
+}
+```
+
+---
+
+## Design Token Usage
+
+### Spacing
+
+```tsx
+<div className="p-4 md:p-6 lg:p-8">
+  {/* Padding: 16px, 24px, 32px on md, lg */}
+</div>
+
+<div className="mt-2 mb-4 mx-auto">
+  {/* Using spacing tokens */}
+</div>
+```
+
+### Typography
+
+```tsx
+// Use semantic typography
+<h1 className="text-3xl font-bold">Heading</h1>
+<p className="text-base font-sans">Body text</p>
+<code className="text-sm font-mono">Code snippet</code>
+```
+
+### Colors
+
+```tsx
+// Use semantic color tokens
+<div className="bg-background text-foreground">
+  <h2 className="text-primary">Primary Text</h2>
+  <p className="text-muted-foreground">Muted Text</p>
+  <button className="bg-accent hover:bg-accent/80">
+    Accent Button
+  </button>
+</div>
+```
+
+### Radius
+
+```tsx
+<Button className="rounded-lg">Rounded Button</Button>
+<Card className="rounded-xl">Extra Rounded Card</Card>
+```
+
+---
+
+## Custom Component Patterns
+
+### 1. Reusable Styled Components
+
+```tsx
+// Create your own styled components
+import { Button } from '@jmruthers/pace-core';
+
+interface PrimaryButtonProps {
+  children: React.ReactNode;
+  onClick?: () => void;
+}
+
+function PrimaryButton({ children, onClick }: PrimaryButtonProps) {
+  return (
+    <Button
+      className="bg-main-600 hover:bg-main-700 text-main-50 px-6 py-2 rounded-lg font-semibold"
+      onClick={onClick}
+    >
+      {children}
+    </Button>
+  );
+}
+
+// Usage
+<PrimaryButton onClick={() => console.log('Clicked')}>
+  Submit Form
+</PrimaryButton>
+```
+
+### 2. Custom DataTable Styling
+
+```tsx
+import { DataTable } from '@jmruthers/pace-core';
+
+function StyledDataTable({ data, columns }) {
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      className="rounded-lg shadow-md border border-main-200"
+      features={{
+        search: true,
+        pagination: true,
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Style Override Patterns
+
+### Pattern 1: Component-Level Overrides
+
+```tsx
+// Override specific component without affecting others
+<Button className="!text-acc-600 !border-acc-600">
+  Custom Button
+</Button>
+```
+
+### Pattern 2: Global Overrides (Not Recommended)
+
+```css
+/* ❌ Avoid global overrides when possible */
+@layer components {
+  .pace-btn {
+    /* This affects ALL buttons globally */
+  }
+}
+```
+
+### Pattern 3: Scoped Overrides
+
+```tsx
+function CustomSection() {
+  return (
+    <div className="custom-section">
+      <style jsx>{`
+        .custom-section :global(.pace-btn) {
+          /* Only affects buttons inside this section */
+        }
+      `}</style>
+      <Button>Scoped Button</Button>
+    </div>
+  );
+}
+```
+
+---
+
+## Advanced Customization
+
+### 1. Custom Design Tokens
+
+```css
+/* src/app.css */
+@theme {
+  /* Custom spacing scale */
+  --spacing-05: calc(var(--spacing-unit) * 0.5);
+  --spacing-1: var(--spacing-unit);
+  --spacing-2: calc(var(--spacing-unit) * 2);
+  --spacing-3: calc(var(--spacing-unit) * 3);
+  
+  /* Custom colors */
+  --color-success: oklch(0.6 0.2 150);
+  --color-warning: oklch(0.7 0.2 50);
+  --color-error: oklch(0.6 0.3 0);
+}
+```
+
+### 2. Custom Animations
+
+```css
+/* src/app.css */
+@keyframes slideIn {
+  from {
+    transform: translateX(-100%);
+    opacity: 0;
+  }
+  to {
+    transform: translateX(0);
+    opacity: 1;
+  }
+}
+
+.animate-slide-in {
+  animation: slideIn 0.3s ease-out;
+}
+```
+
+### 3. Component Composition
+
+```tsx
+import { Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
+
+function CustomDashboardCard({ title, children }) {
+  return (
+    <Card className="bg-gradient-to-br from-main-50 to-sec-50 border-main-300">
+      <CardHeader className="border-b border-main-200 pb-4">
+        <CardTitle className="text-main-900 text-xl">{title}</CardTitle>
+      </CardHeader>
+      <CardContent className="p-6">
+        {children}
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use semantic tokens** for consistency
+   ```tsx
+   <div className="bg-primary text-primary-foreground">
+   ```
+
+2. **Extend components with className**
+   ```tsx
+   <Button className="custom-extra-styles">
+   ```
+
+3. **Create reusable styled components**
+   ```tsx
+   function PrimaryButton() { /* ... */ }
+   ```
+
+4. **Use responsive utilities**
+   ```tsx
+   <div className="p-4 md:p-6 lg:p-8">
+   ```
+
+### ❌ Don't
+
+1. **Don't use arbitrary values unnecessarily**
+   ```tsx
+   // ❌ Bad
+   <div className="bg-[oklch(0.5 0.2 200)]">
+   ```
+
+2. **Don't override design tokens globally**
+   ```css
+   /* ❌ Bad - affects entire app */
+   --color-primary: red;
+   ```
+
+3. **Don't use inline styles**
+   ```tsx
+   // ❌ Bad
+   <div style={{ color: 'red' }}>
+   ```
+
+---
+
+## Common Customizations
+
+### Custom Button Variants
+
+```tsx
+function GradientButton({ children, onClick }) {
+  return (
+    <Button
+      className="bg-gradient-to-r from-main-600 to-sec-600 hover:from-main-700 hover:to-sec-700 text-main-50"
+      onClick={onClick}
+    >
+      {children}
+    </Button>
+  );
+}
+```
+
+### Custom Input Styling
+
+```tsx
+function StyledInput({ label, ...props }) {
+  return (
+    <div className="space-y-2">
+      <Label className="text-main-900 font-semibold">{label}</Label>
+      <Input
+        className="border-main-300 focus:border-main-500 focus:ring-main-500"
+        {...props}
+      />
+    </div>
+  );
+}
+```
+
+### Custom Card Styles
+
+```tsx
+function DashboardCard({ title, children }) {
+  return (
+    <Card className="hover:shadow-lg transition-shadow">
+      <CardHeader className="bg-main-600 text-main-50 rounded-t-lg">
+        <CardTitle>{title}</CardTitle>
+      </CardHeader>
+      <CardContent className="p-6">
+        {children}
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## Related Documentation
+
+- [Styling Overview](../styles/README.md) - Complete styling system
+- [Performance Guide](../best-practices/performance.md) - Performance optimization
+- [Component API Reference](../api-reference/components.md) - Component props
+
+---
+
+**Next Steps**: Start customizing components to match your brand while maintaining design system consistency.

package/docs/implementation-guides/data-tables.md

@@ -1,6 +1,6 @@
 # Data Tables
 
-> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [Forms](./forms.md) | [RBAC Usage](./datatable-rbac-usage.md)
+> **📚 Implementation Guide**: Data Management | [← Back](../README.md) | [Forms](./forms.md) | [RBAC Usage](./datatable-rbac-usage.md)
 
 This guide covers implementing data tables with PACE Core's DataTable component, including basic usage, advanced features, and best practices.