import { Meta, Canvas, Story } from "@storybook/addon-docs/blocks";
import { Button } from "../components/buttons/button";

<Meta title="Guides/CSS Variables" />

# CSS Variables Guide

Learn how to discover and customize CSS custom properties in @fpkit/acss
components.

> **📖 Full Guide:** For comprehensive documentation, see
> [docs/guides/css-variables.md](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/css-variables.md)

---

## Quick Start

All fpkit components use CSS custom properties for theming:

```css
/* Global overrides */
:root {
  --btn-primary-bg: #0066cc;
  --btn-padding-inline: 2rem;
}

/* Component-specific */
.hero-button {
  --btn-padding-inline: 3rem;
  --btn-fs: 1.25rem;
}
```

```tsx
/* Inline styles */
<Button
  style={{
    "--btn-bg": "#e63946",
    "--btn-color": "white",
  }}
>
  Custom Button
</Button>
```

---

## Naming Convention

All CSS variables follow a consistent pattern:

```
--{component}-{element}-{variant}-{property}-{modifier}
```

### Examples

```scss
// Component base property
--btn-bg

// Variant-specific property
--btn-primary-bg

// State-specific property
--btn-hover-bg
--btn-focus-outline

// Element-specific property
--card-header-padding
--card-footer-bg
```

---

## Discovering Variables

### Method 1: Browser DevTools (Recommended)

1. Inspect a component
2. Open **Computed** tab
3. Scroll to **CSS Variables** section
4. See all available variables and values

### Method 2: IDE Autocomplete

```css
/* Type the component prefix */
--btn-   /* IDE shows: --btn-bg, --btn-padding-inline, --btn-radius, etc. */
--alert- /* IDE shows: --alert-error-bg, --alert-success-bg, etc. */
```

### Method 3: Source Code

Browse compiled CSS in `node_modules/@fpkit/acss/libs/index.css`

---

## Common Customization Patterns

### Global Theme

```css
/* global.css */
:root {
  /* Buttons */
  --btn-radius: 0.25rem;
  --btn-padding-inline: 2rem;
  --btn-primary-bg: #0066cc;
  --btn-primary-color: white;

  /* Cards */
  --card-padding: 1.5rem;
  --card-radius: 0.75rem;
  --card-border: 1px solid #e0e0e0;
}
```

### Theme Classes

```css
/* themes.css */
.light-theme {
  --btn-bg: white;
  --btn-color: #333;
  --card-bg: #f9f9f9;
}

.dark-theme {
  --btn-bg: #2d2d2d;
  --btn-color: #f0f0f0;
  --card-bg: #1a1a1a;
  --card-border: 1px solid #444;
}
```

```tsx
<div className="dark-theme">
  <Button>Styled by theme</Button>
</div>
```

### Component-Specific

```css
/* custom.css */
.hero-button {
  --btn-padding-inline: 3rem;
  --btn-padding-block: 1rem;
  --btn-fs: 1.25rem;
}
```

```tsx
<Button className="hero-button">Large CTA</Button>
```

### Inline Overrides

```tsx
<Button
  style={{
    "--btn-bg": "#e63946",
    "--btn-color": "white",
    "--btn-padding-inline": "2.5rem",
  }}
>
  Danger Action
</Button>
```

---

## Button Variables Reference

```scss
// Base properties
--btn-display: inline-flex --btn-padding-inline: 1.5rem --btn-padding-block:
  0.5rem --btn-fs: 1rem --btn-fw: 600 --btn-radius: 0.375rem --btn-gap: 0.5rem
  // Variants
  --btn-primary-bg: #0066cc --btn-primary-color: white --btn-secondary-bg: transparent
  --btn-secondary-color: currentColor // States
  --btn-hover-bg: brightness(1.1) --btn-focus-outline: 2px solid currentColor --btn-focus-outline-offset:
  2px --btn-disabled-opacity: 0.6;
```

---

## Alert Variables Reference

```scss
// Base properties
--alert-padding: 1rem --alert-radius: 0.375rem --alert-border-width: 1px
  // Semantic variants
  --alert-error-bg: #f8d7da --alert-error-border: #f5c6cb --alert-error-color: #721c24
  --alert-success-bg: #d4edda --alert-success-border: #c3e6cb --alert-success-color:
  #155724 --alert-warning-bg: #fff3cd --alert-warning-border: #ffeaa7 --alert-warning-color:
  #856404 --alert-info-bg: #d1ecf1 --alert-info-border: #bee5eb --alert-info-color:
  #0c5460;
```

