Color
Color is a system of meaning, hierarchy, and state.
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
Choose one primary outcome.
A screen with two primary actions has no visual hierarchy. The user should always know the next best action.
Use semantic colors only for semantic meaning.
Success, warning, error, and info are product language. Decoration steals meaning from states that need trust.
Promote missing primitives into the UI package.
Reusable product quality compounds only when every team consumes the same primitive contract.
Do not
Do not style a one-off control.
If a primitive is missing, the system is missing knowledge. Add it to the library with a contract.
Do not use a raw value to “just make it fit.”
Raw values create drift. A layout fix must become a token or component rule.
Do not import another icon set.
Icon rhythm, stroke, fill, and metaphor must be one language across every product.
Live Examples
Color
| State | Token | Rule |
|---|---|---|
Default | theme.palette.text.primary | The element is ready and communicates its task without extra emphasis. |
Hover | theme.palette.action.hover | Only interactive elements receive hover treatment, and it must not move layout. |
Focus | theme.palette.action.focus | Keyboard focus must be visible before pointer styling or decorative motion. |
Selected | theme.palette.action.selected | Selection is persistent state, not a stronger hover. |
Disabled | theme.palette.action.disabled | Disabled means unavailable. It must never hide a control that needs explanation. |
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
Color recipe
<Box
sx={theme => ({
backgroundColor: theme.palette.background.card,
borderRadius: '${theme.shape.borderRadius}px',
boxShadow: theme.shadows[1],
p: theme.spacing(3),
})}
>
Color
</Box>