Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

Improve Switch docs page and block examples (#1604)

Ted McDonaldfa6e5af143f9
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchDisabled.doc.mjs b/packages/cli/templates/blocks/components/Switch/SwitchDisabled.doc.mjs
index 3fe51582f2..75b9f21aa5 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchDisabled.doc.mjs
+++ b/packages/cli/templates/blocks/components/Switch/SwitchDisabled.doc.mjs
@@ -5,5 +5,5 @@ export const doc = {
description: 'Disabled switch with label and description for gated features.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Switch'],
+ componentsUsed: ['Switch', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchDisabled.tsx b/packages/cli/templates/blocks/components/Switch/SwitchDisabled.tsx
index 7cb6a2cf3c..5f57719c2d 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchDisabled.tsx
+++ b/packages/cli/templates/blocks/components/Switch/SwitchDisabled.tsx
@@ -2,16 +2,19 @@
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
+import {XDSCenter} from '@xds/core/Center';
export default function SwitchDisabled() {
const [value, setValue] = useState(false);
return (
- <XDSSwitch
- label="Premium feature"
- description="Upgrade to enable this option"
- value={value}
- onChange={setValue}
- isDisabled
- />
+ <XDSCenter>
+ <XDSSwitch
+ label="Premium feature"
+ description="Upgrade to enable this option"
+ value={value}
+ onChange={setValue}
+ isDisabled
+ />
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.doc.mjs b/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.doc.mjs
index a53a78bdc8..58b3933b91 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.doc.mjs
+++ b/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Switch — Settings Panel',
description:
- 'Real-world settings panel with spread-spaced label-start switches in a card.',
+ 'Settings panel with spread-spaced switches in a card.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Switch'],
+ componentsUsed: ['Switch', 'Card', 'VStack', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.tsx b/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.tsx
index 633e993e69..665bc65188 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.tsx
+++ b/packages/cli/templates/blocks/components/Switch/SwitchSettingsPanel.tsx
@@ -2,6 +2,9 @@
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
+import {XDSCard} from '@xds/core/Card';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSCenter} from '@xds/core/Center';
export default function SwitchSettingsPanel() {
const [notifications, setNotifications] = useState(false);
@@ -9,37 +12,32 @@ export default function SwitchSettingsPanel() {
const [autoSave, setAutoSave] = useState(false);
return (
- <div
- style={{
- display: 'flex',
- flexDirection: 'column',
- gap: 16,
- width: 350,
- border: '1px solid #e0e0e0',
- borderRadius: 8,
- padding: 16,
- }}>
- <XDSSwitch
- label="Enable notifications"
- value={notifications}
- onChange={setNotifications}
- labelPosition="start"
- labelSpacing="spread"
- />
- <XDSSwitch
- label="Dark mode"
- value={darkMode}
- onChange={setDarkMode}
- labelPosition="start"
- labelSpacing="spread"
- />
- <XDSSwitch
- label="Auto-save"
- value={autoSave}
- onChange={setAutoSave}
- labelPosition="start"
- labelSpacing="spread"
- />
- </div>
+ <XDSCenter width={350}>
+ <XDSCard>
+ <XDSVStack gap={4}>
+ <XDSSwitch
+ label="Enable notifications"
+ value={notifications}
+ onChange={setNotifications}
+ labelPosition="start"
+ labelSpacing="spread"
+ />
+ <XDSSwitch
+ label="Dark mode"
+ value={darkMode}
+ onChange={setDarkMode}
+ labelPosition="start"
+ labelSpacing="spread"
+ />
+ <XDSSwitch
+ label="Auto-save"
+ value={autoSave}
+ onChange={setAutoSave}
+ labelPosition="start"
+ labelSpacing="spread"
+ />
+ </XDSVStack>
+ </XDSCard>
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.doc.mjs b/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.doc.mjs
index 038c84bdc2..8502daa35c 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.doc.mjs
+++ b/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.doc.mjs
@@ -5,5 +5,5 @@ export const doc = {
description: 'Toggle with a label and supporting description text.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Switch'],
+ componentsUsed: ['Switch', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.tsx b/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.tsx
index 03e11ed4da..5ffa2d6a11 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.tsx
+++ b/packages/cli/templates/blocks/components/Switch/SwitchWithDescription.tsx
@@ -2,15 +2,18 @@
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
+import {XDSCenter} from '@xds/core/Center';
export default function SwitchWithDescription() {
const [value, setValue] = useState(false);
return (
- <XDSSwitch
- label="Dark mode"
- description="Switch to a darker color scheme for reduced eye strain."
- value={value}
- onChange={setValue}
- />
+ <XDSCenter>
+ <XDSSwitch
+ label="Dark mode"
+ description="Switch to a darker color scheme for reduced eye strain."
+ value={value}
+ onChange={setValue}
+ />
+ </XDSCenter>
);
}
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.doc.mjs b/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.doc.mjs
index 3d232b08a6..9f137dcfae 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.doc.mjs
+++ b/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'Switch — With Status',
description:
- 'Switches with error, warning, and success validation status messages.',
+ 'Switches with error, warning, and success validation states.',
isReady: true,
aspectRatio: 4 / 3,
- componentsUsed: ['Switch'],
+ componentsUsed: ['Switch', 'VStack', 'Center'],
};
diff --git a/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.tsx b/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.tsx
index c6df86779c..6c261d1649 100644
--- a/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.tsx
+++ b/packages/cli/templates/blocks/components/Switch/SwitchWithStatus.tsx
@@ -2,6 +2,8 @@
import {useState} from 'react';
import {XDSSwitch} from '@xds/core/Switch';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSCenter} from '@xds/core/Center';
export default function SwitchWithStatus() {
const [terms, setTerms] = useState(false);
@@ -9,39 +11,35 @@ export default function SwitchWithStatus() {
const [twoFactor, setTwoFactor] = useState(true);
return (
- <div
- style={{
- display: 'flex',
- flexDirection: 'column',
- gap: 24,
- maxWidth: 400,
- }}>
- <XDSSwitch
- label="Accept terms and conditions"
- value={terms}
- onChange={setTerms}
- isRequired
- status={{
- type: 'error',
- message: 'You must accept the terms to continue',
- }}
- />
- <XDSSwitch
- label="Share usage data"
- description="Help us improve by sharing anonymous usage statistics"
- value={sharing}
- onChange={setSharing}
- status={{
- type: 'warning',
- message: 'This data may be shared with partners',
- }}
- />
- <XDSSwitch
- label="Two-factor authentication"
- value={twoFactor}
- onChange={setTwoFactor}
- status={{type: 'success', message: 'Your account is now more secure'}}
- />
- </div>
+ <XDSCenter width={400}>
+ <XDSVStack gap={6}>
+ <XDSSwitch
+ label="Accept terms and conditions"
+ value={terms}
+ onChange={setTerms}
+ isRequired
+ status={{
+ type: 'error',
+ message: 'You must accept the terms to continue',
+ }}
+ />
+ <XDSSwitch
+ label="Share usage data"
+ description="Help us improve by sharing anonymous usage statistics"
+ value={sharing}
+ onChange={setSharing}
+ status={{
+ type: 'warning',
+ message: 'This data may be shared with partners',
+ }}
+ />
+ <XDSSwitch
+ label="Two-factor authentication"
+ value={twoFactor}
+ onChange={setTwoFactor}
+ status={{type: 'success', message: 'Your account is now more secure'}}
+ />
+ </XDSVStack>
+ </XDSCenter>
);
}
diff --git a/packages/core/src/Switch/Switch.doc.mjs b/packages/core/src/Switch/Switch.doc.mjs
index ed868aa485..6bd7812462 100644
--- a/packages/core/src/Switch/Switch.doc.mjs
+++ b/packages/core/src/Switch/Switch.doc.mjs
@@ -123,12 +123,12 @@ export const docs = {
},
usage: {
description:
- 'Switch is a toggle control for boolean on/off states that take effect immediately. Use it for settings or preferences that apply instantly upon toggling. For changes requiring a separate submit step, use a checkbox instead.',
+ 'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
bestPractices: [
{ guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
- { guidance: false, description: 'Use a switch for options that require a form submission to take effect — use a checkbox instead.' },
- { guidance: false, description: 'Hide the label without providing accessible text — use isLabelHidden only when context makes the purpose obvious.' },
+ { guidance: false, description: 'Use for options that require a form submission to take effect — use a checkbox instead.' },
+ { guidance: false, description: 'Use a switch for multi-state values — it\'s strictly on/off.' },
],
},
};
@@ -256,12 +256,12 @@ export const docsZh = {
},
usage: {
description:
- 'Switch is a toggle control for boolean on/off states that take effect immediately. Use it for settings or preferences that apply instantly upon toggling. For changes requiring a separate submit step, use a checkbox instead.',
+ 'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
bestPractices: [
{ guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
- { guidance: false, description: 'Use a switch for options that require a form submission to take effect — use a checkbox instead.' },
- { guidance: false, description: 'Hide the label without providing accessible text — use isLabelHidden only when context makes the purpose obvious.' },
+ { guidance: false, description: 'Use for options that require a form submission to take effect — use a checkbox instead.' },
+ { guidance: false, description: 'Use a switch for multi-state values — it\'s strictly on/off.' },
],
},
};
@@ -271,12 +271,12 @@ export const docsDense = {
description: 'Toggle switch for boolean values w/ integrated label support.',
usage: {
description:
- 'Switch is a toggle control for boolean on/off states that take effect immediately. Use it for settings or preferences that apply instantly upon toggling. For changes requiring a separate submit step, use a checkbox instead.',
+ 'A toggle control for on/off states that take effect immediately. Supports labels, descriptions, loading states, and validation. Use it for settings or preferences that apply instantly. For changes requiring a form submission, use a checkbox instead.',
bestPractices: [
{ guidance: true, description: 'Use for settings that apply immediately — the toggle should take effect without a separate save action.' },
{ guidance: true, description: 'Pair with a clear, concise label that describes the setting being controlled.' },
- { guidance: false, description: 'Use a switch for options that require a form submission to take effect — use a checkbox instead.' },
- { guidance: false, description: 'Hide the label without providing accessible text — use isLabelHidden only when context makes the purpose obvious.' },
+ { guidance: false, description: 'Use for options that require a form submission to take effect — use a checkbox instead.' },
+ { guidance: false, description: 'Use a switch for multi-state values — it\'s strictly on/off.' },
],
},
propDescriptions: {