@pure-ds/storybook 0.1.0

package/stories/foundations/ZIndex.stories.js

@@ -0,0 +1,325 @@
+import { html } from 'lit';
+
+export default {
+  title: 'Foundations/Z-Index',
+  parameters: {
+    docs: {
+      description: {
+        component: 'Z-Index tokens define the stacking order of UI elements along the z-axis. These tokens ensure consistent layering across the application, preventing z-index conflicts and establishing clear visual hierarchy for overlays, modals, dropdowns, and other elevated UI components.'
+      }
+    }
+  }
+};
+
+const zIndexStoryStyles = html`
+  <style>
+    .z-index-section {
+      padding: var(--spacing-8);
+      max-width: 75rem;
+    }
+    .z-index-value {
+      font-weight: 600;
+    }
+    .z-index-number {
+      font-family: var(--font-mono, monospace);
+      margin-left: var(--spacing-3);
+    }
+    .z-index-callout {
+      margin-top: var(--spacing-8);
+      border-left-width: 4px;
+    }
+    .z-index-callout--info {
+      border-left-color: var(--color-info);
+    }
+    .z-index-callout--warning {
+      border-left-color: var(--color-warning);
+    }
+    .z-index-demo-wrapper {
+      position: relative;
+      height: 37.5rem;
+      overflow: hidden;
+    }
+    .z-index-demo-base {
+      padding: var(--spacing-6);
+    }
+    .z-index-demo-dropdown {
+      position: absolute;
+      top: 100px;
+      left: 50px;
+      z-index: var(--z-dropdown);
+      min-width: 12.5rem;
+    }
+    .z-index-demo-sticky {
+      position: absolute;
+      top: 180px;
+      left: 100px;
+      z-index: var(--z-sticky);
+      min-width: 12.5rem;
+    }
+    .z-index-demo-fixed {
+      position: absolute;
+      top: 260px;
+      left: 150px;
+      z-index: var(--z-fixed);
+      min-width: 12.5rem;
+    }
+    .z-index-demo-modal-overlay {
+      position: absolute;
+      border-radius: var(--radius-md);
+      inset: 0;
+      z-index: var(--z-modal);
+      background: rgba(0, 0, 0, 0.1);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
+    .z-index-demo-modal-card {
+      max-width: 25rem;
+    }
+    .z-index-demo-tooltip {
+      position: absolute;
+      top: 50px;
+      right: 50px;
+      z-index: var(--z-tooltip);
+      padding: var(--spacing-2) var(--spacing-3);
+    }
+    .z-index-demo-toast {
+      position: absolute;
+      top: 20px;
+      right: 20px;
+      z-index: var(--z-notification);
+      background: var(--color-success);
+      color: var(--color-text-inverse, #ffffff);
+      min-width: 15.625rem;
+    }
+    .z-index-note {
+      margin-top: var(--spacing-6);
+    }
+  </style>
+`;
+
+export const ZIndexScale = {
+  name: 'Z-Index Scale',
+  render: () => html`
+    ${zIndexStoryStyles}
+    <div class="z-index-section">
+      <h2>Z-Index Token Scale</h2>
+      <p class="text-muted">
+        Tokens are organized from lowest to highest z-index values, ensuring proper stacking of UI layers.
+      </p>
+      
+      <div class="grid grid-cols-1 gap-md">
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-dropdown</code>
+          <span class="z-index-number">1000</span>
+          <p class="text-muted">Dropdown menus and select options</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-sticky</code>
+          <span class="z-index-number">1020</span>
+          <p class="text-muted">Sticky headers and navigation elements</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-fixed</code>
+          <span class="z-index-number">1030</span>
+          <p class="text-muted">Fixed position elements</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-modal</code>
+          <span class="z-index-number">1040</span>
+          <p class="text-muted">Modal dialogs and overlays</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-drawer</code>
+          <span class="z-index-number">1050</span>
+          <p class="text-muted">Drawer panels (side sheets)</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-popover</code>
+          <span class="z-index-number">1060</span>
+          <p class="text-muted">Popovers and context menus</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-tooltip</code>
+          <span class="z-index-number">1070</span>
+          <p class="text-muted">Tooltips and helper text</p>
+        </div>
+        
+        <div class="card surface-subtle">
+          <code class="z-index-value">--z-notification</code>
+          <span class="z-index-number">1080</span>
+          <p class="text-muted">Toast notifications and alerts</p>
+        </div>
+      </div>
+      
+      <div class="card card-outlined z-index-callout z-index-callout--info">
+        <h3><pds-icon icon="info"></pds-icon> Best Practices</h3>
+        <ul>
+          <li>Always use these tokens instead of hard-coded z-index values</li>
+          <li>Tokens are spaced by 10 to allow for intermediate values if needed</li>
+          <li>Higher values appear above lower values in the stacking context</li>
+          <li>Notifications have the highest z-index to ensure visibility</li>
+          <li>Never exceed these values unless absolutely necessary</li>
+        </ul>
+      </div>
+    </div>
+  `
+};
+
+export const VisualDemo = {
+  name: 'Visual Stacking Demo',
+  render: () => html`
+    ${zIndexStoryStyles}
+    <div class="z-index-section">
+      <h2>Interactive Stacking Example</h2>
+      <p class="text-muted">
+        This demo shows how different z-index tokens create proper layering. 
+        Lower elements appear behind higher ones.
+      </p>
+      
+      <div class="surface z-index-demo-wrapper">
+        
+        <div class="z-index-demo-base">
+          <h3>Base Content (z-index: auto)</h3>
+          <p>This is the base layer of content with no explicit z-index.</p>
+        </div>
+        
+        <div class="card card-elevated z-index-demo-dropdown">
+          <strong>Dropdown Menu</strong>
+          <p><small>z-index: var(--z-dropdown) = 1000</small></p>
+        </div>
+        
+        <div class="card surface-elevated z-index-demo-sticky">
+          <strong>Sticky Header</strong>
+          <p><small>z-index: var(--z-sticky) = 1020</small></p>
+        </div>
+        
+        <div class="card surface-elevated z-index-demo-fixed">
+          <strong>Fixed Element</strong>
+          <p><small>z-index: var(--z-fixed) = 1030</small></p>
+        </div>
+        
+        <div class="z-index-demo-modal-overlay">
+          <article class="card card-elevated z-index-demo-modal-card">
+            <h4>Modal Dialog</h4>
+            <p><small>z-index: var(--z-modal) = 1040</small></p>
+            <p class="text-muted">Modal dialogs appear above most other content.</p>
+          </article>
+        </div>
+        
+        <div class="surface-inverse z-index-demo-tooltip">
+          <strong>Tooltip</strong>
+          <p><small>--z-tooltip: 1070</small></p>
+        </div>
+        
+        <div class="card z-index-demo-toast">
+          <strong>🎉 Notification Toast</strong>
+          <p><small>z-index: var(--z-notification) = 1080</small></p>
+          <p><small>Highest layer</small></p>
+        </div>
+        
+      </div>
+      
+      <div class="card card-outlined z-index-note">
+        <p>
+          <strong>Note:</strong> In this demo, elements are positioned to overlap. 
+          Notice how higher z-index values appear above lower ones, with notifications at the top.
+        </p>
+      </div>
+    </div>
+  `
+};
+
+export const UsageExamples = {
+  name: 'Usage Examples',
+  render: () => html`
+    ${zIndexStoryStyles}
+    <div class="z-index-section">
+      <h2>Code Examples</h2>
+      <p class="text-muted">
+        How to use z-index tokens in your components and styles.
+      </p>
+      
+      <div class="grid grid-cols-1 gap-lg">
+        
+        <article class="card surface-subtle">
+          <h3>Modal Dialog</h3>
+          <pre><code>.modal {
+  position: fixed;
+  inset: 0;
+  z-index: var(--z-modal);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}</code></pre>
+        </article>
+        
+        <article class="card surface-subtle">
+          <h3>Dropdown Menu</h3>
+          <pre><code>.dropdown-menu {
+  position: absolute;
+  z-index: var(--z-dropdown);
+  background: var(--color-surface-elevated);
+  box-shadow: var(--shadow-lg);
+  border-radius: var(--radius-md);
+}</code></pre>
+        </article>
+        
+        <article class="card surface-subtle">
+          <h3>Sticky Header</h3>
+          <pre><code>.sticky-header {
+  position: sticky;
+  top: 0;
+  z-index: var(--z-sticky);
+  background: var(--color-surface-base);
+  box-shadow: var(--shadow-sm);
+}</code></pre>
+        </article>
+        
+        <article class="card surface-subtle">
+          <h3>Toast Notification</h3>
+          <pre><code>.toast-notification {
+  position: fixed;
+  top: var(--spacing-4);
+  right: var(--spacing-4);
+  z-index: var(--z-notification);
+  padding: var(--spacing-4);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-xl);
+}</code></pre>
+        </article>
+        
+        <article class="card surface-subtle">
+          <h3>Tooltip</h3>
+          <pre><code>.tooltip {
+  position: absolute;
+  z-index: var(--z-tooltip);
+  padding: var(--spacing-2);
+  background: var(--color-surface-inverse);
+  color: var(--color-text-inverse);
+  font-size: var(--font-size-sm);
+  border-radius: var(--radius-sm);
+}</code></pre>
+        </article>
+        
+      </div>
+      
+      <aside class="card card-outlined z-index-callout z-index-callout--warning">
+        <h3><pds-icon icon="warning"></pds-icon> Important Guidelines</h3>
+        <ul>
+          <li><strong>Never use magic numbers:</strong> Always reference these tokens instead of hardcoded values</li>
+          <li><strong>Respect the hierarchy:</strong> Don't try to make a dropdown appear above a modal</li>
+          <li><strong>Stacking context:</strong> Remember that z-index only works within the same stacking context</li>
+          <li><strong>Negative values:</strong> Avoid negative z-index values; use these tokens instead</li>
+          <li><strong>Component libraries:</strong> Ensure third-party components don't conflict with these ranges</li>
+        </ul>
+      </aside>
+    </div>
+  `
+};

