@repobit/dex-system-design 0.21.2 → 0.22.1

package/src/components/link/link.stories.js

@@ -6,38 +6,63 @@ import './link.js';
 export default {
   title    : 'Atoms/Link',
   component: 'bd-link',
+  tags     : ['autodocs'],
   argTypes : {
     href: {
       control    : 'text',
-      description: 'URL destination'
+      description: 'URL destination for the link',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '#' }
+      }
     },
     target: {
       control    : { type: 'select' },
       options    : ['_self', '_blank', '_parent', '_top'],
-      description: 'Link target attribute'
+      description: 'Link target attribute for browser behavior',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: '_self' }
+      }
     },
     kind: {
       control    : { type: 'select' },
       options    : ['primary', 'secondary', 'danger', 'subtle', 'bold'],
-      description: 'Link style variant'
+      description: 'Visual style variant for the link',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'primary' }
+      }
     },
     underline: {
       control    : 'boolean',
-      description: 'Always show underline'
+      description: 'Always show underline regardless of hover state',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: 'false' }
+      }
     },
     disabled: {
       control    : 'boolean',
-      description: 'Disabled state'
+      description: 'Disabled state that prevents interaction',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: 'false' }
+      }
     },
     content: {
       control    : 'text',
-      description: 'Link text content'
+      description: 'Link text content',
+      table      : {
+        type        : { summary: 'string' },
+        defaultValue: { summary: 'Link Text' }
+      }
     }
   },
   parameters: {
     docs: {
       description: {
-        component: 'A customizable link component with multiple style variants and accessibility features.'
+        component: 'A highly customizable link component with multiple visual variants, accessibility features, and interactive states. Supports both internal and external links with proper semantic HTML.'
       }
     }
   }
@@ -55,37 +80,91 @@ const Template = ({ href, target, kind, underline, disabled, content }) => html`
   </bd-link>
 `;
 
+// ============ STORIES ============
+
+export const Default = Template.bind({});
+Default.args = {
+  href     : '#',
+  target   : '_self',
+  kind     : 'primary',
+  underline: false,
+  disabled : false,
+  content  : 'Default Link'
+};
+Default.parameters = {
+  docs: {
+    description: {
+      story: 'Default link component with primary styling. This is the most commonly used link variant throughout the application.'
+    }
+  }
+};
+
 export const AllVariants = () => html`
-  <div style="display: flex; flex-direction: column; gap: 1rem; max-width: 600px;">
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="primary">primary link</bd-link> inside the text.</bd-p>
-    </div>
-    
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="secondary">secondary link</bd-link> inside the text.</bd-p>
-    </div>
-    
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="danger">danger link</bd-link> inside the text.</bd-p>
-    </div>
-    
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="subtle">subtle link</bd-link> inside the text.</bd-p>
-    </div>
-    
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="bold">bold link</bd-link> inside the text.</bd-p>
-    </div>
-    
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="primary" underline>underlined link</bd-link> inside the text.</bd-p>
-    </div>
+  <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 Link Variants</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 2rem;">
+      Explore all available link variants and their recommended use cases. Each variant is designed for specific contexts and user interactions.
+    </bd-p>
     
-    <div>
-      <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="primary" disabled>disabled link</bd-link> inside the text.</bd-p>
+    <div style="display: flex; flex-direction: column; gap: 1.5rem;">
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="primary">primary link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Primary:</strong> Main calls-to-action, important navigation, key features
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="secondary">secondary link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Secondary:</strong> Supporting links, less prominent actions, alternative navigation
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="danger">danger link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Danger:</strong> Destructive actions, warnings, critical operations, error states
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="subtle">subtle link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Subtle:</strong> Footer links, legal text, supplementary information, low emphasis
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="bold">bold link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Bold:</strong> High emphasis, featured content, important references, key highlights
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="primary" underline>underlined link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Underlined:</strong> Improved accessibility, formal content, academic references
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">This is a paragraph with a <bd-link href="#" kind="primary" disabled>disabled link</bd-link> inside the text.</bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          <strong>Disabled:</strong> Unavailable actions, conditional access, permission-based states
+        </bd-p>
+      </div>
     </div>
   </div>
 `;
