@pure-ds/storybook 0.7.25 → 0.7.26

package/stories/primitives/ArticleLayout.stories.js

@@ -0,0 +1,176 @@
+import { html } from "#pds/lit";
+
+export default {
+  title: "Primitives/Articles",
+  tags: ["typography", "content", "article", "layout", "readability"],
+  parameters: {
+    pds: {
+      tags: ["typography", "content", "article", "layout", "readability"],
+    },
+    docs: {
+      description: {
+        component:
+          "Long-form content layout pattern using semantic article markup and PDS primitives.",
+      },
+    },
+  },
+};
+
+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 • <time datetime="2025-11-17">November 17, 2025</time>
+          • 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>
+
+      <figure class="flex flex-col items-center gap-sm">
+        <img
+          src="/assets/img/og.webp"
+          alt="Pure Design System logo"
+          loading="lazy"
+        />
+        <figcaption class="text-muted">
+          Keep brand assets semantic and documented alongside implementation
+          guidance.
+        </figcaption>
+      </figure>
+
+      <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>
+
+      <nav aria-label="Article sections">
+        <h2 class="h4">In this article</h2>
+        <ol>
+          <li><a href="#components">Key components</a></li>
+          <li><a href="#tokens">Design tokens</a></li>
+          <li><a href="#rollout">Rollout checklist</a></li>
+        </ol>
+      </nav>
+
+      <section id="components">
+        <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>
+
+      <section id="tokens">
+        <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. Instead of repeating one-off values in many places, you
+          define reusable variables like <code>--color-primary</code> that can be
+          updated globally.
+        </p>
+
+        <figure>
+          <pre
+            class="surface-base story-code-block"
+          ><code>/* Design tokens in CSS */
+:root {
+  --color-primary: var(--color-brand-500);
+  --spacing-unit: var(--spacing-1x);
+  --font-family-base: var(--font-family-sans);
+  --border-radius-md: var(--radius-md);
+}</code></pre>
+          <figcaption class="text-muted">
+            Token-first foundation: define semantic aliases once and consume them
+            throughout components and layouts.
+          </figcaption>
+        </figure>
+      </section>
+
+      <aside class="callout callout-info" aria-label="Editorial note">
+        <h4>Editorial note</h4>
+        <p>
+          Teams that publish token naming conventions early usually reduce
+          handoff friction. Keep terminology consistent between design files and
+          code.
+        </p>
+      </aside>
+
+      
+      
+        <h4 class="story-impl-heading">Rollout Checklist</h4>
+        <ul>
+          <li>Document token categories and ownership</li>
+          <li>Ship a pilot component set with usage guidance</li>
+          <li>Track adoption with a lightweight release cadence</li>
+        </ul>
+      
+  
+          <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-sm 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>
+
+        <hr/>
+        
+        <address class="text-muted">
+          <small>Written for the PDS documentation team.</small>
+        </address>
+      </footer>
+    </article>
+  `,
+};

package/stories/primitives/Badges.stories.js

@@ -34,7 +34,10 @@ export const DefaultBadges = {
   render: (args) => {
     return html`
       <div class="card">
-        <h3>Default Badges</h3>
+        <header>
+          <h3>Default Badges</h3>
+          <small class="text-muted">Baseline badge styles for lightweight labels and status markers.</small>
+        </header>
         <div class="flex gap-md flex-wrap items-center">
           <span class="badge">Default</span>
           <span class="badge badge-primary">Primary</span>