package/stories/patterns/BorderEffects.stories.js

@@ -0,0 +1,72 @@
+import { html } from 'lit';
+
+export default {
+  title: 'Patterns/Border Effects',
+  parameters: {
+    docs: {
+      description: {
+        component: 'Special border effects including gradients and glows'
+      }
+    }
+  }
+};
+
+const borderEffectsStoryStyles = html`
+  <style>
+    .border-effects-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(15.625rem, 1fr));
+      gap: var(--spacing-4);
+    }
+    .border-effects-card {
+      padding: var(--spacing-4);
+    }
+    .border-effects-card-angle {
+      --gradient-angle: 45deg;
+    }
+    .border-effects-actions {
+      display: flex;
+      gap: var(--spacing-2);
+      margin-top: var(--spacing-4);
+    }
+  </style>
+`;
+
+export const BorderGradient = () => html`
+  ${borderEffectsStoryStyles}
+  <div class="border-effects-grid">
+    <div class="border-gradient border-effects-card">
+      <h3>Gradient Border</h3>
+      <p>Animated gradient border effect that follows the primary color scheme.</p>
+    </div>
+    <div class="border-gradient border-effects-card border-effects-card-angle">
+      <h3>Custom Angle</h3>
+      <p>Use CSS variables to customize the gradient direction.</p>
+    </div>
+  </div>
+`;
+
+export const BorderGlow = () => html`
+  <div class="grid 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>
+  </div>
+`;
+
+export const Combined = () => html`
+  ${borderEffectsStoryStyles}
+  <article class="card border-gradient">
+    <h2>Premium Feature Card</h2>
+    <p>Combining card primitive with gradient border effect.</p>
+    <div class="border-effects-actions">
+      <button class="btn-primary">Get Started</button>
+      <button class="btn-outline">Learn More</button>
+    </div>
+  </article>
+`;

