@pure-ds/storybook 0.4.16 → 0.4.19

package/public/assets/pds/styles/pds-utilities.css.js

@@ -16,102 +16,28 @@ pds-icon {
 }
 
 /* Icon size utilities */
-.icon-xs,
-pds-icon[size="xs"] {
-  width: var(--icon-size-xs);
-  height: var(--icon-size-xs);
-}
-
-.icon-sm,
-pds-icon[size="sm"] {
-  width: var(--icon-size-sm);
-  height: var(--icon-size-sm);
-}
-
-.icon-md,
-pds-icon[size="md"] {
-  width: var(--icon-size-md);
-  height: var(--icon-size-md);
-}
-
-.icon-lg,
-pds-icon[size="lg"] {
-  width: var(--icon-size-lg);
-  height: var(--icon-size-lg);
-}
-
-.icon-xl,
-pds-icon[size="xl"] {
-  width: var(--icon-size-xl);
-  height: var(--icon-size-xl);
-}
-
-.icon-2xl,
-pds-icon[size="2xl"] {
-  width: var(--icon-size-2xl);
-  height: var(--icon-size-2xl);
-}
+.icon-xs, pds-icon[size="xs"] { width: var(--icon-size-xs); height: var(--icon-size-xs); }
+.icon-sm, pds-icon[size="sm"] { width: var(--icon-size-sm); height: var(--icon-size-sm); }
+.icon-md, pds-icon[size="md"] { width: var(--icon-size-md); height: var(--icon-size-md); }
+.icon-lg, pds-icon[size="lg"] { width: var(--icon-size-lg); height: var(--icon-size-lg); }
+.icon-xl, pds-icon[size="xl"] { width: var(--icon-size-xl); height: var(--icon-size-xl); }
+.icon-2xl, pds-icon[size="2xl"] { width: var(--icon-size-2xl); height: var(--icon-size-2xl); }
 
 /* Icon color utilities */
-.icon-primary,
-pds-icon.primary {
-  color: var(--color-primary-600);
-}
-
-.icon-secondary,
-pds-icon.secondary {
-  color: var(--color-secondary-600);
-}
-
-.icon-accent,
-pds-icon.accent {
-  color: var(--color-accent-600);
-}
-
-.icon-success,
-pds-icon.success {
-  color: var(--color-success-600);
-}
-
-.icon-warning,
-pds-icon.warning {
-  color: var(--color-warning-600);
-}
-
-.icon-danger,
-pds-icon.danger {
-  color: var(--color-danger-600);
-}
-
-.icon-info,
-pds-icon.info {
-  color: var(--color-info-600);
-}
-
-.icon-muted,
-pds-icon.muted {
-  color: var(--color-text-muted);
-}
-
-.icon-subtle,
-pds-icon.subtle {
-  color: var(--color-text-subtle);
-}
+.icon-primary, pds-icon.primary { color: var(--color-primary-600); }
+.icon-secondary, pds-icon.secondary { color: var(--color-secondary-600); }
+.icon-accent, pds-icon.accent { color: var(--color-accent-600); }
+.icon-success, pds-icon.success { color: var(--color-success-600); }
+.icon-warning, pds-icon.warning { color: var(--color-warning-600); }
+.icon-danger, pds-icon.danger { color: var(--color-danger-600); }
+.icon-info, pds-icon.info { color: var(--color-info-600); }
+.icon-muted, pds-icon.muted { color: var(--color-text-muted); }
+.icon-subtle, pds-icon.subtle { color: var(--color-text-subtle); }
 
 /* Icon with text combinations */
