@arbor-education/design-system.components 0.15.0 → 0.16.0

package/dist/components/toggle/Toggle.stories.d.ts

@@ -1,35 +1,13 @@
 import type { StoryObj } from '@storybook/react-vite';
-/**
- * The Toggle component is a binary on/off switch, built on top of Radix UI's
- * Switch primitive. Think of it like the light switch in the St. Olaf town
- * hall — everyone in town knows exactly whether the lights are on or off,
- * and there is never any confusion about which state you are in.
- *
- * Toggling is the right choice when you need an immediate, binary setting
- * change — "dark mode on", "notifications off", "feature enabled". Unlike a
- * checkbox, a toggle implies the change takes effect right away, without
- * needing a form submission.
- *
- * **Accessibility**
- * - Rendered as a `<button role="switch">` — screen readers announce the
- *   current state ("checked" / "not checked") automatically.
- * - Fully keyboard accessible: `Space` or `Enter` toggles the state.
- * - Associate a visible label with the toggle using a `<label htmlFor={id}>`
- *   so users of all abilities know what they are toggling.
- * - The `disabled` prop renders the element as non-interactive and applies
- *   correct ARIA semantics.
- *
- * **CSS classes**
- * - Root element: `ds-toggle`
- * - Thumb (the sliding dot): `ds-toggle__thumb`
- * - Checked state is driven by Radix's `data-state="checked"` attribute,
- *   which the SCSS uses to apply brand colours and shift the thumb position.
- */
+declare function ToggleDocsPage(): import("react/jsx-runtime").JSX.Element;
 declare const meta: {
     title: string;
     component: (props: import("@radix-ui/react-switch").SwitchProps) => import("react/jsx-runtime").JSX.Element;
     parameters: {
         layout: string;
+        docs: {
+            page: typeof ToggleDocsPage;
+        };
     };
     tags: string[];
     args: {
@@ -39,58 +17,95 @@ declare const meta: {
         checked: {
             control: "boolean";
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
         defaultChecked: {
             control: "boolean";
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
         disabled: {
             control: "boolean";
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
         required: {
             control: "boolean";
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
         name: {
             control: "text";
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
         value: {
             control: "text";
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
         onCheckedChange: {
             action: string;
+            control: false;
             description: string;
+            table: {
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
         };
     };
 };
 export default meta;
 type Story = StoryObj<typeof meta>;
-/** The toggle in its default, unchecked (off) state. */
 export declare const Default: Story;
-/**
- * The toggle in its checked (on) state.
- *
- * Uses `defaultChecked` so the component manages its own state — perfect for
- * uncontrolled usage where you just need a sensible starting position.
- */
 export declare const Checked: Story;
-/**
- * A disabled toggle that is currently off.
- *
- * Use this when a setting exists but cannot be changed in the current context
- * — for example, a feature that requires a higher subscription tier.
- */
 export declare const Disabled: Story;
-/**
- * A disabled toggle that is currently on.
- *
- * This communicates "this setting is enabled, but you cannot change it right
- * now." Always pair a disabled toggle with a tooltip or helper text that
- * explains why it cannot be interacted with.
- */
 export declare const DisabledChecked: Story;
 export declare const Controlled: Story;
 export declare const WithLabel: Story;

package/dist/components/toggle/Toggle.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Toggle.stories.d.ts","sourceRoot":"","sources":["../../../src/components/toggle/Toggle.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAI5D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDqB,CAAC;AAEhC,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAMnC,wDAAwD;AACxD,eAAO,MAAM,OAAO,EAAE,KAAU,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,KAIrB,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,KAItB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,KAK7B,CAAC;AAoDF,eAAO,MAAM,UAAU,EAAE,KAExB,CAAC;AA6CF,eAAO,MAAM,SAAS,EAAE,KAEvB,CAAC"}
+{"version":3,"file":"Toggle.stories.d.ts","sourceRoot":"","sources":["../../../src/components/toggle/Toggle.stories.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAQ,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AA4F5D,iBAAS,cAAc,4CAmBtB;AAMD,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8FqB,CAAC;AAEhC,eAAe,IAAI,CAAC;AACpB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AA8FnC,eAAO,MAAM,OAAO,EAAE,KAKrB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,KAuBrB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,KAuBtB,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,KAwB7B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,KAsCxB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,KA0CvB,CAAC"}

package/dist/components/toggle/Toggle.stories.js

@@ -1,38 +1,94 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from 'react';
 import { fn } from 'storybook/test';
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
 import { Toggle } from './Toggle';
-/**
- * The Toggle component is a binary on/off switch, built on top of Radix UI's
- * Switch primitive. Think of it like the light switch in the St. Olaf town
- * hall — everyone in town knows exactly whether the lights are on or off,
- * and there is never any confusion about which state you are in.
- *
- * Toggling is the right choice when you need an immediate, binary setting
- * change — "dark mode on", "notifications off", "feature enabled". Unlike a
- * checkbox, a toggle implies the change takes effect right away, without
- * needing a form submission.
- *
- * **Accessibility**
- * - Rendered as a `<button role="switch">` — screen readers announce the
- *   current state ("checked" / "not checked") automatically.
- * - Fully keyboard accessible: `Space` or `Enter` toggles the state.
- * - Associate a visible label with the toggle using a `<label htmlFor={id}>`
- *   so users of all abilities know what they are toggling.
- * - The `disabled` prop renders the element as non-interactive and applies
- *   correct ARIA semantics.
- *
- * **CSS classes**
- * - Root element: `ds-toggle`
- * - Thumb (the sliding dot): `ds-toggle__thumb`
- * - Checked state is driven by Radix's `data-state="checked"` attribute,
- *   which the SCSS uses to apply brand colours and shift the thumb position.
- */
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'Toggle is an immediate binary on/off switch built on',
+    '[Radix UI Switch](https://www.radix-ui.com/primitives/docs/components/switch).',
+    'It communicates that a change takes effect instantly — without a form submission — making it the right',
+    'choice for settings toggles, feature flags, and preference switches.',
+].join(' ');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- **Immediate settings** — when flipping a switch takes effect right now (dark mode, notifications, feature enabled)',
+    '- **Binary state** — exactly two options: on and off, enabled and disabled',
+    '- **Standalone settings pages** — outside a form, where pressing Submit before seeing the effect would be jarring',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Situation | Use instead |',
+    '|---|---|',
+    '| Choice requires confirmation before taking effect | [`CheckboxInput`](?path=/docs/components-formfield-inputs-checkbox--docs) inside a form |',
+    '| Multiple related on/off items in a list | `CheckboxInput` group — clearer visual grouping |',
+    '| Part of a multi-field form submission | `CheckboxInput` — toggle implies instant action, not deferred submission |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical usage patterns',
+    '',
+    '**Always provide a visible label.** Toggle renders as a styled button with no visible text. Without a',
+    '`<label htmlFor={id}>`, sighted users see a switch with no explanation of what it controls. Screen',
+    'readers announce the state ("checked" / "not checked") but cannot convey the meaning without a label.',
+    '',
+    '**`checked` vs `defaultChecked`.** Use `defaultChecked` for uncontrolled usage where the component',
+    'manages its own state after mount. Use `checked` + `onCheckedChange` for controlled mode when you need',
+    'to read the value elsewhere in the UI or sync with external state.',
+    '',
+    '**`onCheckedChange` receives a boolean — not an event.** Unlike native checkbox `onChange`, this',
+    'callback receives the new boolean value directly: `(checked: boolean) => void`. No `event.target.checked`',
+    'unwrapping needed.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- Rendered as `<button role="switch">` — screen readers announce "checked" / "not checked" automatically',
+    '- Fully keyboard accessible: `Space` or `Enter` toggles the state',
+    '- Associate with `<label htmlFor={id}>` — clicking the label also toggles the switch (larger tap target)',
+    '- The `disabled` prop renders the element as truly non-interactive with correct ARIA semantics',
+    '',
+    '---',
+    '',
+    '### Design tokens used',
+    '',
+    '| Token | Usage |',
+    '|---|---|',
+    '| `--toggle-off-default-color-background` | Track background (unchecked) |',
+    '| `--toggle-on-default-color-background` | Track background (checked — brand colour) |',
+    '| `--toggle-off-disabled-color-background` | Track background (disabled) |',
+    '| `--toggle-radius` | Track border radius |',
+    '| `--toggle-weight-border` | Track border weight |',
+    '| `--border-radius-round` | Thumb shape (circular) |',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[CheckboxInput](?path=/docs/components-formfield-inputs-checkbox--docs) · [FormField](?path=/docs/components-formfield--docs) · [RadioButtonInput](?path=/docs/components-formfield-inputs-radio--docs)',
+].join('\n');
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+function ToggleDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     title: 'Components/Toggle',
     component: Toggle,
     parameters: {
         layout: 'centered',
+        docs: {
+            page: ToggleDocsPage,
+        },
     },
     tags: ['autodocs'],
     args: {
@@ -41,146 +97,279 @@ const meta = {
     argTypes: {
         checked: {
             control: 'boolean',
-            description: 'Controls the checked state when used as a controlled component. '
-                + 'Pair with `onCheckedChange` to keep your state in sync.',
+            description: [
+                'Controls the checked state when used as a controlled component.',
+                'Pair with `onCheckedChange` to keep your state in sync.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
         defaultChecked: {
             control: 'boolean',
-            description: 'Sets the initial checked state for an uncontrolled toggle. '
-                + 'The component manages its own state after mount.',
+            description: [
+                'Sets the initial checked state for an uncontrolled toggle.',
+                'The component manages its own state after mount.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
         disabled: {
             control: 'boolean',
-            description: 'Disables the toggle. The toggle becomes non-interactive and is '
-                + 'visually dimmed. Useful for read-only settings or permission-gated features.',
+            description: [
+                'Disables the toggle. The toggle becomes non-interactive and is visually dimmed.',
+                'Useful for read-only settings or permission-gated features.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
         required: {
             control: 'boolean',
-            description: 'Marks the toggle as required when used inside a `<form>`. '
-                + 'Prevents form submission if the toggle is unchecked.',
+            description: [
+                'Marks the toggle as required when used inside a `<form>`.',
+                'Prevents form submission if the toggle is unchecked.',
+            ].join(' '),
+            table: {
+                type: { summary: 'boolean' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
         name: {
             control: 'text',
-            description: 'The name of the toggle as submitted with form data. '
-                + 'Works the same as the `name` attribute on a native `<input>`.',
+            description: [
+                'The name of the toggle as submitted with form data.',
+                'Works the same as the `name` attribute on a native `<input>`.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
         value: {
             control: 'text',
-            description: 'The value submitted with form data when the toggle is checked. '
-                + 'Defaults to `"on"` (matching native checkbox behaviour).',
+            description: [
+                'The value submitted with form data when the toggle is checked.',
+                'Defaults to `"on"` (matching native checkbox behaviour).',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+                defaultValue: { summary: '"on"' },
+            },
         },
         onCheckedChange: {
             action: 'checkedChange',
-            description: 'Callback fired whenever the checked state changes. '
-                + 'Receives the new boolean value: `(checked: boolean) => void`.',
+            control: false,
+            description: [
+                'Callback fired whenever the checked state changes.',
+                'Receives the new boolean value directly: `(checked: boolean) => void`.',
+                'Unlike native checkbox `onChange`, there is no event object to unwrap.',
+            ].join(' '),
+            table: {
+                type: { summary: '(checked: boolean) => void' },
+                defaultValue: { summary: 'undefined' },
+            },
         },
     },
 };
 export default meta;
 // ---------------------------------------------------------------------------
-// Basic states
-// ---------------------------------------------------------------------------
-/** The toggle in its default, unchecked (off) state. */
-export const Default = {};
-/**
- * The toggle in its checked (on) state.
- *
- * Uses `defaultChecked` so the component manages its own state — perfect for
- * uncontrolled usage where you just need a sensible starting position.
- */
-export const Checked = {
-    args: {
-        defaultChecked: true,
-    },
-};
+// Helper
 // ---------------------------------------------------------------------------
-// Disabled states
-// ---------------------------------------------------------------------------
-/**
- * A disabled toggle that is currently off.
- *
- * Use this when a setting exists but cannot be changed in the current context
- * — for example, a feature that requires a higher subscription tier.
- */
-export const Disabled = {
-    args: {
-        disabled: true,
-    },
-};
-/**
- * A disabled toggle that is currently on.
- *
- * This communicates "this setting is enabled, but you cannot change it right
- * now." Always pair a disabled toggle with a tooltip or helper text that
- * explains why it cannot be interacted with.
- */
-export const DisabledChecked = {
-    args: {
-        defaultChecked: true,
-        disabled: true,
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
     },
-};
+});
 // ---------------------------------------------------------------------------
-// Controlled usage
+// Templates
 // ---------------------------------------------------------------------------
-/**
- * A fully controlled toggle backed by React state.
- *
- * Back in St. Olaf, my neighbour Hildegard Bjornsson kept a hand-written
- * ledger of every switch in her house — she never trusted a switch to remember
- * its own state! A controlled toggle is just like that ledger: your component
- * owns the truth, and the toggle simply displays what you tell it to.
- *
- * Use the controlled pattern when:
- * - You need to read the toggle state elsewhere in the UI.
- * - You want to conditionally show/hide other elements based on the state.
- * - You are submitting state as part of a larger form payload.
- */
 const ControlledTemplate = (args) => {
     const [enabled, setEnabled] = useState(false);
     return (_jsxs("div", { style: {
             display: 'flex',
             flexDirection: 'column',
             alignItems: 'center',
-            gap: '12px',
+            gap: 'var(--spacing-small)',
         }, children: [_jsx(Toggle, { ...args, checked: enabled, onCheckedChange: (checked) => {
                     setEnabled(checked);
                     args.onCheckedChange?.(checked);
                 } }), _jsx("p", { style: {
                     margin: 0,
-                    fontSize: '14px',
+                    fontSize: 'var(--font-size-2-13)',
                     color: enabled ? 'var(--color-brand-700)' : 'var(--color-grey-500)',
                 }, children: enabled ? 'Feature enabled' : 'Feature disabled' })] }));
 };
-export const Controlled = {
-    render: ControlledTemplate,
-};
-// ---------------------------------------------------------------------------
-// With label (accessible usage)
-// ---------------------------------------------------------------------------
-/**
- * A toggle paired with a visible `<label>` element for full accessibility.
- *
- * This is the pattern you should reach for in almost every real-world use
- * case. By wiring the label's `htmlFor` to the toggle's `id`, you get:
- *
- * - Screen readers announce both the label text and the toggle state.
- * - Clicking the label text also toggles the switch (larger click target).
- * - Visual users see a clear description of what the toggle controls.
- *
- * You know, this is a lot like what we learned in St. Olaf Home Economics
- * class — always label your preserves. An unlabelled jar of lingonberry jam
- * looks just like an unlabelled jar of beet relish, and nobody wants that
- * confusion at the dinner table. Or on a settings page!
- */
 const WithLabelTemplate = (args) => {
     const [enabled, setEnabled] = useState(false);
-    return (_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: '8px' }, children: [_jsx(Toggle, { ...args, id: "email-notifications-toggle", checked: enabled, onCheckedChange: (checked) => {
+    return (_jsxs("div", { style: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: 'var(--spacing-xsmall)',
+        }, children: [_jsx(Toggle, { ...args, id: "email-notifications-toggle", checked: enabled, onCheckedChange: (checked) => {
                     setEnabled(checked);
                     args.onCheckedChange?.(checked);
-                } }), _jsx("label", { htmlFor: "email-notifications-toggle", style: { fontSize: '14px', cursor: 'pointer', userSelect: 'none' }, children: "Email notifications" })] }));
+                } }), _jsx("label", { htmlFor: "email-notifications-toggle", style: {
+                    fontSize: 'var(--font-size-2-13)',
+                    cursor: 'pointer',
+                    userSelect: 'none',
+                }, children: "Email notifications" })] }));
 };
-export const WithLabel = {
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    render: args => _jsx(Toggle, { ...args }),
+}, 'The toggle in its default, unchecked (off) state. Use the Controls panel to flip `checked`, `defaultChecked`, `disabled`, and other props.');
+export const Checked = withDescription({
+    args: {
+        defaultChecked: true,
+    },
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Toggle } from '@arbor-education/design-system.components';
+
+function EnabledByDefaultToggle() {
+  return <Toggle defaultChecked />;
+}
+export default EnabledByDefaultToggle;
+`.trim(),
+            },
+        },
+    },
+}, 'The toggle in its checked (on) state. Uses `defaultChecked` for uncontrolled usage — the component manages its own state after mount.');
+export const Disabled = withDescription({
+    args: {
+        disabled: true,
+    },
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Toggle } from '@arbor-education/design-system.components';
+
+function DisabledToggle() {
+  return <Toggle disabled />;
+}
+export default DisabledToggle;
+`.trim(),
+            },
+        },
+    },
+}, 'A disabled toggle in the off state. Use when a setting exists but cannot currently be changed — for example, a feature that requires a higher subscription tier.');
+export const DisabledChecked = withDescription({
+    args: {
+        defaultChecked: true,
+        disabled: true,
+    },
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { Toggle } from '@arbor-education/design-system.components';
+
+function DisabledCheckedToggle() {
+  return <Toggle defaultChecked disabled />;
+}
+export default DisabledCheckedToggle;
+`.trim(),
+            },
+        },
+    },
+}, 'A disabled toggle in the on state. This communicates "this setting is enabled, but you cannot change it right now." Always pair a disabled toggle with a tooltip or helper text explaining why it is locked.');
+export const Controlled = withDescription({
+    render: ControlledTemplate,
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Toggle } from '@arbor-education/design-system.components';
+
+function ControlledToggle() {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+      <Toggle
+        checked={enabled}
+        onCheckedChange={setEnabled}
+      />
+      <p style={{ margin: 0 }}>
+        {enabled ? 'Feature enabled' : 'Feature disabled'}
+      </p>
+    </div>
+  );
+}
+export default ControlledToggle;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'A fully controlled toggle backed by React state.',
+    'Use the controlled pattern when you need to read the toggle state elsewhere in the UI, conditionally',
+    'show or hide other elements, or include the state in a larger form payload.',
+].join(' '));
+export const WithLabel = withDescription({
     render: WithLabelTemplate,
-};
+    parameters: {
+        controls: { disable: true },
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { useState } from 'react';
+import { Toggle } from '@arbor-education/design-system.components';
+
+function ToggleWithLabel() {
+  const [enabled, setEnabled] = useState(false);
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 'var(--spacing-xsmall)' }}>
+      <Toggle
+        id="email-notifications-toggle"
+        checked={enabled}
+        onCheckedChange={setEnabled}
+      />
+      <label
+        htmlFor="email-notifications-toggle"
+        style={{ cursor: 'pointer', userSelect: 'none' }}
+      >
+        Email notifications
+      </label>
+    </div>
+  );
+}
+export default ToggleWithLabel;
+`.trim(),
+            },
+        },
+    },
+}, [
+    'A toggle paired with a visible `<label>` element for full accessibility.',
+    'Wiring `htmlFor` on the label to the toggle\'s `id` means screen readers announce both the label text and',
+    'the toggle state, and clicking the label also toggles the switch — giving a larger tap target for all users.',
+].join(' '));
 //# sourceMappingURL=Toggle.stories.js.map