Interactive route
contrastUse the interactive route to explore this foundation live.
foundations / contrast and distinctness
Contrast and Distinctness
Readable systems need both foreground/background contrast and perceptual separation between related states.
Principles
Core principles
These are the design-system rules this foundation should reinforce.
- Passing contrast does not guarantee usable state separation.
- Status, selected, disabled, and destructive states need enough perceptual distance to be trustworthy.
- Accessibility should survive preset changes, not depend on a single default theme.
Model
How DK models it
This section connects the concept to the actual DK math and token pipeline.
- DK uses APCA-style perceptual contrast checks instead of simpler legacy ratios alone.
- Distinctness checks compare state and semantic colors, including challenging adjacent roles.
- Proof fixtures bind these checks to real components and curated cases.
Practice
How to use it in product work
These are the decisions designers and engineers should make with this foundation in mind.
- Use semantic roles consistently so proofs can evaluate the right pairs.
- Be especially careful with disabled, warning, selected, and placeholder states.
- Check both light and dark presets when tuning a sensitive role.
Proofs
What the proof layer guarantees
These are the reliability claims DK makes about this foundation today.
- Critical component states fail proofs when contrast or distinction drops too low.
- Curated fixtures surface risky states without requiring exhaustive Cartesian tests.
- Status-heavy components remain trustworthy across all four gallery presets.
Token notes
- Contrast and distinctness logic is embedded in proof fixtures, not just standalone docs prose.
- Status and collection families rely heavily on these guarantees.