Implementing Dark Mode in Taste Skill: Dark Mode Protocol Best Practices

Taste Skill enforces a page-level theme lock that applies a single mode (light, dark, or auto) globally to prevent mid-page theme switches, using either Tailwind dark: utilities or CSS custom properties for implementation.

Taste Skill is an AI-driven design-prompt framework that generates full-stack web experiences with dark mode baked into the design specifications rather than added as an afterthought. The repository's Dark Mode Protocol, defined in skills/taste-skill/SKILL.md, mandates strict architectural rules to ensure consistent visual identity across all generated components.

The Page-Level Theme Lock Rule

According to line 921 of skills/taste-skill/SKILL.md, Taste Skill requires a single-theme per page architecture. The entire page must choose one mode—light, dark, or auto based on prefers-color-scheme—and maintain that lock for the duration of the scroll. This prevents jarring mid-page flips where a user might encounter an unexpected light section inside a dark page or vice versa.

The theme lock is considered a global property applied at the document root, ensuring that every child component inherits the same mode context without exception.

Design System Foundations

Dual-Mode Asset Requirements

Every component, image, and logo must be provided in variants that work in both contexts. As specified at line 280, logos must render as "white-on-dark, black-on-light, or a single-color theme variable" to ensure brand fidelity across themes. This requirement eliminates reliance on CSS filters or opacity tricks that can degrade visual quality.

Contrast and Accessibility Standards

All dark-mode palettes must meet WCAG AA standards (AAA for body text). While the project brief determines the exact color families, the designer must retain visual hierarchy and readability regardless of the active theme (lines 532-535). This includes ensuring sufficient contrast ratios between surface backgrounds and text elements.

Implementation Approaches

Tailwind dark: Variant (Utility-First)

For utility-first projects, Taste Skill recommends Tailwind's dark: prefix as the default approach. Each utility has a dark counterpart that automatically activates when the parent carries the dark class or media query.

<section class="bg-white dark:bg-zinc-950 text-gray-900 dark:text-gray-100 py-12">
  <h1 class="text-3xl font-bold">Welcome</h1>
  <p class="mt-4">Your content stays readable in both light and dark mode.</p>
  <button class="mt-6 px-4 py-2 bg-indigo-600 text-white dark:bg-indigo-500 dark:text-black rounded">
    Get Started
  </button>
</section>

The dark: prefix automatically swaps colors when the page is in dark mode, as referenced in line 1084 of the skill specification.

CSS Custom Properties (Component Libraries)

For component libraries such as shadcn/ui or Radix Themes, semantic tokens are preferred. Variables like --surface and --text-primary are swapped under [data-theme="dark"] or @media (prefers-color-scheme: dark) blocks (lines 578-583).

/* core.css */
:root {
  --surface: #ffffff;
  --text-primary: #1f2937;
}

/* Dark override */
@media (prefers-color-scheme: dark) {
  :root {
    --surface: #111827;
    --text-primary: #f9fafb;
  }
}

/* Component usage */
.page {
  background-color: var(--surface);
  color: var(--text-primary);
}

<div class="page p-8">
  <h2>Dark-mode ready component</h2>
  <p>This text respects the CSS variables and adapts automatically.</p>
</div>

Semantic tokens keep the design system consistent and allow easy swapping of whole palettes without refactoring individual utility classes.

System Preference Handling

Unless a brand explicitly forces a mode, the default should follow prefers-color-scheme (line 535). The specification recommends detecting this media query at page load and applying it immediately to prevent flashes of incorrect themes before JavaScript executes.

Enforcing the Theme Lock with JavaScript

To satisfy the "no mid-page flips" rule, Taste Skill suggests running a theme lock script once on page load. This sets the final theme value and prevents later sections from overriding the mode.

// theme-lock.js – run once on page load
const theme = document.documentElement.dataset.theme; // 'light', 'dark', or 'auto'

if (theme === 'auto') {
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  document.documentElement.dataset.theme = prefersDark ? 'dark' : 'light';
}

// Prevent later sections from overriding the mode
document.documentElement.setAttribute('data-theme-locked', 'true');

The lock ensures all later-rendered sections honour the chosen mode, satisfying the architectural requirement documented at line 921.

Avoiding Common Dark Mode Pitfalls

The specification explicitly prohibits several anti-patterns that degrade user experience (lines 39-44, 90-92):

• Pure black backgrounds (#000000) that cause eye strain in OLED environments
• Abrupt color jumps between sections without transitional design elements
• Generic glass-morphism or over-used gradients that reduce readability
• "Centered dark hero" clichés that lack originality or brand distinction

Summary

• Taste Skill uses a page-level theme lock to prevent mid-page theme switches and maintain visual consistency.
• All assets must be designed for both light and dark contexts from the start, with specific logo rendering requirements.
• Implementation supports either Tailwind dark: variants for utility-first projects or CSS custom properties for component libraries.
• System preference detection via prefers-color-scheme is the default unless explicitly overridden by brand requirements.
• WCAG AA contrast standards are mandatory for all dark mode palettes, with AAA required for body text.

Frequently Asked Questions

How does Taste Skill prevent theme flickering on page load?

The framework recommends setting the theme immediately on the document root via JavaScript before rendering begins, then locking it with a data-theme-locked attribute to prevent downstream components from overriding the choice. This ensures the correct CSS variables or Tailwind classes apply before the user sees any content.

Can I mix light and dark sections on the same Taste Skill page?

No. Line 921 of skills/taste-skill/SKILL.md explicitly forbids mid-page theme switches. The entire page must commit to a single mode (light, dark, or auto) to maintain visual consistency and prevent user disorientation during scroll.

What is the recommended way to handle logos in dark mode?

Logos must be provided as "white-on-dark, black-on-light, or a single-color theme variable" according to line 280. This ensures brand visibility regardless of the active color scheme without relying on CSS filters that might reduce image quality or brand recognition.

Does Taste Skill require specific color values for dark mode?

No specific hex codes are mandated, but all combinations must meet WCAG AA contrast ratios (AAA for body text). The exact color families are determined by the project brief, provided they maintain accessible visual hierarchy and brand fidelity across both themes (lines 532-535).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}