Color Usage Guide

Use semantic tokens instead of raw palette colors. Tokens ensure consistency across light/dark modes and future palette changes.

Token Decision Table

Detailed Token Reference

Brand

Maps to: brand | Category: ui

Brand color for the primary brand logo and branding

When to use: Brand expression: logo backgrounds, brand-colored accents, marketing highlights.

When NOT to use: Interactive elements (use primary/navigation). Status feedback (use success/error/warning).

Dark mode: Same token, lighter shades (50-300) for backgrounds, darker (700-950) for text.

Common pairings: neutral for text on brand backgrounds. primary for CTAs alongside brand elements

Error

Maps to: red | Category: status

Error states and destructive actions

When to use: Negative outcomes: validation errors, failed operations, destructive actions (delete, remove).

When NOT to use: Non-destructive warnings (use warning). Quality scores (use quality-* tokens).

Dark mode: Same token.

Common pairings: neutral for text within error banners. primary for recovery actions

Info

Maps to: sky | Category: status

Informational messages and neutral actions

When to use: Neutral information: tips, hints, contextual help, feature announcements.

When NOT to use: Actionable warnings (use warning). Success confirmation (use success).

Dark mode: Same token.

Common pairings: neutral for text within info banners

Navigation

Maps to: brand | Category: navigation

Primary actionable elements that cause navigation to another location (links, buttons, breadcrumbs, menu items)

When to use: Any clickable element that navigates to another page or section.

When NOT to use: State-changing actions like save/delete (use primary). Non-interactive brand elements (use brand).

Dark mode: Same token. Use 400 shade on dark backgrounds, 600 on light.

Common pairings: neutral for non-active nav items. primary to distinguish navigation from actions

Neutral

Maps to: paper | Category: internal

Internal Nuxt UI neutral variant — not for direct use

When to use: Nuxt UI uses this token internally to render colorless component variants. Do not reference it in application code.

When NOT to use: Do not use directly. Nuxt UI applies it automatically when no color prop is set.

Paper

Maps to: paper | Category: ui

Neutral grayscale color for text, borders, and backgrounds, in light mode

When to use: Text, borders, dividers, subtle backgrounds, disabled states.

When NOT to use: Interactive elements that need to stand out (use primary). Status indicators (use success/error).

Common pairings: primary for interactive elements on neutral backgrounds. brand for accents

Phase-active

Maps to: sky | Category: phase

In progress

When to use: Items currently being processed. Animate the icon for running state.

When NOT to use: Completed items (use phase-done). Info messages (use info).

Common pairings: phase-done or phase-failed as terminal states

Phase-archived

Maps to: space | Category: phase

Soft-deleted or moved to cold storage

When to use: Items removed from active view but not permanently deleted.

