@fpkit/acss 1.0.0-beta.1 → 1.0.0

package/src/docs/css-variables.mdx

@@ -0,0 +1,380 @@
+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!