@pure-ds/storybook 0.7.25 → 0.7.26

package/stories/foundations/Typography.stories.js

@@ -31,7 +31,12 @@ export default {
 export const HeadingScale = {
   name: "Heading Scale",
   render: () => html`
-    
+    <header>
+      <h3>Heading Scale</h3>
+      <small class="text-muted">
+        Compare semantic heading levels and their default tokenized sizes.
+      </small>
+    </header>
     <div class="stack-sm story-heading-container">
       <h1>Heading Level 1</h1>
       <p class="text-muted story-heading-description">
@@ -69,7 +74,12 @@ export const HeadingScale = {
 export const TextStyles = {
   name: "Text Styles & Weights",
   render: () => html`
-    
+    <header>
+      <h3>Text Styles & Weights</h3>
+      <small class="text-muted">
+        Review font-weight and inline text semantics for UI copy.
+      </small>
+    </header>
     <div class="stack-sm">
       <h2>Font Weights</h2>
       <div class="stack-sm story-weights-section">
@@ -102,7 +112,12 @@ export const TextStyles = {
 export const LineHeights = {
   name: "Line Heights & Readability",
   render: () => html`
-    
+    <header>
+      <h3>Line Heights & Readability</h3>
+      <small class="text-muted">
+        See how leading affects scanning and long-form readability.
+      </small>
+    </header>
     <div class="stack-lg story-line-height-container">
       <h2>Tight Line Height (1.25)</h2>
       <p class="story-leading-tight story-line-height-example">
@@ -143,113 +158,15 @@ export const LineHeights = {
   `,
 };
 
-export const ArticleLayout = {
-  name: "Article Layout",
-  render: () => html`
-    <article>
-      <header>
-        <div class="text-muted story-article-meta">Design Systems</div>
-        <h1>Building Scalable Design Systems for Modern Web Applications</h1>
-        <small class="text-muted"
-          >By Sarah Chen • November 17, 2025 • 8 min read</small
-        >
-      </header>
-
-      <p>
-        <strong>
-        A design system is more than a component library—it's a shared language
-        that bridges design and development, ensuring consistency and quality
-        across your entire product ecosystem.
-        </strong>
-      </p>
-
-      <p>
-        In today's fast-paced development environment, maintaining visual and
-        functional consistency across multiple products and teams is
-        increasingly challenging. Design systems have emerged as the solution,
-        providing a single source of truth for design decisions, component
-        patterns, and implementation guidelines.
-      </p>
-
-      <section>
-        <h2>Key Components of a Design System</h2>
-
-        <p>
-          A comprehensive design system consists of several interconnected
-          layers, each serving a specific purpose in the overall architecture:
-        </p>
-
-        <ul>
-          <li>
-            <strong>Design Tokens:</strong> The foundational layer defining
-            colors, typography, spacing, and other atomic values
-          </li>
-          <li>
-            <strong>Component Library:</strong> Reusable UI components built
-            with consistent patterns
-          </li>
-          <li>
-            <strong>Documentation:</strong> Clear guidelines on when and how to
-            use each component
-          </li>
-          <li>
-            <strong>Tools & Resources:</strong> Figma libraries, code templates,
-            and development tools
-          </li>
-        </ul>
-
-        <blockquote>
-          <p>
-            A design system isn't a project. It's a product serving products.
-          </p>
-          <cite>Nathan Curtis, Design Systems Expert</cite>
-        </blockquote>
-      </section>
-
-      <h3>Getting Started with Design Tokens</h3>
-
-      <p>
-        Design tokens are the DNA of your design system. These named values
-        represent design decisions that can be shared across platforms and
-        technologies. For example, instead of hardcoding
-        <code>#0066cc</code>, you define <code>--color-primary</code> which can
-        be updated globally.
-      </p>
-
-      <section>
-        <h4 class="story-impl-heading">Implementation Example</h4>
-        <pre
-          class="surface-base story-code-block"
-        ><code>/* Design tokens in CSS */
-:root {
-  --color-primary: #0066cc;
-  --spacing-unit: 4px;
-  --font-family-base: system-ui, sans-serif;
-  --border-radius-md: 8px;
-}</code></pre>
-
-        <p>
-          By adopting this approach, you create a flexible foundation that can
-          evolve with your product needs while maintaining consistency across
-          all touchpoints.
-        </p>
-      </section>
-
-      <footer>
-        <div class="flex gap-md flex-wrap">
-          <span class="badge badge-outline badge-primary">Design Systems</span>
-          <span class="badge badge-outline badge-primary">Web Components</span>
-          <span class="badge badge-outline badge-primary">CSS Architecture</span>
-        </div>
-      </footer>
-    </article>
-  `,
-};
-
 export const UIComponents = {
   name: "UI Component Text",
   render: () => html`
-    
+    <header>
+      <h3>UI Component Text</h3>
+      <small class="text-muted">
+        Typical microcopy patterns for forms, labels, and status messaging.
+      </small>
+    </header>
     <div class="stack-sm">
       <h2>Form Labels & Help Text</h2>
       <div class="story-form-wrapper">
@@ -325,7 +242,12 @@ export const UIComponents = {
 export const DataDisplay = {
   name: "Data Display & Lists",
   render: () => html`
-    
+    <header>
+      <h3>Data Display & Lists</h3>
+      <small class="text-muted">
+        Text hierarchy patterns for lists, metrics, and timeline content.
+      </small>
+    </header>
     <div class="stack-lg">
       <h2>User List with Metadata</h2>
       <div class="card">

package/stories/foundations/ZIndex.stories.js

@@ -85,7 +85,7 @@ export const ZIndexScale = {
     ${zIndexStoryStyles}
     <section class="stack-lg max-w-5xl">
       <header>
-        <h2>Z-Index Token Scale</h2>
+        <h3>Z-Index Token Scale</h3>
         <small class="text-muted">
           Tokens are organized from lowest to highest z-index values, ensuring proper stacking of UI layers.
         </small>
@@ -161,7 +161,7 @@ export const VisualDemo = {
     ${zIndexStoryStyles}
     <section class="stack-lg max-w-5xl">
       <header>
-        <h2>Interactive Stacking Example</h2>
+        <h3>Interactive Stacking Example</h3>
         <small class="text-muted">
           This demo shows how different z-index tokens create proper layering. 
           Lower elements appear behind higher ones.
@@ -227,7 +227,7 @@ export const UsageExamples = {
     ${zIndexStoryStyles}
     <section class="stack-lg max-w-5xl">
       <header>
-        <h2>Code Examples</h2>
+        <h3>Code Examples</h3>
         <small class="text-muted">
           How to use z-index tokens in your components and styles.
         </small>

package/stories/layout/LayoutOverview.stories.js

@@ -100,10 +100,10 @@ export const LayoutIntroduction = () => {
     </style>
     ${layoutOverviewStyles.strings[0]}
     <header>
-      <h1>Layout in PDS</h1>
-      <h4 class="text-muted">
+      <h3>Layout in PDS</h3>
+      <small class="text-muted">
         Power through composition of high-level concepts, not atomic control.
-      </h4>
+      </small>
     </header>
 
     <article class="card surface-translucent-75">

package/stories/layout/LayoutSystem.stories.js

@@ -38,6 +38,10 @@ export default {
 
 export const Container = () => html`
   ${layoutSystemStyles}
+  <header class="card">
+    <h3>Container</h3>
+    <small class="text-muted">Center content with consistent horizontal padding and max-width constraints.</small>
+  </header>
   <div class="card surface-subtle story-demo-area-sm">
     <p class="text-muted text-center">
       Gray background shows viewport width. Container centers content with
@@ -85,7 +89,7 @@ Container.storyName = "Container";
 export const GridFixed = () => html`
   ${layoutSystemStyles}
   <header>
-    <h2>Fixed Column Grids</h2>
+    <h3>Fixed Column Grids</h3>
     <small class="text-muted">Explicit column counts for predictable layouts.</small>
   </header>
 
@@ -142,7 +146,7 @@ GridFixed.storyName = "Grid: Fixed Columns";
 export const GridAuto = () => html`
   ${layoutSystemStyles}
   <header class="card">
-    <h2>Auto-Fit Responsive Grids</h2>
+    <h3>Auto-Fit Responsive Grids</h3>
     <small class="text-muted">
       Automatically adjust columns based on available space. Resize the browser
       to see the effect.
@@ -206,7 +210,7 @@ GridAuto.storyName = "Grid: Auto-Fit";
 export const FlexBasics = () => html`
   ${layoutSystemStyles}
   <header class="card">
-    <h2>Flexbox Utilities</h2>
+    <h3>Flexbox Utilities</h3>
     <small class="text-muted">
       Compose layouts with <code>.flex</code> + modifiers.
     </small>
@@ -257,7 +261,7 @@ FlexBasics.storyName = "Flex: Basics";
 export const FlexAlignment = () => html`
   ${layoutSystemStyles}
   <header class="card">
-    <h2>Alignment Utilities</h2>
+    <h3>Alignment Utilities</h3>
     <small class="text-muted">
       Cross-axis: <code>.items-*</code> | Main-axis: <code>.justify-*</code>
     </small>
@@ -318,7 +322,7 @@ FlexAlignment.storyName = "Flex: Alignment";
 export const Stack = () => html`
   ${layoutSystemStyles}
   <header>
-    <h2>Stack Utilities</h2>
+    <h3>Stack Utilities</h3>
     <small class="text-muted">
       Vertical layouts with consistent spacing.
       <code>.stack-*</code> = <code>.flex .flex-col .gap-*</code> in one class.
@@ -374,7 +378,7 @@ Stack.storyName = "Stack";
 export const Gap = () => html`
   ${layoutSystemStyles}
   <header>
-    <h2>Gap Utilities</h2>
+    <h3>Gap Utilities</h3>
     <small class="text-muted">Control spacing between flex/grid children.</small>
   </header>
 
@@ -415,7 +419,7 @@ Gap.storyName = "Gap";
 export const MaxWidth = () => html`
   ${layoutSystemStyles}
   <header class="card stack-sm">
-    <h2>Max-Width Utilities</h2>
+    <h3>Max-Width Utilities</h3>
     <small class="text-muted">
       Each utility maps to a <code>--layout-max-width-*</code> token that is paired with the
       matching breakpoint token (for example <code>--breakpoint-sm</code>). Updating
@@ -487,7 +491,7 @@ MaxWidth.storyName = "Max-Width";
 export const Section = () => html`
   ${layoutSystemStyles}
   <header>
-    <h2>Section Spacing</h2>
+    <h3>Section Spacing</h3>
     <small class="text-muted">Vertical padding for major content blocks.</small>
   </header>
 
@@ -514,9 +518,10 @@ Section.storyName = "Section";
 
 export const Responsive = () => html`
   ${layoutSystemStyles}
-  <div class="card">
-    <h2>Responsive Utilities</h2>
-  </div>
+  <header class="card">
+    <h3>Responsive Utilities</h3>
+    <small class="text-muted">Responsive helpers that adapt layout behavior across breakpoints.</small>
+  </header>
 
   <div class="card">
     <h3>.mobile-stack</h3>
@@ -560,9 +565,10 @@ Responsive.storyName = "Responsive";
 
 export const TextUtilities = () => html`
   ${layoutSystemStyles}
-  <div class="card">
-    <h2>Text Utilities</h2>
-  </div>
+  <header class="card">
+    <h3>Text Utilities</h3>
+    <small class="text-muted">Helpers for alignment and overflow handling in content layouts.</small>
+  </header>
 
   <div class="card">
     <h3>Text Alignment</h3>
@@ -603,10 +609,10 @@ TextUtilities.storyName = "Text";
 
 export const Reference = () => html`
   ${layoutSystemStyles}
-  <div class="card">
-    <h2>Complete Layout Reference</h2>
-    <p class="text-muted">All layout utilities in PDS.</p>
-  </div>
+  <header class="card">
+    <h3>Complete Layout Reference</h3>
+    <small class="text-muted">All layout utilities in PDS.</small>
+  </header>
 
   <table class="table-bordered table-compact">
     <thead>

package/stories/patterns/BorderEffects.stories.js

@@ -16,27 +16,39 @@ export default {
 };
 
 export const BorderGradient = () => html`
-  <div class="grid grid-auto-sm gap-md">
-    <div class="card border-gradient">
-      <h3>Gradient Border</h3>
-      <p>Animated gradient border effect that follows the primary color scheme.</p>
-    </div>
-    <div class="card border-gradient" style="--gradient-angle: 45deg;">
-      <h3>Custom Angle</h3>
-      <p>Use CSS variables to customize the gradient direction.</p>
+  <div class="stack-md">
+    <header>
+      <h3>Border Gradient</h3>
+      <small class="text-muted">Animated gradient border treatments for emphasis and visual hierarchy.</small>
+    </header>
+    <div class="grid grid-auto-sm gap-md">
+      <div class="card border-gradient">
+        <h4>Gradient Border</h4>
+        <p>Animated gradient border effect that follows the primary color scheme.</p>
+      </div>
+      <div class="card border-gradient" style="--gradient-angle: 45deg;">
+        <h4>Custom Angle</h4>
+        <p>Use CSS variables to customize the gradient direction.</p>
+      </div>
     </div>
   </div>
 `;
 
 export const BorderGlow = () => html`
-  <div class="grid grid-auto-sm gap-md">
-    <div class="card border-glow">
-      <h3>Glowing Border</h3>
-      <p>Subtle glow effect.</p>
-    </div>
-    <div class="card border-glow border-gradient">
-      <h3>Glow + Gradient</h3>
-      <p>Combined glow and gradient border effects.</p>
+  <div class="stack-md">
+    <header>
+      <h3>Border Glow</h3>
+      <small class="text-muted">Soft glow borders that add depth to highlighted surfaces.</small>
+    </header>
+    <div class="grid grid-auto-sm gap-md">
+      <div class="card border-glow">
+        <h4>Glowing Border</h4>
+        <p>Subtle glow effect.</p>
+      </div>
+      <div class="card border-glow border-gradient">
+        <h4>Glow + Gradient</h4>
+        <p>Combined glow and gradient border effects.</p>
+      </div>
     </div>
   </div>
 `;

package/stories/patterns/InteractiveStates.stories.js

@@ -84,11 +84,13 @@ export default {
 
 export const FocusStates = () => html`
   <div class="card">
-    <h2>Focus States</h2>
-    <p>
+    <header>
+      <h3>Focus States</h3>
+      <small class="text-muted">
       Press <kbd>Tab</kbd> to navigate and see focus rings on interactive
       elements
-    </p>
+      </small>
+    </header>
 
     <div class="flex flex-wrap gap-sm align-center">
       <button class="btn-primary">Button 1</button>
@@ -148,8 +150,10 @@ FocusStates.storyName = "Focus States";
 
 export const HoverStates = () => html`
   <div class="card">
-    <h2>Hover States</h2>
-    <p>Hover over elements to see smooth transitions and state changes</p>
+    <header>
+      <h3>Hover States</h3>
+      <small class="text-muted">Hover over elements to see smooth transitions and state changes.</small>
+    </header>
 
     <h3>Buttons</h3>
     <div class="flex flex-wrap gap-sm">
@@ -210,8 +214,10 @@ HoverStates.storyName = "Hover States";
 
 export const ActiveStates = () => html`
   <div class="card">
-    <h2>Active States</h2>
-    <p>Click and hold to see active/pressed states</p>
+    <header>
+      <h3>Active States</h3>
+      <small class="text-muted">Click and hold to see active or pressed states.</small>
+    </header>
 
     <h3>Buttons</h3>
     <div class="flex flex-wrap gap-sm">
@@ -260,11 +266,13 @@ export const TransitionSpeeds = () => {
 
   return html`
     <div class="card">
-      <h2>Transition Speeds</h2>
-      <p>
+      <header>
+        <h3>Transition Speeds</h3>
+        <small class="text-muted">
         The design system provides three transition speed tokens that can be
         configured globally.
-      </p>
+        </small>
+      </header>
 
       <div class="grid gap-lg">
         ${["fast", "normal", "slow"].map(
@@ -325,12 +333,12 @@ export const WorkingStates = () => {
   };
 
   return html`
-    <h2>Working/Loading States</h2>
-    <p>
-      Click buttons to see the <code>.btn-working</code> state with automatic
-      spinner animation. The PDS enhancer automatically swaps existing icons to
-      spinners or adds a spinner if none exists.
-    </p>
+    <header>
+      <h3>Working/Loading States</h3>
+      <small class="text-muted">
+        Click buttons to see the <code>.btn-working</code> state with automatic spinner animation.
+      </small>
+    </header>
 
     <div class="stack-lg">
       <header>
@@ -483,11 +491,13 @@ WorkingStates.storyName = "Working States";
 export const SkeletonLoading = () => html`
   ${interactiveSkeletonStoryStyles}
   <div class="card">
-    <h2>Skeleton Loading</h2>
-    <p>
+    <header>
+      <h3>Skeleton Loading</h3>
+      <small class="text-muted">
       Use the <code>.skeleton</code> class for content placeholders while
       loading
-    </p>
+      </small>
+    </header>
 
     <h3>Card Skeleton</h3>
 
@@ -538,7 +548,10 @@ SkeletonLoading.storyName = "Skeleton Loading";
 
 export const EmptyState = () => html`
   <div class="card">
-    <h2>Empty State</h2>
+    <header>
+      <h3>Empty State</h3>
+      <small class="text-muted">Empty-state pattern for onboarding and first-use workflows.</small>
+    </header>
     <section class="empty-state">
       <header>
         <h2>Feature X isn’t set up yet</h2>
@@ -565,8 +578,10 @@ EmptyState.storyName = "Empty State";
 
 export const DisabledStates = () => html`
   <div class="card">
-    <h2>Disabled States</h2>
-    <p>Disabled elements have reduced opacity and no pointer events</p>
+    <header>
+      <h3>Disabled States</h3>
+      <small class="text-muted">Disabled elements have reduced opacity and no pointer events.</small>
+    </header>
 
     <h3>Buttons</h3>
     <div class="flex flex-wrap gap-sm">
@@ -644,8 +659,8 @@ DisabledStates.storyName = "Disabled States";
 
 export const CombinedStates = () => html`
   <header>
-    <h2>Combined State Examples</h2>
-    <small
+    <h3>Combined State Examples</h3>
+    <small class="text-muted"
       >Comprehensive examples showing all interactive states together</small
     >
   </header>

package/stories/patterns/Utilities.stories.js

@@ -28,6 +28,10 @@ export default {
 
 export const SpacingUtilities = () => html`
   <div class="stack-md">
+    <header>
+      <h3>Spacing Utilities</h3>
+      <small class="text-muted">Gap utilities for consistent spacing between flex and grid items.</small>
+    </header>
     <div class="gap-xs flex">
       <div class="badge">Gap 1</div>
       <div class="badge">Between</div>
@@ -47,39 +51,57 @@ export const SpacingUtilities = () => html`
 `;
 
 export const FlexUtilities = () => html`
-  <div class="card flex items-center gap-md">
-    <pds-icon icon="star" size="lg"></pds-icon>
-    <header class="grow">
-      <h4>Flex Item</h4>
-      <small class="text-muted">Vertically centered with gap</small>
+  <div class="card">
+    <header>
+      <h3>Flex Utilities</h3>
+      <small class="text-muted">Align and distribute content with composable flex helpers.</small>
     </header>
-    <button class="btn-primary">Action</button>
+    <div class="flex items-center gap-md">
+      <pds-icon icon="star" size="lg"></pds-icon>
+      <header class="grow">
+        <h4>Flex Item</h4>
+        <small class="text-muted">Vertically centered with gap</small>
+      </header>
+      <button class="btn-primary">Action</button>
+    </div>
   </div>
 `;
 
 export const BorderUtilities = () => html`
-  <div class="grid grid-auto-sm gap-md">
-    <div class="card">
-      <h4>Default Border</h4>
-      <p>No border specified</p>
-    </div>
-    <div class="card border-gradient">
-      <h4>Gradient Border</h4>
-      <p>Using .border-gradient</p>
-    </div>
-    <div class="card border-glow">
-      <h4>Glowing Border</h4>
-      <p>Using .border-glow</p>
+  <div class="stack-md">
+    <header>
+      <h3>Border Utilities</h3>
+      <small class="text-muted">Apply border effects for emphasis, depth, and visual accents.</small>
+    </header>
+    <div class="grid grid-auto-sm gap-md">
+      <div class="card">
+        <h4>Default Border</h4>
+        <p>No border specified</p>
+      </div>
+      <div class="card border-gradient">
+        <h4>Gradient Border</h4>
+        <p>Using .border-gradient</p>
+      </div>
+      <div class="card border-glow">
+        <h4>Glowing Border</h4>
+        <p>Using .border-glow</p>
+      </div>
     </div>
   </div>
 `;
 
 export const RoundedUtilities = () => html`
   ${utilitiesStoryStyles}
-  <div class="flex gap-md flex-wrap">
-    <div class="card surface-inverse story-radius-sm">--radius-sm</div>
-    <div class="card surface-inverse story-radius-md">--radius-md</div>
-    <div class="card surface-inverse story-radius-lg">--radius-lg</div>
-    <div class="card surface-inverse story-radius-full">--radius-full</div>
+  <div class="stack-md">
+    <header>
+      <h3>Rounded Utilities</h3>
+      <small class="text-muted">Border-radius utilities mapped to PDS radius tokens.</small>
+    </header>
+    <div class="flex gap-md flex-wrap">
+      <div class="card surface-inverse story-radius-sm">--radius-sm</div>
+      <div class="card surface-inverse story-radius-md">--radius-md</div>
+      <div class="card surface-inverse story-radius-lg">--radius-lg</div>
+      <div class="card surface-inverse story-radius-full">--radius-full</div>
+    </div>
   </div>
 `;