When NOT to use: Hard-deleted items (they shouldn't appear in UI).

Common pairings: phase-done before archival. phase-idle if un-archived

Phase-done

Maps to: emerald | Category: phase

Completed successfully

When to use: Items that finished processing without errors.

When NOT to use: Success feedback to user actions (use success). Quality scoring (use quality-* tokens).

Common pairings: phase-archived for items moved to cold storage

Phase-expired

Maps to: yellow | Category: phase

Time-based termination

When to use: Items that ended due to time constraints, not errors.

When NOT to use: Failures (use phase-failed). Active timeouts needing user attention (use warning).

Common pairings: phase-idle for items that can be re-triggered

Phase-failed

Maps to: rose | Category: phase

Terminal failure

When to use: Items that failed permanently and won't be retried.

When NOT to use: User-facing error messages (use error). Retryable failures (use phase-retry).

Common pairings: phase-retry before exhausting attempts

Phase-idle

Maps to: paper | Category: phase

Not started or pending

When to use: Items that exist but have not entered the pipeline yet.

When NOT to use: Items waiting in a queue (use phase-queued).

Common pairings: phase-queued as first transition. phase-active once processing begins

Phase-queued

Maps to: indigo | Category: phase

Waiting in queue

When to use: Items accepted into the pipeline and waiting for their turn.

When NOT to use: Items not yet submitted (use phase-idle). Items being processed (use phase-active).

Common pairings: phase-active as next state

Phase-retry

Maps to: violet | Category: phase

Re-processing after a transient failure

When to use: Items being re-processed after a recoverable failure.

When NOT to use: Terminal failures (use phase-failed). Normal processing (use phase-active).

Common pairings: phase-active when retry succeeds. phase-failed when retries exhausted

Polarity-mixed

Maps to: amber | Category: polarity

Mixed or ambiguous judgment (partial, conflicting, debatable)

When to use: When the judgment is neither clearly positive nor negative.

When NOT to use: Warning states about user actions (use warning). Regular quality scores (use quality-regular).

Common pairings: polarity-positive and polarity-negative for context

Polarity-negative

Maps to: red | Category: polarity

Negative judgment (bad, false, rejected, denied)

When to use: Binary good/bad judgments where 'bad' applies. Sentiment analysis results.

When NOT to use: Error feedback from actions (use error). Quality scores (use quality-* tokens).

Common pairings: polarity-positive for contrast. polarity-neutral for unknown state

Polarity-neutral

Maps to: paper | Category: polarity

Neutral or unknown judgment (N/A, unresolved, no opinion)

When to use: When no positive or negative judgment applies, or data is unknown.

When NOT to use: Disabled states (use neutral). Missing data (use quality-none).

Common pairings: polarity-positive and polarity-negative for tri-state displays

Polarity-positive

Maps to: green | Category: polarity

Positive judgment (good, true, resolved, approved)

When to use: Binary good/bad judgments where 'good' applies. Sentiment analysis results.

When NOT to use: Success feedback from actions (use success). Quality scores (use quality-* tokens).

Common pairings: polarity-negative for contrast. polarity-neutral for unknown state

Primary

Maps to: cyan | Category: action

Primary color for main actions and highlights (primary buttons, form submissions, state-changing actions)

When to use: State-changing actions the user initiates (save, submit, confirm, add).

When NOT to use: Navigation links (use navigation). Status indicators (use success/error/warning). Brand decoration (use brand).

Dark mode: Same token name, shades auto-adjust via palette.

Common pairings: secondary for less-important actions alongside primary. neutral for text on primary backgrounds

Prominent

Maps to: amber | Category: action

Specially decorated action elements for more prominent cosmetic appearance (hero CTAs, featured product actions)

When to use: Hero CTAs, featured product actions, promotional buttons that need extra visual weight.

When NOT to use: Regular actions (use primary). Navigation (use navigation). Repeated elements.

Dark mode: Same token.

Common pairings: Use sparingly — only one prominent element per view

Quality-bad

Maps to: orange | Category: quality

Below standard quality (0.15–0.50)

When to use: Scores in the 0.15–0.50 range, below acceptable standard.

When NOT to use: Warnings about user actions (use warning).

Common pairings: quality-regular as improvement target

Quality-excellent

Maps to: green | Category: quality

Strong performance (0.80–1.0)

When to use: Scores in the 0.80–1.0 range (exclusive of 1.0), outstanding performance.

When NOT to use: Success confirmations (use success).

Common pairings: quality-perfect for flawless distinction

Quality-good

Maps to: lime | Category: quality

Meets standard (0.65–0.80)

When to use: Scores in the 0.65–0.80 range, meets expected standard.

When NOT to use: Success confirmations (use success). Positive judgments (use polarity-positive).

Common pairings: quality-excellent for top-tier distinction

Quality-insufficient

Maps to: red | Category: quality

Unacceptable quality (0–0.15)

When to use: Scores in the 0–0.15 range, clearly unacceptable results.

When NOT to use: Error states from user actions (use error). Destructive actions (use error).

Common pairings: quality-bad for borderline cases

Quality-none

Maps to: paper | Category: quality

No data or not evaluated

When to use: Items that have not been scored or evaluated yet.

When NOT to use: Known zero scores (use quality-insufficient). Disabled states (use neutral).

Common pairings: quality-insufficient once evaluation starts

Quality-perfect

Maps to: brand | Category: quality

Flawless quality (exactly 1.0)

When to use: Score of exactly 1.0, flawless results. Uses brand color for maximum impact.

When NOT to use: General success states (use success).

Common pairings: quality-excellent for near-perfect distinction

Quality-regular

Maps to: amber | Category: quality

Below expectations (0.50–0.65)

When to use: Scores in the 0.50–0.65 range, below expectations but not critically bad.

When NOT to use: Warning states (use warning). Ambiguous judgments (use polarity-mixed).

Common pairings: quality-good as next tier

Secondary

Maps to: emerald | Category: action

Secondary color for supporting actions (secondary buttons, supporting UI elements)

When to use: Supporting actions paired with primary (cancel, back, dismiss).

When NOT to use: Primary actions (use primary). Text and borders (use neutral directly).

Dark mode: Same token.

Common pairings: primary for the main action in a button group

Space

Maps to: space | Category: ui

Neutral grayscale color for text, borders, and backgrounds, in dark mode

When to use: Text, borders, dividers, subtle backgrounds, disabled states.

When NOT to use: Interactive elements that need to stand out (use primary). Status indicators (use success/error).

Common pairings: primary for interactive elements on neutral backgrounds. brand for accents

Success

Maps to: green | Category: status

Success states and confirmations

When to use: Positive outcomes: form submitted, payment processed, action completed.

When NOT to use: Non-status green decoration (use brand palette directly). Quality scores (use quality-* tokens).

Dark mode: Same token.

Common pairings: neutral for text within success banners

Warning

Maps to: orange | Category: status

Warning states and cautions

When to use: Situations requiring attention but not errors: unsaved changes, expiring sessions, approaching limits.

When NOT to use: Errors (use error). Informational messages (use info).

Dark mode: Same token.

Common pairings: neutral for text within warning banners

Forbidden Combinations

• Never use brand for interactive elements — use primary or navigation
• Never use primary for navigation links — use navigation
• Never use status tokens (success/error/warning/info) for decoration
• Only one prominent element per view