@pure-ds/core 0.6.9 → 0.6.11

package/src/js/pds-core/pds-generator.js

@@ -689,14 +689,16 @@ export class Generator {
     const validBase = Number.isFinite(Number(baseBorderWidth))
       ? Number(baseBorderWidth)
       : enums.BorderWidths.medium;
-    const toPx = (value) => `${Math.max(0, Math.round(value * 100) / 100)}px`;
+    // Snap to whole CSS pixels to avoid subpixel border widths that can render
+    // identically across browsers/DPIs (e.g. 0.5px and 1.5px both appearing as 1px).
+    const toRenderablePx = (value) => `${Math.max(1, Math.ceil(value))}px`;
 
     // Generate a derived border width scale based on configured base width
     return {
-      hairline: toPx(validBase * 0.25),
-      thin: toPx(validBase * 0.5),
-      medium: toPx(validBase),
-      thick: toPx(validBase * 1.5),
+      hairline: toRenderablePx(validBase * 0.25),
+      thin: toRenderablePx(validBase * 0.5),
+      medium: toRenderablePx(validBase),
+      thick: toRenderablePx(validBase * 1.5),
     };
   }
 
@@ -805,7 +807,6 @@ export class Generator {
 
   #generateLayoutTokens(layoutConfig) {
     const {
-      maxWidth = 1200,
       containerPadding = 16,
       breakpoints = {
         sm: 640,
@@ -815,10 +816,19 @@ export class Generator {
       },
     } = layoutConfig;
 
-    const resolvedMaxWidths = this.#resolveLayoutMaxWidths(layoutConfig);
+    const hasExplicitMaxWidth =
+      this.#hasDefinedConfigValue(layoutConfig, "maxWidth");
+
+    const explicitMaxWidthValue = layoutConfig.maxWidth;
+
+    const resolvedMaxWidths = this.#resolveLayoutMaxWidths(layoutConfig, {
+      emitFallbacks: false,
+    });
 
     return {
-      maxWidth: this.#formatLength(maxWidth, "1200px"),
+      maxWidth: hasExplicitMaxWidth
+        ? this.#formatLength(explicitMaxWidthValue, "1200px")
+        : undefined,
       maxWidthSm: resolvedMaxWidths.sm,
       maxWidthMd: resolvedMaxWidths.md,
       maxWidthLg: resolvedMaxWidths.lg,
@@ -841,7 +851,8 @@ export class Generator {
     };
   }
 