@@ -56,7 +59,10 @@ export const OutlinedBadges = {
   render: (args) => {
     return html`
       <div class="card">
-        <h3>Outlined Badges</h3>
+        <header>
+          <h3>Outlined Badges</h3>
+          <small class="text-muted">Use <code>.badge-outline</code> for subtle, low-emphasis badge treatments.</small>
+        </header>
         <div class="flex gap-md flex-wrap items-center">
           <span class="badge badge-outline badge-primary">Primary</span>
           <span class="badge badge-outline badge-secondary">Secondary</span>
@@ -77,7 +83,10 @@ export const BadgeSizes = {
   render: (args) => {
     return html`
       <div class="card">
-        <h3>Badge Sizes</h3>
+        <header>
+          <h3>Badge Sizes</h3>
+          <small class="text-muted">Scale badges with <code>.badge-sm</code> and <code>.badge-lg</code> for density and emphasis.</small>
+        </header>
         <div class="flex gap-md flex-wrap items-center">
           <span class="badge badge-primary badge-sm">Small</span>
           <span class="badge badge-primary">Default</span>
@@ -95,7 +104,10 @@ export const Pills = {
   render: (args) => {
     return html`
       <div class="card">
-        <h3>Pills</h3>
+        <header>
+          <h3>Pills</h3>
+          <small class="text-muted">Rounded pill variants for tags, categories, and topic labels.</small>
+        </header>
         <div class="flex gap-md flex-wrap items-center">
           <span class="pill badge-primary">React</span>
           <span class="pill badge-secondary">Vue</span>
@@ -116,8 +128,12 @@ export const AllVariations = {
   render: (args) => {
     return html`
       <div class="card gap-lg">
+        <header>
+          <h3>All Variations</h3>
+          <small class="text-muted">Side-by-side comparison of badge styles, sizes, and pill variants.</small>
+        </header>
         <section class="stack-md">
-          <h3>Default Badges</h3>
+          <h4>Default Badges</h4>
           <div class="flex gap-md flex-wrap items-center">
             <span class="badge">Default</span>
             <span class="badge badge-primary">Primary</span>
@@ -130,7 +146,7 @@ export const AllVariations = {
         </section>
 
         <section class="stack-md">
-          <h3>Outlined Badges</h3>
+          <h4>Outlined Badges</h4>
           <div class="flex gap-md flex-wrap items-center">
             <span class="badge badge-outline badge-primary">Primary</span>
             <span class="badge badge-outline badge-secondary">Secondary</span>
@@ -142,7 +158,7 @@ export const AllVariations = {
         </section>
 
         <section class="stack-md">
-          <h3>Badge Sizes</h3>
+          <h4>Badge Sizes</h4>
           <div class="flex gap-md flex-wrap items-center">
             <span class="badge badge-primary badge-sm">Small</span>
             <span class="badge badge-primary">Default</span>
@@ -151,7 +167,7 @@ export const AllVariations = {
         </section>
 
         <section class="stack-md">
-          <h3>Pills</h3>
+          <h4>Pills</h4>
           <div class="flex gap-md flex-wrap items-center">
             <span class="pill badge-primary">React</span>
             <span class="pill badge-secondary">Vue</span>

package/stories/primitives/Buttons.stories.js

@@ -17,11 +17,16 @@ export default {
 
 export const ButtonVariants = () => html`
   <div class="card">
-    <h3>Button Variants</h3>
+    <header>
+      <h3>Button Variants</h3>
+      <small class="text-muted">Core button styles for primary, secondary, outline, and semantic actions.</small>
+    </header>
     <div class="flex gap-sm flex-wrap">
       <button class="btn-primary">Primary</button>
       <button class="btn-secondary">Secondary</button>
       <button class="btn-outline">Outline</button>
+      <button class="btn-danger">Danger</button>
+      <button class="btn-danger btn-outline">Danger Outline</button>
       <button class="btn-primary" disabled>Disabled</button>
     </div>
   </div>
@@ -31,7 +36,10 @@ ButtonVariants.storyName = 'Button Variants';
 
 export const ButtonSizes = () => html`
   <div class="card">
-    <h3>Button Sizes</h3>
+    <header>
+      <h3>Button Sizes</h3>
+      <small class="text-muted">Scale actions with <code>.btn-sm</code> and <code>.btn-lg</code> size utilities.</small>
+    </header>
     <div class="flex gap-sm flex-wrap items-center">
       <button class="btn-primary btn-sm">Small</button>
       <button class="btn-primary">Default</button>
@@ -44,8 +52,12 @@ ButtonSizes.storyName = 'Button Sizes';
 
 export const IconButtons = () => html`
   <div class="card gap-lg">
-    <section class="stack-md">
+    <header>
       <h3>Buttons with Icons</h3>
+      <small class="text-muted">Combine labels and icons to improve clarity and scanability.</small>
+    </header>
+    <section class="stack-md">
+      <h4>Buttons with Icons</h4>
       <div class="flex gap-sm flex-wrap">
         <button class="btn-primary">
           <pds-icon icon="download"></pds-icon>
@@ -67,7 +79,7 @@ export const IconButtons = () => html`
     </section>
 
     <section class="stack-md">
-      <h3>Icon on Right</h3>
+      <h4>Icon on Right</h4>
       <div class="flex gap-sm flex-wrap">
         <button class="btn-primary">
           <span>Next</span>
@@ -132,8 +144,12 @@ IconOnlyButtons.storyName = 'Icon-Only Buttons';
 
 export const ButtonGroups = () => html`
   <div class="card gap-lg">
-    <section class="stack-md">
+    <header>
       <h3>Button Groups</h3>
+      <small class="text-muted">Cluster related actions for faster decision-making.</small>
+    </header>
+    <section class="stack-md">
+      <h4>Button Groups</h4>
       <div class="flex gap-sm">
         <button class="btn-primary">
           <pds-icon icon="download"></pds-icon>
@@ -147,7 +163,7 @@ export const ButtonGroups = () => html`
     </section>
 
     <section class="stack-md">
-      <h3>Icon-Only Group</h3>
+      <h4>Icon-Only Group</h4>
       <div class="flex gap-sm">
         <button class="icon-only btn-outline">
           <pds-icon icon="text-align-left" label="Align left"></pds-icon>
@@ -167,8 +183,12 @@ ButtonGroups.storyName = 'Button Groups';
 
 export const AllSizesCombinations = () => html`
   <div class="card gap-lg">
+    <header>
+      <h3>All Sizes & Combinations</h3>
+      <small class="text-muted">Compare all button variants across small, default, and large sizes.</small>
+    </header>
     <section class="stack-md">
-      <h3>Small Buttons</h3>
+      <h4>Small Buttons</h4>
       <div class="flex gap-sm flex-wrap">
         <button class="btn-primary btn-sm">Primary</button>
         <button class="btn-secondary btn-sm">Secondary</button>
@@ -184,7 +204,7 @@ export const AllSizesCombinations = () => html`
     </section>
 
     <section class="stack-md">
-      <h3>Default Buttons</h3>
+      <h4>Default Buttons</h4>
       <div class="flex gap-sm flex-wrap">
         <button class="btn-primary">Primary</button>
         <button class="btn-secondary">Secondary</button>
@@ -200,7 +220,7 @@ export const AllSizesCombinations = () => html`
     </section>
 
     <section class="stack-md">
-      <h3>Large Buttons</h3>
+      <h4>Large Buttons</h4>
       <div class="flex gap-sm flex-wrap">
         <button class="btn-primary btn-lg">Primary</button>
         <button class="btn-secondary btn-lg">Secondary</button>

package/stories/primitives/Callouts.stories.js

@@ -17,7 +17,7 @@ export default {
 
 export const Default = () => html`
   <header class="card">
-    <h2>Basic Callouts</h2>
+    <h3>Basic Callouts</h3>
     <small class="text-muted">Simple callout messages with semantic color variants.</small>
   </header>
   
@@ -33,7 +33,7 @@ Default.storyName = 'Basic Callouts';
 
 export const CalloutsWithIcons = () => html`
   <header class="card">
-    <h2>Callouts with Icons</h2>
+    <h3>Callouts with Icons</h3>
     <small class="text-muted">Use <code>.callout-icon</code> to add visual context with icons.</small>
   </header>
   
@@ -80,7 +80,7 @@ CalloutsWithIcons.storyName = 'With Icons';
 
 export const CalloutsWithTitles = () => html`
   <header class="card">
-    <h2>Callouts with Titles</h2>
+    <h3>Callouts with Titles</h3>
     <small class="text-muted">Use <code>.callout-title</code> on text elements for consistent title rendering across presets.</small>
   </header>
   
@@ -131,7 +131,7 @@ CalloutsWithTitles.storyName = 'With Titles';
 
 export const DismissibleCallouts = () => html`
   <header class="card">
-    <h2>Dismissible Callouts</h2>
+    <h3>Dismissible Callouts</h3>
     <small class="text-muted">
       Add <code>.callout-dismissible</code> and <code>.callout-close</code> for closeable Callouts.
       Click the × to dismiss (demo only, JS required for actual dismissal).
@@ -171,9 +171,10 @@ export const DismissibleCallouts = () => html`
 DismissibleCallouts.storyName = 'Dismissible';
 
 export const CalloutsReference = () => html`
-  <div class="card">
-    <h2>Callout Classes Reference</h2>
-  </div>
+  <header class="card">
+    <h3>Callout Classes Reference</h3>
+    <small class="text-muted">Quick overview of the available callout utility classes and behaviors.</small>
+  </header>
   
   <table class="table-bordered table-compact">
     <thead>

package/stories/primitives/Cards.stories.js

@@ -271,7 +271,10 @@ ComplexCards.storyName = "Complex Cards";
 
 export const CardVariantsReference = () => html`
   <div class="card">
-    <h2>Card Classes Reference</h2>
+    <header>
+      <h3>Card Classes Reference</h3>
+      <small class="text-muted">Reference for card primitives and common composition patterns.</small>
+    </header>
 
     <table class="table-bordered">
       <thead>

package/stories/primitives/FormElements.stories.js

@@ -53,6 +53,10 @@ export const Default = {
     return html`
       ${formsStoryStyles}
       <div class="card">
+        <header>
+          <h3>Form Elements</h3>
+          <small class="text-muted">Core HTML controls styled with PDS primitives for manual form composition.</small>
+        </header>
         <form class="story-form-max" @submit=${handleSubmit}>
           <label>
             <span data-label>Text Input</span>
@@ -92,8 +96,10 @@ export const InputsWithIcons = {
     return html`
       ${formsStoryStyles}
       <div class="card">
-        <h3>Inputs with Icons</h3>
-        <p>Enhance inputs with icons for better UX. Icons can be positioned at the start or end of the input.</p>
+        <header>
+          <h3>Inputs with Icons</h3>
+          <small class="text-muted">Enhance inputs with icons positioned at the start or end for better context.</small>
+        </header>
         
         <div class="stack-lg story-form-max">
           <label>

package/stories/primitives/HtmlFormElements.stories.js

@@ -54,6 +54,10 @@ export const HtmlElementsDefault = {
     return html`
       ${formsStoryStyles}
       <div class="card">
+        <header>
+          <h3>Form Elements</h3>
+          <small class="text-muted">Core HTML controls styled with PDS primitives for manual form composition.</small>
+        </header>
         <form class="story-form-max" @submit=${handleSubmit}>
           <label>
             <span data-label>Text Input</span>
@@ -94,8 +98,10 @@ export const HtmlElementsInputsWithIcons = {
     return html`
       ${formsStoryStyles}
       <div class="card">
-        <h3>Inputs with Icons</h3>
-        <p>Enhance inputs with icons for better UX. Icons can be positioned at the start or end of the input.</p>
+        <header>
+          <h3>Inputs with Icons</h3>
+          <small class="text-muted">Enhance inputs with icons positioned at the start or end for better context.</small>
+        </header>
         
         <div class="stack-lg story-form-max">
           <label>

package/stories/primitives/HtmlFormGroups.stories.js

@@ -331,7 +331,10 @@ ToggleSwitches.storyName = "Toggle Switches";
 export const CustomLayout = () => html`
 ${styles}
   <div class="card">
-    <h3>Custom Layout with Flex Utilities</h3>
+    <header>
+      <h3>Custom Layout with Flex Utilities</h3>
+      <small class="text-muted">Override default group flow with flex utilities for horizontal and wrapped layouts.</small>
+    </header>
     <div class="callout callout-info">
       Override default column layout using standard CSS flex properties
     </div>
@@ -457,7 +460,7 @@ export const AccessibleFormGroups = {
     return html`
       <div class="card">
         <header>
-          <h2>Accessibility Features</h2>
+          <h3>Accessibility Features</h3>
           <small class="text-muted"
             >Form groups include proper ARIA attributes, semantic HTML, and
             keyboard navigation support.</small

package/stories/primitives/Media.stories.js

@@ -36,6 +36,10 @@ const mediaStoryStyles = html`
 export const ResponsiveImages = () => html`
   ${mediaStoryStyles}
   <div class="stack-md">
+    <header>
+      <h3>Responsive Images</h3>
+      <small class="text-muted">Semantic figures with responsive images and descriptive captions.</small>
+    </header>
     <div class="grid grid-auto-md gap-lg">
       <figure class="media-figure">
         <img
@@ -69,7 +73,10 @@ ResponsiveImages.storyName = 'Responsive Images';
 export const ImageGallery = () => html`
   ${mediaStoryStyles}
   <div class="stack-md">
-    <h3>Image Gallery Grid</h3>
+    <header>
+      <h3>Image Gallery Grid</h3>
+      <small class="text-muted">Uniform thumbnail gallery layout using PDS media utilities.</small>
+    </header>
     <div class="grid grid-auto-sm gap-sm">
       ${Array.from({ length: 8 }, (_, i) => html`
         <img
@@ -110,10 +117,10 @@ export const ScrollRowGallery = () => html`
 ScrollRowGallery.storyName = 'Horizontal Scroll Row';
 
 export const ImageRoundedUtilities = () => html`
-  <div class="card">
-    <h2>Image Rounded Utilities</h2>
-    <p class="text-muted">Apply consistent border-radius to images with <code>.img-rounded-*</code> classes.</p>
-  </div>
+  <header class="card">
+    <h3>Image Rounded Utilities</h3>
+    <small class="text-muted">Apply consistent border-radius to images with <code>.img-rounded-*</code> classes.</small>
+  </header>
   
   <div class="grid grid-auto-sm gap-lg">
     <figure>
@@ -166,13 +173,13 @@ export const ImageRoundedUtilities = () => html`
 ImageRoundedUtilities.storyName = 'Rounded Utilities';
 
 export const ImageGalleryClass = () => html`
-  <div class="card">
-    <h2>.img-gallery Utility</h2>
-    <p class="text-muted">
+  <header class="card">
+    <h3>.img-gallery Utility</h3>
+    <small class="text-muted">
       The <code>.img-gallery</code> class creates square, cropped thumbnails perfect for grid galleries.
       Images are set to <code>aspect-ratio: 1</code> and <code>object-fit: cover</code>.
-    </p>
-  </div>
+    </small>
+  </header>
   
   <div class="grid grid-auto-sm gap-md">
     ${Array.from({ length: 8 }, (_, i) => html`
@@ -188,12 +195,12 @@ export const ImageGalleryClass = () => html`
 ImageGalleryClass.storyName = '.img-gallery';
 
 export const InlineImages = () => html`
-  <div class="card">
-    <h2>Inline Images</h2>
-    <p class="text-muted">
+  <header class="card">
+    <h3>Inline Images</h3>
+    <small class="text-muted">
       Use <code>.img-inline</code> for small images within text flow, like avatars or icons.
-    </p>
-  </div>
+    </small>
+  </header>
   
   <div class="card">
     <p>
@@ -231,12 +238,12 @@ export const InlineImages = () => html`
 InlineImages.storyName = 'Inline Images';
 
 export const VideoResponsive = () => html`
-  <div class="card">
-    <h2>.video-responsive Utility</h2>
-    <p class="text-muted">
+  <header class="card">
+    <h3>.video-responsive Utility</h3>
+    <small class="text-muted">
       The <code>.video-responsive</code> class constrains video width and applies consistent styling.
-    </p>
-  </div>
+    </small>
+  </header>
   
   <video 
     class="story-video-responsive" 
@@ -264,12 +271,12 @@ export const VideoResponsive = () => html`
 VideoResponsive.storyName = '.video-responsive';
 
 export const FigureResponsive = () => html`
-  <div class="card">
-    <h2>.figure-responsive Utility</h2>
-    <p class="text-muted">
+  <header class="card">
+    <h3>.figure-responsive Utility</h3>
+    <small class="text-muted">
       Apply <code>.figure-responsive</code> to figures for full-width responsive images with captions.
-    </p>
-  </div>
+    </small>
+  </header>
   
   <figure class="figure-responsive">
     <img 
@@ -287,7 +294,10 @@ FigureResponsive.storyName = '.figure-responsive';
 export const VideoElement = () => html`
   ${mediaStoryStyles}
   <div class="stack-md media-video-shell">
-    <h3>Video Element with Controls</h3>
+    <header>
+      <h3>Video Element with Controls</h3>
+      <small class="text-muted">Native video playback with responsive styling and semantic caption support.</small>
+    </header>
     <figure class="video-container">
       <video
         class="video-responsive shadow-md"
@@ -312,7 +322,10 @@ VideoElement.storyName = 'Video Element';
 export const MixedMedia = () => html`
   ${mediaStoryStyles}
   <div class="stack-md">
-    <h2>Mixed Media Layout</h2>
+    <header>
+      <h3>Mixed Media Layout</h3>
+      <small class="text-muted">Combine featured media and supporting thumbnails in a balanced content layout.</small>
+    </header>
     
     <div class="grid grid-cols-2 gap-lg">
       <div>
@@ -350,9 +363,10 @@ export const MixedMedia = () => html`
 MixedMedia.storyName = 'Mixed Media Layout';
 
 export const MediaReference = () => html`
-  <div class="card">
-    <h2>Media Utilities Reference</h2>
-  </div>
+  <header class="card">
+    <h3>Media Utilities Reference</h3>
+    <small class="text-muted">Reference table for image, figure, and video utility classes.</small>
+  </header>
   
   <table class="table-bordered">
     <thead>