Colors
This is a comprehensive, science-based, and developer-proof UI Color Guideline that follows modern design and accessibility standards such as WCAG 2.1, Material Design, Design Tokens, and inclusive UX principles.
✅ TL;DR
- Use only defined color tokens (ask the designer if unsure)
- Always apply hover, active, focus, and disabled states
- Check color contrast using accessibility tools
- Use semantic tokens for logic (e.g., error, success) not brand color names
- Don’t create new shades — use the ones from the system
- Document new uses if you have to extend the system
- Ask: “Will a color-blind person still understand this UI?”
🎯 Purpose of Color in UI
Color in user interfaces is not decoration — it conveys meaning, hierarchy, interactivity, and status. Misusing color can lead to confusion or inaccessibility. Good color usage:
- Improves usability
- Highlights priority elements
- Communicates emotion and intent
- Enhances branding (e.g., this website is from the AET research group)
🧠 Color Psychology (What Colors Mean)
Use colors intentionally to match their psychological impact:
| Color | Meaning & Use Cases |
|---|---|
| Blue | Trust, safety, calm – good for primary actions, links, systems, peace, loyalty, competence |
| Red | Error, danger, urgency – use for destructive actions, errors, excitement, strength, love, energy |
| Green | Success, confirmation, positive status – use for success messages, nature, healing, freshness, quality |
| Yellow | Warning, attention – good for non-critical warnings, creativity, happiness, warmth, cheer |
| Orange | Activity, progress, mild warnings, confidence, bravery, sociability |
| Purple | Creativity, premium, mystery – good for onboarding, premium features, royalty, luxury, spirituality, ambition |
| Black/Gray | Neutral, structure – used for base text, dividers, backgrounds, formality, dramatic, security |
| White | Clean, open background, neutral space, honest, innocence, simplicity |
Use color to reinforce meaning, not as the only indicator (e.g., not only a red button but also an error icon and label).
❗️Color Categories You Need
To build a consistent and accessible design system, it’s essential to define a set of semantic color categories. These categories group colors by their functional role in the UI, such as backgrounds, text, borders, and states, rather than by their visual appearance. This structure ensures clarity, scalability, and easier maintenance across light and dark themes. Below is a list of recommended color categories that should cover all common use cases in modern web applications. For some applications more or not all colors are needed.
| Category | Description | Examples |
|---|---|---|
| Primary | Brand/main interaction color (sometimes two primary colors from the same color family can be helpful) | primary buttons, important headers |
| Secondary | Optional second brand color (sometimes two secondary colors from the same color family can be helpful) | accent buttons, active states |
| Tertiary / Accent | Supporting color for highlights | highlights, tags, borders |
| Neutral | Grayscale spectrum for text, backgrounds | text, backgrounds, borders |
| Success / Warning / Error / Info | Status colors for system feedback | form validation, alerts, toasts |
| Backgrounds | Default, surface, elevated, modal backgrounds | page background, overlays |
| Borders | Dividers, focus rings | separators, outlines |
| Text | Normal, muted, disabled, inverted texts | texts, links |
Background Colors
| Background Name | Description |
|---|---|
| Page | Main page background |
| Surface | Default surface (e.g., cards, modals) |
| Surface-hover | Hover state of the surface |
| Surface-active | Active/pressed state |
| Subtle | Very light backgrounds for grouping |
| Inverse | Background on dark sections (e.g., footer) |
| Backdrop | Overlay backgrounds (e.g., modals, drawers) |
Text Colors
| Token Name | Description |
|---|---|
| Primary | Main content text |
| Secondary | Less important supporting text |
| Disabled | Text on disabled elements |
| Inverse | Text on dark backgrounds |
| Brand | Text colored with brand identity |
| Link | Default link text |
| Error | Error messages or labels |
| Warning | Warning messages or labels |
| Success | Success messages or labels |
🌘 States & Shadings
Define state variants for each interactive color:
| State | Description | Use |
|---|---|---|
| Base | Default appearance | Default button color |
| Hover | On mouse hover | Slightly darker/lighter shade |
| Active | On press/click | Stronger contrast for click |
| Disabled | On keyboard focus | Muted, low contrast |
| Focus | Inactive or unavailable state | Add visible outline (focus ring) |
Use 4–8 shades per color for UI flexibility (e.g., primary-100 to primary-900).
Light & Dark Mode
Define at least two themes: Light and Dark. Use the same semantic token names, different values.
Example Values:
| Token | Light Value | Dark Value |
|---|---|---|
| Primary | #000000 | #FFFFFF |
| Surface | #FFFFFF | #121212 |
| Error | #D32F2F | #EF9A9A |
Don’t invert colors blindly — adjust saturation and contrast to maintain legibility and mood.
🧩 Design Tokens
Design tokens are platform-agnostic variables that store visual design values like colors, spacing, typography. This creates consistency, scalability, and theme-ability across platforms. A well-structured token system helps you separate raw design values from their usage context.
The token system is typically divided into three layers:
-
Primitives (Base Tokens): Raw values like colors, typography, spacing — defined without any specific meaning.
Token Example Description color.blue.500#0078F0A raw color swatch font.size.md16pxA specific font size spacing.sm8pxA spacing unit These tokens do not carry semantic meaning. They’re like your raw material.
🚫Never use primitives in the code. Use semantic tokens instead.
-
Semantic Tokens: Tokens with a specific purpose in your design system. These reference primitives.
Token References Description color.text.primarycolor.gray.900Main body text color.bg.surfacecolor.gray.50Default card background color.brand.primarycolor.blue.500Main interaction color Semantic tokens allow you to swap out themes (e.g., light/dark mode) without changing the meaning.
-
Component Tokens (Optional Layer): Tokens scoped to specific components for full flexibility and design control.
Token Description button.primary.bgBackground of primary button button.primary.textText color of primary button input.border.focusBorder color when input is focused These are especially helpful when you want to override styles for a specific component without affecting the whole system.
📌 Best Practices
- Always define primitives first, then reference them through semantic tokens.
- Use semantic names (
text.primary,bg.surface) instead of visual ones (blue.500) in your UI. - Keep component tokens optional – only add them when you need overrides or granular control.
- Ensure all tokens are documented in one central source of truth (e.g., Tokens Studio or Style Dictionary).
📍Where and How to Define Your Color Tokens
Defining color tokens properly ensures consistency across design and code. Tokens should be created and maintained in a centralized, version-controlled system and be accessible to both designers and developers.
Recommended Tools & Formats
| Tool / Format | Use Case |
|---|---|
| Tokens Studio (Figma Plugin) | Define and sync design tokens visually in Figma |
| Style Dictionary | Export tokens to multiple platforms (CSS, SCSS, JS, Android, iOS, etc.) |
| Tailwind CSS Config | Define colors as part of Tailwind’s theming system |
| Custom JSON/SCSS/TS Files | For custom design systems with manual control |
| CSS Variables (:root) | Native browser token usage via --color-token-name |
Example Locations for Token Definitions
tokens/color-tokens.json→ Source of truth (for automated exports)styles/_tokens.scss→ Imported into SCSS projectstheme/colors.ts→ For JS/TS projects using CSS-in-JS or Tailwindglobal.cssortheme.css→ For CSS variables (--color-text-primary)
Syncing with Figma
If you’re using Figma, you can:
- Use Tokens Studio to define and manage token names and values.
- Sync them with your design system libraries.
- Export them to JSON for development via Style Dictionary or GitHub Actions.
Always document who is responsible for updating tokens (e.g., brand team, design ops) and how they are versioned.
♿️ Accessibility & Contrast
Follow at least WCAG 2.1 Guidelines
| Content Type | Min Contrast Ratio |
|---|---|
| Normal text | 4.5:1 |
| Large text (18pt bold or 24pt normal) | 3:1 |
| UI components (borders, icons) | 3:1 |
Use tools like:
Don’t rely on color alone. Always use icons, text labels, or shape indicators too.
🌐 Where to Find Inspiration
- Material 3 Design System
- Apple Human Interface Guidelines
- Atlassian Design
- Color Hunt
- Coolors
- Open Props
📌 Best Practices
- Never hardcode color values — always use tokens.
- Test for accessibility in both Light and Dark modes.
- Name tokens semantically, not visually (text.error > red-500).
- Use consistent spacing between shades (e.g., 10–20% difference in lightness).
- Ensure interactive elements have visible focus indicators.
- Document everything in a centralized Design System or Tokens file (like Figma Tokens, Style Dictionary, or Tokens Studio).