Color Mode and Theme Skill: Light, Dark or Both

What is the color-mode-and-theme skill?

The color-mode-and-theme skill opens with a flat rule: color mode is a brand and context decision, not a personal preference. It sits in skills/color-mode-and-theme inside dembrandt-skills, a repository of design knowledge packaged for AI agents.

Its frontmatter lists path patterns such as CSS and SCSS files, tokens and theme folders and tailwind.config, plus prompt phrases like dark mode, theme selector and brand tone. These are the triggers the metadata declares for when the skill applies.

Light, dark or combined

Light is called the safer default for most products, because it performs better in bright environments and has broader accessibility coverage out of the box. Dark mode is harder to get right, and light mode beats a broken dark mode.

The combined approach respects prefers-color-scheme for the default and offers a toggle. The skill shows CSS with media queries for dark and light tokens, plus data-theme attribute selectors for the manual override.

When a theme selector earns its place

A selector is a UI control that takes space and adds complexity, so the skill recommends one only when user control genuinely matters. The rule of thumb is whether the user spends hours per day in the tool.

Brand tone also steers the default mode. A very dark primary such as navy or near-black surfaces naturally in dark, while a bright, vivid primary lets light mode breathe.

• Clean, minimal, trustworthy and open brands default to light.
• Premium, exclusive, bold and immersive brands default to dark, as do technical, data-heavy ones.
• Playful, colorful brands default to light, since vivid colors are harder to maintain in dark.
• Neutral, enterprise brands default to light with a system-default toggle.

Dark mode token rules

A theme switcher is a second palette, not a toggle. Each semantic color needs a verified value in every mode, because contrast that passes on light routinely fails on dark.

• Do not use pure black #000000 as the base surface. Use a very dark neutral such as #0A0A0F or #111827.
• Build surface hierarchy from lightness steps, with each higher surface lighter instead of more shadowed.
• Reduce brand color saturation slightly, by about 10 to 15%, so vivid colors stay readable.
• Raise font weight by one step for light text on dark, for example Regular to Medium.
• Verify every text and background contrast pair against WCAG 2.2 AA in both modes.

/* Dark mode surface scale */
--color-surface:         #0A0A0F;  /* base */
--color-surface-raised:  #141419;  /* cards */
--color-surface-overlay: #1E1E26;  /* modals, popovers */
--color-border:          rgba(255,255,255,0.08);
--color-text:            #F0F0F5;
--color-text-secondary:  #8A8F98;

It also warns that a hardcoded color equal to a token's value is that token, written in a form that cannot follow the theme. Its fix is mechanical: grep markup for literal colors, count them as a debt and block new ones.

Who the color-mode-and-theme skill is for

Best for

• Deciding whether a new product needs dark mode, light mode or both.
• Defining a base palette that matches brand tone and use context.
• Adding a theme toggle without creating a second maintenance burden. For deeper implementation detail, see dark-mode-design.
• Reviewing a dark theme that feels off, using the eight-question checklist.

Not for

• Generating a palette from a brand color. The same repository lists a separate algorithmic-color-palette skill for that. See also color-system.
• Full accessibility audits. The README lists a separate WCAG skill, and this one only asks you to verify contrast.
• Pixel-level component styling, since it deals with palette and mode decisions.

Use it with UiChemy

The skill advises on color mode and CSS tokens, and it builds no pages. Its table says a marketing site or landing page should pick one mode and commit to it.

Decide the mode with the skill, design the pages in Figma in that one mode, then convert them with UiChemy Figma to WordPress. Click Get Started on uichemy.com. For building the palette itself, see better-colors.

How to install Color Mode and Theme Skill: Light, Dark or Both

git clone https://github.com/dembrandt/dembrandt-skills.git

1. Clone the repository

   Run git clone https://github.com/dembrandt/dembrandt-skills.git. The skill sits in the skills/color-mode-and-theme folder.

2. Copy the skill folder

   Copy skills/color-mode-and-theme to wherever your AI coding agent loads skills from. For Claude Code, use its skills location.

3. Open a styling project

   Start the agent in a project with CSS, SCSS, token or theme files, which match the path patterns in the skill's metadata.

4. Ask a color mode question

   Try should this app be dark or light, when should I add a theme toggle, or design a dark mode for this dashboard.

Check that it loaded

Ask whether a trading dashboard should be dark or light. The answer should treat it as a brand and context decision, favor dark with a theme selector, and warn about pure black and contrast checks.

Read the official instructions on GitHub

Key features

• Mode as a brand decisionThe agent chooses light, dark or combined from brand tone and use context, and treats the choice as deliberate instead of a personal preference.
• Light mode profileLight is open, trustworthy and content-forward, fits marketing, e-commerce, editorial and mixed-audience products, and is the safer default.
• Dark mode profileDark is premium, focused and technical, fits trading, developer and creative tools, and comes with a caution that it is harder to get right.
• Combined modeUse prefers-color-scheme for the default and data-theme selectors for a manual override, with CSS shown for both.
• Selector decision tableSeven situations from marketing sites to creative tools say whether a theme selector is worth building, with placement in the header or user settings.
• Brand tone mappingFive brand tones map to a default mode, from clean and minimal brands to playful, colorful ones.
• Second palette ruleA theme switcher needs verified values for every semantic color in each mode, instead of one value flipped by an algorithm.
• Dark surface rulesAvoid pure black bases, build hierarchy with lightness steps, soften saturation by about 10 to 15%, and raise font weight one step.
• Hardcoded color ruleA literal equal to a token is that token in a form that cannot follow the theme, so the skill suggests grepping for literals and blocking new ones.
• Review checklistEight questions cover deliberate mode choice, system default, toggle placement, surface steps, saturation, contrast, font weight and pure black.

Frequently asked questions