# Implementing Dark Mode in Taste Skill: Dark Mode Protocol Best Practices > Learn dark mode protocol best practices for Taste Skill. Implement global themes using Tailwind or CSS custom properties to prevent mid-page switches. - Repository: [Leon Lin/taste-skill](https://github.com/Leonxlnx/taste-skill) - Tags: best-practices - Published: 2026-05-30 --- **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`](https://github.com/Leonxlnx/taste-skill/blob/main/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`](https://github.com/Leonxlnx/taste-skill/blob/main/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. ```html

Welcome

Your content stays readable in both light and dark mode.

``` 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). ```css /* 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); } ``` ```html

Dark-mode ready component

This text respects the CSS variables and adapts automatically.

``` 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. ```javascript // 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`](https://github.com/Leonxlnx/taste-skill/blob/main/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).