@repobit/dex-system-design 0.22.11 → 0.23.1

package/src/components/paragraph/paragraph.stories.js

@@ -1,443 +1,118 @@
 import { html } from 'lit';
-import '../cards/card.js';
-import '../heading/heading.js';
 import './paragraph.js';
 
 export default {
-  title    : 'Atoms/Paragraph',
-  component: 'bd-p',
-  tags     : ['autodocs'],
-  argTypes : {
-    kind: {
-      control    : { type: 'select' },
-      options    : ['regular', 'large', 'small', 'lead'],
-      description: 'Paragraph size and emphasis variant',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'regular' }
-      }
-    },
-    align: {
-      control    : { type: 'select' },
-      options    : ['left', 'center', 'right', 'justify'],
-      description: 'Text alignment',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'left' }
-      }
-    },
-    color: {
-      control    : 'color',
-      description: 'Custom text color',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'inherit' }
-      }
-    },
-    content: {
-      control    : 'text',
-      description: 'Paragraph text content',
-      table      : {
-        type        : { summary: 'string' },
-        defaultValue: { summary: 'Paragraph text' }
-      }
-    }
-  },
+  title     : 'Components/Paragraph',
+  tags      : ['autodocs'],
   parameters: {
     docs: {
       description: {
-        component: 'A flexible paragraph component with consistent typography, multiple size variants, and alignment options. Designed for optimal readability and content hierarchy.'
+        component: `
+**BdP** is a Lit paragraph component that renders a \`<p>\` tag with kind-based typography styling.
+
+### Usage
+\`\`\`html
+<bd-p kind="large">Large paragraph text</bd-p>
+<bd-p kind="regular">Regular body text</bd-p>
+<bd-p kind="small">Small supporting text</bd-p>
+\`\`\`
+
+### Kind Values
+The \`kind\` attribute is reflected and used as a CSS selector for typography styling:
+| Kind | Use case |
+|---|---|
+| \`large\` | Lead text, intro paragraphs |
+| \`regular\` | Default body text |
+| \`small\` | Captions, disclaimers, supporting text |
+
+### Notes
+- Content is passed via \`<slot>\`
+- Supports rich HTML content inside the slot (strong, em, a, etc.)
+        `
       }
     }
-  }
-};
-
-const Template = ({ kind, align, color, content }) => html`
-  <bd-p 
-    kind="${kind}" 
-    style="${align ? `text-align: ${align};` : ''} ${color ? `color: ${color};` : ''}"
-  >
-    ${content}
-  </bd-p>
-`;
-
-// ============ STORIES ============
-
-export const Default = Template.bind({});
-Default.args = {
-  kind   : 'regular',
-  align  : 'left',
-  color  : '',
-  content: 'Default paragraph with regular styling for standard body text content.'
-};
-Default.parameters = {
-  docs: {
-    description: {
-      story: 'Default paragraph component with regular size and left alignment. Perfect for most body text content throughout the application.'
+  },
+  argTypes: {
+    kind: {
+      control    : { type: 'select' },
+      options    : ['large', 'regular', 'small'],
+      description: 'Typography size variant, reflected as an attribute for CSS targeting',
+      table      : { type: { summary: "'large'|'regular'|'small'" }, defaultValue: { summary: 'regular' }, category: 'Appearance' }
     }
   }
 };
 
-export const AllVariants = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">All Paragraph Variants</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Explore all available paragraph variants with their specific use cases and typographic characteristics.
-    </bd-p>
-    
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="lead" style="margin-bottom: 1rem;">Lead Paragraph - Introduction and Emphasis</bd-p>
-      <bd-p kind="regular" style="color: #64748b;">
-        <strong>Use case:</strong> Introductory text, article openings, key summaries<br>
-        <strong>CSS Variables:</strong> --typography-paragraph-lead-fontSize, --typography-paragraph-lead-lineHeight<br>
-        <strong>Characteristics:</strong> Larger font size, increased line height for better readability
-      </bd-p>
-    </div>
+const sampleText = 'Bitdefender delivers award-winning cybersecurity to over 500 million users and 150,000 companies worldwide.';
 
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="margin-bottom: 1rem;">Large Paragraph - Emphasized Content</bd-p>
-      <bd-p kind="regular" style="color: #64748b;">
-        <strong>Use case:</strong> Important content, feature highlights, prominent sections<br>
-        <strong>CSS Variables:</strong> --typography-paragraph-large-fontSize, --typography-paragraph-large-lineHeight<br>
-        <strong>Characteristics:</strong> Slightly larger than regular, maintains hierarchy
-      </bd-p>
-    </div>
+// ─── Stories ───────────────────────────────────────────────────────────────
 
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="regular" style="margin-bottom: 1rem;">Regular Paragraph - Standard Body Text</bd-p>
-      <bd-p kind="regular" style="color: #64748b;">
-        <strong>Use case:</strong> Main content, article body, standard text blocks<br>
-        <strong>CSS Variables:</strong> --typography-paragraph-regular-fontSize, --typography-paragraph-regular-lineHeight<br>
-        <strong>Characteristics:</strong> Balanced size and spacing for optimal reading
-      </bd-p>
-    </div>
-
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="small" style="margin-bottom: 1rem;">Small Paragraph - Secondary Information</bd-p>
-      <bd-p kind="regular" style="color: #64748b;">
-        <strong>Use case:</strong> Captions, footnotes, legal text, supplementary info<br>
-        <strong>CSS Variables:</strong> --typography-paragraph-small-fontSize, --typography-paragraph-small-lineHeight<br>
-        <strong>Characteristics:</strong> Compact size, reduced visual weight
-      </bd-p>
-    </div>
-  </div>
-`;
-AllVariants.parameters = {
-  docs: {
-    description: {
-      story: 'Comprehensive overview of all paragraph variants with detailed usage guidelines, CSS variable references, and typographic characteristics for each size option.'
-    }
-  }
+export const Default = {
+  name      : 'Default (Regular)',
+  render    : () => html`<bd-p kind="regular">${sampleText}</bd-p>`,
+  parameters: { docs: { description: { story: 'Default regular paragraph.' } } }
 };
 
-export const Lead = Template.bind({});
-Lead.args = {
-  kind   : 'lead',
-  align  : 'left',
-  color  : '',
-  content: 'This is a lead paragraph designed for introductory text and key summaries. It features larger font size and increased line height for better readability and visual impact.'
-};
-Lead.parameters = {
-  docs: {
-    description: {
-      story: 'Lead paragraph variant - Use for introductory text, article openings, and key summaries. Features larger font size and increased line height for enhanced readability and visual prominence.'
-    }
-  }
-};
-
-export const Large = Template.bind({});
-Large.args = {
-  kind   : 'large',
-  align  : 'left',
-  color  : '',
-  content: 'This is a large paragraph for emphasized content that requires more attention. Perfect for highlighting important features or key information within your content.'
-};
-Large.parameters = {
-  docs: {
-    description: {
-      story: 'Large paragraph variant - Ideal for important content, feature highlights, and prominent sections that need slightly more emphasis than regular body text while maintaining proper hierarchy.'
-    }
-  }
+export const AllKinds = {
+  name  : 'All Kinds',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:16px;">
+      <bd-p kind="large">${sampleText}</bd-p>
+      <bd-p kind="regular">${sampleText}</bd-p>
+      <bd-p kind="small">${sampleText}</bd-p>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'All three kind values stacked for typographic scale comparison: large, regular, small.' } } }
 };
 
-export const Regular = Template.bind({});
-Regular.args = {
-  kind   : 'regular',
-  align  : 'left',
-  color  : '',
-  content: 'This is a regular paragraph with standard body text styling. It provides the perfect balance of readability and space efficiency for most content throughout your application.'
-};
-Regular.parameters = {
-  docs: {
-    description: {
-      story: 'Regular paragraph variant - The default choice for main content, article body, and standard text blocks. Offers optimal readability with balanced typographic proportions.'
-    }
-  }
+export const LargeKind = {
+  name      : 'Kind — Large',
+  render    : () => html`<bd-p kind="large">${sampleText}</bd-p>`,
+  parameters: { docs: { description: { story: 'Large paragraph — suited for lead or intro text.' } } }
 };
 
-export const Small = Template.bind({});
-Small.args = {
-  kind   : 'small',
-  align  : 'left',
-  color  : '',
-  content: 'This is a small paragraph designed for secondary information, captions, and supplementary content. It maintains readability while reducing visual weight.'
-};
-Small.parameters = {
-  docs: {
-    description: {
-      story: 'Small paragraph variant - Perfect for captions, footnotes, legal text, and supplementary information where reduced visual weight and compact spacing are desired.'
-    }
-  }
+export const SmallKind = {
+  name      : 'Kind — Small',
+  render    : () => html`<bd-p kind="small">${sampleText}</bd-p>`,
+  parameters: { docs: { description: { story: 'Small paragraph — suited for captions, disclaimers, and supporting text.' } } }
 };
 
-export const TextAlignment = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Text Alignment Options</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Different text alignment options for various content contexts and design requirements.
+export const RichContent = {
+  name  : 'Rich Slotted Content',
+  render: () => html`
+    <bd-p kind="regular">
+      Protect your devices with <strong>award-winning</strong> security.
+      Visit our <a href="/products">products page</a> or <em>contact us</em> for more info.
     </bd-p>
-    
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="text-align: left; margin-bottom: 1rem;">Left Aligned Paragraph</bd-p>
-      <bd-p kind="regular" style="text-align: left; color: #64748b;">
-        Default alignment. Best for most content, articles, and body text. Provides optimal readability for left-to-right languages and follows natural reading patterns.
-      </bd-p>
-    </div>
-
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="text-align: center; margin-bottom: 1rem;">Center Aligned Paragraph</bd-p>
-      <bd-p kind="regular" style="text-align: center; color: #64748b;">
-        Ideal for short quotes, testimonials, and introductory text. Creates visual balance and emphasis for specific content pieces that need to stand out.
-      </bd-p>
-    </div>
-
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="text-align: right; margin-bottom: 1rem;">Right Aligned Paragraph</bd-p>
-      <bd-p kind="regular" style="text-align: right; color: #64748b;">
-        Useful for asymmetric layouts, captions, and specific design compositions. Use sparingly for intentional visual effects and creative typographic treatments.
-      </bd-p>
-    </div>
-
-    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="text-align: justify; margin-bottom: 1rem;">Justified Paragraph</bd-p>
-      <bd-p kind="regular" style="text-align: justify; color: #64748b;">
-        Creates clean edges on both sides of the text block. Best for formal documents, printed materials, and content where precise alignment is important. May require hyphenation for optimal results in longer texts.
-      </bd-p>
-    </div>
-  </div>
-`;
-TextAlignment.parameters = {
-  docs: {
-    description: {
-      story: 'Demonstration of different text alignment options with recommendations for when to use left, center, right, or justified alignment based on content type and design context.'
-    }
-  }
-};
-
-export const ColorCustomization = () => html`
-  <div style="display: flex; flex-direction: column; gap: 2rem; max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 1rem;">Color Customization Examples</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Paragraphs can be customized with different colors to match various contexts, themes, and semantic meanings.
-    </bd-p>
-    
-    <div style="background: #1e293b; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="color: #ffffff; margin-bottom: 1rem;">White Text on Dark Background</bd-p>
-      <bd-p kind="regular" style="color: #cbd5e1;">
-        Perfect for dark theme sections, hero areas, and high-contrast designs. Maintains excellent readability while providing sophisticated visual appeal.
-      </bd-p>
-    </div>
-
-    <div style="background: #dbeafe; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="color: #1e40af; margin-bottom: 1rem;">Primary Brand Color</bd-p>
-      <bd-p kind="regular" style="color: #374151;">
-        Using brand colors for visual consistency and emphasis. Helps maintain brand identity across different content sections and application areas.
-      </bd-p>
-    </div>
-
-    <div style="background: #f0fdf4; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="color: #166534; margin-bottom: 1rem;">Success Green Color</bd-p>
-      <bd-p kind="regular" style="color: #374151;">
-        Color coding for success states, positive outcomes, and confirmation messages. Provides clear visual feedback for successful operations.
-      </bd-p>
-    </div>
-
-    <div style="background: #fef2f2; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="color: #dc2626; margin-bottom: 1rem;">Error Red Color</bd-p>
-      <bd-p kind="regular" style="color: #374151;">
-        Using red for error states, warnings, and critical information. Draws attention to important alerts and requires-action content.
-      </bd-p>
-    </div>
-
-    <div style="background: #f8fafc; padding: 2rem; border-radius: 8px;">
-      <bd-p kind="large" style="color: #6b7280; margin-bottom: 1rem;">Neutral Gray Color</bd-p>
-      <bd-p kind="regular" style="color: #374151;">
-        Subtle gray tones for secondary content, disabled states, and low-emphasis information. Maintains readability while reducing visual weight.
-      </bd-p>
-    </div>
-  </div>
-`;
-ColorCustomization.parameters = {
-  docs: {
-    description: {
-      story: 'Examples of color customization for paragraphs in different contexts including dark themes, brand colors, semantic color coding, and accessibility considerations.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Rich HTML inside the slot: bold, anchor, and italic elements.' } } }
 };
 
-export const ContentHierarchy = () => html`
-  <div style="max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h1">Cybersecurity Best Practices Guide</bd-h>
-    <bd-p kind="lead" style="margin-bottom: 2rem;">
-      Protecting your digital assets requires a comprehensive approach that combines advanced technology with user awareness and proper security protocols.
+export const Disclaimer = {
+  name  : 'Disclaimer Use Case',
+  render: () => html`
+    <bd-p kind="small">
+      Protection for 1 account & 5 PCs, Macs, tablets, or smartphones.
+      Windows® | macOS® | Android™ | iOS®
     </bd-p>
-    
-    <bd-h as="h2">Threat Prevention Strategies</bd-h>
-    <bd-p kind="large" style="margin-bottom: 1rem;">
-      Implementing proactive security measures is essential for preventing cyber attacks before they can cause damage to your systems and data.
-    </bd-p>
-    <bd-p kind="regular" style="margin-bottom: 2rem;">
-      Regular software updates, strong password policies, and employee training form the foundation of effective threat prevention. These basic measures, when consistently applied, can prevent the majority of common cyber attacks targeting organizations today.
-    </bd-p>
-    
-    <bd-h as="h3">Real-time Monitoring</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
-      Continuous monitoring of network traffic and system activities allows for immediate detection of suspicious behavior and potential security breaches.
-    </bd-p>
-    <bd-p kind="small" style="color: #64748b; margin-bottom: 2rem;">
-      Monitoring systems should be configured to alert security personnel of any anomalous activities that deviate from established baseline patterns.
-    </bd-p>
-    
-    <bd-h as="h2">Incident Response Planning</bd-h>
-    <bd-p kind="regular" style="margin-bottom: 1.5rem;">
-      Having a well-defined incident response plan ensures that your organization can quickly and effectively respond to security incidents when they occur.
-    </bd-p>
-    <bd-p kind="small" style="color: #64748b;">
-      Response plans should include clear escalation procedures, communication protocols, and recovery steps tailored to different types of security incidents.
-    </bd-p>
-  </div>
-`;
-ContentHierarchy.parameters = {
-  docs: {
-    description: {
-      story: 'Demonstrates proper content hierarchy using different paragraph variants in combination with headings. Shows how lead, large, regular, and small paragraphs work together to create clear information structure and reading flow.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Small kind used as a product disclaimer below pricing or CTA buttons.' } } }
 };
 
-export const InCardContext = () => html`
-  <div style="max-width: 1000px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2" style="margin-bottom: 2rem; text-align: center;">Security Product Features</bd-h>
-    
-    <bd-card-section title="Core Protection Features">
-      <bd-card-item 
-        title="Advanced Threat Detection" 
-        icon="/api/placeholder/40/40"
-        align="center"
-      >
-        <bd-p kind="lead" style="text-align: center;">Real-time protection against evolving cyber threats</bd-p>
-        <bd-p kind="regular" style="text-align: center;">
-          Comprehensive security against malware, ransomware, and online threats with advanced behavioral analysis and machine learning algorithms.
-        </bd-p>
-        <bd-p kind="small" style="text-align: center; color: #64748b;">
-          Includes automatic threat detection, quarantine, and removal capabilities
-        </bd-p>
-      </bd-card-item>
-
-      <bd-card-item 
-        title="Privacy & Identity Protection" 
-        icon="/api/placeholder/40/40"
-        align="center"
-      >
-        <bd-p kind="large" style="text-align: center;">Safeguard your personal information</bd-p>
-        <bd-p kind="regular" style="text-align: center;">
-          VPN, password manager, and webcam protection work together to keep your data secure from unauthorized access and identity theft.
-        </bd-p>
-        <bd-p kind="small" style="text-align: center; color: #64748b;">
-          Military-grade encryption for all sensitive data transmission
-        </bd-p>
-      </bd-card-item>
-
-      <bd-card-item 
-        title="Performance Optimization" 
-        icon="/api/placeholder/40/40"
-        align="center"
-      >
-        <bd-p kind="regular" style="text-align: center;">
-          Lightweight design ensures minimal impact on system resources while providing maximum protection and security coverage.
-        </bd-p>
-        <bd-p kind="small" style="text-align: center; color: #64748b;">
-          Average CPU usage: less than 2% • Memory usage: ~150MB
-        </bd-p>
-        <bd-p kind="small" style="text-align: center; color: #64748b;">
-          Compatible with all major operating systems and devices
-        </bd-p>
-      </bd-card-item>
-    </bd-card-section>
-  </div>
-`;
-InCardContext.parameters = {
-  docs: {
-    description: {
-      story: 'Real-world example showing paragraph variants used within card components. Demonstrates how different paragraph sizes create clear hierarchy and improve content organization in feature cards and product descriptions.'
-    }
-  }
-};
-
-export const AccessibilityGuidelines = () => html`
-  <div style="max-width: 800px; margin: 0 auto; padding: 2rem;">
-    <bd-h as="h2">Accessibility Best Practices</bd-h>
-    
-    <bd-p kind="lead" style="margin-bottom: 2rem;">
-      Proper paragraph styling is essential for creating accessible, readable content that works well for all users, including those with visual impairments or reading difficulties.
-    </bd-p>
-    
-    <div style="background: #f0f9ff; padding: 2rem; border-radius: 8px; margin-bottom: 2rem;">
-      <bd-h as="h3" style="color: #0369a1;">✅ Accessible Typography</bd-h>
-      <bd-p kind="regular" style="margin-bottom: 1rem;">
-        All paragraph variants maintain WCAG AA compliance for contrast ratios and readability. The typographic scale ensures comfortable reading experiences across different content types.
-      </bd-p>
-      <bd-p kind="small" style="color: #64748b;">
-        • Minimum contrast ratio of 4.5:1 for normal text<br>
-        • Line height optimized for readability<br>
-        • Responsive font sizes for different viewports<br>
-        • Clear hierarchy without relying solely on color
-      </bd-p>
-    </div>
-    
-    <div style="background: #f8fafc; padding: 2rem; border-radius: 8px;">
-      <bd-h as="h3" style="color: #374151;">Screen Reader Compatibility</bd-h>
-      <bd-p kind="regular" style="margin-bottom: 1rem;">
-        Paragraph components provide proper semantic structure and are fully compatible with screen readers and other assistive technologies.
-      </bd-p>
-      <bd-p kind="small" style="color: #64748b;">
-        • Semantic HTML structure<br>
-        • Proper heading and paragraph relationships<br>
-        • Logical reading order<br>
-        • Support for text resizing and zooming
-      </bd-p>
+export const MultiParagraph = {
+  name  : 'Multiple Paragraphs',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:12px;">
+      <bd-p kind="large">Complete protection for your digital life.</bd-p>
+      <bd-p kind="regular">Bitdefender Total Security combines award-winning antivirus protection with advanced features including VPN, parental controls, and identity protection.</bd-p>
+      <bd-p kind="small">Available on Windows, macOS, Android, and iOS. Subscription required.</bd-p>
     </div>
-  </div>
-`;
-AccessibilityGuidelines.parameters = {
-  docs: {
-    description: {
-      story: 'Accessibility guidelines and best practices for paragraph components, including contrast ratios, readability optimization, screen reader compatibility, and semantic HTML structure considerations.'
-    }
-  }
+  `,
+  parameters: { docs: { description: { story: 'Three paragraphs of different kinds used together as a typical content block.' } } }
 };
 
-export const InteractivePlayground = Template.bind({});
-InteractivePlayground.args = {
-  kind   : 'regular',
-  align  : 'left',
-  color  : '',
-  content: 'Customize this paragraph to see how different variants, alignments, and colors affect the appearance and readability of your text content.'
-};
-InteractivePlayground.parameters = {
-  docs: {
-    description: {
-      story: 'Interactive playground where you can test all paragraph properties in real-time. Use the controls panel to modify the paragraph variant, alignment, color, and content to see immediate results.'
-    }
-  }
+export const Playground = {
+  name      : '🛝 Playground',
+  args      : { kind: 'regular' },
+  render    : (args) => html`<bd-p kind="${args.kind}">${sampleText}</bd-p>`,
+  parameters: { docs: { description: { story: 'Interactive playground. Switch between large, regular, and small via Controls.' } } }
 };