ux-color-system_skill

Overview

This skill provides a semantic, fantasy-themed color system built with CSS custom properties for the Fantasy Phonics game. It codifies surface/text relationships, primary and accent tokens, feedback colors, phase indicators, overlays, gradients, and dark-theme defaults. Use it to apply consistent, accessible colors across components, themes, and game phases. It emphasizes maintainability and color accessibility for a warm, parchment-and-gold aesthetic.

How this skill works

The system exposes named CSS variables for surfaces, on-surface text, primary accents, outlines, semantic feedback colors, and phase-specific tokens. Components consume these tokens for backgrounds, text, borders, overlays, and gradients so visual changes flow from the central token set. It includes overlay rules for hover/active/disabled states, gradient patterns for special elements, and media-query hooks to invert tokens for a light theme. Contrast guidance and explicit do/don't examples ensure accessible pairings.

When to use it

• When styling core app surfaces, cards, and layouts to match the game’s fantasy aesthetic.
• When defining component states (success, error, warning) and interactive feedback.
• When implementing phase-specific visuals (word, collision, mutation, story).
• When creating theme switches or adding a light theme variant.
• When crafting achievement visuals, parchment backgrounds, or immersive vignettes.

Best practices

• Always pair surface variables with the corresponding on-surface token for readable text.
• Use semantic tokens (color-success, color-error) for stateful styling instead of ad-hoc hex values.
• Apply phase colors via data attributes (data-phase) so indicators remain consistent and easy to change.
• Prefer overlay tokens for hover/active/disabled states to keep interaction color consistent.
• Avoid muted outline colors for body text; reserve them for borders and subtle UI elements.

Example use cases

• Card component using --theme-surface-variant, border via --theme-outline-variant, and focus ring with --theme-primary.
• Primary button using --theme-primary and --theme-on-primary with hover/active overlays.
• Phase indicator that sets --phase-color via [data-phase] to highlight the current game phase.
• Achievement tile with a gold shimmer gradient using --theme-primary and --theme-on-primary-container.
• Error/success banners using --color-error and --color-success with accessible contrast on dark surface.