@fpkit/acss 5.0.0 → 6.1.0

package/src/components/form/checkbox.tsx

@@ -31,7 +31,7 @@ import { Input, type InputProps } from "./inputs";
  */
 export interface CheckboxProps extends Omit<
   InputProps,
-  'type' | 'value' | 'onChange' | 'defaultValue' | 'placeholder'
+  'type' | 'value' | 'onChange' | 'defaultValue' | 'placeholder' | 'size'
 > {
   /**
    * Unique identifier for the checkbox input.
@@ -51,6 +51,30 @@ export interface CheckboxProps extends Omit<
    */
   label: React.ReactNode;
 
+  /**
+   * Predefined size variant for the checkbox.
+   * Maps to standardized size tokens for consistent sizing across the design system.
+   *
+   * Available sizes:
+   * - `xs`: Extra small (0.875rem / 14px) - Compact forms, tight spaces
+   * - `sm`: Small (1rem / 16px) - Dense layouts
+   * - `md`: Medium (1.25rem / 20px) - Default, optimal for most use cases
+   * - `lg`: Large (1.5rem / 24px) - Touch-friendly, prominent CTAs
+   *
+   * For custom sizes beyond these presets, use the `styles` prop:
+   * ```tsx
+   * styles={{ '--checkbox-size': '2rem' }}
+   * ```
+   *
+   * @default 'md'
+   * @example
+   * ```tsx
+   * <Checkbox id="small" label="Small checkbox" size="sm" />
+   * <Checkbox id="large" label="Large checkbox" size="lg" />
+   * ```
+   */
+  size?: 'xs' | 'sm' | 'md' | 'lg';
+
   /**
    * Controlled mode: Current checked state.
    * When provided, component becomes controlled and requires onChange handler.
@@ -113,33 +137,46 @@ export interface CheckboxProps extends Omit<
   inputClasses?: string;
 
   /**
-   * CSS custom properties for theming.
+   * CSS custom properties for theming and custom sizing.
    *
-   * Available variables:
-   * - --checkbox-gap: Space between checkbox and label (default: 0.5rem)
-   * - --checkbox-disabled-opacity: Opacity for disabled state (default: 0.6)
-   * - --checkbox-disabled-color: Label color when disabled (default: #6b7280)
-   * - --checkbox-label-fs: Label font size (default: 1rem)
-   * - --checkbox-label-lh: Label line height (default: 1.5)
-   * - --color-required: Required indicator color (default: #dc2626)
-   * - --checkbox-focus-ring-color: Focus ring color (default: #2563eb)
-   * - --checkbox-focus-ring-width: Focus ring width (default: 0.125rem)
-   * - --checkbox-focus-ring-offset: Focus ring offset (default: 0.125rem)
-   * - --checkbox-hover-label-color: Label color on hover
-   * - --checkbox-error-label-color: Label color when invalid (default: #dc2626)
-   * - --checkbox-valid-label-color: Label color when valid (default: #16a34a)
+   * Common variables:
+   * - `--checkbox-size`: Custom checkbox dimensions (for sizes beyond xs/sm/md/lg presets)
+   * - `--checkbox-gap`: Space between checkbox and label (default: 0.5rem)
+   * - `--checkbox-border-color`: Border color (default: var(--color-neutral-600))
+   * - `--checkbox-checked-bg`: Background color when checked (default: var(--color-success))
+   * - `--checkbox-radius`: Border radius (default: 0.25rem)
+   * - `--checkbox-focus-ring-color`: Focus ring color (default: var(--color-focus-ring))
+   * - `--checkbox-disabled-opacity`: Opacity for disabled state (default: 0.6)
+   * - `--checkbox-label-fs`: Label font size (default: 1rem)
+   *
+   * For custom sizes beyond the preset variants (xs/sm/md/lg), use `--checkbox-size`:
    *
    * @example
    * ```tsx
+   * // Custom size beyond presets
    * <Checkbox
    *   id="custom"
-   *   label="Custom styled"
+   *   label="Custom sized (2rem)"
+   *   styles={{
+   *     '--checkbox-size': '2rem',
+   *     '--checkbox-gap': '1rem'
+   *   }}
+   * />
+   *
+   * // Brand theming
+   * <Checkbox
+   *   id="branded"
+   *   label="Brand checkbox"
+   *   size="lg"
    *   styles={{
-   *     '--checkbox-gap': '1rem',
-   *     '--checkbox-focus-ring-color': '#ff0000'
+   *     '--checkbox-checked-bg': '#0066cc',
+   *     '--checkbox-focus-ring-color': '#0066cc'
    *   }}
    * />
    * ```
+   *
+   * @see {@link ./CHECKBOX-STYLES.mdx|CHECKBOX-STYLES.mdx} - Complete CSS variable reference
+   * @see {@link ./CHECKBOX.mdx|CHECKBOX.mdx} - Component documentation with examples
    */
   styles?: React.CSSProperties;
 }