+AllVariants.parameters = {
+  docs: {
+    description: {
+      story: 'Comprehensive overview of all link variants with detailed usage guidelines and context recommendations for each style option.'
+    }
+  }
+};
 
 export const Primary = Template.bind({});
 Primary.args = {
@@ -96,6 +175,13 @@ Primary.args = {
   disabled : false,
   content  : 'Primary Link'
 };
+Primary.parameters = {
+  docs: {
+    description: {
+      story: 'Primary link variant - Use for main calls-to-action, important navigation items, and key feature links. This is the default and most prominent link style.'
+    }
+  }
+};
 
 export const Secondary = Template.bind({});
 Secondary.args = {
@@ -106,6 +192,13 @@ Secondary.args = {
   disabled : false,
   content  : 'Secondary Link'
 };
+Secondary.parameters = {
+  docs: {
+    description: {
+      story: 'Secondary link variant - Ideal for supporting actions, less prominent navigation, and alternative pathways that don\'t require primary emphasis.'
+    }
+  }
+};
 
 export const Danger = Template.bind({});
 Danger.args = {
@@ -116,6 +209,47 @@ Danger.args = {
   disabled : false,
   content  : 'Danger Link'
 };
+Danger.parameters = {
+  docs: {
+    description: {
+      story: 'Danger link variant - Designed for destructive actions, warnings, critical operations, and error-related links. Use sparingly for high-attention scenarios.'
+    }
+  }
+};
+
+export const Subtle = Template.bind({});
+Subtle.args = {
+  href     : '#',
+  target   : '_self',
+  kind     : 'subtle',
+  underline: false,
+  disabled : false,
+  content  : 'Subtle Link'
+};
+Subtle.parameters = {
+  docs: {
+    description: {
+      story: 'Subtle link variant - Perfect for low-emphasis contexts like footer links, legal text, supplementary information, and non-critical references.'
+    }
+  }
+};
+
+export const Bold = Template.bind({});
+Bold.args = {
+  href     : '#',
+  target   : '_self',
+  kind     : 'bold',
+  underline: false,
+  disabled : false,
+  content  : 'Bold Link'
+};
+Bold.parameters = {
+  docs: {
+    description: {
+      story: 'Bold link variant - Use for high-emphasis scenarios, featured content, important references, and key highlights that need extra visual weight.'
+    }
+  }
+};
 
 export const WithUnderline = Template.bind({});
 WithUnderline.args = {
@@ -126,6 +260,13 @@ WithUnderline.args = {
   disabled : false,
   content  : 'Underlined Link'
 };
+WithUnderline.parameters = {
+  docs: {
+    description: {
+      story: 'Link with forced underline - Improves accessibility and clarity, especially useful in formal content, academic references, and dense text blocks.'
+    }
+  }
+};
 
 export const Disabled = Template.bind({});
 Disabled.args = {
@@ -136,42 +277,231 @@ Disabled.args = {
   disabled : true,
   content  : 'Disabled Link'
 };
+Disabled.parameters = {
+  docs: {
+    description: {
+      story: 'Disabled link state - Shows unavailable actions while maintaining visual context. Automatically prevents clicks and maintains semantic structure.'
+    }
+  }
+};
+
+export const TargetOptions = () => 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;">Link Target Options</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1rem;">
+      Different target attributes control how links open in the browser. Choose the appropriate option based on user experience needs.
+    </bd-p>
+    
+    <div style="display: flex; flex-direction: column; gap: 1rem;">
+      <div>
+        <bd-link href="https://example.com" target="_self" kind="primary">
+          _self - Opens in same tab/window
+        </bd-link>
+        <bd-p kind="small" style="color: #64748b;">
+          Default behavior. Use for internal navigation and same-context links.
+        </bd-p>
+      </div>
+      
+      <div>
+        <bd-link href="https://example.com" target="_blank" kind="secondary">
+          _blank - Opens in new tab
+        </bd-link>
+        <bd-p kind="small" style="color: #64748b;">
+          For external links, references, and resources that shouldn\'t interrupt user flow.
+        </bd-p>
+      </div>
+      
+      <div>
+        <bd-link href="https://example.com" target="_parent" kind="subtle">
+          _parent - Opens in parent frame
+        </bd-link>
+        <bd-p kind="small" style="color: #64748b;">
+          Specific to frame-based layouts. Rarely used in modern web applications.
+        </bd-p>
+      </div>
+      
+      <div>
+        <bd-link href="https://example.com" target="_top" kind="subtle">
+          _top - Opens in full window
+        </bd-link>
+        <bd-p kind="small" style="color: #64748b;">
+          Breaks out of frames to full browser window. Useful in embedded contexts.
+        </bd-p>
+      </div>
+    </div>
+  </div>
+`;
+TargetOptions.parameters = {
+  docs: {
+    description: {
+      story: 'Demonstration of different target attributes and their browser behaviors with recommendations for when to use each option based on user experience considerations.'
+    }
+  }
+};
 
 export const ExternalLinks = () => html`
-  <div style="display: flex; flex-direction: column; gap: 1rem;">
-    <bd-link href="https://example.com" target="_blank" kind="primary">
-      External Primary Link
-    </bd-link>
+  <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;">External Link Examples</bd-h>
+    <bd-p kind="regular" style="margin-bottom: 1rem;">
+      External links typically open in new tabs to prevent users from leaving your application. Here are common patterns for external references.
+    </bd-p>
     
-    <bd-link href="https://example.com" target="_blank" kind="secondary" underline>
-      External Underlined Link
-    </bd-link>
+    <div style="display: flex; flex-direction: column; gap: 1.5rem;">
+      <div>
+        <bd-link href="https://example.com" target="_blank" kind="primary">
+          External Primary Link with Security
+        </bd-link>
+        <bd-p kind="small" style="color: #64748b;">
+          Opens in new tab with proper security attributes for external resources.
+        </bd-p>
+      </div>
+      
+      <div>
+        <bd-link href="https://example.com" target="_blank" kind="secondary" underline>
+          External Underlined Reference
+        </bd-link>
+        <bd-p kind="small" style="color: #64748b;">
+          Clear visual indication for external academic or reference material.
+        </bd-p>
+      </div>
+      
+      <div style="border: 2px solid #e2e8f0; padding: 1.5rem; border-radius: 8px;">
+        <bd-p kind="regular">
+          This is a paragraph with an <bd-link href="https://example.com" target="_blank" kind="primary">external link</bd-link> that opens in a new tab for better user experience and flow preservation.
+        </bd-p>
+        <bd-p kind="small" style="color: #64748b; margin-top: 0.5rem;">
+          Best practice: Use target="_blank" for all external links to keep users in your application context.
+        </bd-p>
+      </div>
+    </div>
+  </div>
+`;
+ExternalLinks.parameters = {
+  docs: {
+    description: {
+      story: 'Examples and best practices for external links, including security considerations, user experience patterns, and visual styling recommendations for outbound navigation.'
+    }
+  }
+};
+
+export const AccessibilityExamples = () => 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;">Accessibility Guidelines</bd-h>
     
-    <bd-p kind="regular">
-      This is a paragraph with an <bd-link href="https://example.com" target="_blank" kind="primary">external link</bd-link> that opens in a new tab.
-    </bd-p>
+    <div style="border: 2px solid #10b981; padding: 2rem; border-radius: 12px; background: #f0fdf4;">
+      <bd-h as="h3" style="color: #059669; margin-bottom: 1rem;">✅ Accessible Link Practices</bd-h>
+      
+      <div style="display: flex; flex-direction: column; gap: 1rem;">
+        <div>
+          <bd-p kind="regular"><strong>Descriptive Text:</strong> Always use meaningful link text that makes sense out of context.</bd-p>
+          <bd-p kind="small" style="color: #059669;">
+            ✅ <bd-link href="#" kind="primary">Download security whitepaper</bd-link><br>
+            ❌ <bd-link href="#" kind="danger">Click here</bd-link>
+          </bd-p>
+        </div>
+        
+        <div>
+          <bd-p kind="regular"><strong>Underline for Clarity:</strong> Use underlined links in paragraphs for better visual identification.</bd-p>
+          <bd-p kind="small" style="color: #059669;">
+            This <bd-link href="#" kind="primary" underline>underlined link</bd-link> is easier to identify in text blocks.
+          </bd-p>
+        </div>
+        
+        <div>
+          <bd-p kind="regular"><strong>Color Contrast:</strong> All link variants maintain WCAG AA contrast ratios.</bd-p>
+          <bd-p kind="small" style="color: #059669;">
+            Tested for accessibility: <bd-link href="#" kind="subtle">Subtle</bd-link>, <bd-link href="#" kind="primary">Primary</bd-link>, <bd-link href="#" kind="danger">Danger</bd-link>
+          </bd-p>
+        </div>
+        
+        <div>
+          <bd-p kind="regular"><strong>Focus Indicators:</strong> Clear focus rings for keyboard navigation.</bd-p>
+          <bd-p kind="small" style="color: #059669;">
+            Try tabbing through these links to see the focus indicators.
+          </bd-p>
+        </div>
+      </div>
+    </div>
+    
+    <div style="border: 2px solid #e2e8f0; padding: 2rem; border-radius: 12px;">
+      <bd-h as="h3" style="color: #3b82f6; margin-bottom: 1rem;">Screen Reader Considerations</bd-h>
+      <bd-p kind="regular" style="margin-bottom: 1rem;">
+        Links provide proper semantic information for assistive technologies:
+      </bd-p>
+      
+      <ul style="color: #374151; margin-left: 1.5rem;">
+        <li style="margin-bottom: 0.5rem;">Disabled links become <code>&lt;span&gt;</code> elements to prevent interaction</li>
+        <li style="margin-bottom: 0.5rem;">External links should include visual or textual indicators</li>
+        <li style="margin-bottom: 0.5rem;">Link text should be unique and descriptive</li>
+        <li>Focus management works correctly with keyboard navigation</li>
+      </ul>
+    </div>
   </div>
 `;
+AccessibilityExamples.parameters = {
+  docs: {
+    description: {
+      story: 'Comprehensive accessibility guidelines and best practices for link components, including screen reader compatibility, keyboard navigation, color contrast, and semantic HTML structure.'
+    }
+  }
+};
 
 export const InContext = () => html`
-  <div style="max-width: 600px;">
-    <bd-h as="h2">Cybersecurity Features</bd-h>
+  <div style="max-width: 800px; margin: 0 auto; padding: 2rem;">
+    <bd-h as="h2">Cybersecurity Features Documentation</bd-h>
     
     <bd-p kind="lead">
       Protect your digital life with our comprehensive security solutions. 
-      Learn more about <bd-link href="#" kind="primary">threat protection</bd-link> 
-      and <bd-link href="#" kind="bold">advanced features</bd-link>.
+      Learn more about <bd-link href="#" kind="primary">advanced threat protection</bd-link> 
+      and <bd-link href="#" kind="bold">real-time monitoring features</bd-link>.
     </bd-p>
     
     <bd-p kind="regular">
-      Our <bd-link href="#" kind="danger">emergency response</bd-link> team is available 24/7 
+      Our <bd-link href="#" kind="danger">emergency response team</bd-link> is available 24/7 
       to handle security incidents. For less urgent matters, check our 
-      <bd-link href="#" kind="subtle">knowledge base</bd-link>.
+      <bd-link href="#" kind="subtle">comprehensive knowledge base</bd-link> or 
+      <bd-link href="#" kind="secondary">community support forums</bd-link>.
     </bd-p>
     
-    <bd-p kind="small">
-      <bd-link href="#" kind="secondary" underline>Terms of service</bd-link> • 
-      <bd-link href="#" kind="secondary" underline>Privacy policy</bd-link>
+    <bd-h as="h3" style="margin-top: 2rem;">Additional Resources</bd-h>
+    
+    <bd-p kind="regular">
+      Download our <bd-link href="#" kind="primary" underline>security best practices guide</bd-link> 
+      or explore <bd-link href="https://example.com" target="_blank" kind="secondary">external security resources</bd-link> 
+      for more in-depth information.
     </bd-p>
+    
+    <div style="margin-top: 2rem; padding-top: 1rem; border-top: 1px solid #e2e8f0;">
+      <bd-p kind="small">
+        <bd-link href="#" kind="subtle" underline>Terms of service</bd-link> • 
+        <bd-link href="#" kind="subtle" underline>Privacy policy</bd-link> • 
+        <bd-link href="#" kind="subtle" underline>Cookie policy</bd-link> • 
+        <bd-link href="#" kind="subtle" underline>Contact support</bd-link>
+      </bd-p>
+    </div>
   </div>
-`;
+`;
+InContext.parameters = {
+  docs: {
+    description: {
+      story: 'Real-world example showing links used in various contexts including content paragraphs, feature descriptions, resource references, and footer navigation with appropriate variant selection.'
+    }
+  }
+};
+
+export const InteractivePlayground = Template.bind({});
+InteractivePlayground.args = {
+  href     : '#',
+  target   : '_self',
+  kind     : 'primary',
+  underline: false,
+  disabled : false,
+  content  : 'Customize This Link'
+};
+InteractivePlayground.parameters = {
+  docs: {
+    description: {
+      story: 'Interactive playground where you can test all link properties in real-time. Use the controls panel to modify the link variant, target, underline, disabled state, and content.'
+    }
+  }
+};

package/src/components/paragraph/paragraph.css.js

@@ -9,7 +9,7 @@ export default css`
     all: unset;
     display: block;
     font-family: var(--typography-body-regular-fontFamily, var(--typography-fontFamily-sans));
-    color: var(--color-neutral-900);
+    // color: var(--color-neutral-900);
     margin-bottom: var(--spacing-md);
   }