---

## Card Variables Reference

```scss
// Base properties
--card-padding: 1rem --card-bg: white --card-radius: 0.5rem --card-border: 1px
  solid #e0e0e0 // Header
  --card-header-padding: 1rem 1.5rem --card-header-bg: #f9f9f9 --card-header-border-bottom:
  1px solid #e0e0e0 --card-header-fs: 1.25rem --card-header-fw: 600 // Footer
  --card-footer-padding: 1rem 1.5rem --card-footer-bg: #f9f9f9
  --card-footer-border-top: 1px solid #e0e0e0;
```

---

## Abbreviation Reference

### ✅ Abbreviated Properties

| Abbreviation | Full Name                     | Example        |
| ------------ | ----------------------------- | -------------- |
| `bg`         | background / background-color | `--btn-bg`     |
| `fs`         | font-size                     | `--btn-fs`     |
| `fw`         | font-weight                   | `--btn-fw`     |
| `radius`     | border-radius                 | `--btn-radius` |
| `gap`        | gap                           | `--btn-gap`    |

### ✅ Full Word Properties

| Property | Variable Pattern                    |
| -------- | ----------------------------------- |
| padding  | `--{component}-padding-{direction}` |
| margin   | `--{component}-margin-{direction}`  |
| color    | `--{component}-color`               |
| border   | `--{component}-border`              |
| display  | `--{component}-display`             |
| width    | `--{component}-width`               |
| height   | `--{component}-height`              |

---

## rem Units

**All spacing and sizing uses rem units** for accessibility.

**Conversion:** `px / 16 = rem`

**Common values:**

- 8px = 0.5rem
- 12px = 0.75rem
- 16px = 1rem (base)
- 20px = 1.25rem
- 24px = 1.5rem
- 32px = 2rem

**Why rem?**

- Respects user font size preferences
- Consistent scaling across breakpoints
- Better for responsive design

---

## Framework Integration

### React

```jsx
import "./theme.css"; // Global overrides

function CustomButton() {
  return (
    <Button
      style={{
        "--btn-padding-inline": "2rem",
        "--btn-radius": "0.5rem",
      }}
    >
      Custom
    </Button>
  );
}
```

### CSS Modules

```css
/* Button.module.css */
.customButton {
  --btn-primary-bg: #e63946;
  --btn-primary-color: white;
  --btn-padding-inline: 2rem;
}
```

```jsx
import styles from "./Button.module.css";

<Button className={styles.customButton}>Custom</Button>;
```

### Styled Components

```jsx
import styled from "styled-components";
import { Button } from "@fpkit/acss";

const CustomButton = styled(Button)`
  --btn-padding-inline: 2rem;
  --btn-radius: 0.5rem;
  --btn-primary-bg: #e63946;
`;
```

---

## Best Practices

### ✅ Do

- Use the naming pattern when creating custom variables
- Use rem units for spacing and sizing
- Use logical properties (`padding-inline`, `padding-block`)
- Test across themes to ensure customizations work
- Use semantic naming for custom variants

### ❌ Don't

- Don't use px units (use rem)
- Don't use forbidden abbreviations (px/py, w/h, cl, dsp, bdr)
- Don't use `!important` unless absolutely necessary
- Don't create one-off variables - follow the component pattern

---

## Troubleshooting

### Variables Not Applying

1. **Check specificity** - Ensure your selector has equal or higher specificity
2. **Check cascade order** - Import fpkit CSS before your overrides
3. **Check typos** - Variable names are case-sensitive

```css
/* ❌ Won't work - imported after */
@import "@fpkit/acss/libs/index.css";

:root {
  --btn-bg: red; /* Applied first, then overwritten */
}

/* ✅ Works - correct order */
:root {
  --btn-bg: red; /* Overrides fpkit defaults */
}

@import "@fpkit/acss/libs/index.css";
```

---

## Additional Resources

- **📖
  [Full CSS Variables Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/css-variables.md)** -
  Comprehensive documentation
- **📘
  [Composition Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/composition.md)** -
  Building custom components
- **♿
  [Accessibility Guide](https://github.com/shawn-sandy/acss/blob/main/packages/fpkit/docs/guides/accessibility.md)** -
  WCAG compliance

---

**Explore component stories** in this Storybook to see CSS variable
customization examples in action!