package/stories/patterns/Layout.stories.js

@@ -0,0 +1,99 @@
+import { html } from 'lit';
+
+export default {
+  title: 'Patterns/Layout',
+  tags: ['grouping'],
+  parameters: {
+    pds: {
+      tags: ['layout', 'grid', 'flex', 'grouping']
+    },
+    docs: {
+      description: {
+        component: 'Layout patterns using grid, flex, and container utilities'
+      }
+    }
+  }
+};
+
+const layoutStoryStyles = html`
+  <style>
+    .layout-auto-grid {
+      grid-template-columns: repeat(auto-fill, minmax(12.5rem, 1fr));
+      gap: var(--spacing-4);
+    }
+    .layout-flex-item {
+      flex: 1;
+      min-width: 12.5rem;
+    }
+    .layout-container {
+      max-width: 75rem;
+      margin: 0 auto;
+      padding: var(--spacing-4);
+    }
+    .layout-section-spacing {
+      margin-top: var(--spacing-4);
+    }
+    .layout-grid-card {
+      padding: var(--spacing-4);
+      text-align: center;
+    }
+  </style>
+`;
+
+export const GridLayout = () => html`
+  ${layoutStoryStyles}
+  <div class="grid layout-auto-grid">
+    ${Array.from({ length: 6 }, (_, i) => html`
+      <div class="card">
+        <h4>Grid Item ${i + 1}</h4>
+        <p>Content in grid cell</p>
+      </div>
+    `)}
+  </div>
+`;
+
+export const FlexLayout = () => html`
+  ${layoutStoryStyles}
+  <div class="flex gap-sm flex-wrap">
+    <div class="card layout-flex-item">
+      <h4>Flexible Box 1</h4>
+      <p>Grows to fill space</p>
+    </div>
+    <div class="card layout-flex-item">
+      <h4>Flexible Box 2</h4>
+      <p>Equal flex basis</p>
+    </div>
+    <div class="card layout-flex-item">
+      <h4>Flexible Box 3</h4>
+      <p>Responsive wrapping</p>
+    </div>
+  </div>
+`;
+
+export const ContainerLayout = () => html`
+  ${layoutStoryStyles}
+  <div class="layout-container">
+    <h2>Centered Container</h2>
+    <p>Content is constrained to a maximum width and centered.</p>
+    <div class="grid grid-cols-3 gap-md layout-section-spacing">
+      ${Array.from({ length: 3 }, (_, i) => html`
+        <div class="card">
+          <h4>Column ${i + 1}</h4>
+          <p>Three equal columns</p>
+        </div>
+      `)}
+    </div>
+  </div>
+`;
+
+export const ResponsiveGrid = () => html`
+  ${layoutStoryStyles}
+  <div class="grid grid-auto-md gap-md">
+    ${Array.from({ length: 12 }, (_, i) => html`
+      <div class="card layout-grid-card">
+        <h4>Item ${i + 1}</h4>
+        <p>Auto-responsive grid cell</p>
+      </div>
+    `)}
+  </div>
+`;