-  #resolveLayoutMaxWidths(layoutConfig = {}) {
+  #resolveLayoutMaxWidths(layoutConfig = {}, options = {}) {
+    const { emitFallbacks = true } = options;
     const defaultBreakpoints = {
       sm: 640,
       md: 768,
@@ -849,15 +860,29 @@ export class Generator {
       xl: 1280,
     };
 
-    const {
-      maxWidths = {},
-      maxWidth = 1200,
-      containerPadding = 16,
-      breakpoints = defaultBreakpoints,
-    } = layoutConfig || {};
+    const { maxWidths = {}, containerPadding = 16, breakpoints = defaultBreakpoints } =
+      layoutConfig || {};
+
+    const hasExplicitMaxWidth =
+      this.#hasDefinedConfigValue(layoutConfig, "maxWidth");
+
+    const hasExplicitMaxWidths = ["sm", "md", "lg", "xl"].some((key) =>
+      this.#hasDefinedConfigValue(maxWidths, key),
+    );
+
+    if (!emitFallbacks && !hasExplicitMaxWidth && !hasExplicitMaxWidths) {
+      return {
+        sm: undefined,
+        md: undefined,
+        lg: undefined,
+        xl: undefined,
+      };
+    }
+
+    const maxWidthValue = layoutConfig?.maxWidth;
 
     const paddingValue = this.#toNumber(containerPadding, 16);
-    const baseMaxWidth = this.#toNumber(maxWidth, defaultBreakpoints.xl);
+    const baseMaxWidth = this.#toNumber(maxWidthValue, defaultBreakpoints.xl);
 
     const resolvedBreakpoints = {
       sm: this.#toNumber(breakpoints.sm, defaultBreakpoints.sm),
@@ -888,6 +913,15 @@ export class Generator {
     };
   }
 
+  #hasDefinedConfigValue(source, key) {
+    if (!source || typeof source !== "object") return false;
+    if (!Object.prototype.hasOwnProperty.call(source, key)) return false;
+    const value = source[key];
+    if (value === undefined || value === null) return false;
+    if (typeof value === "string" && value.trim().length === 0) return false;
+    return true;
+  }
+
   #formatLength(value, fallback) {
     if (typeof value === "number" && Number.isFinite(value)) {
       return `${value}px`;
@@ -1186,6 +1220,10 @@ export class Generator {
       // Convert camelCase keys to kebab-case
       const kebabKey = key.replace(/([A-Z])/g, "-$1").toLowerCase();
 
+      if (value === undefined || value === null) {
+        return;
+      }
+
       // Skip breakpoints object - it's used in JS but doesn't belong in CSS variables
       // Breakpoints are used in @media queries, not as CSS custom properties
       if (key === "breakpoints") {
@@ -1279,7 +1317,7 @@ export class Generator {
       smartLines.push(`\n`);
     }
 
-    const semantic = `  --color-text-primary: var(--color-gray-100);\n  --color-text-secondary: var(--color-gray-300);\n  --color-text-muted: var(--color-gray-400);\n  --color-border: var(--color-gray-700);\n  --color-input-bg: var(--color-gray-800);\n  --color-input-disabled-bg: var(--color-gray-900);\n  --color-input-disabled-text: var(--color-gray-600);\n  --color-code-bg: var(--color-gray-800);\n`;
+    const semantic = `  --color-text-primary: var(--color-gray-100);\n  --color-text-secondary: var(--color-gray-300);\n  --color-text-muted: var(--color-gray-600);\n  --color-border: var(--color-gray-700);\n  --color-input-bg: var(--color-gray-800);\n  --color-input-disabled-bg: var(--color-gray-900);\n  --color-input-disabled-text: var(--color-gray-600);\n  --color-code-bg: var(--color-gray-800);\n`;
 
     const backdrop = `  /* Backdrop tokens - dark mode */\n  --backdrop-bg: linear-gradient(\n      135deg,\n      rgba(0, 0, 0, 0.6),\n      rgba(0, 0, 0, 0.4)\n    );\n  --backdrop-blur: 10px;\n  --backdrop-saturate: 120%;\n  --backdrop-brightness: 0.7;\n  --backdrop-filter: blur(var(--backdrop-blur)) saturate(var(--backdrop-saturate)) brightness(var(--backdrop-brightness));\n  --backdrop-opacity: 1;\n  \n  /* Legacy alias for backwards compatibility */\n  --backdrop-background: var(--backdrop-bg);\n`;
 
@@ -1377,7 +1415,7 @@ export class Generator {
     const semantic = [
       `    --color-text-primary: var(--color-gray-100);\n`,
       `    --color-text-secondary: var(--color-gray-300);\n`,
-      `    --color-text-muted: var(--color-gray-400);\n`,
+      `    --color-text-muted: var(--color-gray-600);\n`,
       `    --color-border: var(--color-gray-700);\n`,
       `    --color-input-bg: var(--color-gray-800);\n`,
       `    --color-input-disabled-bg: var(--color-gray-900);\n`,
@@ -1605,7 +1643,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient {
   border: var(--border-width-medium) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-primary-400),
       var(--color-accent-400)
@@ -1616,7 +1654,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-primary {
   border: var(--border-width-medium) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-primary-300),
       var(--color-primary-600)
@@ -1626,7 +1664,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-accent {
   border: var(--border-width-medium) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-accent-300),
       var(--color-accent-600)
@@ -1636,7 +1674,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-secondary {
   border: var(--border-width-medium) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-secondary-300),
       var(--color-secondary-600)
@@ -1647,7 +1685,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-soft {
   border: var(--border-width-thin) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-primary-400),
       var(--color-accent-400)
@@ -1657,7 +1695,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-medium {
   border: var(--border-width-medium) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-primary-400),
       var(--color-accent-400)
@@ -1667,7 +1705,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-strong {
   border: var(--border-width-thick) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(var(--gradient-angle, 135deg),
       var(--color-primary-400),
       var(--color-accent-400)
@@ -1691,7 +1729,7 @@ html[data-theme="dark"] .liquid-glass {
 .border-gradient-glow {
   border: var(--border-width-medium) solid transparent;
   background:
-    linear-gradient(var(--color-surface-base), var(--color-surface-base)) padding-box,
+    linear-gradient(var(--border-gradient-fill, var(--color-surface-base)), var(--border-gradient-fill, var(--color-surface-base))) padding-box,
     linear-gradient(135deg,
       var(--color-primary-400),
       var(--color-accent-400)
@@ -1945,7 +1983,7 @@ html[data-theme="dark"] .liquid-glass {
   #generateFormStyles() {
     const {
       shape = {},
-      gap,
+      spatialRhythm = {},
       inputPadding,
       buttonPadding,
       focusRingWidth,
@@ -1963,14 +2001,15 @@ html[data-theme="dark"] .liquid-glass {
           ? (enums.BorderWidths[shape.borderWidth] ?? null)
           : null;
 
-    const inputPaddingValue = inputPadding || 0.75;
-    const buttonPaddingValue = buttonPadding || 1.0;
+    const inputPaddingValue = spatialRhythm.inputPadding ?? inputPadding ?? 0.75;
+    const buttonPaddingValue =
+      spatialRhythm.buttonPadding ?? buttonPadding ?? 1.0;
     const focusWidth = focusRingWidth || 3;
     const borderWidth =
       borderWidthThin || shapeBorderWidth || enums.BorderWidths.thin;
-    const gapValue = gap || 1.0;
-    const sectionSpacingValue = sectionSpacing || 2.0;
-    const minButtonHeight = buttonMinHeight || 44;
+    const sectionSpacingValue =
+      spatialRhythm.sectionSpacing ?? sectionSpacing ?? 2.0;
+    const minButtonHeight = buttonMinHeight || 30;
     const minInputHeight = inputMinHeight || 40;
 
     return /*css*/ `/* Mobile-First Form Styles - Generated from Design Config */
@@ -2235,24 +2274,31 @@ input[type="range"]:active::-moz-range-thumb {
 
 input[type="color"] {
   -webkit-appearance: none;
+  appearance: none;
   padding: 0;
-  width: 3rem;
-  height: 3rem;
-  border-radius: 0.75rem; /* your radius */
-  overflow: hidden; /* important */
+  width: calc(var(--spacing-8) + var(--spacing-1));
+  height: calc(var(--spacing-8) + var(--spacing-1));
+  min-height: auto;
+  border-radius: var(--radius-sm);
+  border: var(--border-width-thin) solid var(--color-border);
+  overflow: hidden;
   cursor: pointer;
+  background: transparent;
 
-  /* The wrapper */
   &::-webkit-color-swatch-wrapper {
     padding: 0;
     border-radius: inherit;
   }
 
-  /* The swatch (the actual color box) */
   &::-webkit-color-swatch {
     border: none;
     border-radius: inherit;
   }
+
+  &::-moz-color-swatch {
+    border: none;
+    border-radius: inherit;
+  }
 }
 
 /* Button-style checkbox inputs outside of fieldsets */
@@ -2555,6 +2601,116 @@ label[data-toggle] {
   }
 }
 
+/* Color input enhancement shell - applied by enhanceColorInput on label[data-color] */
+label[data-color] {
+  display: grid;
+  gap: var(--spacing-2);
+
+  .color-control {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--spacing-3);
+    width: fit-content;
+    min-height: var(--input-min-height, 40px);
+    padding: var(--spacing-2) var(--spacing-3);
+    border: var(--border-width-thin) solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-surface-base);
+    color: var(--color-text-primary);
+    transition: border-color var(--transition-fast), box-shadow var(--transition-fast), background-color var(--transition-fast);
+  }
+
+  .color-control .color-swatch {
+    position: relative;
+    display: inline-flex;
+    width: calc(var(--spacing-8) + var(--spacing-1));
+    height: calc(var(--spacing-8) + var(--spacing-1));
+    border-radius: var(--radius-sm);
+  }
+
+  .color-control output {
+    margin: 0;
+    min-width: 8ch;
+    font-family: var(--font-family-mono);
+    font-size: var(--font-size-sm);
+    line-height: var(--font-line-height-tight);
+    color: var(--color-text-secondary);
+    text-transform: lowercase;
+  }
+
+  .color-control[data-unset="1"] output {
+    font-style: italic;
+    color: var(--color-text-muted);
+  }
+
+  .color-control input[type="color"] {
+    width: calc(var(--spacing-8) + var(--spacing-1));
+    height: calc(var(--spacing-8) + var(--spacing-1));
+    border-radius: var(--radius-sm);
+    border: var(--border-width-thin) solid var(--color-border);
+    background: transparent;
+    padding: 0;
+  }
+
+  .color-control input[type="color"]::-webkit-color-swatch {
+    border: none;
+    border-radius: calc(var(--radius-sm) - var(--border-width-thin));
+  }
+
+  .color-control input[type="color"]::-moz-color-swatch {
+    border: none;
+    border-radius: calc(var(--radius-sm) - var(--border-width-thin));
+  }
+
+  .color-control .color-swatch[data-unset="1"]::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    border-radius: var(--radius-sm);
+    border: var(--border-width-thin) solid var(--color-border);
+    background-color: color-mix(in oklab, var(--color-surface-subtle) 78%, var(--color-text-primary) 22%);
+    background-image:
+      linear-gradient(
+        45deg,
+        color-mix(in oklab, var(--color-surface-base) 88%, var(--color-text-primary) 12%) 25%,
+        transparent 25%,
+        transparent 75%,
+        color-mix(in oklab, var(--color-surface-base) 88%, var(--color-text-primary) 12%) 75%,
+        color-mix(in oklab, var(--color-surface-base) 88%, var(--color-text-primary) 12%)
+      ),
+      linear-gradient(
+        45deg,
+        color-mix(in oklab, var(--color-surface-base) 88%, var(--color-text-primary) 12%) 25%,
+        transparent 25%,
+        transparent 75%,
+        color-mix(in oklab, var(--color-surface-base) 88%, var(--color-text-primary) 12%) 75%,
+        color-mix(in oklab, var(--color-surface-base) 88%, var(--color-text-primary) 12%)
+      );
+    background-size: calc(var(--spacing-2) * 1.25) calc(var(--spacing-2) * 1.25);
+    background-position:
+      0 0,
+      calc(var(--spacing-2) * 0.625) calc(var(--spacing-2) * 0.625);
+    pointer-events: none;
+  }
+
+  .color-control .color-swatch[data-unset="1"] input[type="color"] {
+    opacity: 0;
+  }
+
+  &:focus-within .color-control {
+    border-color: var(--color-primary-500);
+    box-shadow: 0 0 0 ${focusWidth}px color-mix(in oklab, var(--color-primary-500) ${Math.round(
+      (focusRingOpacity || 0.3) * 100,
+    )}%, transparent);
+  }
+
+  &:has(input[type="color"]:disabled) .color-control {
+    background: var(--color-input-disabled-bg);
+    color: var(--color-input-disabled-text);
+    cursor: not-allowed;
+  }
+}
+
 input[type="file"] {
   padding: var(--spacing-2) var(--spacing-4);
   cursor: pointer;
@@ -2762,7 +2918,7 @@ a.btn-working {
   color: var(--color-text-secondary);
   padding: var(--spacing-6) var(--spacing-4);
   background-color: var(--color-surface-subtle);
-  max-width: var(--layout-max-width-md);
+  max-width: var(--layout-max-width-md, 736px);
   border-radius: var(--radius-md);
   nav {
     margin-top: var(--spacing-4);
@@ -3126,12 +3282,15 @@ tbody {
   overflow: hidden;
 
   &[open] {
+    overflow: visible;
+
     & > summary::after {
       transform: rotate(45deg);
     }
 
     &::details-content {
       block-size: auto;
+      overflow: visible;
     }
   }
 
@@ -3205,6 +3364,7 @@ tbody {
 
     &[open] > :not(summary) {
       grid-template-rows: 1fr;
+      overflow: visible;
     }
   }
 }
@@ -3508,6 +3668,12 @@ dialog.dialog-full { width: calc(100vw - var(--spacing-8)); max-width: calc(100v
   dialog, dialog::backdrop { transition-duration: 0.01s !important; }
 }
 
+html:has(dialog[open]:modal) {
+ overflow: hidden;
+ scrollbar-gutter: stable;
+}
+
+
 `;
   }
 
@@ -3651,9 +3817,8 @@ pds-tabstrip {
   }
 
   #generateIconStyles() {
-    const { a11y = {} } = this.options.design;
-    const minTouchTarget =
-      a11y.minTouchTarget || enums.TouchTargetSizes.standard;
+    const { layout = {} } = this.options.design;
+    const iconOnlySize = layout.buttonMinHeight || 30;
 
     return /*css*/ `/* Icon System */
 
@@ -3700,13 +3865,31 @@ button, a {
 
   &.icon-only {
     padding: var(--spacing-2);
-    min-width: ${minTouchTarget}px;
-    width: ${minTouchTarget}px;
-    height: ${minTouchTarget}px;
+    min-width: ${iconOnlySize}px;
+    width: ${iconOnlySize}px;
+    height: ${iconOnlySize}px;
     display: inline-flex;
     align-items: center;
     justify-content: center;
   }
+
+  &.btn-sm.icon-only {
+    min-width: calc(${iconOnlySize}px * 0.8);
+    width: calc(${iconOnlySize}px * 0.8);
+    height: calc(${iconOnlySize}px * 0.8);
+  }
+
+  &.btn-xs.icon-only {
+    min-width: calc(${iconOnlySize}px * 0.6);
+    width: calc(${iconOnlySize}px * 0.6);
+    height: calc(${iconOnlySize}px * 0.6);
+  }
+
+  &.btn-lg.icon-only {
+    min-width: calc(${iconOnlySize}px * 1.2);
+    width: calc(${iconOnlySize}px * 1.2);
+    height: calc(${iconOnlySize}px * 1.2);
+  }
 }
 
 /* Icon in inputs */
@@ -3757,17 +3940,16 @@ nav[data-dropdown] {
     max-width: none;
     max-inline-size: none;
     opacity: 0;
-    scale: 0.95;
     visibility: hidden;
     display: none;
     pointer-events: none;
     transform-origin: top center;
     z-index: var(--z-dropdown, 1050);
     max-height: min(60vh, 24rem);
+    overflow-x: hidden;
     overflow-y: auto;
     transition:
       opacity var(--dropdown-transition-duration) ease,
-      scale var(--dropdown-transition-duration) ease,
       visibility 0s linear var(--dropdown-transition-duration),
       display 0s linear var(--dropdown-transition-duration);
     transition-behavior: allow-discrete;
@@ -3776,12 +3958,10 @@ nav[data-dropdown] {
   & > :last-child[aria-hidden="false"] {
     display: inline-block;
     opacity: 1;
-    scale: 1;
     visibility: visible;
     pointer-events: auto;
     transition:
       opacity var(--dropdown-transition-duration) ease,
-      scale var(--dropdown-transition-duration) ease,
       visibility 0s linear 0s,
       display 0s linear 0s;
   }
@@ -3879,7 +4059,6 @@ nav[data-dropdown] {
 @starting-style {
   nav[data-dropdown] > :last-child[aria-hidden="false"] {
     opacity: 0;
-    scale: 0.95;
   }
 }
 `;
@@ -4108,7 +4287,7 @@ nav[data-dropdown] {
 /* Touch device optimizations */
 @media (hover: none) and (pointer: coarse) {
   /* Touch devices - larger touch targets for interactive elements */
-  button, a, select, textarea,
+  button:not(.icon-only), a:not(.icon-only), select, textarea,
   input:not([type="radio"]):not([type="checkbox"]) {
     min-height: ${minTouchTarget}px;
     min-width: ${minTouchTarget}px;
@@ -4795,39 +4974,48 @@ ${this.#generateBorderGradientUtilities()}
 
 .surface {
   background-color: var(--color-surface-base);
+  --border-gradient-fill: var(--color-surface-base);
 }
 
 .surface-subtle {
   background-color: var(--color-surface-subtle);
+  --border-gradient-fill: var(--color-surface-subtle);
 }
 
 .surface-elevated {
   background-color: var(--color-surface-elevated);
+  --border-gradient-fill: var(--color-surface-elevated);
 }
 
 .surface-sunken {
   background-color: var(--color-surface-sunken);
+  --border-gradient-fill: var(--color-surface-sunken);
 }
 
 .surface-overlay {
   background-color: var(--color-surface-overlay);
+  --border-gradient-fill: var(--color-surface-overlay);
 }
 
 /* Translucent semantic variants */
 .surface-translucent {
   background-color: var(--color-surface-translucent-50);
+  --border-gradient-fill: var(--color-surface-translucent-50);
 }
 
 .surface-translucent-25 {
   background-color: var(--color-surface-translucent-25);
+  --border-gradient-fill: var(--color-surface-translucent-25);
 }
 
 .surface-translucent-50 {
   background-color: var(--color-surface-translucent-50);
+  --border-gradient-fill: var(--color-surface-translucent-50);
 }
 
 .surface-translucent-75 {
   background-color: var(--color-surface-translucent-75);
+  --border-gradient-fill: var(--color-surface-translucent-75);
 }
 
 /* Legacy utility retained for backwards compatibility (opinionated overlay) */
@@ -4853,6 +5041,7 @@ ${this.#generateBorderGradientUtilities()}
 /* Surface-inverse visual properties (shared, uses smart surface tokens) */
 .surface-inverse {
   background-color: var(--color-surface-inverse);
+  --border-gradient-fill: var(--color-surface-inverse);
   color: var(--surface-inverse-text);
 
   pds-icon {
@@ -4876,7 +5065,7 @@ ${this.#generateBorderGradientUtilities()}
 html:not([data-theme="dark"]) .surface-inverse {
   --color-text-primary: var(--color-gray-100);
   --color-text-secondary: var(--color-gray-300);
-  --color-text-muted: var(--color-gray-400);
+  --color-text-muted: var(--color-gray-600);
   --color-border: var(--color-gray-700);
   --color-input-bg: var(--color-gray-800);
   --color-input-disabled-bg: var(--color-gray-900);
@@ -5326,6 +5515,8 @@ export const ${name}CSS = \`${escapedCSS}\`;
  */
 export function validateDesign(designConfig = {}, options = {}) {
   const MIN = Number(options.minContrast || 4.5);
+  const MIN_MUTED = Number(options.minMutedContrast || 3.0);
+  const EXTENDED = Boolean(options.extendedChecks);
 
   // Local helpers (keep public; no dependency on private Generator methods)
   const hexToRgb = (hex) => {
@@ -5366,10 +5557,20 @@ export function validateDesign(designConfig = {}, options = {}) {
     const light = {
       surfaceBg: c.surface?.base,
       surfaceText: c.gray?.[900] || "#000000",
+      surfaceTextSecondary: c.gray?.[700] || c.gray?.[800] || c.gray?.[900],
+      surfaceTextMuted: c.gray?.[500] || c.gray?.[600] || c.gray?.[700],
+      surfaceElevated: c.surface?.elevated || c.surface?.base,
       primaryFill: c.interactive?.light?.fill || c.primary?.[600],
       primaryText: c.interactive?.light?.text || c.primary?.[600],
+      accentFill: c.accent?.[600] || c.accent?.[500],
+      successFill: c.success?.[600] || c.success?.[500],
+      warningFill: c.warning?.[600] || c.warning?.[500],
+      dangerFill: c.danger?.[600] || c.danger?.[500],
+      infoFill: c.info?.[600] || c.info?.[500],
     };
 
+    const bestTextContrast = (bg) => Math.max(contrast(bg, "#ffffff"), contrast(bg, "#000000"));
+
     // Primary button (light): check button fill with white text
     const lightBtnRatio = contrast(light.primaryFill, "#ffffff");
     if (lightBtnRatio < MIN) {
@@ -5398,6 +5599,50 @@ export function validateDesign(designConfig = {}, options = {}) {
       });
     }
 
+    if (EXTENDED) {
+      // Secondary body text (light)
+      const lightSecondaryRatio = contrast(light.surfaceBg, light.surfaceTextSecondary);
+      if (lightSecondaryRatio < MIN) {
+        issues.push({
+          path: "/colors/secondary",
+          message: `Secondary text contrast on base surface (light) is too low (${lightSecondaryRatio.toFixed(
+            2,
+          )} < ${MIN}).`,
+          ratio: lightSecondaryRatio,
+          min: MIN,
+          context: "light/surface-text-secondary",
+        });
+      }
+
+      // Muted text should still be readable for helper text
+      const lightMutedRatio = contrast(light.surfaceBg, light.surfaceTextMuted);
+      if (lightMutedRatio < MIN_MUTED) {
+        issues.push({
+          path: "/colors/secondary",
+          message: `Muted text contrast on base surface (light) is too low (${lightMutedRatio.toFixed(
+            2,
+          )} < ${MIN_MUTED}).`,
+          ratio: lightMutedRatio,
+          min: MIN_MUTED,
+          context: "light/surface-text-muted",
+        });
+      }
+
+      // Elevated cards often dominate page UI; enforce readable default text
+      const elevatedTextRatio = contrast(light.surfaceElevated, light.surfaceText);
+      if (elevatedTextRatio < MIN) {
+        issues.push({
+          path: "/colors/background",
+          message: `Elevated surface text contrast (light) is too low (${elevatedTextRatio.toFixed(
+            2,
+          )} < ${MIN}).`,
+          ratio: elevatedTextRatio,
+          min: MIN,
+          context: "light/surface-elevated-text",
+        });
+      }
+    }
+
     // Primary text for outline/link: check link text on surface
     const lightOutlineRatio = contrast(light.primaryText, light.surfaceBg);
     if (lightOutlineRatio < MIN) {
@@ -5412,11 +5657,39 @@ export function validateDesign(designConfig = {}, options = {}) {
       });
     }
 
+    if (EXTENDED) {
+      // Semantic/accent fills must support readable foreground (white or black)
+      const semanticFills = [
+        { path: "/colors/accent", key: "accent", value: light.accentFill },
+        { path: "/colors/success", key: "success", value: light.successFill },
+        { path: "/colors/warning", key: "warning", value: light.warningFill },
+        { path: "/colors/danger", key: "danger", value: light.dangerFill },
+        { path: "/colors/info", key: "info", value: light.infoFill },
+      ];
+      semanticFills.forEach((entry) => {
+        if (!entry?.value) return;
+        const ratio = bestTextContrast(entry.value);
+        if (ratio < MIN) {
+          issues.push({
+            path: entry.path,
+            message: `${entry.key} fill color cannot achieve accessible text contrast (${ratio.toFixed(
+              2,
+            )} < ${MIN}) with either white or black text.`,
+            ratio,
+            min: MIN,
+            context: `light/${entry.key}-fill`,
+          });
+        }
+      });
+    }
+
     // Dark theme checks - use computed interactive tokens
     const d = c.dark;
     if (d) {
       const dark = {
         surfaceBg: d.surface?.base || c.surface?.inverse,
+        surfaceText: d.gray?.[50] || d.gray?.[100] || "#ffffff",
+        surfaceTextMuted: d.gray?.[300] || d.gray?.[400] || d.gray?.[500],
         primaryFill: c.interactive?.dark?.fill || d.primary?.[600],
         primaryText: c.interactive?.dark?.text || d.primary?.[600],
       };
@@ -5448,6 +5721,34 @@ export function validateDesign(designConfig = {}, options = {}) {
           context: "dark/outline",
         });
       }
+
+      if (EXTENDED) {
+        const darkTextRatio = contrast(dark.surfaceBg, dark.surfaceText);
+        if (darkTextRatio < MIN) {
+          issues.push({
+            path: "/colors/darkMode/background",
+            message: `Base text contrast on surface (dark) is too low (${darkTextRatio.toFixed(
+              2,
+            )} < ${MIN}).`,
+            ratio: darkTextRatio,
+            min: MIN,
+            context: "dark/surface-text",
+          });
+        }
+
+        const darkMutedRatio = contrast(dark.surfaceBg, dark.surfaceTextMuted);
+        if (darkMutedRatio < MIN_MUTED) {
+          issues.push({
+            path: "/colors/darkMode/secondary",
+            message: `Muted text contrast on surface (dark) is too low (${darkMutedRatio.toFixed(
+              2,
+            )} < ${MIN_MUTED}).`,
+            ratio: darkMutedRatio,
+            min: MIN_MUTED,
+            context: "dark/surface-text-muted",
+          });
+        }
+      }
     }
   } catch (err) {
     issues.push({