@stachelock/ui 0.1.9 → 0.2.1

package/CUSTOMIZATION.md

@@ -0,0 +1,325 @@
+# Customizing Stachelock UI Design Tokens
+
+Stachelock UI now supports customizing design tokens (colors, spacing, typography, etc.) to match your project's design system while maintaining the `sl-` prefixed utility classes.
+
+## Overview
+
+The customization system allows you to:
+- Override default colors, spacing, shadows, and typography
+- Generate custom CSS variables and Tailwind configurations
+- Maintain the `sl-` prefix to avoid conflicts with your existing styles
+- Use both programmatic configuration and build-time generation
+
+## Quick Start
+
+### 1. Create a Custom Tokens File
+
+Create a JSON file (e.g., `my-tokens.json`) with your custom design tokens:
+
+```json
+{
+  "colors": {
+    "primary": {
+      "50": "#f0f9ff",
+      "100": "#e0f2fe",
+      "500": "#0ea5e9",
+      "600": "#0284c7",
+      "700": "#0369a1"
+    },
+    "stachelock": {
+      "600": "#dc2626",
+      "700": "#b91c1c"
+    }
+  },
+  "spacing": {
+    "18": "4.5rem",
+    "22": "5.5rem"
+  }
+}
+```
+
+### 2. Generate Custom Configuration
+
+Use the CLI tool to generate custom CSS variables and Tailwind config:
+
+```bash
+# From your project directory
+npx @stachelock/ui generate-config ./my-tokens.json ./generated/
+```
+
+This will create:
+- `stachelock-ui-variables.css` - CSS custom properties
+- `stachelock-ui-tailwind.config.js` - Tailwind configuration
+- `stachelock-ui-tokens.json` - Merged tokens for reference
+
+### 3. Import and Use
+
+In your main CSS file:
+```css
+@import "./generated/stachelock-ui-variables.css";
+@import "@stachelock/ui/style.css";
+```
+
+In your `tailwind.config.js`:
+```javascript
+const stachelockConfig = require('./generated/stachelock-ui-tailwind.config.js');
+
+module.exports = {
+  content: ["./src/**/*.{vue,js,ts,jsx,tsx}"],
+  theme: {
+    extend: {
+      ...stachelockConfig.theme.extend
+    }
+  }
+};
+```
+
+## Programmatic Configuration
+
+### Using the Vue Plugin
+
+```typescript
+import { createApp } from 'vue';
+import { StachelockUI } from '@stachelock/ui';
+import App from './App.vue';
+
+const app = createApp(App);
+
+app.use(StachelockUI, {
+  designTokens: {
+    colors: {
+      primary: {
+        600: '#0ea5e9',
+        700: '#0369a1'
+      }
+    }
+  }
+});
+
+app.mount('#app');
+```
+
+### Advanced Plugin Usage
+
+```typescript
+import { StachelockUI } from '@stachelock/ui';
+
+// Configure after installation
+StachelockUI.configure({
+  designTokens: {
+    colors: {
+      brand: {
+        500: '#ff6b6b',
+        600: '#ee5a52'
+      }
+    }
+  },
+  prefix: 'sl-', // Keep default prefix
+  injectCSS: true // Automatically inject CSS variables
+});
+
+// Get current design tokens
+const tokens = StachelockUI.getDesignTokens();
+
+// Generate custom CSS
+const css = StachelockUI.generateCSS();
+```
+
+## Design Token Structure
+
+### Colors
+```typescript
+colors: {
+  primary: {
+    50: '#f0f9ff',    // Lightest
+    100: '#e0f2fe',
+    200: '#bae6fd',
+    300: '#7dd3fc',
+    400: '#38bdf8',
+    500: '#0ea5e9',   // Base
+    600: '#0284c7',
+    700: '#0369a1',
+    800: '#075985',
+    900: '#0c4a6e'    // Darkest
+  }
+}
+```
+
+### Spacing
+```typescript
+spacing: {
+  '0': '0',
+  '1': '0.25rem',
+  '2': '0.5rem',
+  '4': '1rem',
+  '8': '2rem',
+  '16': '4rem',
+  '32': '8rem',
+  '64': '16rem'
+}
+```
+
+### Border Radius
+```typescript
+borderRadius: {
+  'none': '0',
+  'sm': '0.125rem',
+  'DEFAULT': '0.25rem',
+  'md': '0.375rem',
+  'lg': '0.5rem',
+  'xl': '0.75rem',
+  '2xl': '1rem',
+  'full': '9999px'
+}
+```
+
+### Shadows
+```typescript
+shadows: {
+  'sm': '0 1px 2px 0 rgb(0 0 0 / 0.05)',
+  'DEFAULT': '0 1px 3px 0 rgb(0 0 0 / 0.1)',
+  'md': '0 4px 6px -1px rgb(0 0 0 / 0.1)',
+  'lg': '0 10px 15px -3px rgb(0 0 0 / 0.1)',
+  'xl': '0 20px 25px -5px rgb(0 0 0 / 0.1)'
+}
+```
+
+### Typography
+```typescript
+typography: {
+  fontFamily: {
+    sans: ['Inter', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+    display: ['Poppins', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+    mono: ['JetBrains Mono', 'ui-monospace', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'monospace']
+  },
+  fontSize: {
+    'xs': '0.75rem',
+    'sm': '0.875rem',
+    'base': '1rem',
+    'lg': '1.125rem',
+    'xl': '1.25rem',
+    '2xl': '1.5rem',
+    '3xl': '1.875rem',
+    '4xl': '2.25rem'
+  }
+}
+```
+
+### Breakpoints
+```typescript
+breakpoints: {
+  'sm': '640px',
+  'md': '768px',
+  'lg': '1024px',
+  'xl': '1280px',
+  '2xl': '1536px',
+  '3xl': '1600px'
+}
+```
+
+## Generated CSS Variables
+
+The system generates CSS custom properties that you can use in your own CSS:
+
+```css
+:root {
+  --sl-color-primary-50: #f0f9ff;
+  --sl-color-primary-100: #e0f2fe;
+  --sl-color-primary-500: #0ea5e9;
+  --sl-color-primary-600: #0284c7;
+  --sl-color-primary-700: #0369a1;
+  
+  --sl-spacing-18: 4.5rem;
+  --sl-spacing-22: 5.5rem;
+  
+  --sl-border-radius-2xl: 1rem;
+  --sl-border-radius-3xl: 1.5rem;
+  
+  --sl-shadow-glow: 0 0 20px rgba(59, 130, 246, 0.5);
+  --sl-shadow-glow-lg: 0 0 40px rgba(59, 130, 246, 0.3);
+}
+```
+
+## Using Custom Tokens in Components
+
+### In Vue Templates
+```vue
+<template>
+  <div class="sl-bg-primary-500 sl-text-white sl-p-18 sl-rounded-2xl sl-shadow-glow">
+    Custom styled content
+  </div>
+</template>
+```
+
+### In CSS
+```css
+.my-custom-component {
+  background-color: var(--sl-color-primary-500);
+  padding: var(--sl-spacing-18);
+  border-radius: var(--sl-border-radius-2xl);
+  box-shadow: var(--sl-shadow-glow);
+}
+```
+
+## Migration from Previous Versions
+
+If you're upgrading from a previous version:
+
+1. **No breaking changes** - existing `sl-` classes continue to work
+2. **New customization options** - you can now override design tokens
+3. **Backward compatibility** - all existing functionality is preserved
+
+## Best Practices
+
+### 1. Token Naming
+- Use semantic names (e.g., `primary`, `secondary`, `accent`)
+- Follow the 50-900 scale for colors
+- Use consistent naming across your design system
+
+### 2. Color Selection
+- Ensure sufficient contrast for accessibility
+- Test colors in both light and dark modes
+- Consider using tools like [Coolors](https://coolors.co/) for color generation
+
+### 3. Spacing Scale
+- Use consistent spacing increments
+- Consider your design system's needs
+- Common scales: 4px (0.25rem), 8px (0.5rem), 16px (1rem)
+
+### 4. Typography
+- Choose fonts that complement your brand
+- Ensure good readability across devices
+- Consider loading performance for custom fonts
+
+## Troubleshooting
+
+### Common Issues
+
+**CSS variables not loading**
+- Check that the CSS file is imported before other styles
+- Verify the file path is correct
+- Ensure the build process completed successfully
+
+**Tailwind classes not working**
+- Verify the Tailwind config is properly merged
+- Check that content paths include your components
+- Ensure the prefix is set to `sl-`
+
+**Build errors**
+- Check that all required dependencies are installed
+- Verify the JSON syntax in your tokens file
+- Ensure the output directory is writable
+
+### Getting Help
+
+- Check the [main README](../README.md) for general usage
+- Review the [examples](../examples/) directory for sample configurations
+- Open an issue on GitHub for bugs or feature requests
+
+## Examples
+
+See the [examples](../examples/) directory for complete working examples:
+
+- `custom-tokens.json` - Sample token configuration
+- `vue-app/` - Complete Vue application with custom tokens
+- `react-app/` - Complete React application with custom tokens