package/stories/patterns/Utilities.stories.js

@@ -0,0 +1,107 @@
+import { html } from 'lit';
+
+export default {
+  title: 'Patterns/Utilities',
+  tags: ['utilities', 'spacing', 'layout', 'gap'],
+  parameters: {
+    pds: {
+      tags: ['utilities', 'layout', 'spacing', 'gap']
+    },
+    docs: {
+      description: {
+        component: 'Utility classes for spacing, sizing, and common patterns'
+      }
+    }
+  }
+};
+
+const utilitiesStoryStyles = html`
+  <style>
+    .utilities-flex-fill {
+      flex: 1;
+    }
+    .utilities-heading-reset {
+      margin: 0;
+    }
+    .utilities-helper-text {
+      margin: 0;
+      font-size: 0.875rem;
+      color: var(--surface-text-secondary);
+    }
+    .utilities-auto-grid {
+      grid-template-columns: repeat(auto-fit, minmax(12.5rem, 1fr));
+    }
+    .utilities-radius-sm {
+      border-radius: var(--radius-sm);
+    }
+    .utilities-radius-md {
+      border-radius: var(--radius-md);
+    }
+    .utilities-radius-lg {
+      border-radius: var(--radius-lg);
+    }
+    .utilities-radius-full {
+      border-radius: var(--radius-full);
+    }
+  </style>
+`;
+
+export const SpacingUtilities = () => html`
+  <div class="flex flex-col gap-md">
+    <div class="gap-xs flex" >
+      <div class="badge">Gap 1</div>
+      <div class="badge">Between</div>
+      <div class="badge">Items</div>
+    </div>
+    <div class="gap-sm flex" >
+      <div class="badge">Gap 2</div>
+      <div class="badge">Between</div>
+      <div class="badge">Items</div>
+    </div>
+    <div class="gap-md flex" >
+      <div class="badge">Gap 4</div>
+      <div class="badge">Between</div>
+      <div class="badge">Items</div>
+    </div>
+  </div>
+`;
+
+export const FlexUtilities = () => html`
+  ${utilitiesStoryStyles}
+  <div class="card flex items-center gap-md" >
+    <pds-icon icon="star" size="lg"></pds-icon>
+    <div class="utilities-flex-fill">
+      <h4 class="utilities-heading-reset">Flex Item</h4>
+      <p class="utilities-helper-text">Vertically centered with gap</p>
+    </div>
+    <button class="btn-primary">Action</button>
+  </div>
+`;
+
+export const BorderUtilities = () => html`
+  ${utilitiesStoryStyles}
+  <div class="grid gap-md utilities-auto-grid">
+    <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>
+`;
+
+export const RoundedUtilities = () => html`
+  ${utilitiesStoryStyles}
+  <div class="flex gap-md flex-wrap">
+    <div class="card surface-inverse utilities-radius-sm">--radius-sm</div>
+    <div class="card surface-inverse utilities-radius-md">--radius-md</div>
+    <div class="card surface-inverse utilities-radius-lg">--radius-lg</div>
+    <div class="card surface-inverse utilities-radius-full">--radius-full</div>
+  </div>
+`;