@@ -152,6 +189,7 @@ export interface CheckboxProps extends Omit<
  * validation, disabled state, and ARIA logic from the base Input component.
  *
  * **Key Features:**
+ * - ✅ Semantic size variants (xs, sm, md, lg) via `size` prop
  * - ✅ Boolean onChange API (`onChange={(checked) => ...}`)
  * - ✅ Automatic label association via htmlFor
  * - ✅ WCAG 2.1 AA compliant (uses aria-disabled pattern)
@@ -199,11 +237,21 @@ export interface CheckboxProps extends Omit<
  *
  * @example
  * ```tsx
+ * // Size variants
+ * <Checkbox id="small" label="Small" size="sm" />
+ * <Checkbox id="large" label="Large" size="lg" />
+ * ```
+ *
+ * @example
+ * ```tsx
  * // Custom styling
  * <Checkbox
  *   id="custom"
- *   label="Large checkbox"
- *   styles={{ '--checkbox-gap': '1rem' }}
+ *   label="Custom sized"
+ *   styles={{
+ *     '--checkbox-size': '2rem',
+ *     '--checkbox-gap': '1rem'
+ *   }}
  * />
  * ```
  *
@@ -211,6 +259,8 @@ export interface CheckboxProps extends Omit<
  * @param {React.Ref<HTMLInputElement>} ref - Forwarded ref to the input element
  * @returns {JSX.Element} Checkbox wrapper with input and label
  *
+ * @see {@link ./CHECKBOX.mdx|CHECKBOX.mdx} - Complete component documentation
+ * @see {@link ./CHECKBOX-STYLES.mdx|CHECKBOX-STYLES.mdx} - CSS customization guide
  * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html|WCAG 4.1.2 Name, Role, Value}
  * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html|WCAG 2.4.7 Focus Visible}
  * @see {@link https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html|WCAG 3.3.1 Error Identification}
