@repobit/dex-system-design 0.22.11 → 0.23.1

package/src/components/carousel/carousel.stories.js

@@ -1,233 +1,204 @@
-import { html } from "lit";
-import "../heading/heading.js";
-import "../paragraph/paragraph.js";
-
-import "./carousel.js";
+import { html } from 'lit';
+import './carousel.js';
 
 export default {
-  title    : "Components/Carousel Section",
-  component: "bd-carousel-section",
-  tags     : ["autodocs"],
-  argTypes : {
-    title: { control: "text" },
-
-    // Item 1
-    item1Title    : { control: "text", name: "Item 1 Title" },
-    item1SubTitle : { control: "text", name: "Item 1 SubTitle" },
-    item1ModalText: { control: "text", name: "Item 1 Modal Text" },
-    item1Icon     : { control: "text", name: "Item 1 Icon" },
-    item1Content  : { control: "text", name: "Item 1 Content (use \\n\\n for paragraphs)" },
-
-    // Item 2
-    item2Title    : { control: "text", name: "Item 2 Title" },
-    item2SubTitle : { control: "text", name: "Item 2 SubTitle" },
-    item2ModalText: { control: "text", name: "Item 2 Modal Text" },
-    item2Icon     : { control: "text", name: "Item 2 Icon" },
-    item2Content  : { control: "text", name: "Item 2 Content (use \\n\\n for paragraphs)" },
-
-    // Item 3
-    item3Title    : { control: "text", name: "Item 3 Title" },
-    item3SubTitle : { control: "text", name: "Item 3 SubTitle" },
-    item3ModalText: { control: "text", name: "Item 3 Modal Text" },
-    item3Icon     : { control: "text", name: "Item 3 Icon" },
-    item3Content  : { control: "text", name: "Item 3 Content (use \\n\\n for paragraphs)" },
-
-    // Item 4
-    item4Title    : { control: "text", name: "Item 4 Title" },
-    item4SubTitle : { control: "text", name: "Item 4 SubTitle" },
-    item4ModalText: { control: "text", name: "Item 4 Modal Text" },
-    item4Icon     : { control: "text", name: "Item 4 Icon" },
-    item4Content  : { control: "text", name: "Item 4 Content (use \\n\\n for paragraphs)" },
-
-    // Item 5
-    item5Title    : { control: "text", name: "Item 5 Title" },
-    item5SubTitle : { control: "text", name: "Item 5 SubTitle" },
-    item5ModalText: { control: "text", name: "Item 5 Modal Text" },
-    item5Icon     : { control: "text", name: "Item 5 Icon" },
-    item5Content  : { control: "text", name: "Item 5 Content (use \\n\\n for paragraphs)" },
-
-    // Item 6
-    item6Title    : { control: "text", name: "Item 6 Title" },
-    item6SubTitle : { control: "text", name: "Item 6 SubTitle" },
-    item6ModalText: { control: "text", name: "Item 6 Modal Text" },
-    item6Icon     : { control: "text", name: "Item 6 Icon" },
-    item6Content  : { control: "text", name: "Item 6 Content (use \\n\\n for paragraphs)" },
-
-    // Item 7
-    item7Title    : { control: "text", name: "Item 7 Title" },
-    item7SubTitle : { control: "text", name: "Item 7 SubTitle" },
-    item7ModalText: { control: "text", name: "Item 7 Modal Text" },
-    item7Icon     : { control: "text", name: "Item 7 Icon" },
-    item7Content  : { control: "text", name: "Item 7 Content (use \\n\\n for paragraphs)" },
-
-    // Item 8
-    item8Title    : { control: "text", name: "Item 8 Title" },
-    item8SubTitle : { control: "text", name: "Item 8 SubTitle" },
-    item8ModalText: { control: "text", name: "Item 8 Modal Text" },
-    item8Icon     : { control: "text", name: "Item 8 Icon" },
-    item8Content  : { control: "text", name: "Item 8 Content (use \\n\\n for paragraphs)" }
+  title     : 'Components/Carousel',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**CustomCarousel** and **CarouselItem** are Lit components for a scrollable, draggable card carousel with modal support.
+
+- \`<bd-carousel-section>\` — scrollable container with left/right arrows and optional title
+- \`<bd-carousel-item>\` — individual card with icon, slotted content, and a \`+\` button to open a modal
+
+### Usage
+\`\`\`html
+<bd-carousel-section title="Security Features">
+  <bd-carousel-item title="VPN" icon="/assets/vpn.svg" modalText="Our VPN protects your connection.">
+    <p>Unlimited VPN included</p>
+  </bd-carousel-item>
+</bd-carousel-section>
+\`\`\`
+
+### Behavior
+- Left/right arrows scroll by one item width with smooth scroll
+- Arrows disable automatically at scroll boundaries
+- Click and drag (mouse + touch) supported for scrolling
+- Clicking \`+\` on an item fires \`open-modal\` custom event, caught by the carousel to show \`<bd-modal>\`
+- Modal closes via \`close-modal\` event
+
+### Keyboard Support
+- Arrow buttons respond to Enter/Space
+- \`+\` button on items responds to Enter/Space
+        `
+      }
+    }
+  },
+  argTypes: {
+    title: {
+      control    : 'text',
+      description: 'Optional section title rendered as `<h1>` above the carousel track',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'CarouselSection' }
+    },
+    itemTitle: {
+      control    : 'text',
+      description: 'Title of a carousel item, shown in the modal header',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'CarouselItem' }
+    },
+    itemIcon: {
+      control    : 'text',
+      description: 'Path to the icon image shown at the top of a carousel item',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'CarouselItem' }
+    },
+    modalText: {
+      control    : 'text',
+      description: 'Text passed to the modal when the `+` button is clicked',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'CarouselItem' }
+    }
   }
 };
 
