@fpkit/acss 3.6.0 → 3.8.0

package/src/components/checkbox/STYLES.mdx

@@ -0,0 +1,434 @@
+import { Meta } from "@storybook/addon-docs/blocks";
+
+<Meta title="FP.React Forms/Inputs/Checkbox/Styles" />
+
+# Checkbox CSS Variables
+
+Complete reference for customizing the Checkbox component using CSS custom
+properties.
+
+## Overview
+
+The Checkbox component uses CSS custom properties for flexible theming and
+customization. All properties follow the standardized naming convention:
+`--checkbox-{element}-{variant}-{property}`.
+
+## Quick Start
+
+```css
+/* Global customization */
+:root {
+  --checkbox-size: 1.5rem;
+  --checkbox-checked-bg: #7c3aed;
+  --checkbox-radius: 0.5rem;
+}
+
+/* Scoped customization */
+.my-form {
+  --checkbox-checked-bg: #10b981;
+  --checkbox-focus-outline-color: #86efac;
+}
+```
+
+```tsx
+/* Inline customization */
+<Checkbox
+  id="custom"
+  label="Custom styled"
+  styles={{
+    "--checkbox-size": "2rem",
+    "--checkbox-checked-bg": "#7c3aed",
+  }}
+/>
+```
+
+## Size Tokens
+
+Control checkbox dimensions with size tokens:
+
+```css
+--checkbox-size-sm: 1rem; /* 16px - Small */
+--checkbox-size-md: 1.25rem; /* 20px - Medium (default) */
+--checkbox-size-lg: 1.5rem; /* 24px - Large */
+```
+
+**Usage:**
+
+```css
+[data-checkbox~="sm"] {
+  --checkbox-size: var(--checkbox-size-sm);
+}
+[data-checkbox~="md"] {
+  --checkbox-size: var(--checkbox-size-md);
+}
+[data-checkbox~="lg"] {
+  --checkbox-size: var(--checkbox-size-lg);
+}
+```
+
+## Base Properties
+
+Core checkbox styling properties:
+
+| Variable                  | Default                      | Description                  |
+| ------------------------- | ---------------------------- | ---------------------------- |
+| `--checkbox-size`         | `var(--checkbox-size-md)`    | Width and height of checkbox |
+| `--checkbox-bg`           | `#ffffff`                    | Background color (unchecked) |
+| `--checkbox-border`       | `0.125rem solid #6b7280`     | Border style                 |
+| `--checkbox-border-color` | `#6b7280`                    | Border color                 |
+| `--checkbox-radius`       | `0.25rem`                    | Border radius (4px)          |
+| `--checkbox-cursor`       | `pointer`                    | Cursor style                 |
+| `--checkbox-transition`   | `all 0.2s cubic-bezier(...)` | Transition animation         |
+
+## Checkmark Properties
+
+Styling for the checkmark indicator:
+
+| Variable                         | Default      | Description            |
+| -------------------------------- | ------------ | ---------------------- |
+| `--checkbox-checkmark-color`     | `#ffffff`    | Checkmark color        |
+| `--checkbox-checkmark-opacity`   | `0`          | Opacity when unchecked |
+| `--checkbox-checkmark-transform` | `scale(0.7)` | Scale when unchecked   |
+
+## Label Properties
+
+Label text styling:
+
+| Variable                  | Default   | Description                          |
+| ------------------------- | --------- | ------------------------------------ |
+| `--checkbox-label-gap`    | `0.5rem`  | Gap between checkbox and label (8px) |
+| `--checkbox-label-fs`     | `1rem`    | Label font size (16px)               |
+| `--checkbox-label-color`  | `inherit` | Label text color                     |
+| `--checkbox-label-cursor` | `pointer` | Label cursor style                   |
+| `--checkbox-label-fw`     | `400`     | Label font weight                    |
+
+## Description Properties
+
+Helper text styling:
+
+| Variable                                      | Default     | Description           |
+| --------------------------------------------- | ----------- | --------------------- |
+| `--checkbox-description-fs`                   | `0.875rem`  | Font size (14px)      |
+| `--checkbox-description-color`                | `#6b7280`   | Text color (Gray 500) |
+| `--checkbox-description-margin-block-start`   | `0.25rem`   | Top margin (4px)      |
+| `--checkbox-description-padding-inline-start` | `calc(...)` | Left padding          |
+
+## Error Message Properties
+
+Error text styling:
+
+| Variable                                | Default     | Description          |
+| --------------------------------------- | ----------- | -------------------- |
+| `--checkbox-error-fs`                   | `0.875rem`  | Font size (14px)     |
+| `--checkbox-error-color`                | `#dc2626`   | Text color (Red 600) |
+| `--checkbox-error-margin-block-start`   | `0.25rem`   | Top margin (4px)     |
+| `--checkbox-error-padding-inline-start` | `calc(...)` | Left padding         |
+
+## Required Indicator
+
+Required asterisk styling:
+
+| Variable                    | Default   | Description     |
+| --------------------------- | --------- | --------------- |
+| `--checkbox-required-color` | `#dc2626` | Color (Red 600) |
+| `--checkbox-required-fw`    | `600`     | Font weight     |
+
+## Color Variants
+
+All color variants meet WCAG 2.1 AA contrast requirements (4.5:1 minimum).
+
+### Primary (Blue)
+
+```css
+--checkbox-primary-checked-bg: #2563eb; /* 4.68:1 contrast */
+--checkbox-primary-checked-border: #2563eb;
+--checkbox-primary-hover-border: #3b82f6;
+--checkbox-primary-focus-outline-color: #93c5fd;
+```
+
+### Secondary (Gray)
+
+```css
+--checkbox-secondary-checked-bg: #4b5563; /* 7.56:1 contrast */
+--checkbox-secondary-checked-border: #4b5563;
+--checkbox-secondary-hover-border: #6b7280;
+--checkbox-secondary-focus-outline-color: #9ca3af;
+```
+
+### Error (Red)
+
+```css
+--checkbox-error-checked-bg: #dc2626; /* 5.14:1 contrast */
+--checkbox-error-checked-border: #dc2626;
+--checkbox-error-hover-border: #ef4444;
+--checkbox-error-focus-outline-color: #fca5a5;
+```
+
+### Success (Green)
+
+```css
+--checkbox-success-checked-bg: #16a34a; /* 4.54:1 contrast */
+--checkbox-success-checked-border: #16a34a;
+--checkbox-success-hover-border: #22c55e;
+--checkbox-success-focus-outline-color: #86efac;
+```
+
+## State Properties
+
+### Hover State
+
+```css
+--checkbox-hover-border-color: #9ca3af;
+--checkbox-hover-bg: #f9fafb;
+```
+
+### Focus State
+
+```css
+--checkbox-focus-outline: 0.125rem solid;
+--checkbox-focus-outline-offset: 0.125rem;
+--checkbox-focus-outline-color: var(--checkbox-primary-focus-outline-color);
+```
+
+### Checked State
+
+```css
+--checkbox-checked-bg: var(--checkbox-primary-checked-bg);
+--checkbox-checked-border: var(--checkbox-primary-checked-border);
+--checkbox-checked-checkmark-opacity: 1;
+--checkbox-checked-checkmark-transform: scale(1);
+```
+
+### Indeterminate State
+
+```css
+--checkbox-indeterminate-bg: var(--checkbox-primary-checked-bg);
+--checkbox-indeterminate-border: var(--checkbox-primary-checked-border);
+--checkbox-indeterminate-dash-width: 0.625rem;
+--checkbox-indeterminate-dash-height: 0.125rem;
+--checkbox-indeterminate-dash-opacity: 1;
+```
+
+### Disabled State
+
+```css
+--checkbox-disabled-bg: #f3f4f6;
+--checkbox-disabled-border-color: #d1d5db;
+--checkbox-disabled-opacity: 0.6;
+--checkbox-disabled-cursor: not-allowed;
+```
+
+### Invalid State
+
+```css
+--checkbox-invalid-border-color: #dc2626;
+--checkbox-invalid-focus-outline-color: #fca5a5;
+```
+
+## Customization Examples
+
+### Example 1: Custom Brand Colors
+
+```css
+:root {
+  /* Purple brand theme */
+  --checkbox-checked-bg: #7c3aed;
+  --checkbox-checked-border: #7c3aed;
+  --checkbox-focus-outline-color: #c4b5fd;
+  --checkbox-hover-border-color: #a78bfa;
+}
+```
+
+### Example 2: Larger Touch Targets
+
+```css
+.mobile-form {
+  /* Increase size for mobile devices */
+  --checkbox-size: 1.75rem; /* 28px */
+  --checkbox-label-fs: 1.125rem; /* 18px */
+  --checkbox-label-gap: 0.75rem; /* 12px */
+}
+```
+
+### Example 3: Rounded/Pill Style
+
+```css
+.rounded-checkboxes {
+  --checkbox-radius: 100rem; /* Fully rounded */
+}
+```
+
+### Example 4: Shadow Instead of Border
+
+```css
+.shadow-checkboxes {
+  --checkbox-border: none;
+  --checkbox-bg: #f3f4f6;
+  --checkbox-checked-bg: #10b981;
+  /* Add shadow via inline styles or custom class */
+}
+```
+
+### Example 5: High Contrast Theme
+
+```css
+.high-contrast {
+  --checkbox-border: 0.1875rem solid #000000; /* 3px black border */
+  --checkbox-checked-bg: #000000;
+  --checkbox-focus-outline: 0.1875rem solid #000000;
+  --checkbox-focus-outline-offset: 0.25rem;
+}
+```
+
+### Example 6: Dark Mode
+
+```css
+.dark-theme {
+  --checkbox-bg: #1f2937; /* Gray 800 */
+  --checkbox-border-color: #4b5563; /* Gray 600 */
+  --checkbox-checked-bg: #3b82f6; /* Blue 500 */
+  --checkbox-checked-border: #3b82f6;
+  --checkbox-label-color: #f3f4f6; /* Gray 100 */
+  --checkbox-description-color: #9ca3af; /* Gray 400 */
+  --checkbox-hover-bg: #374151; /* Gray 700 */
+}
+```
+
+### Example 7: Minimal Style
+
+```css
+.minimal-checkboxes {
+  --checkbox-border: 0.0625rem solid #d1d5db; /* 1px thin border */
+  --checkbox-radius: 0.125rem; /* 2px small radius */
+  --checkbox-checked-bg: #000000;
+  --checkbox-transition: none; /* No animation */
+}
+```
+
+## Complete Variable List
+
+Here's every CSS variable available for customization:
+
+```css
+/* Size Tokens */
+--checkbox-size-sm
+--checkbox-size-md
+--checkbox-size-lg
+
+/* Base Properties */
+--checkbox-size
+--checkbox-bg
+--checkbox-border
+--checkbox-border-color
+--checkbox-radius
+--checkbox-cursor
+--checkbox-transition
+
+/* Checkmark */
+--checkbox-checkmark-color
+--checkbox-checkmark-opacity
+--checkbox-checkmark-transform
+
+/* Label */
+--checkbox-label-gap
+--checkbox-label-fs
+--checkbox-label-color
+--checkbox-label-cursor
+--checkbox-label-fw
+
+/* Description */
+--checkbox-description-fs
+--checkbox-description-color
+--checkbox-description-margin-block-start
+--checkbox-description-padding-inline-start
+
+/* Error */
+--checkbox-error-fs
+--checkbox-error-color
+--checkbox-error-margin-block-start
+--checkbox-error-padding-inline-start
+
+/* Required */
+--checkbox-required-color
+--checkbox-required-fw
+
+/* Primary Variant */
+--checkbox-primary-checked-bg
+--checkbox-primary-checked-border
+--checkbox-primary-hover-border
+--checkbox-primary-focus-outline-color
+
+/* Secondary Variant */
+--checkbox-secondary-checked-bg
+--checkbox-secondary-checked-border
+--checkbox-secondary-hover-border
+--checkbox-secondary-focus-outline-color
+
+/* Error Variant */
+--checkbox-error-checked-bg
+--checkbox-error-checked-border
+--checkbox-error-hover-border
+--checkbox-error-focus-outline-color
+
+/* Success Variant */
+--checkbox-success-checked-bg
+--checkbox-success-checked-border
+--checkbox-success-hover-border
+--checkbox-success-focus-outline-color
+
+/* Hover State */
+--checkbox-hover-border-color
+--checkbox-hover-bg
+
+/* Focus State */
+--checkbox-focus-outline
+--checkbox-focus-outline-offset
+--checkbox-focus-outline-color
+
+/* Checked State */
+--checkbox-checked-bg
+--checkbox-checked-border
+--checkbox-checked-checkmark-opacity
+--checkbox-checked-checkmark-transform
+
+/* Indeterminate State */
+--checkbox-indeterminate-bg
+--checkbox-indeterminate-border
+--checkbox-indeterminate-dash-width
+--checkbox-indeterminate-dash-height
+--checkbox-indeterminate-dash-opacity
+
+/* Disabled State */
+--checkbox-disabled-bg
+--checkbox-disabled-border-color
+--checkbox-disabled-opacity
+--checkbox-disabled-cursor
+
+/* Invalid State */
+--checkbox-invalid-border-color
+--checkbox-invalid-focus-outline-color
+```
+
+## Best Practices
+
+### ✅ Do
+
+- Use CSS custom properties for theming
+- Follow the naming convention when creating new variables
+- Test custom colors for WCAG contrast requirements
+- Use rem units for all size-related properties
+- Scope variables appropriately (:root, class, inline)
+
+### ❌ Don't
+
+- Use pixel units (use rem instead)
+- Override library source files directly
+- Create one-off variables that don't follow the naming pattern
+- Remove required variables (checkbox will break)
+- Use `!important` unless absolutely necessary
+
+## Resources
+
+- [CSS Variables Guide](../../docs/css-variables.md)
+- [WCAG Color Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [Checkbox Component README](./README.mdx)