Use semantic elements, labels, focus behavior, and readable contrast as part of the component contract.
Semantic structure
Choose the host element that matches the content. Use Heading for document hierarchy and native Whisk/UI controls for interaction instead of styling a generic container into a button or input. Use WCAG 2.2 AA as the product accessibility target; a component API cannot make a composition accessible on its own.
Billing details
Review the payment method before confirming the invoice.
import{ Heading, Text }from"@smoothie-framework/whisk-react";<Headinglevel={2}>Billing details</Heading><Text>Review the payment method before confirming the invoice.</Text>
Keyboard and focus
Use the focus and keyboard behavior provided by interactive components. Do not remove focus visibility to make a surface look cleaner. Icon-only Buttons require a non-empty accessible name. Default focus indicators use the semantic borderFocus token, which maps to the active theme’s accent color.
Components with motion honor prefers-reduced-motion: reduce. Keep any application-authored animation optional too: reduce or stop nonessential motion rather than using it as the only way to convey progress or a state change.
Content and contrast
Pair concise labels with visible descriptions, keep status meaning in text as well as color, and use theme tokens that preserve readable contrast. Components own their detailed keyboard and ARIA behavior, so check the component page when composing a control, field, menu, or dialog.
text on background is 16.67:1 in both default light and dark themes.
textSubtle on background is 10.50:1 in light mode and 12.23:1 in dark mode.
textInverse on accent is 14.57:1 in light mode and 15.86:1 in dark mode.
Associate each control with a visible label, description, and error when needed.
Do not rely on color alone for a status, validation result, or required field.
Custom themes and custom color pairings must be checked independently; test keyboard order, focus visibility, contrast, and overflow at each responsive layout.