-const renderParagraphs = (text) =>
-  text
-    ? text.split("\n\n").map(
-      (paragraph) => html`<bd-p>${paragraph}</bd-p>`
-    )
-    : null;
-
-const Template = (args) => html`
-  <bd-carousel-section title="${args.title}">
-    <bd-carousel-item
-      title="${args.item1Title}"
-      subTitle="${args.item1SubTitle}"
-      modalText="${args.item1ModalText}"
-      icon="${args.item1Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item1Title}</bd-h>
-      ${renderParagraphs(args.item1Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item2Title}"
-      subTitle="${args.item2SubTitle}"
-      modalText="${args.item2ModalText}"
-      icon="${args.item2Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item2Title}</bd-h>
-      ${renderParagraphs(args.item2Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item3Title}"
-      subTitle="${args.item3SubTitle}"
-      modalText="${args.item3ModalText}"
-      icon="${args.item3Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item3Title}</bd-h>
-      ${renderParagraphs(args.item3Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item4Title}"
-      subTitle="${args.item4SubTitle}"
-      modalText="${args.item4ModalText}"
-      icon="${args.item4Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item4Title}</bd-h>
-      ${renderParagraphs(args.item4Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item5Title}"
-      subTitle="${args.item5SubTitle}"
-      modalText="${args.item5ModalText}"
-      icon="${args.item5Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item5Title}</bd-h>
-      ${renderParagraphs(args.item5Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item6Title}"
-      subTitle="${args.item6SubTitle}"
-      modalText="${args.item6ModalText}"
-      icon="${args.item6Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item6Title}</bd-h>
-      ${renderParagraphs(args.item6Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item7Title}"
-      subTitle="${args.item7SubTitle}"
-      modalText="${args.item7ModalText}"
-      icon="${args.item7Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item7Title}</bd-h>
-      ${renderParagraphs(args.item7Content)}
-    </bd-carousel-item>
-
-    <bd-carousel-item
-      title="${args.item8Title}"
-      subTitle="${args.item8SubTitle}"
-      modalText="${args.item8ModalText}"
-      icon="${args.item8Icon}"
-    >
-      <bd-h as="h4" padding="10px 0">${args.item8Title}</bd-h>
-      ${renderParagraphs(args.item8Content)}
-    </bd-carousel-item>
-  </bd-carousel-section>
+const sampleItems = [
+  { title: 'VPN Protection',       icon: '/assets/vpn.svg',       modalText: 'Our VPN encrypts your internet traffic and hides your IP address.',       content: 'Unlimited encrypted VPN traffic' },
+  { title: 'Antivirus',            icon: '/assets/antivirus.svg', modalText: 'Real-time antivirus protection against all known and emerging threats.',    content: 'Award-winning threat detection' },
+  { title: 'Password Manager',     icon: '/assets/password.svg',  modalText: 'Store and autofill all your passwords securely across all devices.',        content: 'Secure password vault' },
+  { title: 'Parental Controls',    icon: '/assets/parental.svg',  modalText: 'Monitor and control your children\'s online activity and screen time.',     content: 'Advanced content filtering' },
+  { title: 'Anti-Phishing',        icon: '/assets/phishing.svg',  modalText: 'Detects and blocks phishing websites before they can steal your data.',     content: 'Real-time phishing protection' },
+  { title: 'Webcam Protection',    icon: '/assets/webcam.svg',    modalText: 'Prevents unauthorized apps from accessing your webcam.',                    content: 'Webcam & mic access control' }
+];
+
+const renderItem = (item) => html`
+  <bd-carousel-item title="${item.title}" icon="${item.icon}" modalText="${item.modalText}">
+    <p>${item.content}</p>
+  </bd-carousel-item>
 `;
 
-export const Default = Template.bind({});
-Default.args = {
-  title: "Need help? We've got answers!",
-
-  item1Title: "Scam Copilot Bot",
-  item1SubTitle:
-    "Specialized AI chatbot that helps you identify suspicious online interactions so you don't become a victim",
-  item1ModalText:
-    "Specialized AI chatbot that helps you identify suspicious online interactions so you don't become a victim",
-  item1Icon   : "/assets/light-carousel-img1.png",
-  item1Content: `Specialized AI chatbot that helps you identify suspicious online interactions so you don't become a victim.\n\nSpecialized AI chatbot that helps you identify suspicious online interactions so you don't become a victim.\n\nTest Scam Copilot Bot`,
-
-  item2Title    : "Scam Wave Alerts",
-  item2SubTitle : "Proactively informs you about scam outbreaks in your region",
-  item2ModalText: "Proactively informs you about scam outbreaks in your region",
-  item2Icon     : "/assets/light-carousel-img1.png",
-  item2Content  : "Proactively informs you about scam outbreaks in your region.",
-
-  item3Title: "AI-Powered Scam Check",
-  item3SubTitle:
-    "AI-driven tool that instantly evaluates the legitimacy of any link, message, or online interaction",
-  item3ModalText:
-    "AI-driven tool that instantly evaluates the legitimacy of any link, message, or online interaction",
-  item3Icon: "/assets/light-carousel-img1.png",
-  item3Content:
-    "AI-driven tool that instantly evaluates the legitimacy of any link, message, or online interaction.",
-
-  item4Title: "Educational Resources",
-  item4SubTitle:
-    "Access a wealth of information and best practices to stay informed and vigilant against scams",
-  item4ModalText:
-    "Access a wealth of information and best practices to stay informed and vigilant against scams",
-  item4Icon: "/assets/light-carousel-img1.png",
-  item4Content:
-    "Access a wealth of information and best practices to stay informed and vigilant against scams.",
-
-  item5Title: "Phishing Simulator",
-  item5SubTitle:
-    "Simulates phishing attacks to help you recognize and respond appropriately to real threats",
-  item5ModalText:
-    "Simulates phishing attacks to help you recognize and respond appropriately to real threats",
-  item5Icon: "/assets/light-carousel-img1.png",
-  item5Content:
-    "Simulates phishing attacks to help you recognize and respond appropriately to real threats.",
-
-  item6Title: "Real-Time Scam Updates",
-  item6SubTitle:
-    "Stay ahead with up-to-the-minute alerts on the latest scams targeting your region or industry",
-  item6ModalText:
-    "Stay ahead with up-to-the-minute alerts on the latest scams targeting your region or industry",
-  item6Icon: "/assets/light-carousel-img1.png",
-  item6Content:
-    "Stay ahead with up-to-the-minute alerts on the latest scams targeting your region or industry.",
-
-  item7Title: "Community Reporting Hub",
-  item7SubTitle:
-    "A platform where users can report scams and share experiences to help protect others",
-  item7ModalText:
-    "A platform where users can report scams and share experiences to help protect others",
-  item7Icon   : "/assets/light-carousel-img1.png",
-  item7Content: "A platform where users can report scams and share experiences to help protect others.",
-
-  item8Title: "Fraud Prevention Workshops",
-  item8SubTitle:
-    "Interactive workshops that educate users on identifying and avoiding scams",
-  item8ModalText:
-    "Interactive workshops that educate users on identifying and avoiding scams",
-  item8Icon: "/assets/light-carousel-img1.png",
-  item8Content:
-    "Interactive workshops that educate users on identifying and avoiding scams."
+// ─── Stories ───────────────────────────────────────────────────────────────
+
+export const Default = {
+  name  : 'Default (6 items)',
+  render: () => html`
+    <bd-carousel-section title="Security Features">
+      ${sampleItems.map(renderItem)}
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: '6-item carousel with title. Scroll with arrows or drag.' } } }
+};
+
+export const NoTitle = {
+  name  : 'No Section Title',
+  render: () => html`
+    <bd-carousel-section>
+      ${sampleItems.map(renderItem)}
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Carousel without a title — the header `<div>` is conditionally omitted.' } } }
+};
+
+export const FewItems = {
+  name  : 'Few Items (2)',
+  render: () => html`
+    <bd-carousel-section title="Features">
+      ${sampleItems.slice(0, 2).map(renderItem)}
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Only 2 items — right arrow should be disabled if all items fit in view.' } } }
+};
+
+export const SingleItem = {
+  name  : 'Single Item (edge case)',
+  render: () => html`
+    <bd-carousel-section title="Features">
+      ${renderItem(sampleItems[0])}
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Edge case with a single item. Both arrows should be disabled.' } } }
+};
+
+export const NoIcon = {
+  name  : 'Items Without Icons',
+  render: () => html`
+    <bd-carousel-section title="Features">
+      ${sampleItems.slice(0, 4).map(item => html`
+        <bd-carousel-item title="${item.title}" modalText="${item.modalText}">
+          <p>${item.content}</p>
+        </bd-carousel-item>
+      `)}
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Items with no `icon` prop — the `<img>` is conditionally omitted.' } } }
+};
+
+export const RichSlottedContent = {
+  name  : 'Rich Slotted Content',
+  render: () => html`
+    <bd-carousel-section title="Features">
+      <bd-carousel-item title="VPN" icon="/assets/vpn.svg" modalText="Full VPN details here.">
+        <ul>
+          <li>Unlimited bandwidth</li>
+          <li>200+ server locations</li>
+          <li>No-log policy</li>
+        </ul>
+      </bd-carousel-item>
+      <bd-carousel-item title="Antivirus" icon="/assets/antivirus.svg" modalText="Antivirus details here.">
+        <p>Real-time protection</p>
+        <a href="#">Learn more</a>
+      </bd-carousel-item>
+      <bd-carousel-item title="Parental Controls" icon="/assets/parental.svg" modalText="Parental control details.">
+        <p>Safe browsing for kids</p>
+        <p>Screen time management</p>
+      </bd-carousel-item>
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Items with lists, links, and multiple paragraphs as slotted content.' } } }
+};
+
+export const ModalTrigger = {
+  name  : 'Modal — Click + to Open',
+  render: () => html`
+    <p style="font-size:14px; margin-bottom:12px;">Click the <strong>+</strong> button on any card to open the modal.</p>
+    <bd-carousel-section title="Features">
+      ${sampleItems.slice(0, 3).map(renderItem)}
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Demonstrates the modal flow. Click `+` on a card to fire `open-modal`, which renders `<bd-modal>` with the item\'s title and modalText.' } } }
+};
+
+export const MobileView = {
+  name  : 'Mobile View (375px)',
+  render: () => html`
+    <bd-carousel-section title="Security Features">
+      ${sampleItems.map(renderItem)}
+    </bd-carousel-section>
+  `,
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+    docs    : { description: { story: 'Carousel at 375px. Touch drag scrolling is supported.' } }
+  }
+};
+
+export const Playground = {
+  name: '🛝 Playground',
+  args: {
+    title    : 'Security Features',
+    itemTitle: 'VPN Protection',
+    itemIcon : '/assets/vpn.svg',
+    modalText: 'Our VPN encrypts your connection and protects your privacy.'
+  },
+  render: (args) => html`
+    <bd-carousel-section title="${args.title}">
+      <bd-carousel-item title="${args.itemTitle}" icon="${args.itemIcon}" modalText="${args.modalText}">
+        <p>Slotted content for this item.</p>
+      </bd-carousel-item>
+      <bd-carousel-item title="Antivirus" icon="/assets/antivirus.svg" modalText="Real-time antivirus protection.">
+        <p>Award-winning threat detection</p>
+      </bd-carousel-item>
+      <bd-carousel-item title="Parental Controls" icon="/assets/parental.svg" modalText="Monitor your children's activity.">
+        <p>Advanced content filtering</p>
+      </bd-carousel-item>
+    </bd-carousel-section>
+  `,
+  parameters: { docs: { description: { story: 'Interactive playground. Modify the section title and first item props via Controls.' } } }
 };

