@fpkit/acss 4.0.0 → 5.0.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "4.0.0",
+  "version": "5.0.0",
   "engines": {
     "node": ">=22.12.0",
     "npm": ">=8.0.0"
@@ -126,5 +126,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2ffaeeeb8cebe0a38f95f65837f505c56218ee67"
+  "gitHead": "79600c132b52299259f087d029847acfcb2196e1"
 }

package/src/components/alert/alert.scss

@@ -12,34 +12,34 @@
 }
 
 [role="alert"] {
-  /* Success colors */
-  --alert-success-bg: #e6f4ea;
-  --alert-success-border: #34a853;
-  --alert-success-text: #1e4620;
-
-  /* Error colors */
-  --alert-error-bg: #fdeded;
-  --alert-error-border: #d32f2f;
-  --alert-error-text: #5f2120;
-
-  /* Warning colors */
-  --alert-warning-bg: #fff4e5;
-  --alert-warning-border: #ff9800;
-  --alert-warning-text: #663c00;
-
-  /* Info colors */
-  --alert-info-bg: #e5f6fd;
-  --alert-info-border: #0288d1;
-  --alert-info-text: #084154;
+  /* Success colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-success-bg: var(--color-success-bg);
+  --alert-success-border: var(--color-success-border);
+  --alert-success-text: var(--color-success-text);
+
+  /* Error colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-error-bg: var(--color-error-bg);
+  --alert-error-border: var(--color-error-border);
+  --alert-error-text: var(--color-error-text);
+
+  /* Warning colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-warning-bg: var(--color-warning-bg);
+  --alert-warning-border: var(--color-warning-border);
+  --alert-warning-text: var(--color-warning-text);
+
+  /* Info colors - WCAG AA compliant (mapped to semantic tokens) */
+  --alert-info-bg: var(--color-info-bg);
+  --alert-info-border: var(--color-info-border);
+  --alert-info-text: var(--color-info-text);
 
   /* Animation */
   --alert-transition-duration: 0.3s;
 
   --alert-border: thin solid currentColor;
 
-  background-color: var(--alert-bg, whitesmoke);
-  border: var(--alert-border, currentColor);
-  color: var(--alert-color, currentColor);
+  background-color: var(--alert-bg, var(--color-surface));
+  border: var(--alert-border, var(--color-border));
+  color: var(--alert-color, var(--color-text));
   padding: var(--alert-padding, var(--spc-4));
   margin-block-end: var(--alert-margin-block-end);
   font-size: var(--fs-0);

package/src/components/alert/views/alert-view.tsx

@@ -143,8 +143,12 @@ export const AlertView = React.forwardRef<HTMLDivElement, AlertViewProps>(
         {...props}
       >
         <AlertScreenReaderText severity={severity} />
-        <AlertIcon severity={severity} iconProps={iconProps} hideIcon={hideIcon} />
-        <UI as="div" className="alert-message">
+        <AlertIcon
+          severity={severity}
+          iconProps={iconProps}
+          hideIcon={hideIcon}
+        />
+        <UI as="div" classes="alert-message">
           <AlertTitle title={title} titleLevel={titleLevel} />
           <AlertContent contentType={contentType}>{children}</AlertContent>
           <AlertActions actions={actions} />

package/src/components/badge/badge.scss

@@ -1,5 +1,5 @@
 sup:has(> span) {
-  --badge-bg: lightgray;
+  --badge-bg: var(--color-neutral-300);
   --badge-color: currentColor;
   --badge-radius: 0.5rem;
   --badge-padding: 0.3rem;

package/src/components/buttons/button.scss

@@ -7,7 +7,7 @@ button {
   --btn-pill: 100rem;
   --btn-fs: var(--btn-size-md);
   --btn-height: calc(var(--btn-fs) * 2.25);
-  --btn-bg: lightgray;
+  --btn-bg: var(--color-neutral-300);
   --btn-width: max-content;
 
   font-size: var(--btn-fs);
@@ -36,14 +36,14 @@ button {
   line-height: 0cap;
 
   &[type] {
-    background-color: var(--btn-bg, var(--neutral-300));
+    background-color: var(--btn-bg, var(--color-neutral-300));
     --btn-border: solid var(--btn-sg);
   }
 
   &[type="submit"],
   &[style*="submit"] {
-    --btn-bg: var(--primary-500, royal-blue);
-    --btn-color: white;
+    --btn-bg: var(--color-primary);
+    --btn-color: var(--color-text-inverse);
   }
 
   &[disabled],
@@ -81,13 +81,13 @@ button {
 
   &[type="reset"] {
     --btn-bg: transparent;
-    --btn-color: gray;
-    --btn-border: gray thin solid;
+    --btn-color: var(--color-text-secondary);
+    --btn-border: var(--color-border) thin solid;
   }
 
   &[type="submit"] {
-    --btn-bg: var(--primary-700, blue);
-    --btn-color: #fff;
+    --btn-bg: var(--color-primary);
+    --btn-color: var(--color-text-inverse);
     --btn-border: none;
   }
 

package/src/components/cards/card.scss

@@ -1,24 +1,24 @@
 :root {
   // Base card properties
   --card-padding: 1.5rem;
-  --card-bg: var(--color-surface, #ffffff);
+  --card-bg: var(--color-surface);
   --card-radius: calc(var(--card-padding) / 4);
   --card-gap: 1rem;
 
   // Element-specific variables (NEW - for complex card layouts)
   --card-header-padding: 1rem 1.5rem;
-  --card-header-bg: var(--color-surface-secondary, #f8f9fa);
+  --card-header-bg: var(--color-surface-secondary);
   --card-header-border-bottom-width: 0.0625rem;
   --card-header-border-bottom-style: solid;
-  --card-header-border-bottom-color: var(--color-border, #dee2e6);
+  --card-header-border-bottom-color: var(--color-border);
 
   --card-body-padding: 1.5rem;
 
   --card-footer-padding: 1rem 1.5rem;
-  --card-footer-bg: var(--color-surface-secondary, #f8f9fa);
+  --card-footer-bg: var(--color-surface-secondary);
   --card-footer-border-top-width: 0.0625rem;
   --card-footer-border-top-style: solid;
-  --card-footer-border-top-color: var(--color-border, #dee2e6);
+  --card-footer-border-top-color: var(--color-border);
 }
 
 [data-card],
@@ -27,7 +27,7 @@
   flex-direction: column;
   gap: var(--card-gap);
   border-radius: var(--card-radius);
-  border: var(--card-border, 0.0625rem solid rgba(0, 0, 0, 0.08));
+  border: var(--card-border, 0.0625rem solid var(--color-border-subtle));
   background-color: var(--card-bg);
   text-align: var(--card-align, left);
 
@@ -99,7 +99,7 @@
 
   // Visible focus indicator with 3:1 minimum contrast (WCAG 2.4.7)
   &:focus-visible {
-    outline: 0.125rem solid var(--color-focus, #0066cc);
+    outline: 0.125rem solid var(--color-focus);
     outline-offset: 0.125rem;
   }
 

package/src/components/details/details.scss

@@ -1,5 +1,5 @@
 details {
-  --details-border: 0.0625rem solid #dfdfdf;
+  --details-border: 0.0625rem solid var(--color-border-subtle);
   --details-direction: column;
   --details-display: flex;
   --details-gap: 0rem;
@@ -33,7 +33,6 @@ details {
 
   @starting-style {
     transition: var(--summary-transitions);
-    color: red;
   }
 
   & + details {
@@ -77,7 +76,7 @@ details {
     &:focus-within {
       outline: none;
       border-bottom: solid 2px currentColor;
-      background-color: whitesmoke;
+      background-color: var(--color-surface-secondary);
     }
 
     /* This ensures no bullet points are shown */

package/src/components/dialog/dialog.scss

@@ -1,21 +1,21 @@
 :root {
   --dialog-min-width: max(20rem, 80%);
   --dialog-gap: 0.625rem;
-  --dialog-border-color: lightgray;
+  --dialog-border-color: var(--color-border);
   --dialog-border-width: thin;
   --dialog-border-style: solid;
   --dialog-border-radius: var(--border-radius);
   --dialog-padding: 1.5rem;
   --dialog-padding-inline: 1rem;
-  --dialog-close-color: gray;
+  --dialog-close-color: var(--color-text-secondary);
   --dialog-button-bg: transparent;
   --dialog-button-border: transparent thin solid;
-  --dialog-button-hover-bg: whitesmoke;
+  --dialog-button-hover-bg: var(--color-surface-secondary);
   --dialog-display: flex;
   --dialog-flex-direction: column;
 
   /* Focus and accessibility */
-  --dialog-focus-color: #0066cc;
+  --dialog-focus-color: var(--color-focus);
   --dialog-focus-width: 0.125rem;
   --dialog-focus-offset: 0.125rem;
   --dialog-focus-outline: var(--dialog-focus-width) solid var(--dialog-focus-color);

package/src/components/form/checkbox.scss

@@ -8,15 +8,15 @@
  * CSS Custom Properties:
  * - --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-disabled-color: Label color when disabled (default: var(--color-disabled-text))
  * - --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)
+ * - --color-required: Required indicator color (default: var(--color-required))
+ * - --checkbox-focus-ring-color: Focus ring color (default: var(--color-focus-ring))
  * - --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 (default: inherit)
- * - --checkbox-error-label-color: Label color when invalid (default: #dc2626)
+ * - --checkbox-error-label-color: Label color when invalid (default: var(--color-error-text))
  * - --checkbox-valid-label-color: Label color when valid (default: #16a34a)
  * - --checkbox-focus-radius: Focus outline border radius (default: 0.125rem)
  *
@@ -53,7 +53,7 @@ div:has(> input[type="checkbox"]) {
   &:has(> input:focus-visible) {
     .checkbox-label {
       outline: var(--checkbox-focus-ring-width, 0.125rem) solid
-        var(--checkbox-focus-ring-color, #2563eb);
+        var(--checkbox-focus-ring-color, var(--color-focus-ring));
       outline-offset: var(--checkbox-focus-ring-offset, 0.125rem);
       border-radius: var(--checkbox-focus-radius, 0.125rem);
     }
@@ -66,7 +66,7 @@ div:has(> input[type="checkbox"]) {
     cursor: not-allowed;
 
     .checkbox-label {
-      color: var(--checkbox-disabled-color, #6b7280);
+      color: var(--checkbox-disabled-color, var(--color-disabled-text));
       cursor: not-allowed;
     }
   }
@@ -75,7 +75,7 @@ div:has(> input[type="checkbox"]) {
   // Color alone is not sufficient - error message text must also be provided
   &:has(> input[aria-invalid="true"]) {
     .checkbox-label {
-      color: var(--checkbox-error-label-color, #dc2626);
+      color: var(--checkbox-error-label-color, var(--color-error-text));
     }
   }
 
@@ -104,7 +104,7 @@ div:has(> input[type="checkbox"]) {
   }
 
   .checkbox-required {
-    color: var(--color-required, #dc2626);
+    color: var(--color-required);
     font-weight: 600;
     margin-inline-start: 0.125rem;
   }

package/src/components/form/form.scss

@@ -2,7 +2,7 @@
 @use "./checkbox";
 
 :root {
-  --input-border-color: gray;
+  --input-border-color: var(--color-border);
   --input-appearance: none;
   --input-bg: inherit;
   --input-border: none;
@@ -18,12 +18,12 @@
   --input-focus-outline-offset: 0;
 
   // Disabled state variables (NEW)
-  --input-disabled-bg: #f5f5f5;
+  --input-disabled-bg: var(--color-disabled-bg);
   --input-disabled-opacity: 0.6;
   --input-disabled-cursor: not-allowed;
 
   // Placeholder variables
-  --placeholder-color: gray;
+  --placeholder-color: var(--color-text-tertiary);
   --placeholder-style: italic;
   --placeholder-fs: smaller;
 
@@ -43,9 +43,9 @@
      ========================================================================== */
 
   --checkbox-size: var(--checkbox-size-md);
-  --checkbox-bg: #ffffff;
-  --checkbox-border: 0.125rem solid #6b7280; /* 2px border */
-  --checkbox-border-color: #6b7280; /* Gray 500 */
+  --checkbox-bg: var(--color-surface);
+  --checkbox-border: 0.125rem solid var(--color-neutral-600); /* 2px border */
+  --checkbox-border-color: var(--color-neutral-600); /* Gray 500 */
   --checkbox-radius: 0.25rem; /* 4px */
   --checkbox-cursor: pointer;
   --checkbox-transition: all 0.2s cubic-bezier(0.4, 0, 0.2, 1);
@@ -54,8 +54,8 @@
      Checked State Properties
      ========================================================================== */
 
-  --checkbox-checked-outline-color: darkgreen;
-  --checkbox-checked-bg: green;
+  --checkbox-checked-outline-color: var(--color-success);
+  --checkbox-checked-bg: var(--color-success);
 }
 
 form {
@@ -83,7 +83,7 @@ input {
   padding-inline: var(--input-padding-inline);
   padding-block: var(--input-padding-block);
   border-radius: var(--input-radius);
-  background-color: var(--input-bg, #fff);
+  background-color: var(--input-bg, var(--color-surface));
 
   &:focus-visible,
   &:focus {
@@ -93,7 +93,7 @@ input {
 
   &[aria-disabled="true"],
   &:disabled {
-    --input-border-color: lightgray;
+    --input-border-color: var(--color-border-subtle);
     background-color: var(--input-disabled-bg);
     opacity: var(--input-disabled-opacity);
     cursor: var(--input-disabled-cursor);

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

@@ -407,7 +407,8 @@ export const CheckboxWithHint: Story = {
 /**
  * CheckboxCustomSize - Custom sized checkboxes using CSS variables
  *
- * Demonstrates responsive sizing via --checkbox-size variable.
+ * Demonstrates responsive sizing by overriding --checkbox-size and --checkbox-gap variables.
+ * Useful for contexts requiring larger touch targets or compact layouts.
  */
 export const CheckboxCustomSize: Story = {
   render: () => (
@@ -415,21 +416,33 @@ export const CheckboxCustomSize: Story = {
       <CheckboxComponent
         id="small"
         label="Small (1rem)"
-        styles={{ "--checkbox-gap": "0.375rem" } as React.CSSProperties}
+        styles={{
+          "--checkbox-size": "1rem",
+          "--checkbox-gap": "0.5rem",
+        } as React.CSSProperties}
       />
       <CheckboxComponent
         id="medium"
         label="Medium (1.25rem - default)"
+        styles={{
+          "--checkbox-gap": "0.5rem",
+        } as React.CSSProperties}
       />
       <CheckboxComponent
         id="large"
         label="Large (1.5rem)"
-        styles={{ "--checkbox-gap": "0.75rem" } as React.CSSProperties}
+        styles={{
+          "--checkbox-size": "1.5rem",
+          "--checkbox-gap": "0.625rem",
+        } as React.CSSProperties}
       />
       <CheckboxComponent
         id="xlarge"
         label="Extra Large (2rem)"
-        styles={{ "--checkbox-gap": "1rem" } as React.CSSProperties}
+        styles={{
+          "--checkbox-size": "2rem",
+          "--checkbox-gap": "0.75rem",
+        } as React.CSSProperties}
       />
     </div>
   ),

package/src/components/link/link.scss

@@ -14,7 +14,7 @@
 
 a[href] {
   // Color & Typography
-  --link-color: #085ab7;
+  --link-color: var(--color-link);
   --link-fw: 400;
   --link-fs: 1rem;
 

package/src/components/nav/nav.scss

@@ -22,7 +22,7 @@ body > nav,
       padding-inline: var(--nav-padding-inline, 0.75rem);
 
       &:hover {
-        background-color: var(--nav-hover-bg, #e8e8e8);
+        background-color: var(--nav-hover-bg, var(--color-surface-secondary));
       }
       &:hover:has(img, button) {
         background-color: transparent;

package/src/components/progress/progress.scss

@@ -3,8 +3,8 @@ progress {
   all: revert;
   --progress-width: 100%;
   --progress-height: 1rem;
-  --progress-bg: #cccccc;
-  --progress-color: rgb(71, 71, 245);
+  --progress-bg: var(--color-neutral-300);
+  --progress-color: var(--color-primary);
   --progress-accent-color: var(--progress-color);
 
   /* This code changes the color of the progress bar. */

package/src/components/tag/tag.scss

@@ -20,16 +20,16 @@ p[role='note'],
 small > span,
 [data-tag] {
   /* Variant color tokens - WCAG AA compliant colors */
-  --beta: #fbbf24;            /* Amber: 6.94:1 contrast with black */
-  --stable: #0f7c3e;          /* Dark green: 4.56:1 contrast with white */
-  --production: #1e3a8a;      /* Dark blue: 8.59:1 contrast with white */
+  --beta: var(--color-amber-400);            /* Amber: 6.94:1 contrast with black */
+  --stable: var(--color-green-700);          /* Dark green: 4.56:1 contrast with white */
+  --production: var(--color-blue-900);      /* Dark blue: 8.59:1 contrast with white */
 
   /* Tag component tokens */
   --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-bg: var(--color-neutral-300);           /* Default background color */
   --tag-fw: 500;                 /* Medium font weight */
   --tag-color: currentColor;     /* Default text color (inherits) */
   --tag-display: inline-block;   /* Display type */
@@ -65,7 +65,7 @@ small > span,
 
   /* Alpha variant - early development stage */
   &[data-tag~='alpha'] {
-    --tag-color: #000000;      /* Black: maximum contrast with amber background */
+    --tag-color: var(--color-neutral-900);      /* Black: maximum contrast with amber background */
     --tag-bg: var(--beta);
 
     /* Visual indicator beyond color - warning symbol */
@@ -79,7 +79,7 @@ small > span,
 
   /* Beta variant - pre-release version */
   &[data-tag~='beta'] {
-    --tag-color: #000000;      /* Black: maximum contrast with amber background */
+    --tag-color: var(--color-neutral-900);      /* Black: maximum contrast with amber background */
     --tag-bg: var(--beta);
 
     /* Visual indicator beyond color - warning symbol */
@@ -93,7 +93,7 @@ small > span,
 
   /* Stable variant - production-ready release */
   &[data-tag~='stable'] {
-    --tag-color: #ffffff;      /* White: 4.56:1 contrast with dark green */
+    --tag-color: var(--color-text-inverse);      /* White: 4.56:1 contrast with dark green */
     --tag-bg: var(--stable);
 
     /* Visual indicator beyond color - checkmark symbol */

package/src/components/text-to-speech/text-to-speech.scss

@@ -1,6 +1,6 @@
 [data-tts] {
   --tts-gap: 0.5rem;
-  --tts-bg: #fff;
+  --tts-bg: var(--color-surface);
   --tts-border-width: 0.125rem;
   --tts-border-style: solid;
   --tts-border-color: currentColor;

package/src/components/title/title.scss

@@ -37,10 +37,10 @@
   &[data-title~="2xl"] { --title-fs: var(--title-size-2xl); }
 
   /* Color variants - WCAG AA compliant (4.5:1 minimum) */
-  &[data-title~="primary"] { --title-color: #1e3a8a; }    /* 8.59:1 */
-  &[data-title~="secondary"] { --title-color: #4b5563; }  /* 7.56:1 */
-  &[data-title~="accent"] { --title-color: #7c3aed; }     /* 4.62:1 */
-  &[data-title~="muted"] { --title-color: #6b7280; }      /* 5.49:1 */
+  &[data-title~="primary"] { --title-color: var(--color-primary); }    /* 8.59:1 */
+  &[data-title~="secondary"] { --title-color: var(--color-text-secondary); }  /* 7.56:1 */
+  &[data-title~="accent"] { --title-color: var(--color-primary); }     /* 4.62:1 */
+  &[data-title~="muted"] { --title-color: var(--color-text-tertiary); }      /* 5.49:1 */
   &[data-title~="inherit"] { --title-color: inherit; }
 }
 

package/src/index.scss

@@ -1,10 +1,24 @@
+// ============================================
+// TOKENS - Foundation Layer (Tier 1 & 2)
+// Must load FIRST to be available to all components
+// ============================================
+@use "./sass/tokens";
+
+// ============================================
+// Base Styles
+// ============================================
 @use "./sass/reset";
 @use "./sass/layout";
 @use "./sass/type";
 @use "./sass/properties";
 @use "./sass/globals";
 @use "./sass/elements";
-@use "./styles/utilities/disabled";
+
+// ============================================
+// Utilities
+// Loaded after tokens, before components
+// ============================================
+@use "./sass/utilities";
 @use "./components/buttons/button.scss";
 @use "./components/tag/tag.scss";
 @use "./components/images/img.scss";

package/src/sass/_globals.scss

@@ -66,7 +66,7 @@ body {
     z-index: 100;
     transition: top 0.3s;
     border-radius: 0;
-    background-color: var(--color-skip-link-bg, #f5f5f5);
+    background-color: var(--color-skip-link-bg, var(--color-neutral-100));
     &:focus {
       top: 0;
     }
@@ -128,7 +128,7 @@ blockquote {
   --blockquote-padding: 1rem;
   --blockquote-border-width: 0.3125rem;
   --blockquote-border-style: solid;
-  --blockquote-border-color: var(--color-border, #d3d3d3);
+  --blockquote-border-color: var(--color-border);
   padding: var(--blockquote-padding);
   border-left: var(--blockquote-border-width) var(--blockquote-border-style) var(--blockquote-border-color);
 }
@@ -151,7 +151,7 @@ h6 {
 
 hr {
   --hr-border-width: 0.0625rem;
-  --hr-border-color: var(--color-border-subtle, #d3d3d3);
+  --hr-border-color: var(--color-border-subtle);
   --hr-margin-block: 1.5rem;
   --hr-border-style: solid;
   border: none;

package/src/sass/styles/_colors.scss

@@ -1,3 +1,19 @@
+/**
+ * DEPRECATED: This file is deprecated in favor of the new token system.
+ *
+ * Use tokens from src/sass/tokens/ instead:
+ * - Primitives: src/sass/tokens/_color-primitives.scss
+ * - Semantic: src/sass/tokens/_color-semantic.scss
+ *
+ * Use utility classes from src/sass/utilities/ for quick styling:
+ * - .text-primary, .text-success, .text-error, etc.
+ * - .bg-primary, .bg-success, .bg-error, etc.
+ * - .border-primary, .border-success, .border-error, etc.
+ *
+ * This file will be removed in v6.0.0
+ * Keeping for backward compatibility only.
+ */
+
 :root {
   --transparent: transparent;
 }