# Button Make the next action clear with one primary button and quieter supporting actions. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: curated Source: packages/design-system/src/components/primitives/Button/Button.tsx ## Guidance { "summary": "Make the next action clear with one primary button and quieter supporting actions.", "when_to_use": [ "Initiate an action that changes the current state.", "Show one primary action per view.", "Use danger tone when the action is destructive." ], "avoid": [ "Using a button to navigate to another URL; use a link.", "Treating the link variant as an anchor.", "Disabling an action without explaining what is needed." ], "accessibility": [ "Use a descriptive visible label, or ariaLabel for icon-only buttons.", "Loading preserves the label, sets aria-busy, and blocks duplicate presses.", "Keyboard focus is visible in both themes." ], "constraints": [ "Text buttons use children and optional leading/trailing content.", "Icon-only buttons require icon and ariaLabel and cannot have children or leading/trailing.", "Always renders type=button. A form must explicitly request submission." ] } ## Contract and public API ```json { "props": [ { "name": "variant", "type": "ButtonVariant", "required": true, "description": "Visual treatment by action hierarchy." }, { "name": "tone", "type": "ButtonTone", "required": false, "description": "Semantic action tone, independent of hierarchy." }, { "name": "size", "type": "ButtonSize", "required": true, "description": "Height and padding tier; icon-only buttons use their own square size for each tier." }, { "name": "onPress", "type": "() => void", "required": false, "description": "Fires on tap. Omitted, the button renders inert without looking disabled." }, { "name": "disabled", "type": "boolean", "required": false, "description": "Blocks presses and dims the button. Use `loading` when the block is an in-flight action." }, { "name": "loading", "type": "boolean", "required": false, "description": "Shows the loading treatment and prevents interaction." }, { "name": "fullWidth", "type": "boolean", "required": false, "description": "Stretches the button to the width of its parent." }, { "name": "ariaLabel", "type": "string", "required": false, "description": "Accessible label for icon-only buttons." }, { "name": "className", "type": "string", "required": false, "description": "" }, { "name": "style", "type": "React.CSSProperties", "required": false, "description": "" }, { "name": "haptic", "type": "HapticFeedback", "required": false, "description": "Haptic feedback for successful presses. Defaults to `true` (`light`)." }, { "name": "testId", "type": "string", "required": false, "description": "Selector on the `

{presses ? `Pressed ${presses} ${presses === 1 ? 'time' : 'times'}.` : 'Try the button, then explore its states.'}

; } function ButtonControls({ props, change }: { props: ButtonExampleProps; change: (value: Partial) => void }) { const state = props.loading ? 'loading' : props.disabled ? 'disabled' : 'default'; return <> change({ variant: value as ButtonVariant })} /> change({ tone: value as ButtonTone })} /> change({ size: value as ButtonSize })} /> change({ disabled: value === 'disabled', loading: value === 'loading' })} /> ; } export function ButtonHierarchy() { const [message, setMessage] = useState('Choose one primary action. Let supporting actions step back.'); return
A clear next step

Keep your personal email private.

Create an address you can turn off when you no longer need it.

{message}

; } ``` ## One clear next step Source: packages/design-system/examples/ButtonPlayground.tsx ```tsx import { useState } from 'react'; import { Button, type ButtonVariant, type ButtonTone, type ButtonSize } from '../src'; import { DemoFrame, SelectControl } from './DemoFrame'; import { buttonExampleCode, initialButtonProps, type ButtonExampleProps } from './code'; export function ButtonPlayground() { const [props, setProps] = useState(initialButtonProps); const [presses, setPresses] = useState(0); const change = (value: Partial) => { setProps(previous => ({ ...previous, ...value })); setPresses(0); }; return }>

{presses ? `Pressed ${presses} ${presses === 1 ? 'time' : 'times'}.` : 'Try the button, then explore its states.'}

