UX Color System Skill

Semantic color architecture for the Fantasy Phonics game. Uses CSS custom properties for maintainable, accessible theming.

Color Philosophy

Colors in this project follow a fantasy/medieval aesthetic:

• Warm, parchment-like surfaces
• Gold accents for primary actions
• Earth tones for secondary elements
• Success greens and error reds for feedback

Semantic Color Tokens

Surface & Background

/* Base surfaces */
--theme-surface: #252119;           /* Main background */
--theme-surface-variant: #2f2a21;   /* Elevated surfaces */
--theme-surface-dim: #1a1814;       /* Recessed areas */

/* Text on surfaces */
--theme-on-surface: #f5e6c8;        /* Primary text */
--theme-on-surface-variant: #9b8b72; /* Secondary/muted text */

Primary & Accent

/* Primary gold accent */
--theme-primary: #d4a84b;           /* Buttons, links, focus */
--theme-on-primary: #1a1814;        /* Text on primary */
--theme-primary-container: #3d3525; /* Primary backgrounds */
--theme-on-primary-container: #f5daa0;

/* Secondary/outline */
--theme-outline: #8b7355;           /* Borders */
--theme-outline-variant: #5c4d3d;   /* Subtle borders */

Semantic Colors

/* Feedback colors */
--color-success: #6bcf7f;           /* Completed, correct */
--color-error: #ef4444;             /* Errors, wrong */
--color-warning: #f59e0b;           /* Caution states */

/* Phase-specific colors */
--color-word: #6366f1;              /* Word phase (indigo) */
--color-collision: #ec4899;         /* Collision phase (pink) */
--color-mutation: #f59e0b;          /* Mutation phase (amber) */
--color-story: #22c55e;             /* Story phase (green) */

Usage Patterns

Surface/Text Pairing

Always pair surface and text colors correctly:

.card {
  background: var(--theme-surface);
  color: var(--theme-on-surface);
}

.card-muted {
  color: var(--theme-on-surface-variant);
}

.button-primary {
  background: var(--theme-primary);
  color: var(--theme-on-primary);
}

State Colors

Apply semantic colors for component states:

/* Success state */
.completed {
  color: var(--color-success);
  border-color: var(--color-success);
}

/* Error state */
.error {
  color: var(--color-error);
  border-color: var(--color-error);
}

/* Active/focus state */
.focused {
  border-color: var(--theme-primary);
  box-shadow: 0 0 0 3px rgba(212, 168, 75, 0.2);
}

Phase Indicators

Use phase colors consistently throughout game:

[data-phase="word"] {
  --phase-color: var(--color-word);
}

[data-phase="collision"] {
  --phase-color: var(--color-collision);
}

[data-phase="mutation"] {
  --phase-color: var(--color-mutation);
}

[data-phase="story"] {
  --phase-color: var(--color-story);
}

.phase-indicator {
  background: var(--phase-color);
}

Overlay Colors

For hover, active, and disabled states:

:root {
  /* Overlays */
  --color-hover-overlay: rgba(212, 168, 75, 0.08);
  --color-active-overlay: rgba(212, 168, 75, 0.2);
  --color-disabled-overlay: rgba(0, 0, 0, 0.4);
}

.button:hover {
  background: var(--color-hover-overlay);
}

.button:active {
  background: var(--color-active-overlay);
}

.button:disabled {
  opacity: 0.6;
}

Gradient Patterns

Fantasy-themed gradients for special elements:

/* Parchment gradient */
.parchment {
  background: linear-gradient(
    180deg,
    var(--theme-surface) 0%,
    var(--theme-surface-variant) 100%
  );
}

/* Gold shimmer for achievements */
.achievement {
  background: linear-gradient(
    135deg,
    var(--theme-primary) 0%,
    var(--theme-on-primary-container) 50%,
    var(--theme-primary) 100%
  );
}

/* Vignette for immersion */
.vignette::after {
  content: '';
  position: absolute;
  inset: 0;
  background: radial-gradient(
    ellipse at center,
    transparent 0%,
    rgba(0, 0, 0, 0.3) 100%
  );
  pointer-events: none;
}

Color Accessibility

Contrast Requirements

Combination	Ratio	Pass
--theme-on-surface on --theme-surface	12.5:1	AAA
--theme-on-surface-variant on --theme-surface	4.8:1	AA
--theme-primary on --theme-surface	7.2:1	AAA
--color-success on --theme-surface	6.1:1	AA

Never Do

/* DON'T: Low contrast combinations */
.bad {
  color: var(--theme-outline);        /* Too muted for body text */
  background: var(--theme-surface);
}

/* DON'T: Colored text on colored background */
.bad {
  color: var(--color-success);
  background: var(--color-word);
}

Always Do

/* DO: Use semantic pairings */
.good {
  background: var(--theme-surface);
  color: var(--theme-on-surface);
}

/* DO: Use muted for large, non-critical text */
.hint {
  font-size: var(--step--1);          /* Larger text */
  color: var(--theme-on-surface-variant);
}

Dark Theme (Default)

This project uses dark theme as default. If adding light theme:

@media (prefers-color-scheme: light) {
  :root {
    --theme-surface: #f5e6c8;
    --theme-on-surface: #1a1814;
    --theme-surface-variant: #e8d9b8;
    /* Invert other tokens... */
  }
}

Component Examples

Card Component

.card {
  background: var(--theme-surface-variant);
  border: 1px solid var(--theme-outline-variant);
  color: var(--theme-on-surface);
}

.card:hover {
  border-color: var(--theme-outline);
}

.card:focus-within {
  border-color: var(--theme-primary);
}

Button Variants

/* Primary */
.btn-primary {
  background: var(--theme-primary);
  color: var(--theme-on-primary);
}

/* Secondary/Ghost */
.btn-secondary {
  background: transparent;
  color: var(--theme-primary);
  border: 1px solid var(--theme-primary);
}

/* Danger */
.btn-danger {
  background: var(--color-error);
  color: white;
}