Button
Buttons initiate explicit actions.
What It Is
Anatomy
A clear structural role: page, pane, control, feedback, or input.
A token recipe drawn from @socra/theme by name.
A state contract covering default, hover, focus, selected, loading, disabled, and mobile behavior where relevant.
An accessibility contract that survives dark mode, keyboard use, and assistive technology.
Do / Do Not
Do
Use contained primary for the one screen goal.
Contained primary is the strongest call to action; more than one breaks decision hierarchy.
Use outlined for visible alternatives.
Outlined keeps options discoverable while preserving the primary action.
Use text for low-risk support.
Text actions work for cancel, dismiss, learn more, and secondary inline commands.
Do not
Do not place two primary buttons on one screen.
The screen can have one next best action. Competing primary buttons force the user to design the flow.
Do not use semantic colors for marketing emphasis.
Error, warning, success, and info are reserved for meaning.
Do not hand-roll a button.
Use MUI Button through the Socra theme; missing behavior belongs in the UI package.
Live Examples
| State | Token | Rule |
|---|---|---|
Contained primary | theme.palette.primary.main | One per screen for the action that completes the current intent. |
Contained secondary | theme.palette.secondary.main | Use when the action is important but not the screen goal. |
Outlined | theme.palette.divider | Use for alternative actions that need visibility without competing with the primary action. |
Text | theme.palette.text.secondary | Use for low-risk inline actions, cancel, dismiss, and overflow-adjacent commands. |
Disabled | theme.palette.action.disabled | Use only when the action cannot run; pair with nearby cause or recovery. |
Tokens Used
Primary accent
The only accent for the screen goal. Use it for one primary action, not for decoration.
Main canvas
Desktop application canvas and the default depth behind structured panes.
List surface
Dense panes, table regions, and repeated item containers.
Input surface
Editable fields and controls that receive user data.
Primary text
Essential labels, active values, and sentences required to complete the task.
Secondary text
Explanatory copy, metadata, and lower-priority information that remains readable.
Spacing scale
All distances, insets, row gaps, and layout rhythm. Never write a raw size.
Standard radius
Default component and card corner treatment unless the primitive owns a stronger contract.
Elevation
Depth and separation by layer. Never write a raw shadow string.
Accessibility
Every interactive element has a semantic name and a keyboard path.
Focus order follows the visual task order and never jumps across panes.
Color communicates priority only with text, icon, or structural backup.
Motion honors reduced-motion preferences and never carries essential meaning alone.
Copy-Paste Code
Button recipe
<Stack direction="row" spacing={2}>
<Button variant="contained" color="primary">Continue</Button>
<Button variant="outlined" color="secondary">Review</Button>
<Button variant="text" color="secondary">Cancel</Button>
</Stack>