@@ -218,7 +268,7 @@ export interface CheckboxProps extends Omit<
 export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
   ({
     id, label, checked, defaultChecked, value = "on",
-    onChange, classes, inputClasses, styles,
+    onChange, classes, inputClasses, styles, size,
     name, disabled, required, validationState,
     errorMessage, hintText, onBlur, onFocus, autoFocus,
     ...props
@@ -264,7 +314,7 @@ export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
     // Note: No need to manage disabled class - CSS uses :has() selector with aria-disabled
     // The Input component handles aria-disabled automatically via useDisabledState hook
     return (
-      <div className={classes} style={styles}>
+      <div className={classes} style={styles} data-checkbox-size={size}>
         <Input
           ref={ref}
           type="checkbox"

package/src/components/form/form.scss

@@ -1,5 +1,7 @@
 // Import checkbox wrapper component styles
 @use "./checkbox";
+// Import select component styles
+@use "./select";
 
 :root {
   --input-border-color: var(--color-border);
@@ -9,9 +11,9 @@
   --input-outline: thin solid var(--input-border-color);
   --input-padding-inline: 0.6rem;
   --input-padding-block: 0.4rem;
-  --input-radius: --var(--radius);
+  --input-radius: var(--radius);
   --input-fs: var(--fs);
-  --input-width: clamp(200px, 100%, 500px);
+  --input-width: clamp(12.5rem, 100%, 31.25rem);
 
   // Focus state variables (NEW - for accessibility)
   --input-focus-outline: medium solid var(--input-border-color);
@@ -28,16 +30,22 @@
   --placeholder-fs: smaller;
 
   --form-direction: column;
-  --select-arrow: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='20' height='20'><polyline points='6,9 10,13 14,9' stroke='%23000000' stroke-width='1.5' fill='none' /></svg>");
 
   /* ==========================================================================
      Size Tokens
      ========================================================================== */
 
+  --checkbox-size-xs: 0.875rem; /* 14px - extra small */
   --checkbox-size-sm: 1rem; /* 16px */
   --checkbox-size-md: 1.25rem; /* 20px */
   --checkbox-size-lg: 1.5rem; /* 24px */
 
+  /* Gap tokens for each size variant */
+  --checkbox-gap-xs: 0.375rem; /* 6px */
+  --checkbox-gap-sm: 0.5rem; /* 8px */
+  --checkbox-gap-md: 0.5rem; /* 8px - default */
+  --checkbox-gap-lg: 0.625rem; /* 10px */
+
   /* ==========================================================================
      Base Properties
      ========================================================================== */
@@ -138,14 +146,3 @@ input[type="checkbox"] {
       no-repeat center center;
   }
 }
-
-select {
-  border: var(--input-outline);
-  outline: none;
-  -webkit-appearance: none; /* Remove default arrow in Chrome and Safari */
-  -moz-appearance: none; /* Remove default arrow in Firefox */
-  appearance: none; /* Remove default arrow in other browsers */
-  background: var(--select-arrow) no-repeat;
-  background-position: right 0.5rem top 50%;
-  padding-inline-end: 0;
-}

package/src/components/form/form.stories.tsx

@@ -10,7 +10,7 @@ import "./form.scss";
 const FormComponent = Form as unknown as typeof Form;
 
 const meta: Meta<typeof FormComponent> = {
-  title: "FP.REACT Forms/Form",
+  title: "FP.React Forms/Form",
   tags: ["stable", "autodocs"],
   component: FormComponent,
   parameters: {

package/src/components/form/input.stories.tsx

@@ -7,7 +7,7 @@ import { Checkbox as CheckboxComponent } from "./checkbox";
 import "./form.scss";
 
 const meta: Meta<typeof Input> = {
-  title: "FP.REACT  Forms/Inputs",
+  title: "FP.React Forms/Inputs",
   component: Input,
   tags: ["stable"],
   args: {},
@@ -405,47 +405,96 @@ export const CheckboxWithHint: Story = {
 };
 
 /**
- * CheckboxCustomSize - Custom sized checkboxes using CSS variables
+ * CheckboxCustomSize - Predefined size variants using size prop
  *
- * Demonstrates responsive sizing by overriding --checkbox-size and --checkbox-gap variables.
- * Useful for contexts requiring larger touch targets or compact layouts.
+ * Demonstrates semantic size prop for common size variants.
+ * For custom sizes beyond presets, see CheckboxCustomSizeCSSOverride story.
  */
 export const CheckboxCustomSize: Story = {
   render: () => (
     <div style={{ display: "flex", gap: "1.5rem", flexDirection: "column" }}>
       <CheckboxComponent
-        id="small"
-        label="Small (1rem)"
-        styles={{
-          "--checkbox-size": "1rem",
-          "--checkbox-gap": "0.5rem",
-        } as React.CSSProperties}
+        id="xs"
+        label="Extra Small (0.875rem / 14px)"
+        size="xs"
       />
       <CheckboxComponent
-        id="medium"
-        label="Medium (1.25rem - default)"
-        styles={{
-          "--checkbox-gap": "0.5rem",
-        } as React.CSSProperties}
+        id="sm"
+        label="Small (1rem / 16px)"
+        size="sm"
       />
       <CheckboxComponent
-        id="large"
-        label="Large (1.5rem)"
+        id="md"
+        label="Medium (1.25rem / 20px) - Default"
+        size="md"
+      />
+      <CheckboxComponent
+        id="lg"
+        label="Large (1.5rem / 24px)"
+        size="lg"
+      />
+    </div>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step("XS checkbox has correct data attribute", async () => {
+      const checkbox = canvas.getByRole("checkbox", { name: /Extra Small/ });
+      const wrapper = checkbox.closest('div');
+      expect(wrapper).toHaveAttribute("data-checkbox-size", "xs");
+    });
+
+    await step("LG checkbox has correct data attribute", async () => {
+      const checkbox = canvas.getByRole("checkbox", { name: /Large/ });
+      const wrapper = checkbox.closest('div');
+      expect(wrapper).toHaveAttribute("data-checkbox-size", "lg");
+    });
+
+    await step("All checkboxes are functional", async () => {
+      const xsCheckbox = canvas.getByRole("checkbox", { name: /Extra Small/ });
+      await userEvent.click(xsCheckbox);
+      expect(xsCheckbox).toBeChecked();
+    });
+  },
+};
+
+/**
+ * CheckboxCustomSizeCSSOverride - Custom sizes via CSS variables
+ *
+ * Demonstrates that CSS variable overrides still work for custom sizes
+ * beyond the predefined xs/sm/md/lg variants.
+ */
+export const CheckboxCustomSizeCSSOverride: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: "1.5rem", flexDirection: "column" }}>
+      <CheckboxComponent
+        id="custom-tiny"
+        label="Custom Tiny (0.75rem)"
         styles={{
-          "--checkbox-size": "1.5rem",
-          "--checkbox-gap": "0.625rem",
+          "--checkbox-size": "0.75rem",
+          "--checkbox-gap": "0.375rem",
         } as React.CSSProperties}
       />
       <CheckboxComponent
-        id="xlarge"
-        label="Extra Large (2rem)"
+        id="custom-huge"
+        label="Custom Huge (2.5rem)"
         styles={{
-          "--checkbox-size": "2rem",
-          "--checkbox-gap": "0.75rem",
+          "--checkbox-size": "2.5rem",
+          "--checkbox-gap": "1rem",
         } as React.CSSProperties}
       />
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+For sizes outside the predefined variants, use the \`styles\` prop to override CSS variables directly.
+This provides maximum flexibility while keeping the API clean for common cases.
+        `,
+      },
+    },
+  },
 };
 
 /**

package/src/components/form/select.scss

@@ -0,0 +1,97 @@
+// Select Component Styles
+
+:root {
+  // Select arrow color (themeable)
+  --select-arrow-color: var(--color-text);
+
+  // Select width (responsive)
+  --select-width-mobile: 18.75rem; /* 300px minimum on mobile */
+  --select-width-desktop: 100%; /* Full width on larger screens */
+}
+
+select {
+  // Match input component styling
+  border: var(--input-outline);
+  border-radius: var(--input-radius);
+  outline: none;
+  background-color: var(--input-bg, var(--color-surface));
+
+  // Remove default browser select styling
+  -webkit-appearance: none; /* Remove default arrow in Chrome and Safari */
+  -moz-appearance: none; /* Remove default arrow in Firefox */
+  appearance: none; /* Remove default arrow in other browsers */
+
+  // Create themeable arrow using CSS gradients
+  background-image: linear-gradient(45deg, transparent 50%, var(--select-arrow-color, currentColor) 50%),
+                    linear-gradient(135deg, var(--select-arrow-color, currentColor) 50%, transparent 50%);
+  background-position: calc(100% - 1.25rem) center,
+                       calc(100% - 1rem) center;
+  background-size: 0.3125rem 0.3125rem,
+                   0.3125rem 0.3125rem;
+  background-repeat: no-repeat;
+
+  // Match input component height using shared padding variables
+  padding-inline-start: var(--input-padding-inline);
+  padding-inline-end: 2.5rem; // Extra space for arrow
+  padding-block: var(--input-padding-block);
+
+  // Responsive width: uses larger of 300px or 100% of container
+  width: max(var(--select-width-mobile), var(--select-width-desktop));
+}
+
+/* ==========================================================================
+   Option Styling with Data Attributes
+   ========================================================================== */
+
+// Example: Variant-based option styling
+// Uncomment and customize for your design system
+/*
+option[data-option="primary"] {
+  background-color: var(--color-primary-light, #dbeafe);
+  color: var(--color-primary, #2563eb);
+  font-weight: 600;
+}
+
+option[data-option="success"] {
+  background-color: var(--color-success-bg, #dcfce7);
+  color: var(--color-success, #16a34a);
+}
+
+option[data-option="error"] {
+  background-color: var(--color-error-bg, #fee2e2);
+  color: var(--color-error, #dc2626);
+}
+
+option[data-option="warning"] {
+  background-color: var(--color-warning-bg, #fef3c7);
+  color: var(--color-warning, #d97706);
+}
+*/
+
+// Example: Size-based option styling
+/*
+option[data-size="sm"] {
+  font-size: 0.875rem; // 14px
+  padding: 0.25rem 0.5rem;
+}
+
+option[data-size="lg"] {
+  font-size: 1.125rem; // 18px
+  padding: 0.75rem 1rem;
+  font-weight: 500;
+}
+*/
+
+// Example: Custom data attribute styling
+/*
+option[data-featured="true"] {
+  font-weight: 700;
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+}
+
+option[data-category="premium"] {
+  background-color: #fef3c7;
+  font-style: italic;
+}
+*/