; } function ButtonControls({ props, change }: { props: ButtonExampleProps; change: (value: Partial) => void }) { const state = props.loading ? 'loading' : props.disabled ? 'disabled' : 'default'; return <> change({ variant: value as ButtonVariant })} /> change({ tone: value as ButtonTone })} /> change({ size: value as ButtonSize })} /> change({ disabled: value === 'disabled', loading: value === 'loading' })} /> ; } export function ButtonHierarchy() { const [message, setMessage] = useState('Choose one primary action. Let supporting actions step back.'); return
A clear next step

Keep your personal email private.

Create an address you can turn off when you no longer need it.

{message}

; } ``` ## Create a protected email Source: packages/design-system/examples/ProtectedEmailFlow.tsx ```tsx import { useEffect, useLayoutEffect, useRef, useState, type FormEvent } from 'react'; import { Button, Field, Input } from '../src'; import { DemoFrame } from './DemoFrame'; import { createSampleIdentity, validateIdentity, type IdentityDraft, type IdentityErrors } from './protected-email'; const EMPTY_DRAFT: IdentityDraft = { name: '', website: '' }; export function ProtectedEmailFlow() { const [draft, setDraft] = useState(EMPTY_DRAFT); const [errors, setErrors] = useState({}); const [stage, setStage] = useState<'editing' | 'loading' | 'success'>('editing'); const form = useRef(null); const success = useRef(null); useEffect(() => { if (stage !== 'loading') return; const timer = window.setTimeout(() => setStage('success'), 700); return () => window.clearTimeout(timer); }, [stage]); useEffect(() => { if (stage === 'success') success.current?.focus(); }, [stage]); useLayoutEffect(() => { if (Object.keys(errors).length) form.current?.querySelector('[aria-invalid="true"]')?.focus(); }, [errors]); const restart = () => { setDraft(EMPTY_DRAFT); setErrors({}); setStage('editing'); requestAnimationFrame(() => form.current?.querySelector('input')?.focus()); }; const submit = (event: FormEvent) => { event.preventDefault(); if (stage !== 'editing') return; const nextErrors = validateIdentity(draft); setErrors(nextErrors); if (Object.keys(nextErrors).length) return; setStage('loading'); }; return

Interactive example · Sample data only. Nothing is sent or saved.

{stage === 'success' ? :
form.current?.requestSubmit()} />

{stage === 'loading' ? 'Creating your sample address…' : 'Your personal email stays yours.'}

}
; } function FlowHeading() { return
A little more privacy

An email for this part of your life.

Give it a name so you know where you used it.

; } function FlowFields({ draft, errors, loading, change, submit }: { draft: IdentityDraft; errors: IdentityErrors; loading: boolean; change: (draft: IdentityDraft) => void; submit: () => void; }) { return
change({ ...draft, name })} placeholder="Shopping" name="identity-name" autoComplete="off" maxLength={80} enterKeyHint="next" /> change({ ...draft, website })} placeholder="example.com" name="identity-website" autoComplete="off" inputMode="url" autoCapitalize="none" maxLength={200} enterKeyHint="done" enterBehavior="callback" onEnter={submit} />
; } function FlowSuccess({ draft, headingRef, restart }: { draft: IdentityDraft; headingRef: React.RefObject; restart: () => void; }) { const identity = createSampleIdentity(draft); return
Ready to use

A fresh address for {identity.name}.

This sample address demonstrates the result. It cannot receive email.

Protected email{identity.email}
; } ``` ## Tokens together Source: packages/design-system/examples/foundations/FoundationOverview.tsx ```tsx import { useState } from 'react'; import { Button } from '../../src'; import { ContextCard, FoundationFrame, FoundationSelect } from './FoundationShared'; import { radiusSteps, spacingSteps } from './foundation-data'; export function FoundationOverview() { const [radius, setRadius] = useState('--cds-radius-xl'); const [inset, setInset] = useState('--cds-space-24'); const [selected, setSelected] = useState(false); return ['16px', '24px', '32px'].includes(token.value))} onChange={setInset} /> } code={`const cardStyle = {\n padding: 'var(${inset})',\n borderRadius: 'var(${radius})',\n background: 'var(--cds-bg-surface)',\n boxShadow: 'var(--cds-shadow-card)',\n};\n// Text and Button consume their own semantic tokens.`}>
Small decisions. One coherent experience.

{selected ? 'Action selected. This is a local composition example.' : 'Change the container tokens. The real components keep their own behavior.'}

Typography--cds-type-h3-serif-* Surface--cds-bg-surface Action--cds-button-primary-*
; } ``` ## Motion Source: packages/design-system/examples/foundations/FoundationMotion.tsx ```tsx import { MotionShowcase } from '../../src/foundations/MotionShowcase'; import { FoundationFrame } from './FoundationShared'; /** The website and original Foundations Motion story render this same showcase. */ export function FoundationMotion() { return ; } ``` Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.