Skip to content

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

TypeScript

fix(storybook): bug bash story improvements — Field, AppShell, Breadcrumbs, Card, Text (#520)

Cindy Zhang98e457cd7407
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index 993f26fcf7..04c3e5c3a6 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -258,6 +258,69 @@ const meta: Meta<typeof XDSAppShell> = {
export default meta;
type Story = StoryObj<typeof XDSAppShell>;
+// =============================================================================
+// Playground (interactive controls)
+// =============================================================================
+
+/**
+ * Interactive playground with controls for toggling top nav and side nav.
+ * When top nav is turned off, the side nav automatically shows a header
+ * with the app title since there's no top bar to display it.
+ */
+export const Playground: StoryObj<
+ typeof XDSAppShell & {showTopNav: boolean; showSideNav: boolean}
+> = {
+ argTypes: {
+ showTopNav: {
+ control: 'boolean',
+ description: 'Show the top navigation bar',
+ },
+ showSideNav: {
+ control: 'boolean',
+ description: 'Show the side navigation',
+ },
+ background: {
+ control: 'radio',
+ options: ['surface', 'wash'],
+ description: 'Background color of the shell',
+ },
+ height: {
+ control: 'radio',
+ options: ['fill', 'auto'],
+ },
+ },
+ args: {
+ showTopNav: true,
+ showSideNav: true,
+ background: 'wash',
+ height: 'fill',
+ },
+ render: function PlaygroundStory(args: {
+ showTopNav: boolean;
+ showSideNav: boolean;
+ background: 'surface' | 'wash';
+ height: 'fill' | 'auto';
+ }) {
+ return (
+ <XDSAppShell
+ topNav={args.showTopNav ? <AppTopNav /> : undefined}
+ sideNav={
+ args.showSideNav ? (
+ args.showTopNav ? (
+ <SideNavWithoutHeader />
+ ) : (
+ <SideNavWithHeader />
+ )
+ ) : undefined
+ }
+ background={args.background}
+ height={args.height}>
+ <MockContent />
+ </XDSAppShell>
+ );
+ },
+};
+
// =============================================================================
// Stories
// =============================================================================
diff --git a/apps/storybook/stories/Breadcrumbs.stories.tsx b/apps/storybook/stories/Breadcrumbs.stories.tsx
index 09b5727563..25f595d21a 100644
--- a/apps/storybook/stories/Breadcrumbs.stories.tsx
+++ b/apps/storybook/stories/Breadcrumbs.stories.tsx
@@ -153,3 +153,22 @@ export const SupportingWithIcons: Story = {
</XDSBreadcrumbs>
),
};
+
+/**
+ * Shows `isCurrent` on a middle breadcrumb item rather than the last one.
+ * This is useful when navigating to a child page that isn't represented
+ * in the breadcrumb trail — the parent is still the "current" page in
+ * the hierarchy.
+ */
+export const CurrentOnMiddleItem: Story = {
+ name: 'Current on Middle Item',
+ render: () => (
+ <XDSBreadcrumbs>
+ <XDSBreadcrumbItem href="/">Home</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem isCurrent>Projects</XDSBreadcrumbItem>
+ <XDSBreadcrumbItem href="/projects/my-project/settings">
+ Settings
+ </XDSBreadcrumbItem>
+ </XDSBreadcrumbs>
+ ),
+};
diff --git a/apps/storybook/stories/Card.stories.tsx b/apps/storybook/stories/Card.stories.tsx
index a07d80504d..4b7962e794 100644
--- a/apps/storybook/stories/Card.stories.tsx
+++ b/apps/storybook/stories/Card.stories.tsx
@@ -315,3 +315,65 @@ export const FullBleed: Story = {
</div>
),
};
+
+/**
+ * Cards shown on top of different background treatments.
+ * Demonstrates the visual contrast between cards on wash (gray)
+ * backgrounds vs surface (white) backgrounds.
+ */
+export const OnBackgrounds: Story = {
+ decorators: [Story => <Story />],
+ render: () => (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 0,
+ }}>
+ <div {...stylex.props(styles.pageWrapper)}>
+ <h4 {...stylex.props(styles.heading)}>Cards on wash background</h4>
+ <div {...stylex.props(styles.storyWrapper)}>
+ <XDSCard width={250}>
+ <XDSVStack gap="space2">
+ <h3 {...stylex.props(styles.text)}>Card on Wash</h3>
+ <p {...stylex.props(styles.text, styles.textSecondary)}>
+ Cards stand out clearly against the wash background, creating a
+ layered visual hierarchy.
+ </p>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard width={250}>
+ <XDSVStack gap="space2">
+ <h3 {...stylex.props(styles.text)}>Another Card</h3>
+ <p {...stylex.props(styles.text, styles.textSecondary)}>
+ Multiple cards on wash create a dashboard-like layout.
+ </p>
+ </XDSVStack>
+ </XDSCard>
+ </div>
+ </div>
+ <XDSSection variant="section" width="100%">
+ <h4 {...stylex.props(styles.heading)}>Cards on surface section</h4>
+ <div {...stylex.props(styles.storyWrapper)}>
+ <XDSCard width={250}>
+ <XDSVStack gap="space2">
+ <h3 {...stylex.props(styles.text)}>Card on Surface</h3>
+ <p {...stylex.props(styles.text, styles.textSecondary)}>
+ On a surface background, cards are more subtle since both share
+ the same base color.
+ </p>
+ </XDSVStack>
+ </XDSCard>
+ <XDSCard width={250}>
+ <XDSVStack gap="space2">
+ <h3 {...stylex.props(styles.text)}>Another Card</h3>
+ <p {...stylex.props(styles.text, styles.textSecondary)}>
+ The card border and shadow provide separation from the surface.
+ </p>
+ </XDSVStack>
+ </XDSCard>
+ </div>
+ </XDSSection>
+ </div>
+ ),
+};
diff --git a/apps/storybook/stories/Field.stories.tsx b/apps/storybook/stories/Field.stories.tsx
index 4004f7749e..27f341f329 100644
--- a/apps/storybook/stories/Field.stories.tsx
+++ b/apps/storybook/stories/Field.stories.tsx
@@ -1,49 +1,71 @@
import {useState} from 'react';
import type {Meta, StoryObj} from '@storybook/react';
+import * as stylex from '@stylexjs/stylex';
import {XDSField} from '@xds/core/Field';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ typographyVars,
+} from '@xds/core/theme/tokens.stylex';
+
+// A minimal native input styled to match XDS aesthetics —
+// demonstrating that XDSField wraps any custom or native input.
+const inputStyles = stylex.create({
+ root: {
+ width: '100%',
+ boxSizing: 'border-box',
+ fontFamily: typographyVars['--font-body'],
+ fontSize: '14px',
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderWidth: 1,
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-divider'],
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: colorVars['--color-surface'],
+ color: colorVars['--color-text-primary'],
+ outline: 'none',
+ ':focus': {
+ borderColor: colorVars['--color-accent'],
+ },
+ },
+});
+
+const NativeInput = ({
+ id,
+ describedBy,
+ placeholder,
+ value,
+ onChange,
+}: {
+ id: string;
+ describedBy?: string;
+ placeholder?: string;
+ value: string;
+ onChange: (v: string) => void;
+}) => (
+ <input
+ id={id}
+ aria-describedby={describedBy}
+ placeholder={placeholder}
+ value={value}
+ onChange={e => onChange(e.target.value)}
+ {...stylex.props(inputStyles.root)}
+ />
+);
const meta: Meta<typeof XDSField> = {
title: 'Form/XDSField',
component: XDSField,
tags: ['autodocs'],
argTypes: {
- label: {
- control: 'text',
- description: 'Label text (required)',
- },
- isLabelHidden: {
- control: 'boolean',
- description:
- 'Visually hide the label (still accessible to screen readers)',
- },
- description: {
- control: 'text',
- description: 'Description text displayed between the label and input',
- },
- inputID: {
- control: 'text',
- description:
- 'ID for the input element (used for label htmlFor attribute)',
- },
- descriptionID: {
- control: 'text',
- description: 'ID for the description element (use for aria-describedby)',
- },
- isOptional: {
- control: 'boolean',
- description:
- 'Whether the field is optional (mutually exclusive with isRequired)',
- },
- isRequired: {
- control: 'boolean',
- description:
- 'Whether the field is required (mutually exclusive with isOptional)',
- },
- labelTooltip: {
- control: 'text',
- description:
- 'Tooltip text to display in an info icon at the end of the label',
- },
+ label: {control: 'text'},
+ isLabelHidden: {control: 'boolean'},
+ description: {control: 'text'},
+ isOptional: {control: 'boolean'},
+ isRequired: {control: 'boolean'},
+ labelTooltip: {control: 'text'},
},
};
@@ -51,384 +73,210 @@ export default meta;
type Story = StoryObj<typeof XDSField>;
export const Default: Story = {
+ args: {label: 'Email'},
render: args => {
const [value, setValue] = useState('');
return (
<XDSField {...args} inputID="email-input">
- <input
+ <NativeInput
id="email-input"
+ placeholder="[email protected]"
value={value}
- onChange={e => setValue(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ onChange={setValue}
/>
</XDSField>
);
},
- args: {
- label: 'Email',
- },
};
export const WithDescription: Story = {
+ args: {label: 'Email', description: "We'll never share your email."},
render: args => {
const [value, setValue] = useState('');
return (
- <XDSField {...args} inputID="email-input" descriptionID="email-desc">
- <input
- id="email-input"
- aria-describedby="email-desc"
+ <XDSField {...args} inputID="email-desc-input" descriptionID="email-desc">
+ <NativeInput
+ id="email-desc-input"
+ describedBy="email-desc"
+ placeholder="[email protected]"
value={value}
- onChange={e => setValue(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ onChange={setValue}
/>
</XDSField>
);
},
- args: {
- label: 'Email',
- description: "We'll never share your email with anyone.",
- },
};
export const WithHiddenLabel: Story = {
+ args: {label: 'Search', isLabelHidden: true},
render: args => {
const [value, setValue] = useState('');
return (
<XDSField {...args} inputID="search-input">
- <input
+ <NativeInput
id="search-input"
- value={value}
- onChange={e => setValue(e.target.value)}
placeholder="Search..."
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ value={value}
+ onChange={setValue}
/>
</XDSField>
);
},
- args: {
- label: 'Search',
- isLabelHidden: true,
- },
-};
-
-export const AllVariations: Story = {
- render: () => {
- const [value1, setValue1] = useState('');
- const [value2, setValue2] = useState('');
- const [value3, setValue3] = useState('');
- const [value4, setValue4] = useState('');
- const [value5, setValue5] = useState('');
- return (
- <div
- style={{
- display: 'flex',
- flexDirection: 'column',
- gap: '24px',
- maxWidth: '300px',
- }}>
- <XDSField label="Default field" inputID="default-input">
- <input
- id="default-input"
- value={value1}
- onChange={e => setValue1(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
- <XDSField
- label="With description"
- description="This is helpful information"
- inputID="desc-input"
- descriptionID="desc-text">
- <input
- id="desc-input"
- aria-describedby="desc-text"
- value={value2}
- onChange={e => setValue2(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
- <XDSField label="Optional field" isOptional inputID="optional-input">
- <input
- id="optional-input"
- value={value3}
- onChange={e => setValue3(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
- <XDSField label="Required field" isRequired inputID="required-input">
- <input
- id="required-input"
- value={value4}
- onChange={e => setValue4(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
- <XDSField
- label="With description and optional"
- description="Enter your nickname"
- isOptional
- inputID="desc-optional-input"
- descriptionID="desc-optional-text">
- <input
- id="desc-optional-input"
- aria-describedby="desc-optional-text"
- value={value5}
- onChange={e => setValue5(e.target.value)}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
- </div>
- );
- },
};
export const OptionalField: Story = {
+ args: {label: 'Nickname', isOptional: true},
render: args => {
const [value, setValue] = useState('');
return (
<XDSField {...args} inputID="nickname-input">
- <input
+ <NativeInput
id="nickname-input"
- value={value}
- onChange={e => setValue(e.target.value)}
placeholder="Enter your nickname"
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ value={value}
+ onChange={setValue}
/>
</XDSField>
);
},
- args: {
- label: 'Nickname',
- isOptional: true,
- },
};
export const RequiredField: Story = {
+ args: {label: 'Username', isRequired: true},
render: args => {
const [value, setValue] = useState('');
return (
<XDSField {...args} inputID="username-input">
- <input
+ <NativeInput
id="username-input"
- value={value}
- onChange={e => setValue(e.target.value)}
placeholder="Enter your username"
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
- );
- },
- args: {
- label: 'Username',
- isRequired: true,
- },
-};
-
-export const DescriptionWithOptional: Story = {
- render: args => {
- const [value, setValue] = useState('');
- return (
- <XDSField {...args} inputID="bio-input" descriptionID="bio-desc">
- <input
- id="bio-input"
- aria-describedby="bio-desc"
value={value}
- onChange={e => setValue(e.target.value)}
- placeholder="Tell us about yourself"
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ onChange={setValue}
/>
</XDSField>
);
},
- args: {
- label: 'Bio',
- description: 'A short description about yourself',
- isOptional: true,
- },
};
export const WithTooltip: Story = {
+ args: {
+ label: 'API Key',
+ labelTooltip: 'Your unique API key. Keep this secret!',
+ },
render: args => {
const [value, setValue] = useState('');
return (
- <XDSField {...args} inputID="tooltip-input">
- <input
- id="tooltip-input"
+ <XDSField {...args} inputID="api-key-input">
+ <NativeInput
+ id="api-key-input"
+ placeholder="sk-..."
value={value}
- onChange={e => setValue(e.target.value)}
- placeholder="Enter value"
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ onChange={setValue}
/>
</XDSField>
);
},
- args: {
- label: 'API Key',
- labelTooltip: 'Your unique API key for authentication. Keep this secret!',
- },
};
-export const TooltipWithOptional: Story = {
- render: args => {
- const [value, setValue] = useState('');
+export const AllVariations: Story = {
+ render: () => {
+ const [vals, setVals] = useState({a: '', b: '', c: '', d: '', e: ''});
+ const set = (k: keyof typeof vals) => (v: string) =>
+ setVals(prev => ({...prev, [k]: v}));
return (
- <XDSField {...args} inputID="tooltip-optional-input">
- <input
- id="tooltip-optional-input"
- value={value}
- onChange={e => setValue(e.target.value)}
- placeholder="Enter value"
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
- />
- </XDSField>
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: 24,
+ maxWidth: 320,
+ }}>
+ <XDSField label="Default" inputID="v-a">
+ <NativeInput id="v-a" value={vals.a} onChange={set('a')} />
+ </XDSField>
+ <XDSField
+ label="With description"
+ description="Some helpful info"
+ inputID="v-b"
+ descriptionID="v-b-desc">
+ <NativeInput
+ id="v-b"
+ describedBy="v-b-desc"
+ value={vals.b}
+ onChange={set('b')}
+ />
+ </XDSField>
+ <XDSField label="Optional" isOptional inputID="v-c">
+ <NativeInput id="v-c" value={vals.c} onChange={set('c')} />
+ </XDSField>
+ <XDSField label="Required" isRequired inputID="v-d">
+ <NativeInput id="v-d" value={vals.d} onChange={set('d')} />
+ </XDSField>
+ <XDSField
+ label="With tooltip"
+ labelTooltip="Extra info here"
+ inputID="v-e">
+ <NativeInput id="v-e" value={vals.e} onChange={set('e')} />
+ </XDSField>
+ </div>
);
},
- args: {
- label: 'Webhook URL',
- labelTooltip: 'The URL where we will send event notifications.',
- isOptional: true,
- },
};
-// =============================================================================
-// Status Variants
-// =============================================================================
-
export const StatusVariants: Story = {
render: () => {
- const [values, setValues] = useState({
+ const [vals, setVals] = useState({
error: 'bad-email',
warning: 'admin',
success: 'valid-user',
});
+ const set = (k: keyof typeof vals) => (v: string) =>
+ setVals(prev => ({...prev, [k]: v}));
return (
<div
style={{
display: 'flex',
flexDirection: 'column',
- gap: '24px',
- maxWidth: '400px',
+ gap: 24,
+ maxWidth: 400,
}}>
<XDSField
label="Email"
- description="Enter your work email address"
- inputID="status-error-input"
+ description="Enter your work email"
+ inputID="s-error"
status={{
type: 'error',
message: 'Please enter a valid email address',
}}>
- <input
- id="status-error-input"
- value={values.error}
- onChange={e => setValues(v => ({...v, error: e.target.value}))}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ <NativeInput
+ id="s-error"
+ value={vals.error}
+ onChange={set('error')}
/>
</XDSField>
<XDSField
label="Username"
description="Choose a unique username"
- inputID="status-warning-input"
+ inputID="s-warning"
status={{
type: 'warning',
message: 'This username is reserved for administrators',
}}>
- <input
- id="status-warning-input"
- value={values.warning}
- onChange={e => setValues(v => ({...v, warning: e.target.value}))}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ <NativeInput
+ id="s-warning"
+ value={vals.warning}
+ onChange={set('warning')}
/>
</XDSField>
<XDSField
label="API Key"
description="Paste your API key"
- inputID="status-success-input"
+ inputID="s-success"
status={{type: 'success', message: 'API key is valid and active'}}>
- <input
- id="status-success-input"
- value={values.success}
- onChange={e => setValues(v => ({...v, success: e.target.value}))}
- style={{
- padding: '8px',
- fontSize: '14px',
- width: '100%',
- boxSizing: 'border-box',
- }}
+ <NativeInput
+ id="s-success"
+ value={vals.success}
+ onChange={set('success')}
/>
</XDSField>
</div>
diff --git a/apps/storybook/stories/Text.stories.tsx b/apps/storybook/stories/Text.stories.tsx
index b36e8a8a33..64270c167f 100644
--- a/apps/storybook/stories/Text.stories.tsx
+++ b/apps/storybook/stories/Text.stories.tsx
@@ -566,7 +566,12 @@ export const MetricsExample: Story = {
),
};
-export const FormExample: Story = {
+/**
+ * Text types in a form-like context. Note: for actual forms, prefer
+ * XDSTextInput or XDSTextArea which include built-in labels and
+ * descriptions. This example shows how Text types pair with content.
+ */
+export const FormLikeContext: Story = {
render: () => (
<div
style={{
@@ -576,27 +581,26 @@ export const FormExample: Story = {
gap: '16px',
}}>
<div>
- <XDSText type="label" as="label" display="block">
- Email address
+ <XDSText type="label" display="block">
+ Section title as label
+ </XDSText>
+ <XDSText type="body" display="block">
+ Body text provides the main content or instructions for this section.
</XDSText>
- <input
- type="email"
- style={{width: '100%', padding: '8px', marginTop: '4px'}}
- />
<XDSText type="supporting" display="block">
- We'll never share your email.
+ Supporting text adds extra context or constraints.
</XDSText>
</div>
<div>
- <XDSText type="label" as="label" display="block">
- Password
+ <XDSText type="label" display="block">
+ Another section
+ </XDSText>
+ <XDSText type="body" display="block">
+ These text types create a natural visual hierarchy without any
+ additional styling.
</XDSText>
- <input
- type="password"
- style={{width: '100%', padding: '8px', marginTop: '4px'}}
- />
<XDSText type="supporting" color="active" display="block">
- Must be at least 8 characters.
+ Active supporting text draws attention to important details.
</XDSText>
</div>
</div>