@fpkit/acss 0.6.2 → 1.0.0

package/src/components/layout/landmarks.stories.tsx

@@ -15,6 +15,48 @@ import Img from "#components/images/img";
 const meta: Meta<typeof Header> = {
   title: "FP.React Components/Layout/Landmarks",
   component: Header,
+  parameters: {
+    docs: {
+      description: {
+        component: `Semantic landmark components including Header (banner), Main, and Footer with responsive content layout.
+
+## CSS Variables (Header/Overlay)
+
+### Layout & Display
+- \`--overlay-display\`: Display mode (default: grid)
+- \`--overlay-grid-area\`: Grid area name (default: overlay)
+- \`--overlay-placement\`: Item placement (default: center)
+
+### Sizing
+- \`--overlay-width\`: Overlay width (default: 100%)
+- \`--overlay-height\`: Minimum overlay height (default: 40vh)
+- \`--overlay-max-height\`: Maximum overlay height (default: 500px)
+- \`--overlay-content-width\`: Content max width (default: 80%)
+
+### Spacing
+- \`--overlay-padding\`: General padding (default: 2rem)
+- \`--overlay-padding-inline\`: Horizontal padding (default: auto)
+- \`--overlay-padding-block\`: Vertical padding (default: auto)
+- \`--overlay-margin-inline\`: Horizontal margin (default: auto)
+- \`--overlay-margin-block\`: Vertical margin (default: auto)
+- \`--overlay-gap\`: Gap between elements (default: 2rem)
+
+### Colors & Typography
+- \`--overlay-color\`: Text color (default: currentColor)
+- \`--overlay-bg\`: Background color (default: whitesmoke)
+- \`--header-line-height\`: Heading line height (default: 1.1)
+
+## CSS Variables (Main/Footer)
+
+### Content Layout
+- \`--content-width\`: Max content width (default: min(100%, 1480px))
+- \`--content-margin-inline\`: Horizontal margin for centering (default: auto)
+- \`--content-padding-inline\`: Horizontal padding (default: 1rem)
+- \`--content-gap\`: Gap between article and aside (default: 2rem)
+`,
+      },
+    },
+  },
   args: {
     children: "Default Header",
     "data-testid": "banner",

package/src/components/link/link.scss

@@ -15,7 +15,7 @@
 a[href] {
   // Color & Typography
   --link-color: #085ab7;
-  --link-weight: 400;
+  --link-fw: 400;
   --link-fs: 1rem;
 
   // Text Decoration
@@ -29,8 +29,8 @@ a[href] {
   --link-radius: 0.25rem;
 
   // Spacing (for button variants)
-  --link-px: 0;
-  --link-py: 0;
+  --link-padding-inline: 0;
+  --link-padding-block: 0;
 
   // Transitions
   --link-transition: all 0.75s ease-in-out;
@@ -44,7 +44,7 @@ a[href] {
   // Apply base styles
   color: var(--link-color);
   font-size: var(--link-fs);
-  font-weight: var(--link-weight);
+  font-weight: var(--link-fw);
   text-decoration: var(--link-decoration);
   text-underline-offset: var(--link-decoration-offset);
   text-decoration-thickness: var(--link-decoration-thickness);
@@ -56,7 +56,7 @@ a[href] {
   // Ensure child elements inherit weight/style
   > i,
   > b {
-    font-weight: var(--link-weight);
+    font-weight: var(--link-fw);
     font-style: normal;
   }
 

package/src/components/link/link.scss.backup

@@ -0,0 +1,145 @@
+@use '../../sass/mixins';
+
+/**
+ * Link Component Styles
+ *
+ * Provides accessible, customizable link styles using CSS custom properties.
+ * Supports standard text links, button-styled links, and pill variants.
+ *
+ * WCAG 2.1 AA Compliance:
+ * - Focus indicators meet 2.4.7 (3:1 contrast minimum)
+ * - Color contrast meets 1.4.3 (4.5:1 for normal text)
+ * - Uses :focus-visible for better UX (keyboard vs mouse)
+ */
+
+a[href] {
+  // Color & Typography
+  --link-color: #085ab7;
+  --link-weight: 400;
+  --link-fs: 1rem;
+
+  // Text Decoration
+  --link-decoration: none;
+  --link-decoration-offset: 0.09375rem; // 1.5px converted to rem
+  --link-decoration-thickness: 0.0625rem; // 1px converted to rem
+  --link-skip-ink: auto;
+
+  // Background & Border
+  --link-bg: transparent;
+  --link-radius: 0.25rem;
+
+  // Spacing (for button variants)
+  --link-px: 0;
+  --link-py: 0;
+
+  // Transitions
+  --link-transition: all 0.75s ease-in-out;
+
+  // Focus Indicator (WCAG 2.4.7 - 3:1 contrast minimum)
+  --link-focus-color: currentColor;
+  --link-focus-width: 0.125rem; // 2px
+  --link-focus-offset: 0.125rem; // 2px
+  --link-focus-style: solid;
+
+  // Apply base styles
+  color: var(--link-color);
+  font-size: var(--link-fs);
+  font-weight: var(--link-weight);
+  text-decoration: var(--link-decoration);
+  text-underline-offset: var(--link-decoration-offset);
+  text-decoration-thickness: var(--link-decoration-thickness);
+  text-decoration-skip-ink: var(--link-skip-ink);
+  background-color: var(--link-bg);
+  border-radius: var(--link-radius);
+  transition: var(--link-transition);
+
+  // Ensure child elements inherit weight/style
+  > i,
+  > b {
+    font-weight: var(--link-weight);
+    font-style: normal;
+  }
+
+  // Hover state - add underline for clarity
+  &:hover {
+    --link-decoration: underline;
+  }
+
+  // Focus state - WCAG 2.4.7 compliant focus indicator
+  &:focus {
+    outline: var(--link-focus-width) var(--link-focus-style)
+      var(--link-focus-color);
+    outline-offset: var(--link-focus-offset);
+    --link-decoration: underline;
+  }
+
+  // Focus-visible for better UX (only show outline on keyboard focus)
+  &:focus-visible {
+    outline: var(--link-focus-width) var(--link-focus-style)
+      var(--link-focus-color);
+    outline-offset: var(--link-focus-offset);
+  }
+
+  // Visited and active states
+  &:visited,
+  &:active {
+    --link-color: currentColor;
+  }
+
+  // Button-styled links (via <b> wrapper, data-btn attribute, or <i> for pill)
+  &:has(> b),
+  &[data-btn],
+  &:has(> i) {
+    --link-button-color: var(--link-color);
+    --link-bg: transparent;
+    --link-decoration: none;
+    --link-border-width: 0.125rem; // 2px
+    --link-border-color: currentColor;
+    --link-border-style: solid;
+    --link-fs: 0.9rem;
+
+    color: var(--link-button-color);
+    background-color: var(--link-bg);
+    font-style: normal;
+    font-size: var(--link-fs);
+    padding-inline: var(--link-fs);
+    padding-block: calc(var(--link-fs) - 0.4rem);
+    border-radius: var(--link-radius, 99rem);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    outline: var(--link-border-width) var(--link-border-color)
+      var(--link-border-style);
+
+    // Focus state for button links
+    &:focus,
+    &:focus-visible {
+      outline: var(--link-border-width) var(--link-border-color)
+        var(--link-border-style);
+      outline-offset: var(--link-focus-offset);
+      --link-decoration: none;
+    }
+
+    // Hover state for button links
+    &:hover {
+      --link-decoration: none;
+    }
+
+    // Apply scale transition from mixins
+    @include mixins.scale-transitions;
+  }
+
+  // Pill variant (rounded corners)
+  &[data-link~='pill'],
+  &:has(> i) {
+    --link-radius: 99rem;
+    --link-decoration: none;
+    font-style: normal;
+
+    &:hover,
+    &:focus,
+    &:focus-visible {
+      --link-decoration: none;
+    }
+  }
+}

package/src/components/link/link.stories.tsx

@@ -39,8 +39,44 @@ const meta = {
   parameters: {
     docs: {
       description: {
-        component:
-          "A semantic, accessible anchor component with enhanced security for external links and flexible styling variants.",
+        component: `A semantic, accessible anchor component with enhanced security for external links and flexible styling variants.
+
+## CSS Variables
+
+### Typography & Color
+- \`--link-color\`: Link text color (default: #085ab7)
+- \`--link-fw\`: Font weight (default: 400)
+- \`--link-fs\`: Font size (default: 1rem)
+
+### Text Decoration
+- \`--link-decoration\`: Text decoration style (default: none, underline on hover/focus)
+- \`--link-decoration-offset\`: Underline offset (default: 0.09375rem / 1.5px)
+- \`--link-decoration-thickness\`: Underline thickness (default: 0.0625rem / 1px)
+- \`--link-skip-ink\`: Text decoration skip ink (default: auto)
+
+### Background & Border
+- \`--link-bg\`: Background color (default: transparent)
+- \`--link-radius\`: Border radius (default: 0.25rem, 99rem for pills)
+
+### Spacing (Button Variants)
+- \`--link-padding-inline\`: Horizontal padding (default: 0, calculated for button variants)
+- \`--link-padding-block\`: Vertical padding (default: 0, calculated for button variants)
+
+### Focus Indicators (WCAG 2.4.7)
+- \`--link-focus-color\`: Focus outline color (default: currentColor)
+- \`--link-focus-width\`: Focus outline width (default: 0.125rem / 2px)
+- \`--link-focus-offset\`: Focus outline offset (default: 0.125rem / 2px)
+- \`--link-focus-style\`: Focus outline style (default: solid)
+
+### Transitions
+- \`--link-transition\`: Transition timing (default: all 0.75s ease-in-out)
+
+### Button Variants
+- \`--link-button-color\`: Button link text color (default: var(--link-color))
+- \`--link-border-width\`: Button border width (default: 0.125rem / 2px)
+- \`--link-border-color\`: Button border color (default: currentColor)
+- \`--link-border-style\`: Button border style (default: solid)
+`,
       },
     },
   },

package/src/components/list/list.scss

@@ -18,7 +18,7 @@ dl {
   --list-margin-top: 0;
   --list-margin-bottom: 1rem; // 16px
   --list-margin-inline: 0;
-  --list-padding-inline: 2.5rem; // 40px - default browser indent
+  --list-padding-inline: 0.5rem; // 40px - default browser indent
   --list-gap: 0.5rem; // 8px - gap between items
 
   // List marker/bullet styling

package/src/components/nav/nav.scss

@@ -1,8 +1,8 @@
 body > nav,
 [aria-label~="navbar"],
 .navbar {
-  padding-inline: var(--nav-px, 1rem);
-  min-height: var(--nav-h, fit-content);
+  padding-inline: var(--nav-padding-inline, 1rem);
+  min-height: var(--nav-height, fit-content);
 
   @media (max-width: 580px) {
     flex-direction: column;
@@ -19,10 +19,10 @@ body > nav,
       margin: 0;
       padding: 0;
       min-height: 100%;
-      padding-inline: var(--nav-px, 0.75rem);
+      padding-inline: var(--nav-padding-inline, 0.75rem);
 
       &:hover {
-        background-color: var(--nav-hov-bg, #e8e8e8);
+        background-color: var(--nav-hover-bg, #e8e8e8);
       }
       &:hover:where(img) {
         background-color: transparent;
@@ -38,25 +38,25 @@ nav {
   --nav-focus-offset: 0.125rem; // 2px
   --nav-focus-style: solid;
 
-  display: var(--nav-dsp, flex);
+  display: var(--nav-display, flex);
   flex-direction: var(--nav-direction, row);
-  width: var(--nav-w, auto);
+  width: var(--nav-width, auto);
   place-items: var(--nav-align, center);
   justify-content: var(--nav-justify, space-between);
-  margin-inline: var(--nav-mx, 0);
+  margin-inline: var(--nav-margin-inline, 0);
   background-color: var(--nav-bg, initial);
 
   > section,
   > ul {
-    --nav-dsp: flex;
+    --nav-display: flex;
     flex-direction: var(--nav-direction, row);
-    display: var(--nav-dsp, flex);
+    display: var(--nav-display, flex);
     gap: var(--nav-gap, 0);
     font-size: var(--nav-fs, 0.9rem);
     align-items: var(--nav-align, center);
-    padding-inline: var(--nav-px, 1rem);
-    padding-block: var(--nav-py, 0);
-    margin-block-end: var(--nav-mb, 0);
+    padding-inline: var(--nav-padding-inline, 1rem);
+    padding-block: var(--nav-padding-block, 0);
+    margin-block-end: var(--nav-margin-block-end, 0);
     height: 100%;
     &[data-list~="block"] {
       --nav-direction: column;
@@ -65,7 +65,7 @@ nav {
 
   > section {
     > div {
-      --py: 0;
+      --nav-padding-block: 0;
     }
   }
 
@@ -77,18 +77,18 @@ nav {
       margin: 0;
       padding: 0;
       min-height: 100%;
-      padding-inline: var(--nav-px, 1rem);
+      padding-inline: var(--nav-padding-inline, 1rem);
     }
   }
 
   img[alt] {
-    --px: 0 var(--s1);
-    --w: var(--brand-w, 3.6rem);
+    --nav-img-padding-inline: 0 var(--s1);
+    --nav-img-width: var(--brand-w, 3.6rem);
   }
 
   &[data-variant] {
     background-color: var(--nav-bg);
-    color: var(--nav-cl);
+    color: var(--nav-color);
     font-size: var(--nav-fs, 0.9rem);
   }
 

package/src/components/nav/nav.scss.backup

@@ -0,0 +1,123 @@
+body > nav,
+[aria-label~="navbar"],
+.navbar {
+  padding-inline: var(--nav-px, 1rem);
+  min-height: var(--nav-h, fit-content);
+
+  @media (max-width: 580px) {
+    flex-direction: column;
+    height: fit-content;
+    min-height: fit-content;
+    padding-block: unset;
+    gap: 0.5rem;
+  }
+  ul {
+    > li {
+      display: flex;
+      align-items: center;
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      min-height: 100%;
+      padding-inline: var(--nav-px, 0.75rem);
+
+      &:hover {
+        background-color: var(--nav-hov-bg, #e8e8e8);
+      }
+      &:hover:where(img) {
+        background-color: transparent;
+      }
+    }
+  }
+}
+
+nav {
+  // Focus Indicator Variables (WCAG 2.4.7 - 3:1 contrast minimum)
+  --nav-focus-color: currentColor;
+  --nav-focus-width: 0.125rem; // 2px
+  --nav-focus-offset: 0.125rem; // 2px
+  --nav-focus-style: solid;
+
+  display: var(--nav-dsp, flex);
+  flex-direction: var(--nav-direction, row);
+  width: var(--nav-w, auto);
+  place-items: var(--nav-align, center);
+  justify-content: var(--nav-justify, space-between);
+  margin-inline: var(--nav-mx, 0);
+  background-color: var(--nav-bg, initial);
+
+  > section,
+  > ul {
+    --nav-dsp: flex;
+    flex-direction: var(--nav-direction, row);
+    display: var(--nav-dsp, flex);
+    gap: var(--nav-gap, 0);
+    font-size: var(--nav-fs, 0.9rem);
+    align-items: var(--nav-align, center);
+    padding-inline: var(--nav-px, 1rem);
+    padding-block: var(--nav-py, 0);
+    margin-block-end: var(--nav-mb, 0);
+    height: 100%;
+    &[data-list~="block"] {
+      --nav-direction: column;
+    }
+  }
+
+  > section {
+    > div {
+      --py: 0;
+    }
+  }
+
+  ul {
+    > li {
+      display: flex;
+      align-items: center;
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      min-height: 100%;
+      padding-inline: var(--nav-px, 1rem);
+    }
+  }
+
+  img[alt] {
+    --px: 0 var(--s1);
+    --w: var(--brand-w, 3.6rem);
+  }
+
+  &[data-variant] {
+    background-color: var(--nav-bg);
+    color: var(--nav-cl);
+    font-size: var(--nav-fs, 0.9rem);
+  }
+
+  > div {
+    margin-block-start: 0;
+  }
+
+  // Focus indicators for links and buttons (WCAG 2.4.7)
+  a:focus {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+
+  a:focus-visible {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+
+  button:focus {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+
+  button:focus-visible {
+    outline: var(--nav-focus-width) var(--nav-focus-style)
+      var(--nav-focus-color);
+    outline-offset: var(--nav-focus-offset);
+  }
+}

package/src/components/nav/nav.stories.tsx

@@ -9,12 +9,46 @@ import Link from "../link/link";
 const meta: Meta<typeof Nav> = {
   title: "FP.REACT Components/Nav",
   component: Nav,
-  tags: ["rc"],
+  tags: ["stable"],
   parameters: {
     actions: { argTypesRegex: "^on.*" },
     docs: {
       description: {
-        component: "Nav description here...",
+        component: `Navigation component with accessible markup and customizable styling via CSS variables.
+
+## CSS Variables
+
+### Layout & Sizing
+- \`--nav-display\`: Display mode (default: flex)
+- \`--nav-width\`: Nav width (default: auto)
+- \`--nav-height\`: Minimum height (default: fit-content)
+- \`--nav-direction\`: Flex direction (default: row)
+- \`--nav-align\`: Vertical alignment (default: center)
+- \`--nav-justify\`: Horizontal justification (default: space-between)
+
+### Spacing
+- \`--nav-padding-inline\`: Horizontal padding (default: 1rem)
+- \`--nav-padding-block\`: Vertical padding (default: 0)
+- \`--nav-margin-inline\`: Horizontal margin (default: 0)
+- \`--nav-margin-block-end\`: Bottom margin (default: 0)
+- \`--nav-gap\`: Gap between nav items (default: 0)
+
+### Typography & Color
+- \`--nav-fs\`: Font size (default: 0.9rem)
+- \`--nav-color\`: Text color
+- \`--nav-bg\`: Background color (default: initial)
+- \`--nav-hover-bg\`: Background color on hover (default: #e8e8e8)
+
+### Focus Indicators (WCAG 2.4.7)
+- \`--nav-focus-color\`: Focus outline color (default: currentColor)
+- \`--nav-focus-width\`: Focus outline width (default: 0.125rem / 2px)
+- \`--nav-focus-offset\`: Focus outline offset (default: 0.125rem / 2px)
+- \`--nav-focus-style\`: Focus outline style (default: solid)
+
+### Image Elements
+- \`--nav-img-padding-inline\`: Image padding (default: 0 var(--s1))
+- \`--nav-img-width\`: Image width (default: var(--brand-w, 3.6rem))
+`,
       },
     },
   },

package/src/components/progress/progress.scss

@@ -1,8 +1,8 @@
 progress {
   /* Revert all styles */
   all: revert;
-  --progress-w: 100%;
-  --progress-h: 1rem;
+  --progress-width: 100%;
+  --progress-height: 1rem;
   --progress-bg: #cccccc;
   --progress-color: rgb(71, 71, 245);
   --progress-accent-color: var(--progress-color);
@@ -12,8 +12,8 @@ progress {
   /* The colors are used in the progress bar. */
   &[value] {
 
-    width: var(--progress-w);
-    height: var(--progress-h);
+    width: var(--progress-width);
+    height: var(--progress-height);
     background-color: var(--progress-bg);
     accent-color: var(--progress-accent-color);
 
@@ -42,9 +42,9 @@ progress {
   /* If the progress element is busy, remove the revert styles */
   &[aria-busy] {
     // all: revert;
-    width: var(--progress-w);
-    height: var(--progress-h);
-    // height: calc(var(--progress-h) + var(--progress-h));
+    width: var(--progress-width);
+    height: var(--progress-height);
+    // height: calc(var(--progress-height) + var(--progress-height));
     accent-color: var(--progress-accent-color);
 
     &::-webkit-progress-value {

package/src/components/progress/progress.scss.backup

@@ -0,0 +1,70 @@
+progress {
+  /* Revert all styles */
+  all: revert;
+  --progress-w: 100%;
+  --progress-h: 1rem;
+  --progress-bg: #cccccc;
+  --progress-color: rgb(71, 71, 245);
+  --progress-accent-color: var(--progress-color);
+
+  /* This code changes the color of the progress bar. */
+  /* The variable names indicate the colors that are used. */
+  /* The colors are used in the progress bar. */
+  &[value] {
+
+    width: var(--progress-w);
+    height: var(--progress-h);
+    background-color: var(--progress-bg);
+    accent-color: var(--progress-accent-color);
+
+
+    &::-webkit-progress-value {
+      /* Color for Chrome, Safari, and newer Opera */
+      background-color: var(--progress-accent-color);
+      accent-color: var(--progress-accent-color);
+
+    }
+
+    &::-moz-progress-bar {
+      /* Color for Firefox */
+      background-color: var(--progress-accent-color);
+      accent-color: var(--progress-accent-color)
+    }
+
+    /* Styling for the remaining part of the& bar */
+    &::-webkit-progress-bar {
+      /* Background for Chrome, Safari, and newer Opera */
+      background-color: var(--progress-background-color);
+      accent-color: var(--progress-accent-color)
+    }
+  }
+
+  /* If the progress element is busy, remove the revert styles */
+  &[aria-busy] {
+    // all: revert;
+    width: var(--progress-w);
+    height: var(--progress-h);
+    // height: calc(var(--progress-h) + var(--progress-h));
+    accent-color: var(--progress-accent-color);
+
+    &::-webkit-progress-value {
+      /* Color for Chrome, Safari, and newer Opera */
+      // background-color: var(--progress-accent-color);
+      accent-color: var(--progress-accent-color)
+    }
+
+    &::-moz-progress-bar {
+      // /* Color for Firefox */
+      // background-color: var(--progress-bg);
+      accent-color: var(--progress-accent-color)
+    }
+
+    /* Styling for the remaining part of the& bar */
+    &::-webkit-progress-bar {
+      /* Background for Chrome, Safari, and newer Opera */
+      // background-color: var(--progress-bg);
+      accent-color: var(--progress-accent-color)
+    }
+  }
+
+}

package/src/components/tag/tag.scss

@@ -25,19 +25,19 @@ small > span,
   --production: #1e3a8a;      /* Dark blue: 8.59:1 contrast with white */
 
   /* Tag component tokens */
-  --tag-px: 0.7rem;           /* Horizontal padding (11.2px at 16px base) */
-  --tag-py: 0.2rem;           /* Vertical padding (3.2px at 16px base) */
-  --tag-fs: 0.8rem;           /* Font size (12.8px at 16px base) */
-  --tag-radius: 99rem;        /* Fully rounded pill shape */
-  --tag-bg: lightgray;        /* Default background color */
-  --tag-fw: 500;              /* Medium font weight */
-  --tag-color: currentColor;  /* Default text color (inherits) */
-  --tag-display: inline-block;/* Display type */
+  --tag-padding-inline: 0.7rem;  /* Horizontal padding (11.2px at 16px base) */
+  --tag-padding-block: 0.2rem;   /* Vertical padding (3.2px at 16px base) */
+  --tag-fs: 0.8rem;              /* Font size (12.8px at 16px base) */
+  --tag-radius: 99rem;           /* Fully rounded pill shape */
+  --tag-bg: lightgray;           /* Default background color */
+  --tag-fw: 500;                 /* Medium font weight */
+  --tag-color: currentColor;     /* Default text color (inherits) */
+  --tag-display: inline-block;   /* Display type */
 
   /* Apply CSS custom properties */
   display: var(--tag-display);
-  padding-inline: var(--tag-px);
-  padding-block: var(--tag-py);
+  padding-inline: var(--tag-padding-inline);
+  padding-block: var(--tag-padding-block);
   font-size: var(--tag-fs);
   color: var(--tag-color);
   background-color: var(--tag-bg);