> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abdalkader.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Theming

> Customize the look and feel of components with CSS custom properties

## CSS Custom Properties

The library uses CSS custom properties (CSS variables) for theming. Override these variables to customize the appearance:

```css theme={null}
:root {
  /* Colors */
  --primary-color: #007bff;
  --primary-hover: #0056b3;
  --secondary-color: #6c757d;
  --secondary-hover: #545b62;
  --danger-color: #dc3545;
  --success-color: #28a745;
  --warning-color: #ffc107;
  --info-color: #17a2b8;
  
  /* Typography */
  --font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  
  /* Spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  
  /* Borders */
  --border-radius: 0.375rem;
  --border-width: 1px;
  --border-color: #dee2e6;
}
```

## Custom Theme Example

Create a custom theme by overriding variables:

```css theme={null}
/* theme.css */
:root {
  --primary-color: #8b5cf6;
  --primary-hover: #7c3aed;
  --border-radius: 0.5rem;
  --font-family: 'Inter', sans-serif;
}
```

Import your theme after the library styles:

```tsx theme={null}
import '@abdalkader/component-library/dist/styles.css';
import './theme.css';
```

## Dark Mode

Implement dark mode using CSS variables:

```css theme={null}
/* Dark mode theme */
[data-theme='dark'] {
  --primary-color: #3b9eff;
  --primary-hover: #007bff;
  --dark-color: #f8f9fa;
  --light-color: #343a40;
  --border-color: #495057;
}
```

Toggle dark mode in your app:

```tsx theme={null}
function App() {
  const [theme, setTheme] = useState('light');
  
  useEffect(() => {
    document.documentElement.setAttribute('data-theme', theme);
  }, [theme]);
  
  return (
    <div>
      <Button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
        Toggle Theme
      </Button>
    </div>
  );
}
```

## Component-Specific Styling

Override styles for specific components:

```css theme={null}
/* Custom button styles */
.btn--primary {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border: none;
}

.btn--primary:hover {
  background: linear-gradient(135deg, #764ba2 0%, #667eea 100%);
}
```

## Scoped Theming

Apply different themes to different parts of your app:

```tsx theme={null}
<div style={{ '--primary-color': '#e91e63' }}>
  <Button variant="primary">Pink Button</Button>
</div>

<div style={{ '--primary-color': '#4caf50' }}>
  <Button variant="primary">Green Button</Button>
</div>
```

## Available Variables

### Colors

| Variable            | Default   | Description         |
| ------------------- | --------- | ------------------- |
| `--primary-color`   | `#007bff` | Primary brand color |
| `--primary-hover`   | `#0056b3` | Primary hover state |
| `--secondary-color` | `#6c757d` | Secondary color     |
| `--danger-color`    | `#dc3545` | Danger/error color  |
| `--success-color`   | `#28a745` | Success color       |

### Typography

| Variable               | Default      | Description        |
| ---------------------- | ------------ | ------------------ |
| `--font-family`        | System fonts | Font family        |
| `--font-size-base`     | `1rem`       | Base font size     |
| `--font-weight-medium` | `500`        | Medium font weight |
| `--line-height-base`   | `1.5`        | Base line height   |

### Spacing

| Variable       | Default   | Description         |
| -------------- | --------- | ------------------- |
| `--spacing-xs` | `0.25rem` | Extra small spacing |
| `--spacing-sm` | `0.5rem`  | Small spacing       |
| `--spacing-md` | `1rem`    | Medium spacing      |
| `--spacing-lg` | `1.5rem`  | Large spacing       |

### Borders

| Variable          | Default    | Description   |
| ----------------- | ---------- | ------------- |
| `--border-radius` | `0.375rem` | Border radius |
| `--border-width`  | `1px`      | Border width  |
| `--border-color`  | `#dee2e6`  | Border color  |

## Best Practices

<AccordionGroup>
  <Accordion title="Use semantic color names">
    Define colors based on their purpose (primary, danger) rather than their appearance (blue, red).
  </Accordion>

  <Accordion title="Maintain contrast ratios">
    Ensure text and interactive elements meet WCAG AA standards (4.5:1 for normal text).
  </Accordion>

  <Accordion title="Test in both themes">
    If implementing dark mode, test all components in both light and dark themes.
  </Accordion>

  <Accordion title="Use relative units">
    Use rem/em for spacing and sizing to support user font size preferences.
  </Accordion>
</AccordionGroup>

## Examples

<CardGroup cols={2}>
  <Card title="Storybook Themes" icon="palette" href="https://components.abdalkader.dev">
    See themed components in action
  </Card>

  <Card title="CSS Variables Reference" icon="code" href="/api/button-props">
    Complete variable reference
  </Card>
</CardGroup>