-.icon-text {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--spacing-2);
-}
-
-.icon-text-start {
-  flex-direction: row;
-}
-
-.icon-text-end {
-  flex-direction: row-reverse;
-}
+.icon-text { display: inline-flex; align-items: center; gap: var(--spacing-2); }
+.icon-text-start { flex-direction: row; }
+.icon-text-end { flex-direction: row-reverse; }
 
 /* Button icon utilities */
 button, a {
@@ -131,46 +57,19 @@ button, a {
 }
 
 /* Icon in inputs */
-.input-icon {
+.input-icon, .input-icon-end {
   position: relative;
   display: flex;
   align-items: center;
-
-  pds-icon {
-    position: absolute;
-    left: var(--spacing-3);
-    color: var(--color-text-muted);
-    pointer-events: none;
-    width: var(--icon-size-md);
-    height: var(--icon-size-md);
-  }
-
-  input {
-    padding-left: calc(var(--icon-size-md) + var(--spacing-6));
-    width: 100%;
-  }
+  pds-icon { position: absolute; color: var(--color-text-muted); pointer-events: none; width: var(--icon-size-md); height: var(--icon-size-md); }
+}
+.input-icon {
+  pds-icon { left: var(--spacing-3); }
+  input { padding-left: calc(var(--icon-size-md) + var(--spacing-6)); width: 100%; }
 }
-
 .input-icon-end {
-  position: relative;
-  display: flex;
-  align-items: center;
-
-  pds-icon {
-    position: absolute;
-    left: unset;
-    right: var(--spacing-3);
-    color: var(--color-text-muted);
-    pointer-events: none;
-    width: var(--icon-size-md);
-    height: var(--icon-size-md);
-  }
-
-  input {
-    padding-left: var(--spacing-4);
-    padding-right: calc(var(--icon-size-md) + var(--spacing-6));
-    width: 100%;
-  }
+  pds-icon { left: unset; right: var(--spacing-3); }
+  input { padding-left: var(--spacing-4); padding-right: calc(var(--icon-size-md) + var(--spacing-6)); width: 100%; }
 }
 
 
@@ -209,44 +108,45 @@ button, a {
 .grid-auto-xl { grid-template-columns: repeat(auto-fit, minmax(450px, 1fr)); }
 
 /* Gap utilities */
-.gap-0 { gap: 0; }
-.gap-xs { gap: var(--spacing-1); }
-.gap-sm { gap: var(--spacing-2); }
-.gap-md { gap: var(--spacing-4); }
-.gap-lg { gap: var(--spacing-6); }
-.gap-xl { gap: var(--spacing-8); }
+.gap-0 { gap: 0; } .gap-xs { gap: var(--spacing-1); } .gap-sm { gap: var(--spacing-2); } .gap-md { gap: var(--spacing-4); } .gap-lg { gap: var(--spacing-6); } .gap-xl { gap: var(--spacing-8); }
 
 
 /* Flexbox System */
-.flex {
-  display: flex;
-}
+.flex { display: flex; }
+.flex-wrap { flex-wrap: wrap; }
+.flex-col { flex-direction: column; }
+.flex-row { flex-direction: row; }
+.grow { flex: 1 1 0%; }
 
-.flex-wrap {
-  flex-wrap: wrap;
-}
+/* Alignment utilities */
+.items-start { align-items: flex-start; } .items-center { align-items: center; } .items-end { align-items: flex-end; } .items-stretch { align-items: stretch; } .items-baseline { align-items: baseline; }
+.justify-start { justify-content: flex-start; } .justify-center { justify-content: center; } .justify-end { justify-content: flex-end; } .justify-between { justify-content: space-between; } .justify-around { justify-content: space-around; } .justify-evenly { justify-content: space-evenly; }
+.text-left { text-align: left; } .text-center { text-align: center; } .text-right { text-align: right; }
 
-.flex-col {
-  flex-direction: column;
+/* Text overflow utility */
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
-.flex-row {
-  flex-direction: row;
-}
+/* Max-width utilities */
+.max-w-sm { max-width: 400px; } .max-w-md { max-width: 600px; } .max-w-lg { max-width: 800px; } .max-w-xl { max-width: 1200px; }
 
-/* Flex alignment */
-.items-start { align-items: flex-start; }
-.items-center { align-items: center; }
-.items-end { align-items: flex-end; }
-.items-stretch { align-items: stretch; }
-.items-baseline { align-items: baseline; }
+/* Stack utilities - vertical rhythm for stacked elements */
+[class^="stack-"], [class*=" stack-"] {
+  display: flex;
+  flex-direction: column;
+}
+.stack-xs { gap: var(--spacing-1); }
+.stack-sm { gap: var(--spacing-2); }
+.stack-md { gap: var(--spacing-4); }
+.stack-lg { gap: var(--spacing-6); }
+.stack-xl { gap: var(--spacing-8); }
 
-.justify-start { justify-content: flex-start; }
-.justify-center { justify-content: center; }
-.justify-end { justify-content: flex-end; }
-.justify-between { justify-content: space-between; }
-.justify-around { justify-content: space-around; }
-.justify-evenly { justify-content: space-evenly; }
+/* Section spacing - for major content blocks */
+.section { padding-block: var(--spacing-8); }
+.section-lg { padding-block: var(--spacing-12); }
 
 /* Responsive helpers */
 @media (max-width: 767px) {
@@ -277,27 +177,9 @@ button, a {
 }
 
 /* Backdrop variants */
-.backdrop-light {
-  --backdrop-bg: linear-gradient(135deg, rgba(255, 255, 255, 0.3), rgba(255, 255, 255, 0.2));
-  --backdrop-brightness: 1.1;
-}
-
-.backdrop-dark {
-  --backdrop-bg: linear-gradient(135deg, rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.5));
-  --backdrop-brightness: 0.6;
-}
-
-.backdrop-blur-sm {
-  --backdrop-blur: 5px;
-}
-
-.backdrop-blur-md {
-  --backdrop-blur: 10px;
-}
-
-.backdrop-blur-lg {
-  --backdrop-blur: 20px;
-}
+.backdrop-light { --backdrop-bg: linear-gradient(135deg, rgba(255, 255, 255, 0.3), rgba(255, 255, 255, 0.2)); --backdrop-brightness: 1.1; }
+.backdrop-dark { --backdrop-bg: linear-gradient(135deg, rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.5)); --backdrop-brightness: 0.6; }
+.backdrop-blur-sm { --backdrop-blur: 5px; } .backdrop-blur-md { --backdrop-blur: 10px; } .backdrop-blur-lg { --backdrop-blur: 20px; }
 
 
 /* Optional utilities/features controlled by config options */
@@ -542,22 +424,101 @@ html[data-theme="dark"] .liquid-glass {
 }
 
 
-/* Inverse surface (dark) using PDS tokens; text/icons inherit currentColor */
+/* 
+ * SURFACE-INVERSE: Local Theme Context Flip
+ * 
+ * We can't simply add .surface-inverse to the dark mode selector because that would
+ * also apply the dark color PALETTE (grays, surfaces, etc.), which would override
+ * --color-surface-inverse itself. Instead, we duplicate only the SEMANTIC tokens.
+ * 
+ * Light theme .surface-inverse → dark semantic tokens
+ * Dark theme .surface-inverse  → light semantic tokens (flip back)
+ */
+
+/* Surface-inverse visual properties (shared, uses smart surface tokens) */
 .surface-inverse {
   background-color: var(--color-surface-inverse);
-  /* Ensure foregrounds inside use the correct smart-surface tokens */
   color: var(--surface-inverse-text);
-  --color-text-primary: var(--surface-inverse-text);
-  --color-text-secondary: var(--surface-inverse-text-secondary);
-  --color-text-muted: var(--surface-inverse-text-muted);
-  /* Ensure code/pre and other muted surfaces have contrast on inverse */
-  --color-surface-muted: rgba(255, 255, 255, 0.08);
-  /* Optional: adjust borders/shadows if utilities/components read these */
-  --color-border: var(--surface-inverse-border);
 
   pds-icon {
     color: var(--surface-inverse-icon);
   }
+  
+  /* btn-primary stays vibrant in any context */
+  & .btn-primary {
+    background-color: var(--color-primary-500);
+    border-color: var(--color-primary-500);
+    color: var(--color-primary-contrast, #ffffff);
+    
+    &:hover {
+      background-color: var(--color-primary-400);
+      border-color: var(--color-primary-400);
+    }
+  }
+}
+
+/* Light-mode inverse: apply dark semantic tokens */
+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-border: var(--color-gray-700);
+  --color-input-bg: var(--color-gray-800);
+  --color-input-disabled-bg: var(--color-gray-900);
+  --color-input-disabled-text: var(--color-gray-600);
+  --color-code-bg: var(--color-gray-800);
+  --color-surface-muted: rgba(255, 255, 255, 0.08);
+  
+  & button:not(.btn-primary):not(.btn-outline):not(.btn-danger):not(.btn-success):not(.btn-warning),
+  & .btn-secondary {
+    background-color: rgba(255, 255, 255, 0.12);
+    color: var(--surface-inverse-text);
+    border-color: rgba(255, 255, 255, 0.25);
+    
+    &:hover { background-color: rgba(255, 255, 255, 0.2); }
+    &:active { background-color: rgba(255, 255, 255, 0.28); }
+  }
+  
+  & select {
+    background-color: rgba(255, 255, 255, 0.1);
+    color: var(--surface-inverse-text);
+  }
+  
+  & a:not([class*="btn"]) {
+    color: var(--color-primary-300, #7dd3fc);
+  }
+}
+
+/* Dark-mode inverse: flip back to light semantic tokens */
+html[data-theme="dark"] .surface-inverse {
+  --color-text-primary: var(--color-gray-900);
+  --color-text-secondary: var(--color-gray-600);
+  --color-text-muted: var(--color-gray-600);
+  --color-border: var(--color-gray-300);
+  --color-input-bg: var(--color-surface-base);
+  --color-input-disabled-bg: var(--color-gray-50);
+  --color-input-disabled-text: var(--color-gray-500);
+  --color-code-bg: var(--color-gray-100);
+  --color-surface-muted: var(--color-gray-100);
+  
+  & button:not(.btn-primary):not(.btn-outline):not(.btn-danger):not(.btn-success):not(.btn-warning),
+  & .btn-secondary {
+    background-color: rgba(0, 0, 0, 0.06);
+    color: var(--surface-inverse-text);
+    border-color: rgba(0, 0, 0, 0.15);
+    
+    &:hover { background-color: rgba(0, 0, 0, 0.1); }
+    &:active { background-color: rgba(0, 0, 0, 0.15); }
+  }
+  
+  & select {
+    background-color: #ffffff;
+    color: var(--surface-inverse-text);
+  }
+  
+  & a:not([class*="btn"]) {
+    color: var(--color-primary-600, #0284c7);
+  }
 }
 
 /* Shadow utilities */
@@ -606,11 +567,7 @@ html[data-theme="dark"] .liquid-glass {
 }
 
 /* Responsive images with different radius sizes */
-.img-rounded-sm { border-radius: var(--radius-sm); }
-.img-rounded-md { border-radius: var(--radius-md); }
-.img-rounded-lg { border-radius: var(--radius-lg); }
-.img-rounded-xl { border-radius: var(--radius-xl); }
-.img-rounded-full { border-radius: var(--radius-full); }
+.img-rounded-sm { border-radius: var(--radius-sm); } .img-rounded-md { border-radius: var(--radius-md); } .img-rounded-lg { border-radius: var(--radius-lg); } .img-rounded-xl { border-radius: var(--radius-xl); } .img-rounded-full { border-radius: var(--radius-full); }
 
 /* Inline images */
 .img-inline {
@@ -642,37 +599,17 @@ html[data-theme="dark"] .liquid-glass {
 
 /* Small devices (640px and up) */
 @media (min-width: 640px) {
-  .sm\\:grid-cols-2 { grid-template-columns: repeat(2, 1fr); }
-  .sm\\:flex-row { flex-direction: row; }
-  .sm\\:text-sm { font-size: var(--font-size-sm); }
-  .sm\\:p-6 { padding: var(--spacing-6); }
-  .sm\\:gap-6 { gap: var(--spacing-6); }
-  .sm\\:hidden { display: none; }
-  .sm\\:block { display: block; }
+  .sm\\:grid-cols-2 { grid-template-columns: repeat(2, 1fr); } .sm\\:flex-row { flex-direction: row; } .sm\\:text-sm { font-size: var(--font-size-sm); } .sm\\:p-6 { padding: var(--spacing-6); } .sm\\:gap-6 { gap: var(--spacing-6); } .sm\\:hidden { display: none; } .sm\\:block { display: block; }
 }
 
 /* Medium devices (768px and up) */
 @media (min-width: 768px) {
-  .md\\:grid-cols-3 { grid-template-columns: repeat(3, 1fr); }
-  .md\\:text-lg { font-size: var(--font-size-lg); }
-  .md\\:p-8 { padding: var(--spacing-8); }
-  .md\\:gap-8 { gap: var(--spacing-8); }
-  .md\\:flex-row { flex-direction: row; }
-  .md\\:w-1\\/2 { width: 50%; }
-  .md\\:w-1\\/3 { width: 33.333333%; }
-  .md\\:hidden { display: none; }
-  .md\\:block { display: block; }
+  .md\\:grid-cols-3 { grid-template-columns: repeat(3, 1fr); } .md\\:text-lg { font-size: var(--font-size-lg); } .md\\:p-8 { padding: var(--spacing-8); } .md\\:gap-8 { gap: var(--spacing-8); } .md\\:flex-row { flex-direction: row; } .md\\:w-1\\/2 { width: 50%; } .md\\:w-1\\/3 { width: 33.333333%; } .md\\:hidden { display: none; } .md\\:block { display: block; }
 }
 
 /* Large devices (1024px and up) */
 @media (min-width: 1024px) {
-  .lg\\:grid-cols-4 { grid-template-columns: repeat(4, 1fr); }
-  .lg\\:text-xl { font-size: var(--font-size-xl); }
-  .lg\\:p-12 { padding: var(--spacing-12); }
-  .lg\\:gap-12 { gap: var(--spacing-12); }
-  .lg\\:w-1\\/4 { width: 25%; }
-  .lg\\:hidden { display: none; }
-  .lg\\:block { display: block; }
+  .lg\\:grid-cols-4 { grid-template-columns: repeat(4, 1fr); } .lg\\:text-xl { font-size: var(--font-size-xl); } .lg\\:p-12 { padding: var(--spacing-12); } .lg\\:gap-12 { gap: var(--spacing-12); } .lg\\:w-1\\/4 { width: 25%; } .lg\\:hidden { display: none; } .lg\\:block { display: block; }
 }
 
 /* Touch device optimizations */
@@ -781,102 +718,28 @@ pds-icon {
 }
 
 /* Icon size utilities */
-.icon-xs,
-pds-icon[size="xs"] {
-  width: var(--icon-size-xs);
-  height: var(--icon-size-xs);
-}
-
-.icon-sm,
-pds-icon[size="sm"] {
-  width: var(--icon-size-sm);
-  height: var(--icon-size-sm);
-}
-
-.icon-md,
-pds-icon[size="md"] {
-  width: var(--icon-size-md);
-  height: var(--icon-size-md);
-}
-
-.icon-lg,
-pds-icon[size="lg"] {
-  width: var(--icon-size-lg);
-  height: var(--icon-size-lg);
-}
-
-.icon-xl,
-pds-icon[size="xl"] {
-  width: var(--icon-size-xl);
-  height: var(--icon-size-xl);
-}
-
-.icon-2xl,
-pds-icon[size="2xl"] {
-  width: var(--icon-size-2xl);
-  height: var(--icon-size-2xl);
-}
+.icon-xs, pds-icon[size="xs"] { width: var(--icon-size-xs); height: var(--icon-size-xs); }
+.icon-sm, pds-icon[size="sm"] { width: var(--icon-size-sm); height: var(--icon-size-sm); }
+.icon-md, pds-icon[size="md"] { width: var(--icon-size-md); height: var(--icon-size-md); }
+.icon-lg, pds-icon[size="lg"] { width: var(--icon-size-lg); height: var(--icon-size-lg); }
+.icon-xl, pds-icon[size="xl"] { width: var(--icon-size-xl); height: var(--icon-size-xl); }
+.icon-2xl, pds-icon[size="2xl"] { width: var(--icon-size-2xl); height: var(--icon-size-2xl); }
 
 /* Icon color utilities */
-.icon-primary,
-pds-icon.primary {
-  color: var(--color-primary-600);
-}
-
-.icon-secondary,
-pds-icon.secondary {
-  color: var(--color-secondary-600);
-}
-
-.icon-accent,
-pds-icon.accent {
-  color: var(--color-accent-600);
-}
-
-.icon-success,
-pds-icon.success {
-  color: var(--color-success-600);
-}
-
-.icon-warning,
-pds-icon.warning {
-  color: var(--color-warning-600);
-}
-
-.icon-danger,
-pds-icon.danger {
-  color: var(--color-danger-600);
-}
-
-.icon-info,
-pds-icon.info {
-  color: var(--color-info-600);
-}
-
-.icon-muted,
-pds-icon.muted {
-  color: var(--color-text-muted);
-}
-
-.icon-subtle,
-pds-icon.subtle {
-  color: var(--color-text-subtle);
-}
+.icon-primary, pds-icon.primary { color: var(--color-primary-600); }
+.icon-secondary, pds-icon.secondary { color: var(--color-secondary-600); }
+.icon-accent, pds-icon.accent { color: var(--color-accent-600); }
+.icon-success, pds-icon.success { color: var(--color-success-600); }
+.icon-warning, pds-icon.warning { color: var(--color-warning-600); }
+.icon-danger, pds-icon.danger { color: var(--color-danger-600); }
+.icon-info, pds-icon.info { color: var(--color-info-600); }
+.icon-muted, pds-icon.muted { color: var(--color-text-muted); }
+.icon-subtle, pds-icon.subtle { color: var(--color-text-subtle); }
 
 /* Icon with text combinations */
-.icon-text {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--spacing-2);
-}
-
-.icon-text-start {
-  flex-direction: row;
-}
-
-.icon-text-end {
-  flex-direction: row-reverse;
-}
+.icon-text { display: inline-flex; align-items: center; gap: var(--spacing-2); }
+.icon-text-start { flex-direction: row; }
+.icon-text-end { flex-direction: row-reverse; }
 
 /* Button icon utilities */
 button, a {
@@ -896,46 +759,19 @@ button, a {
 }
 
 /* Icon in inputs */
-.input-icon {
+.input-icon, .input-icon-end {
   position: relative;
   display: flex;
   align-items: center;
-
-  pds-icon {
-    position: absolute;
-    left: var(--spacing-3);
-    color: var(--color-text-muted);
-    pointer-events: none;
-    width: var(--icon-size-md);
-    height: var(--icon-size-md);
-  }
-
-  input {
-    padding-left: calc(var(--icon-size-md) + var(--spacing-6));
-    width: 100%;
-  }
+  pds-icon { position: absolute; color: var(--color-text-muted); pointer-events: none; width: var(--icon-size-md); height: var(--icon-size-md); }
+}
+.input-icon {
+  pds-icon { left: var(--spacing-3); }
+  input { padding-left: calc(var(--icon-size-md) + var(--spacing-6)); width: 100%; }
 }
-
 .input-icon-end {
-  position: relative;
-  display: flex;
-  align-items: center;
-
-  pds-icon {
-    position: absolute;
-    left: unset;
-    right: var(--spacing-3);
-    color: var(--color-text-muted);
-    pointer-events: none;
-    width: var(--icon-size-md);
-    height: var(--icon-size-md);
-  }
-
-  input {
-    padding-left: var(--spacing-4);
-    padding-right: calc(var(--icon-size-md) + var(--spacing-6));
-    width: 100%;
-  }
+  pds-icon { left: unset; right: var(--spacing-3); }
+  input { padding-left: var(--spacing-4); padding-right: calc(var(--icon-size-md) + var(--spacing-6)); width: 100%; }
 }
 
 
@@ -974,44 +810,45 @@ button, a {
 .grid-auto-xl { grid-template-columns: repeat(auto-fit, minmax(450px, 1fr)); }
 
 /* Gap utilities */
-.gap-0 { gap: 0; }
-.gap-xs { gap: var(--spacing-1); }
-.gap-sm { gap: var(--spacing-2); }
-.gap-md { gap: var(--spacing-4); }
-.gap-lg { gap: var(--spacing-6); }
-.gap-xl { gap: var(--spacing-8); }
+.gap-0 { gap: 0; } .gap-xs { gap: var(--spacing-1); } .gap-sm { gap: var(--spacing-2); } .gap-md { gap: var(--spacing-4); } .gap-lg { gap: var(--spacing-6); } .gap-xl { gap: var(--spacing-8); }
 
 
 /* Flexbox System */
-.flex {
-  display: flex;
-}
+.flex { display: flex; }
+.flex-wrap { flex-wrap: wrap; }
+.flex-col { flex-direction: column; }
+.flex-row { flex-direction: row; }
+.grow { flex: 1 1 0%; }
 
-.flex-wrap {
-  flex-wrap: wrap;
-}
+/* Alignment utilities */
+.items-start { align-items: flex-start; } .items-center { align-items: center; } .items-end { align-items: flex-end; } .items-stretch { align-items: stretch; } .items-baseline { align-items: baseline; }
+.justify-start { justify-content: flex-start; } .justify-center { justify-content: center; } .justify-end { justify-content: flex-end; } .justify-between { justify-content: space-between; } .justify-around { justify-content: space-around; } .justify-evenly { justify-content: space-evenly; }
+.text-left { text-align: left; } .text-center { text-align: center; } .text-right { text-align: right; }
 
-.flex-col {
-  flex-direction: column;
+/* Text overflow utility */
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
 }
 
-.flex-row {
-  flex-direction: row;
-}
+/* Max-width utilities */
+.max-w-sm { max-width: 400px; } .max-w-md { max-width: 600px; } .max-w-lg { max-width: 800px; } .max-w-xl { max-width: 1200px; }
 
-/* Flex alignment */
-.items-start { align-items: flex-start; }
-.items-center { align-items: center; }
-.items-end { align-items: flex-end; }
-.items-stretch { align-items: stretch; }
-.items-baseline { align-items: baseline; }
+/* Stack utilities - vertical rhythm for stacked elements */
+[class^="stack-"], [class*=" stack-"] {
+  display: flex;
+  flex-direction: column;
+}
+.stack-xs { gap: var(--spacing-1); }
+.stack-sm { gap: var(--spacing-2); }
+.stack-md { gap: var(--spacing-4); }
+.stack-lg { gap: var(--spacing-6); }
+.stack-xl { gap: var(--spacing-8); }
 
-.justify-start { justify-content: flex-start; }
-.justify-center { justify-content: center; }
-.justify-end { justify-content: flex-end; }
-.justify-between { justify-content: space-between; }
-.justify-around { justify-content: space-around; }
-.justify-evenly { justify-content: space-evenly; }
+/* Section spacing - for major content blocks */
+.section { padding-block: var(--spacing-8); }
+.section-lg { padding-block: var(--spacing-12); }
 
 /* Responsive helpers */
 @media (max-width: 767px) {
@@ -1042,27 +879,9 @@ button, a {
 }
 
 /* Backdrop variants */
-.backdrop-light {
-  --backdrop-bg: linear-gradient(135deg, rgba(255, 255, 255, 0.3), rgba(255, 255, 255, 0.2));
-  --backdrop-brightness: 1.1;
-}
-
-.backdrop-dark {
-  --backdrop-bg: linear-gradient(135deg, rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.5));
-  --backdrop-brightness: 0.6;
-}
-
-.backdrop-blur-sm {
-  --backdrop-blur: 5px;
-}
-
-.backdrop-blur-md {
-  --backdrop-blur: 10px;
-}
-
-.backdrop-blur-lg {
-  --backdrop-blur: 20px;
-}
+.backdrop-light { --backdrop-bg: linear-gradient(135deg, rgba(255, 255, 255, 0.3), rgba(255, 255, 255, 0.2)); --backdrop-brightness: 1.1; }
+.backdrop-dark { --backdrop-bg: linear-gradient(135deg, rgba(0, 0, 0, 0.7), rgba(0, 0, 0, 0.5)); --backdrop-brightness: 0.6; }
+.backdrop-blur-sm { --backdrop-blur: 5px; } .backdrop-blur-md { --backdrop-blur: 10px; } .backdrop-blur-lg { --backdrop-blur: 20px; }
 
 
 /* Optional utilities/features controlled by config options */
@@ -1307,22 +1126,101 @@ html[data-theme="dark"] .liquid-glass {
 }
 
 
-/* Inverse surface (dark) using PDS tokens; text/icons inherit currentColor */
+/* 
+ * SURFACE-INVERSE: Local Theme Context Flip
+ * 
+ * We can't simply add .surface-inverse to the dark mode selector because that would
+ * also apply the dark color PALETTE (grays, surfaces, etc.), which would override
+ * --color-surface-inverse itself. Instead, we duplicate only the SEMANTIC tokens.
+ * 
+ * Light theme .surface-inverse → dark semantic tokens
+ * Dark theme .surface-inverse  → light semantic tokens (flip back)
+ */
+
+/* Surface-inverse visual properties (shared, uses smart surface tokens) */
 .surface-inverse {
   background-color: var(--color-surface-inverse);
-  /* Ensure foregrounds inside use the correct smart-surface tokens */
   color: var(--surface-inverse-text);
-  --color-text-primary: var(--surface-inverse-text);
-  --color-text-secondary: var(--surface-inverse-text-secondary);
-  --color-text-muted: var(--surface-inverse-text-muted);
-  /* Ensure code/pre and other muted surfaces have contrast on inverse */
-  --color-surface-muted: rgba(255, 255, 255, 0.08);
-  /* Optional: adjust borders/shadows if utilities/components read these */
-  --color-border: var(--surface-inverse-border);
 
   pds-icon {
     color: var(--surface-inverse-icon);
   }
+  
+  /* btn-primary stays vibrant in any context */
+  & .btn-primary {
+    background-color: var(--color-primary-500);
+    border-color: var(--color-primary-500);
+    color: var(--color-primary-contrast, #ffffff);
+    
+    &:hover {
+      background-color: var(--color-primary-400);
+      border-color: var(--color-primary-400);
+    }
+  }
+}
+
+/* Light-mode inverse: apply dark semantic tokens */
+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-border: var(--color-gray-700);
+  --color-input-bg: var(--color-gray-800);
+  --color-input-disabled-bg: var(--color-gray-900);
+  --color-input-disabled-text: var(--color-gray-600);
+  --color-code-bg: var(--color-gray-800);
+  --color-surface-muted: rgba(255, 255, 255, 0.08);
+  
+  & button:not(.btn-primary):not(.btn-outline):not(.btn-danger):not(.btn-success):not(.btn-warning),
+  & .btn-secondary {
+    background-color: rgba(255, 255, 255, 0.12);
+    color: var(--surface-inverse-text);
+    border-color: rgba(255, 255, 255, 0.25);
+    
+    &:hover { background-color: rgba(255, 255, 255, 0.2); }
+    &:active { background-color: rgba(255, 255, 255, 0.28); }
+  }
+  
+  & select {
+    background-color: rgba(255, 255, 255, 0.1);
+    color: var(--surface-inverse-text);
+  }
+  
+  & a:not([class*="btn"]) {
+    color: var(--color-primary-300, #7dd3fc);
+  }
+}
+
+/* Dark-mode inverse: flip back to light semantic tokens */
+html[data-theme="dark"] .surface-inverse {
+  --color-text-primary: var(--color-gray-900);
+  --color-text-secondary: var(--color-gray-600);
+  --color-text-muted: var(--color-gray-600);
+  --color-border: var(--color-gray-300);
+  --color-input-bg: var(--color-surface-base);
+  --color-input-disabled-bg: var(--color-gray-50);
+  --color-input-disabled-text: var(--color-gray-500);
+  --color-code-bg: var(--color-gray-100);
+  --color-surface-muted: var(--color-gray-100);
+  
+  & button:not(.btn-primary):not(.btn-outline):not(.btn-danger):not(.btn-success):not(.btn-warning),
+  & .btn-secondary {
+    background-color: rgba(0, 0, 0, 0.06);
+    color: var(--surface-inverse-text);
+    border-color: rgba(0, 0, 0, 0.15);
+    
+    &:hover { background-color: rgba(0, 0, 0, 0.1); }
+    &:active { background-color: rgba(0, 0, 0, 0.15); }
+  }
+  
+  & select {
+    background-color: #ffffff;
+    color: var(--surface-inverse-text);
+  }
+  
+  & a:not([class*="btn"]) {
+    color: var(--color-primary-600, #0284c7);
+  }
 }
 
 /* Shadow utilities */
@@ -1371,11 +1269,7 @@ html[data-theme="dark"] .liquid-glass {
 }
 
 /* Responsive images with different radius sizes */
-.img-rounded-sm { border-radius: var(--radius-sm); }
-.img-rounded-md { border-radius: var(--radius-md); }
-.img-rounded-lg { border-radius: var(--radius-lg); }
-.img-rounded-xl { border-radius: var(--radius-xl); }
-.img-rounded-full { border-radius: var(--radius-full); }
+.img-rounded-sm { border-radius: var(--radius-sm); } .img-rounded-md { border-radius: var(--radius-md); } .img-rounded-lg { border-radius: var(--radius-lg); } .img-rounded-xl { border-radius: var(--radius-xl); } .img-rounded-full { border-radius: var(--radius-full); }
 
 /* Inline images */
 .img-inline {
@@ -1407,37 +1301,17 @@ html[data-theme="dark"] .liquid-glass {
 
 /* Small devices (640px and up) */
 @media (min-width: 640px) {
-  .sm\\:grid-cols-2 { grid-template-columns: repeat(2, 1fr); }
-  .sm\\:flex-row { flex-direction: row; }
-  .sm\\:text-sm { font-size: var(--font-size-sm); }
-  .sm\\:p-6 { padding: var(--spacing-6); }
-  .sm\\:gap-6 { gap: var(--spacing-6); }
-  .sm\\:hidden { display: none; }
-  .sm\\:block { display: block; }
+  .sm\\:grid-cols-2 { grid-template-columns: repeat(2, 1fr); } .sm\\:flex-row { flex-direction: row; } .sm\\:text-sm { font-size: var(--font-size-sm); } .sm\\:p-6 { padding: var(--spacing-6); } .sm\\:gap-6 { gap: var(--spacing-6); } .sm\\:hidden { display: none; } .sm\\:block { display: block; }
 }
 
 /* Medium devices (768px and up) */
 @media (min-width: 768px) {
-  .md\\:grid-cols-3 { grid-template-columns: repeat(3, 1fr); }
-  .md\\:text-lg { font-size: var(--font-size-lg); }
-  .md\\:p-8 { padding: var(--spacing-8); }
-  .md\\:gap-8 { gap: var(--spacing-8); }
-  .md\\:flex-row { flex-direction: row; }
-  .md\\:w-1\\/2 { width: 50%; }
-  .md\\:w-1\\/3 { width: 33.333333%; }
-  .md\\:hidden { display: none; }
-  .md\\:block { display: block; }
+  .md\\:grid-cols-3 { grid-template-columns: repeat(3, 1fr); } .md\\:text-lg { font-size: var(--font-size-lg); } .md\\:p-8 { padding: var(--spacing-8); } .md\\:gap-8 { gap: var(--spacing-8); } .md\\:flex-row { flex-direction: row; } .md\\:w-1\\/2 { width: 50%; } .md\\:w-1\\/3 { width: 33.333333%; } .md\\:hidden { display: none; } .md\\:block { display: block; }
 }
 
 /* Large devices (1024px and up) */
 @media (min-width: 1024px) {
-  .lg\\:grid-cols-4 { grid-template-columns: repeat(4, 1fr); }
-  .lg\\:text-xl { font-size: var(--font-size-xl); }
-  .lg\\:p-12 { padding: var(--spacing-12); }
-  .lg\\:gap-12 { gap: var(--spacing-12); }
-  .lg\\:w-1\\/4 { width: 25%; }
-  .lg\\:hidden { display: none; }
-  .lg\\:block { display: block; }
+  .lg\\:grid-cols-4 { grid-template-columns: repeat(4, 1fr); } .lg\\:text-xl { font-size: var(--font-size-xl); } .lg\\:p-12 { padding: var(--spacing-12); } .lg\\:gap-12 { gap: var(--spacing-12); } .lg\\:w-1\\/4 { width: 25%; } .lg\\:hidden { display: none; } .lg\\:block { display: block; }
 }
 
 /* Touch device optimizations */