@fpkit/acss 0.6.2 → 1.0.0

package/src/components/badge/badge.stories.tsx

@@ -8,6 +8,46 @@ const meta: Meta<typeof Badge> = {
   title: "FP.REACT Components/Badge",
   component: Badge,
   tags: ["beta", "accessible"],
+  parameters: {
+    docs: {
+      description: {
+        component: `A notification badge component for displaying counts or status indicators with accessibility support.
+
+## CSS Variables
+
+Customize the Badge appearance using CSS custom properties:
+
+### Layout & Structure
+- \`--badge-bg\`: Background color (default: \`lightgray\`)
+- \`--badge-color\`: Text color (default: \`currentColor\`)
+- \`--badge-radius\`: Border radius (default: \`0.5rem\`)
+- \`--badge-padding\`: Internal padding (default: \`0.3rem\`)
+- \`--badge-vertical-align\`: Vertical alignment (default: \`0.5rem\`)
+
+### Typography
+- \`--badge-fs\`: Font size (default: \`var(--fs-1)\`)
+
+### Rounded Variant
+When using \`variant="rounded"\`:
+- \`--badge-size\`: Fixed circular size (default: \`1.5625rem\`)
+- Border radius automatically becomes \`50%\`
+- Padding becomes \`0\`
+- Content truncated with ellipsis if too long
+
+**Example:**
+\`\`\`css
+sup:has(> span) {
+  --badge-bg: #ef4444;
+  --badge-color: white;
+  --badge-radius: 0.25rem;
+  --badge-padding: 0.5rem;
+  --badge-vertical-align: 0.75rem;
+  --badge-fs: 0.875rem;
+}
+\`\`\``,
+      },
+    },
+  },
   args: {
     children: "5",
   },

package/src/components/breadcrumbs/breadcrumb.scss

@@ -1,7 +1,7 @@
 nav:not(body > nav),
 nav[data-breadcrumb] {
-  --breadcrumb-px: unset;
-  --breadcrumb-dsp: flex;
+  --breadcrumb-padding-inline: unset;
+  --breadcrumb-display: flex;
   --breadcrumb-gap: 0.5rem;
   --breadcrumb-color: currentColor;
   --breadcrumb-current-color: rgb(46, 46, 46);
@@ -9,12 +9,12 @@ nav[data-breadcrumb] {
   margin-inline: unset;
   padding-inline: unset;
   ol {
-    padding-inline: var(--breadcrumb-px);
-    display: var(--breadcrumb-dsp);
+    padding-inline: var(--breadcrumb-padding-inline);
+    display: var(--breadcrumb-display);
     gap: var(--breadcrumb-gap);
     li {
       padding-inline: unset;
-      width: var(--breadcrumb-w, fit-content);
+      width: var(--breadcrumb-width, fit-content);
       text-transform: capitalize;
       display: flex;
       color: var(--breadcrumb-color);

package/src/components/breadcrumbs/breadcrumb.scss.backup

@@ -0,0 +1,35 @@
+nav:not(body > nav),
+nav[data-breadcrumb] {
+  --breadcrumb-px: unset;
+  --breadcrumb-dsp: flex;
+  --breadcrumb-gap: 0.5rem;
+  --breadcrumb-color: currentColor;
+  --breadcrumb-current-color: rgb(46, 46, 46);
+  --breadcrumb-fs: var(--fs-3);
+  margin-inline: unset;
+  padding-inline: unset;
+  ol {
+    padding-inline: var(--breadcrumb-px);
+    display: var(--breadcrumb-dsp);
+    gap: var(--breadcrumb-gap);
+    li {
+      padding-inline: unset;
+      width: var(--breadcrumb-w, fit-content);
+      text-transform: capitalize;
+      display: flex;
+      color: var(--breadcrumb-color);
+      gap: 0.5rem;
+      font-size: var(--breadcrumb-fs);
+      span[aria-hidden="true"] {
+        opacity: 0.6;
+      }
+      a[href] {
+        font-size: var(--breadcrumb-fs);
+        &[aria-current] {
+          color: var(--breadcrumb-current-color);
+          text-decoration: none;
+        }
+      }
+    }
+  }
+}

package/src/components/breadcrumbs/breadcrumb.stories.tsx

@@ -17,7 +17,23 @@ const meta: Meta<typeof Breadcrumb> = {
 
 **Features:** Automatic path parsing, custom route naming, text truncation, full accessibility support, and performance optimized with memoization.
 
-**Accessibility:** Semantic HTML (\`<nav>\`, \`<ol>\`), proper ARIA labels, current page marked with \`aria-current="page"\`, and truncated text includes full text in \`aria-label\`.`,
+**Accessibility:** Semantic HTML (\`<nav>\`, \`<ol>\`), proper ARIA labels, current page marked with \`aria-current="page"\`, and truncated text includes full text in \`aria-label\`.
+
+## CSS Variables
+
+### Layout & Display
+- \`--breadcrumb-display\`: Display mode for breadcrumb list (default: flex)
+- \`--breadcrumb-width\`: Width of list items (default: fit-content)
+
+### Spacing
+- \`--breadcrumb-padding-inline\`: Horizontal padding (default: unset)
+- \`--breadcrumb-gap\`: Gap between breadcrumb items (default: 0.5rem)
+
+### Typography & Color
+- \`--breadcrumb-fs\`: Font size (default: var(--fs-3))
+- \`--breadcrumb-color\`: Text color (default: currentColor)
+- \`--breadcrumb-current-color\`: Current page color (default: rgb(46, 46, 46))
+`,
       },
     },
   },

package/src/components/buttons/button.scss

@@ -1,10 +1,11 @@
 button {
-  --btn-xs: 0.6875rem;
-  --btn-sm: 0.8125rem;
-  --btn-md: 0.9375rem;
-  --btn-lg: 1.125rem;
+  // Size tokens - renamed for clarity
+  --btn-size-xs: 0.6875rem;
+  --btn-size-sm: 0.8125rem;
+  --btn-size-md: 0.9375rem;
+  --btn-size-lg: 1.125rem;
   --btn-pill: 100rem;
-  --btn-fs: var(--btn-md);
+  --btn-fs: var(--btn-size-md);
   --btn-height: calc(var(--btn-fs) * 2.25);
   --btn-bg: lightgray;
   --btn-width: max-content;
@@ -13,16 +14,16 @@ button {
   font-weight: var(--btn-fw, 500);
   height: var(--btn-height);
   place-items: var(--btn-place, center);
-  padding-inline: var(--btn-px, calc(var(--btn-fs) * 1.5));
-  padding-block: var(--btn-py, calc(var(--btn-fs) * 0.5));
-  border: var(--btn-bdr, none);
-  border-radius: var(--btn-rds, calc(6rem / 16));
+  padding-inline: var(--btn-padding-inline, calc(var(--btn-fs) * 1.5));
+  padding-block: var(--btn-padding-block, calc(var(--btn-fs) * 0.5));
+  border: var(--btn-border, none);
+  border-radius: var(--btn-radius, calc(6rem / 16));
   text-decoration: var(--btn-deco, none);
-  color: var(--btn-cl, currentColor);
-  display: var(--btn-dsp, inline-flex);
+  color: var(--btn-color, currentColor);
+  display: var(--btn-display, inline-flex);
   gap: var(--btn-gap, 0.2rem);
-  white-space: var(--btn-wspc, inherit);
-  margin: var(--btn-spc, 0);
+  white-space: var(--btn-whitespace, inherit);
+  margin: var(--btn-spacing, 0);
   transition: var(
     --btn-transition,
     var(--tran-all, all 0.3s cubic-bezier(0.4, 0, 0.2, 1))
@@ -36,7 +37,7 @@ button {
 
   &[type] {
     background-color: var(--btn-bg, var(--neutral-300));
-    --btn-bdr: solid var(--btn-sg);
+    --btn-border: solid var(--btn-sg);
   }
 
   &[type="submit"],
@@ -73,16 +74,20 @@ button {
     }
   }
 
+  &:focus-visible {
+    outline: var(--btn-focus-outline, 2px solid currentColor);
+    outline-offset: var(--btn-focus-outline-offset, 1px);
+  }
+
   &[type="reset"] {
     --btn-bg: transparent;
     --btn-color: gray;
-    --btn-bdr: gray thin solid;
+    --btn-border: gray thin solid;
   }
 
   &[type="submit"] {
     --btn-bg: var(--primary-700, blue);
-    --btn-cl: #fff;
-    --btn-color: rgb(231, 231, 231);
+    --btn-color: #fff;
     --btn-border: none;
   }
 
@@ -94,23 +99,23 @@ button {
 
   &[data-btn~="xs"],
   .btn-xs {
-    --btn-fs: var(--btn-xs);
+    --btn-fs: var(--btn-size-xs);
     text-transform: uppercase;
   }
 
   &[data-btn~="sm"],
   .btn-sm {
-    --btn-fs: var(--btn-sm);
+    --btn-fs: var(--btn-size-sm);
   }
 
   &[data-btn~="md"],
   .btn-md {
-    --btn-fs: var(--btn-md);
+    --btn-fs: var(--btn-size-md);
   }
 
   &[data-btn~="lg"],
   .btn-lg {
-    --btn-fs: var(--btn-lg);
+    --btn-fs: var(--btn-size-lg);
   }
 
   &[data-btn~="icon"],
@@ -129,15 +134,15 @@ button {
   &[data-btn~="text"],
   .btn-text {
     --btn-bg: transparent;
-    --btn-cl: currentColor;
-    --btn-bdr: none;
+    --btn-color: currentColor;
+    --btn-border: none;
     --btn-height: unset;
     --btn-width: unset;
-    --btn-py: 0.75rem;
-    --btn-px: 0.75rem;
+    --btn-padding-block: 0.75rem;
+    --btn-padding-inline: 0.75rem;
     &:is(:hover, :focus) {
-      background-color: color-mix(in srgb, var(--btn-cl) 10%, transparent);
-      outline: 0.025rem solid var(--btn-cl);
+      background-color: color-mix(in srgb, var(--btn-color) 10%, transparent);
+      outline: 0.025rem solid var(--btn-color);
       outline-offset: 0;
       filter: none; // Override parent filter
     }

package/src/components/buttons/button.scss.backup

@@ -0,0 +1,145 @@
+button {
+  --btn-xs: 0.6875rem;
+  --btn-sm: 0.8125rem;
+  --btn-md: 0.9375rem;
+  --btn-lg: 1.125rem;
+  --btn-pill: 100rem;
+  --btn-fs: var(--btn-md);
+  --btn-height: calc(var(--btn-fs) * 2.25);
+  --btn-bg: lightgray;
+  --btn-width: max-content;
+
+  font-size: var(--btn-fs);
+  font-weight: var(--btn-fw, 500);
+  height: var(--btn-height);
+  place-items: var(--btn-place, center);
+  padding-inline: var(--btn-px, calc(var(--btn-fs) * 1.5));
+  padding-block: var(--btn-py, calc(var(--btn-fs) * 0.5));
+  border: var(--btn-bdr, none);
+  border-radius: var(--btn-rds, calc(6rem / 16));
+  text-decoration: var(--btn-deco, none);
+  color: var(--btn-cl, currentColor);
+  display: var(--btn-dsp, inline-flex);
+  gap: var(--btn-gap, 0.2rem);
+  white-space: var(--btn-wspc, inherit);
+  margin: var(--btn-spc, 0);
+  transition: var(
+    --btn-transition,
+    var(--tran-all, all 0.3s cubic-bezier(0.4, 0, 0.2, 1))
+  );
+  background-color: var(--btn-bg, var(--btn));
+  outline: none;
+  width: var(--btn-width);
+  display: inline-flex;
+  align-items: center;
+  line-height: 0cap;
+
+  &[type] {
+    background-color: var(--btn-bg, var(--neutral-300));
+    --btn-bdr: solid var(--btn-sg);
+  }
+
+  &[type="submit"],
+  &[style*="submit"] {
+    --btn-bg: var(--primary-500, royal-blue);
+    --btn-color: white;
+  }
+
+  &[disabled],
+  &[aria-disabled="true"] {
+    cursor: var(--btn-cursor, not-allowed);
+    // opacity: var(--btn-opacity, 0.5);
+
+    &:is(:hover, :focus) {
+      transform: none;
+      // background-color: var(--btn-bg, lightgray);
+      // opacity: var(--btn-opacity, 0.5);
+    }
+  }
+
+  // TODO: add hover/focus with :if()
+  &:is(:hover, :focus) {
+    // Darken the background on hover by reducing brightness
+    filter: var(--btn-hover-filter, brightness(0.85));
+    transform: var(--btn-hover-transform, scale(1.03));
+    outline: var(--btn-hover-outline, thin);
+    outline-offset: var(--line-offset, 1px);
+    // outline-style: var(--line-style, solid);
+
+    &[aria-disabled="true"] {
+      transform: none;
+      opacity: var(--btn-opacity, 0.5);
+      filter: none;
+    }
+  }
+
+  &[type="reset"] {
+    --btn-bg: transparent;
+    --btn-color: gray;
+    --btn-bdr: gray thin solid;
+  }
+
+  &[type="submit"] {
+    --btn-bg: var(--primary-700, blue);
+    --btn-cl: #fff;
+    --btn-color: rgb(231, 231, 231);
+    --btn-border: none;
+  }
+
+  &[data-fp-btn~="pill"],
+  &[data-btn~="pill"],
+  &[data-style~="pill"] {
+    border-radius: var(--btn-pill, 100rem);
+  }
+
+  &[data-btn~="xs"],
+  .btn-xs {
+    --btn-fs: var(--btn-xs);
+    text-transform: uppercase;
+  }
+
+  &[data-btn~="sm"],
+  .btn-sm {
+    --btn-fs: var(--btn-sm);
+  }
+
+  &[data-btn~="md"],
+  .btn-md {
+    --btn-fs: var(--btn-md);
+  }
+
+  &[data-btn~="lg"],
+  .btn-lg {
+    --btn-fs: var(--btn-lg);
+  }
+
+  &[data-btn~="icon"],
+  .btn-icon {
+    padding: unset;
+    height: unset;
+    --btn-bg: transparent;
+    min-width: 1.5rem;
+    min-height: 1.5rem;
+    text-align: center;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  &[data-btn~="text"],
+  .btn-text {
+    --btn-bg: transparent;
+    --btn-cl: currentColor;
+    --btn-bdr: none;
+    --btn-height: unset;
+    --btn-width: unset;
+    --btn-py: 0.75rem;
+    --btn-px: 0.75rem;
+    &:is(:hover, :focus) {
+      background-color: color-mix(in srgb, var(--btn-cl) 10%, transparent);
+      outline: 0.025rem solid var(--btn-cl);
+      outline-offset: 0;
+      filter: none; // Override parent filter
+    }
+  }
+}

package/src/components/buttons/button.stories.tsx

@@ -9,7 +9,7 @@ const buttonClicked = fn();
 const meta = {
   title: "FP.React Components/Buttons",
   component: Button,
-  tags: ["rc"],
+  tags: ["beta"],
   args: {
     children: "Click me",
     onClick: buttonClicked,
@@ -149,10 +149,13 @@ export const Disabled: Story = {
       expect(button).toHaveAttribute("aria-disabled", "true");
     });
 
-    await step("Disabled button remains focusable for accessibility", async () => {
-      await userEvent.tab();
-      expect(button).toHaveFocus();
-    });
+    await step(
+      "Disabled button remains focusable for accessibility",
+      async () => {
+        await userEvent.tab();
+        expect(button).toHaveFocus();
+      }
+    );
 
     await step("Disabled button prevents click interactions", async () => {
       const clickHandler = fn();
@@ -181,8 +184,8 @@ export const DisabledCustom: Story = {
     classes: "my-custom-button",
     styles: {
       "--btn-fs": "1.25rem",
-      "--btn-py": "0.75rem",
-      "--btn-px": "1.5rem",
+      "--btn-padding-block": "0.75rem",
+      "--btn-padding-inline": "1.5rem",
     },
     children: "Custom Disabled",
   },
@@ -225,3 +228,189 @@ Try clicking - only enabled button responds.
     },
   },
 } as Story;
+
+/**
+ * CSS Variable Customization
+ *
+ * Demonstrates how to customize button appearance using the new standardized
+ * CSS custom property naming convention.
+ *
+ * New variable naming patterns:
+ * - Size tokens: `--btn-size-{xs|sm|md|lg}`
+ * - Logical properties: `--btn-padding-inline`, `--btn-padding-block`
+ * - Full property names: `--btn-radius`, `--btn-color`, `--btn-display`, `--btn-border`
+ * - Approved abbreviations: `--btn-fs` (font-size), `--btn-bg` (background), `--btn-fw` (font-weight)
+ */
+export const Customization: Story = {
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "2rem" }}>
+      {/* Custom brand colors */}
+      <div>
+        <h4>Custom Brand Colors</h4>
+        <Button
+          type="button"
+          styles={{
+            "--btn-bg": "#0066cc",
+            "--btn-color": "white",
+            "--btn-radius": "0.5rem",
+            "--btn-padding-inline": "2rem",
+            "--btn-padding-block": "0.75rem",
+          }}
+        >
+          Brand Button
+        </Button>
+      </div>
+
+      {/* Custom sizes using logical properties */}
+      <div>
+        <h4>Custom Padding (Logical Properties)</h4>
+        <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
+          <Button
+            type="button"
+            styles={{
+              "--btn-padding-inline": "0.5rem",
+              "--btn-padding-block": "0.25rem",
+              "--btn-fs": "0.875rem",
+            }}
+          >
+            Compact
+          </Button>
+          <Button
+            type="button"
+            styles={{
+              "--btn-padding-inline": "3rem",
+              "--btn-padding-block": "1rem",
+              "--btn-fs": "1.125rem",
+            }}
+          >
+            Spacious
+          </Button>
+        </div>
+      </div>
+
+      {/* Custom hover effects */}
+      <div>
+        <h4>Custom Hover Effects</h4>
+        <Button
+          type="button"
+          styles={{
+            "--btn-bg": "#28a745",
+            "--btn-color": "white",
+            "--btn-hover-filter": "brightness(1.1)",
+            "--btn-hover-transform": "translateY(-2px)",
+          }}
+        >
+          Hover Me
+        </Button>
+      </div>
+
+      {/* Custom borders and shapes */}
+      <div>
+        <h4>Custom Borders & Shapes</h4>
+        <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
+          <Button
+            type="button"
+            styles={{
+              "--btn-bg": "transparent",
+              "--btn-color": "#0066cc",
+              "--btn-border": "2px solid currentColor",
+              "--btn-radius": "0",
+            }}
+          >
+            Square Outline
+          </Button>
+          <Button
+            type="button"
+            styles={{
+              "--btn-bg": "#dc3545",
+              "--btn-color": "white",
+              "--btn-radius": "100rem",
+              "--btn-padding-inline": "2rem",
+            }}
+          >
+            Pill Shape
+          </Button>
+        </div>
+      </div>
+
+      {/* Dark theme example */}
+      <div
+        style={{
+          background: "#1a1a1a",
+          padding: "1.5rem",
+          borderRadius: "0.5rem",
+        }}
+      >
+        <h4 style={{ color: "white", marginTop: 0 }}>Dark Theme Example</h4>
+        <div style={{ display: "flex", gap: "1rem", flexWrap: "wrap" }}>
+          <Button
+            type="button"
+            styles={{
+              "--btn-bg": "#3b82f6",
+              "--btn-color": "white",
+              "--btn-hover-filter": "brightness(1.2)",
+            }}
+          >
+            Primary
+          </Button>
+          <Button
+            type="button"
+            styles={{
+              "--btn-bg": "transparent",
+              "--btn-color": "#e5e7eb",
+              "--btn-border": "1px solid #4b5563",
+              "--btn-hover-filter": "brightness(1.3)",
+            }}
+          >
+            Secondary
+          </Button>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+## Available CSS Variables
+
+### Size Tokens
+- \`--btn-size-xs\`: 0.6875rem (11px)
+- \`--btn-size-sm\`: 0.8125rem (13px)
+- \`--btn-size-md\`: 0.9375rem (15px)
+- \`--btn-size-lg\`: 1.125rem (18px)
+
+### Base Properties
+- \`--btn-padding-inline\`: Horizontal padding (logical property)
+- \`--btn-padding-block\`: Vertical padding (logical property)
+- \`--btn-radius\`: Border radius
+- \`--btn-color\`: Text color
+- \`--btn-bg\`: Background color
+- \`--btn-border\`: Border style
+- \`--btn-display\`: Display property
+- \`--btn-whitespace\`: White-space handling
+- \`--btn-spacing\`: Margin/spacing
+
+### Typography (Approved Abbreviations)
+- \`--btn-fs\`: Font size
+- \`--btn-fw\`: Font weight
+
+### State Variables
+- \`--btn-hover-filter\`: Filter on hover
+- \`--btn-hover-transform\`: Transform on hover
+- \`--btn-hover-outline\`: Outline on hover
+
+### Migration from Old Names
+- ❌ \`--btn-px\` → ✅ \`--btn-padding-inline\`
+- ❌ \`--btn-py\` → ✅ \`--btn-padding-block\`
+- ❌ \`--btn-rds\` → ✅ \`--btn-radius\`
+- ❌ \`--btn-cl\` → ✅ \`--btn-color\`
+- ❌ \`--btn-dsp\` → ✅ \`--btn-display\`
+- ❌ \`--btn-bdr\` → ✅ \`--btn-border\`
+- ❌ \`--btn-wspc\` → ✅ \`--btn-whitespace\`
+- ❌ \`--btn-spc\` → ✅ \`--btn-spacing\`
+        `,
+      },
+    },
+  },
+} as Story;

package/src/components/cards/card.scss

@@ -1,11 +1,23 @@
 :root {
-  --card-p: 2rem;
+  // Base card properties
+  --card-padding: 2rem;
   --card-bg: #fff;
-  --card-radius: calc(var(--card-p) / 4);
+  --card-radius: calc(var(--card-padding) / 4);
   --card-position: relative;
   --card-display: flex;
   --card-direction: column;
   --card-gap: 1rem;
+
+  // Element-specific variables (NEW - for complex card layouts)
+  --card-header-padding: 1rem 1.5rem;
+  --card-header-bg: #f8f9fa;
+  --card-header-border-bottom: 1px solid #dee2e6;
+
+  --card-body-padding: 1.5rem;
+
+  --card-footer-padding: 1rem 1.5rem;
+  --card-footer-bg: #f8f9fa;
+  --card-footer-border-top: 1px solid #dee2e6;
 }
 
 [data-card],
@@ -32,14 +44,36 @@
   }
 
   > *:not(img) {
-    padding-inline: var(--card-p);
+    padding-inline: var(--card-padding);
   }
   > *:last-child:not(img) {
     // margin-block-end: 0;
-    padding-block-end: var(--card-p);
+    padding-block-end: var(--card-padding);
   }
   > *:first-child:not(img) {
-    padding-block-start: calc(var(--card-p) - 0.5rem);
+    padding-block-start: calc(var(--card-padding) - 0.5rem);
+  }
+
+  // Element-specific styling (using new scoped variables)
+  > header,
+  > [data-card-header] {
+    padding: var(--card-header-padding);
+    background-color: var(--card-header-bg);
+    border-bottom: var(--card-header-border-bottom);
+    border-radius: var(--card-radius) var(--card-radius) 0 0;
+  }
+
+  > [data-card-body] {
+    padding: var(--card-body-padding);
+    flex: 1;
+  }
+
+  > footer,
+  > [data-card-footer] {
+    padding: var(--card-footer-padding);
+    background-color: var(--card-footer-bg);
+    border-top: var(--card-footer-border-top);
+    border-radius: 0 0 var(--card-radius) var(--card-radius);
   }
 }