Short answer
Fewer than most systems start with: surfaces (default, raised, sunken, inverse), content on those surfaces (primary, secondary and disabled text, icons), borders (subtle, strong, focus), an action or accent role with its 'on' colour, and status roles (danger, warning, success, info) each with text, background and border variants. Every role that holds content is defined as a pair with the surface it sits on, so contrast is a property of the role, not something checked later.
A semantic role answers 'what is this colour for?'. The key insight in most mature systems is that roles come in pairs: a surface and the content that sits on it. Material's colour roles make this explicit with names such as primary and on-primary, surface and on-surface; Apple's semantic colours distinguish label, secondary label and tertiary label for text over system backgrounds. Defining roles as pairs means that when a theme changes the surface, it must also say what content colour goes on it, and a contrast check can be attached to the pair. A role with no defined partner — a 'brand-accent' used for backgrounds, text and borders alike — is where accessibility regressions usually start.
Surfaces: the page background, raised surfaces such as cards and menus, sunken areas such as inputs and wells, and an inverse surface for tooltips and snackbars. Content: primary text, secondary text, placeholder or disabled text, and icon colours, each specified against each surface it can appear on. Lines: a subtle divider, a stronger border for interactive controls (which, unlike dividers, WCAG 1.4.11 may require at 3:1), and a focus indicator. Action: the colour of primary buttons and links, with its on-colour. Status: danger, warning, success and information, each with a strong variant for icons and text and a pale variant for backgrounds. That is roughly twenty to thirty roles, enough for most products; more tends to mean component details have leaked into the semantic layer.
Each content role implies a WCAG target against its surface. Primary and secondary text need 4.5:1 (or 3:1 if only ever used for large text). Control borders and meaningful icons need 3:1 under 1.4.11. Dividers and decorative fills have no requirement, which is precisely why they must be separate roles from control borders — a system that uses one 'border' role for both either makes dividers too heavy or input outlines too faint. Disabled text is exempt from 1.4.3 but should still be legible enough to tell what is unavailable. Writing these targets into the role documentation, and testing them per theme, turns contrast from an audit finding into a build failure.
Status roles carry meaning that users rely on, so they need more than one colour each. A danger role is typically a strong red for text and icons (4.5:1 on the page), a pale red background for banners, a border between the two, and the text colour to use on that pale background. They also need a non-colour partner — an icon or a word — because WCAG 1.4.1 does not allow colour to be the only signal, and Apple's guidelines ask that the same colour never mean two different things. The status-colours topic covers choosing the four hues; here the point is structural: status roles should never be reused for decoration, or users learn that red does not always mean danger.
| Role family | Examples | Target against its surface | Basis |
|---|---|---|---|
| Primary and secondary text | text-primary, text-secondary | 4.5:1 (3:1 if large text only) | WCAG 2.2 SC 1.4.3 |
| Control boundaries | border-input, border-control | 3:1 where needed to identify the control | WCAG 2.2 SC 1.4.11 |
| Meaningful icons | icon-default, icon-status | 3:1 | WCAG 2.2 SC 1.4.11 |
| Focus indicator | border-focus | 3:1 against adjacent colours | WCAG 2.2 SC 1.4.11; 2.4.13 (AAA) adds area and change of contrast |
| Dividers, decorative fills | border-subtle, surface-tint | None required | Decorative; not needed to identify a component |
| Disabled content | text-disabled | Exempt | WCAG 2.2 exempts inactive components |
Why: Controls share the light divider colour for their borders.
Fix: Give control borders their own role at 3:1 against the surface.
Why: It was checked only against the page background.
Fix: Define and test each content role against every surface it can appear on.
Why: The danger role was borrowed for decoration.
Fix: Keep status roles for status and add a separate accent role.
Each statement is labelled by kind — established fact, a standard’s requirement, observed market data, a convention, or Colourwise’s own interpretation or analysis — with the strength of the evidence behind it.
StandardStrong evidence
WCAG 2.2 requires 4.5:1 for normal text and 3:1 for large text (1.4.3), and 3:1 for the visual information needed to identify user-interface components and their states (1.4.11), with exemptions for inactive components.
Source: Web Content Accessibility Guidelines (WCAG) 2.2; Understanding Success Criterion 1.4.3: Contrast (Minimum) (WCAG 2.2)
ConventionModerate evidence
Apple's guidelines recommend semantic colours such as label, secondary label and separator that adapt automatically to appearance, and advise using colour consistently so that one colour does not mean different things.
Source: Human Interface Guidelines: Color; Human Interface Guidelines: Dark Mode
Colourwise interpretationModerate evidence
Separating divider lines from interactive-control borders into different roles lets a system keep decorative lines light while meeting the 3:1 non-text contrast that control boundaries may need.
Based on: Follows from WCAG 1.4.11 applying to visual information needed to identify components but not to decorative lines, as explained in the W3C Understanding document.
Reviewed 29 September 2026. Colourwise summarises its sources in its own words and does not reproduce standards text or proprietary colour data. Spotted an error? Tell us.