package/src/components/checkbox/checkbox.stories.js

@@ -2,62 +2,147 @@ import { html } from 'lit';
 import './checkbox.js';
 
 export default {
-  title: 'Atoms/Checkbox',
-  component: 'bd-checkbox',
-  tags: ['autodocs'], // activează Docs
-  argTypes: {
-    name: { control: 'text' },
-    value: { control: 'text' },
-    label: { control: 'text' },
-    checked: { control: 'boolean' },
-    disabled: { control: 'boolean' },
+  title     : 'Components/Checkbox',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdCheckbox** is a fully accessible Lit checkbox component.
+
+### Usage
+\`\`\`html
+<bd-checkbox label="Accept terms" name="terms" value="accepted"></bd-checkbox>
+<bd-checkbox label="Disabled" disabled></bd-checkbox>
+<bd-checkbox label="Pre-checked" checked></bd-checkbox>
+\`\`\`
+
+### Accessibility
+- Uses \`role="checkbox"\` with \`aria-checked\` and \`aria-disabled\`
+- Keyboard support: Space and Enter toggle the checkbox
+- Focus ring appears only on keyboard navigation (Tab), not on mouse click
+- \`tabindex="-1"\` when disabled
+
+### Events
+- \`change\` — fires with \`detail: { value }\` where value is the checkbox's \`value\` prop when checked, or \`null\` when unchecked
+        `
+      }
+    }
   },
+  argTypes: {
+    label: {
+      control    : 'text',
+      description: 'Visible text label rendered next to the checkbox',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
+    },
+    name: {
+      control    : 'text',
+      description: 'Form field name',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Form' }
+    },
+    value: {
+      control    : 'text',
+      description: 'Value emitted in the `change` event detail when checked',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Form' }
+    },
+    checked: {
+      control    : 'boolean',
+      description: 'Whether the checkbox is checked',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    disabled: {
+      control    : 'boolean',
+      description: 'Disables interaction and applies disabled styles',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    }
+  }
 };
 
-// Template de bază
-const Template = ({ name, value, label, checked, disabled }) => html`
+const render = (args) => html`
   <bd-checkbox
-    .name=${name}
-    .value=${value}
-    .label=${label}
-    .checked=${checked}
-    .disabled=${disabled}
+    label="${args.label}"
+    name="${args.name}"
+    value="${args.value}"
+    ?checked="${args.checked}"
+    ?disabled="${args.disabled}"
   ></bd-checkbox>
 `;
 
-// Exemple BdCheckbox
-export const Default = Template.bind({});
-Default.args = {
-  name: 'group1',
-  value: 'default',
-  label: 'Checkbox normal',
-  checked: false,
-  disabled: false,
-};
-
-export const Checked = Template.bind({});
-Checked.args = {
-  name: 'group1',
-  value: 'checked',
-  label: 'Checkbox checked',
-  checked: true,
-  disabled: false,
-};
-
-export const Disabled = Template.bind({});
-Disabled.args = {
-  name: 'group1',
-  value: 'disabled',
-  label: 'Checkbox disabled',
-  checked: false,
-  disabled: true,
-};
-
-export const DisabledChecked = Template.bind({});
-DisabledChecked.args = {
-  name: 'group1',
-  value: 'disabled-checked',
-  label: 'Checkbox disabled & checked',
-  checked: true,
-  disabled: true,
+const defaultArgs = { label: 'Accept terms and conditions', name: 'terms', value: 'accepted', checked: false, disabled: false };
+
+// ─── Stories ───────────────────────────────────────────────────────────────
+
+export const Default = {
+  name      : 'Default (Unchecked)',
+  render    : () => html`<bd-checkbox label="Accept terms and conditions" name="terms" value="accepted"></bd-checkbox>`,
+  parameters: { docs: { description: { story: 'Default unchecked checkbox.' } } }
+};
+
+export const Checked = {
+  name      : 'Checked',
+  render    : () => html`<bd-checkbox label="I agree to the privacy policy" name="privacy" value="agreed" checked></bd-checkbox>`,
+  parameters: { docs: { description: { story: 'Checkbox pre-checked via the `checked` attribute.' } } }
+};
+
+export const Disabled = {
+  name      : 'Disabled (Unchecked)',
+  render    : () => html`<bd-checkbox label="This option is unavailable" name="unavailable" value="n/a" disabled></bd-checkbox>`,
+  parameters: { docs: { description: { story: 'Disabled checkbox — not interactable, `tabindex="-1"`, `aria-disabled="true"`.' } } }
 };
+
+export const DisabledChecked = {
+  name      : 'Disabled (Checked)',
+  render    : () => html`<bd-checkbox label="Already selected (locked)" name="locked" value="locked" checked disabled></bd-checkbox>`,
+  parameters: { docs: { description: { story: 'Disabled checkbox in the checked state — locked selection.' } } }
+};
+
+export const NoLabel = {
+  name      : 'No Label',
+  render    : () => html`<bd-checkbox name="no-label" value="yes"></bd-checkbox>`,
+  parameters: { docs: { description: { story: 'Checkbox with no visible label text.' } } }
+};
+
+export const AllStates = {
+  name  : 'All States',
+  render: () => html`
+    <div style="display:flex; flex-direction:column; gap:12px;">
+      <bd-checkbox label="Unchecked"          name="s1" value="1"></bd-checkbox>
+      <bd-checkbox label="Checked"            name="s2" value="2" checked></bd-checkbox>
+      <bd-checkbox label="Disabled unchecked" name="s3" value="3" disabled></bd-checkbox>
+      <bd-checkbox label="Disabled checked"   name="s4" value="4" checked disabled></bd-checkbox>
+    </div>
+  `,
+  parameters: { docs: { description: { story: 'All four checkbox states side by side: unchecked, checked, disabled unchecked, disabled checked.' } } }
+};
+
+export const Group = {
+  name  : 'Checkbox Group',
+  render: () => html`
+    <fieldset style="border:none; padding:0;">
+      <legend style="font-weight:600; margin-bottom:12px;">Select your platforms</legend>
+      <div style="display:flex; flex-direction:column; gap:8px;">
+        <bd-checkbox label="Windows" name="platform" value="windows" checked></bd-checkbox>
+        <bd-checkbox label="macOS"   name="platform" value="macos"></bd-checkbox>
+        <bd-checkbox label="Android" name="platform" value="android" checked></bd-checkbox>
+        <bd-checkbox label="iOS"     name="platform" value="ios"></bd-checkbox>
+      </div>
+    </fieldset>
+  `,
+  parameters: { docs: { description: { story: 'A group of checkboxes simulating a multi-select form field.' } } }
+};
+
+export const KeyboardFocus = {
+  name  : 'Keyboard Focus',
+  render: () => html`
+    <p style="font-size:14px; margin-bottom:8px;">Tab to focus, Space or Enter to toggle.</p>
+    <bd-checkbox label="Keyboard accessible checkbox" name="kb" value="kb"></bd-checkbox>
+  `,
+  parameters: { docs: { description: { story: 'Focus ring appears only via keyboard Tab navigation. Clicking with mouse does not show the focus ring.' } } }
+};
+
+export const Playground = {
+  name      : '🛝 Playground',
+  args      : { ...defaultArgs },
+  render,
+  parameters: { docs: { description: { story: 'Interactive playground. Toggle checked, disabled, and edit label/value via Controls.' } } }
+};