Short answer: Dark mode is not light mode with the colours inverted. A good dark theme uses dark grey backgrounds instead of pure black, reduces text to around 85% opacity instead of pure white, adjusts image brightness, and uses muted accent colours. Most AI coding tools get this wrong by default. Here is how to fix it.
Dark mode has gone from a developer preference to a user expectation. Most visitors use their operating system in dark mode. When they land on a website that does not support it, the bright white background is jarring. When they land on a website with a poorly implemented dark mode, the text is hard to read and the images look wrong.
AI coding tools handle dark mode inconsistently. Some generate a working theme toggle but get the colours wrong. Others produce a dark background with white text that has too much contrast. And many skip dark mode entirely unless you specifically ask for it. This guide covers the design principles behind a good dark theme and how to prompt for them when building with AI.
Use dark grey, not pure black
The first rule of dark mode design is to avoid pure black (#000000) as the background. Pure black creates too much contrast with text and UI elements. It makes the page look harsh and tiring to read. Instead, use a dark grey in the range of #111111 to #1A1A1A for the main background. This is what Apple, Linear, Vercel, and every well-designed dark theme uses.
For surface elements like cards, modals, and dropdowns, use a slightly lighter grey: #1E1E1E to #262626. This creates a subtle elevation hierarchy without relying on shadows, which are less visible on dark backgrounds. The layered greys replace the shadow-based depth that works in light mode.
When prompting your AI coding tool, be specific about the background values. "Dark mode" in a prompt will produce unpredictable results. "Dark mode with a #141414 background, #1E1E1E cards, and #0A0A0A borders" gives the AI values to follow. Better still, paste a design template that includes dark mode definitions.
Reduce text brightness
Pure white text (#FFFFFF) on a dark background is too bright. It causes halation, where the text appears to glow and bleed into the surrounding dark space. This makes long-form text physically uncomfortable to read. Reduce the primary text colour to around 87% brightness: rgba(255,255,255,0.87) or #DEDEDE.
Secondary text, like captions and metadata, should be even dimmer: around 60% brightness. This creates a clear reading hierarchy without the eye strain of multiple high-contrast text levels. The hierarchy should feel quiet. If the text is competing for attention on a dark background, it is too bright.
AI coding tools almost always set dark mode text to pure white. When you review the generated output, check the text colours first. This is the most common dark mode mistake and the easiest to fix. Add "use rgba(255,255,255,0.87) for body text" to your prompt.
Adjust your accent colours
An accent colour that works on a white background often looks wrong on a dark background. Saturated colours like bright blue (#0066FF) or vivid green (#22C55E) can appear to vibrate against dark grey. They draw too much attention and tire the eye.
The solution is to desaturate your accent colours slightly for dark mode. Reduce the saturation by 10 to 15% and increase the lightness by 5 to 10%. This keeps the colour recognisable while making it comfortable on a dark ground. Stripe does this well: their blue is slightly different between light and dark modes, but the shift is subtle enough that you would not notice unless you compared them side by side.
If your design system defines colours as CSS custom properties, create separate dark mode values for each accent. This is the correct approach. Do not use the same hex value in both themes.
Handle images and illustrations
Images that look natural on a white background can look wrong on a dark background. Product screenshots with white chrome create bright rectangles that break the dark theme. Illustrations with white or transparent backgrounds float awkwardly against the dark ground.
For screenshots, add a subtle dark border or place them in a card with rounded corners and a slightly lighter background. This frames the bright image and creates a visual boundary. For illustrations, either provide dark-mode versions or apply a subtle brightness reduction using CSS: filter brightness(0.9) is usually enough to take the edge off without making the image look dull.
For hero sections, gradient backgrounds work particularly well in dark mode because they add colour without competing with the content. A dark radial gradient from the background colour to a slightly lighter shade creates depth that flat backgrounds lack.
Borders and dividers
In light mode, borders are typically a light grey like #E5E5E5. In dark mode, the equivalent is a colour slightly lighter than the background: around #2A2A2A to #333333. The border should be visible enough to define edges but not bright enough to create visual noise.
AI tools often get this wrong by using a border that is either too bright or too dark. A border at rgba(255,255,255,0.1) is a reliable default. It adapts naturally to different dark background shades because it is relative to the text colour rather than absolute.
Use fewer borders in dark mode than in light mode. On a dark background, spacing alone creates sufficient separation between sections. A dark theme with too many borders looks cluttered. When in doubt, remove the border and increase the gap.
How to prompt for dark mode
The most reliable way to get a good dark mode from an AI coding tool is to include the specific colour values in your prompt. A prompt like "build a landing page with dark mode" will produce generic results. A prompt like "build a landing page. Dark mode uses #141414 background, #1E1E1E cards, rgba(255,255,255,0.87) text, rgba(255,255,255,0.5) secondary text, and #3B82F6 accent" gives the AI everything it needs.
An even better approach is to paste a BrowserMoon template that already includes dark mode definitions. The template's CSS custom properties define both light and dark values. The AI reads them and applies them correctly. No guesswork, no iteration.
For a complete guide to controlling the visual quality of your AI-generated output, read the vibe coder's design guide. It covers typography, spacing, colour systems, and component design, including how to maintain consistency across light and dark themes.
Frequently asked questions
How do I add dark mode to a vibe-coded website?
Include specific dark mode colour values in your prompt: background (#141414), card surfaces (#1E1E1E), text brightness (rgba(255,255,255,0.87)), and adjusted accent colours. Or paste a design template that includes dark mode CSS custom properties. The AI applies the values to every section it generates.
Why does my AI-generated dark mode look bad?
Most AI tools default to pure black backgrounds and pure white text, which creates harsh contrast and eye strain. They also reuse light mode accent colours unchanged, which look too bright on dark grounds. Fix both by specifying dark grey backgrounds, reduced text brightness, and desaturated accents.
Should I use pure black or dark grey for dark mode?
Dark grey. Pure black (#000000) creates too much contrast with text and UI elements. A dark grey like #141414 or #1A1A1A is easier on the eyes and matches how Apple, Linear, and Vercel implement dark mode. Pure black is acceptable only for OLED-optimised mobile apps where true black saves battery.
How do I handle images in dark mode?
Add a dark border or place images in a slightly lighter card to frame them against the dark background. For illustrations, either provide dark-mode versions or reduce brightness slightly with CSS filter. For hero sections, use gradient backgrounds instead of flat colours to add depth.
What is the best text colour for dark mode?
Primary text should be around 87% brightness: rgba(255,255,255,0.87) or #DEDEDE. Secondary text should be around 60% brightness. Pure white (#FFFFFF) is too bright for body text and causes halation, making long-form content uncomfortable to read.
Related templates
Design system for vibe coding
Build a coherent design system with typography, colour, and spacing that works across every section.
The vibe coder's design guide
Control the visual quality of every AI-generated section from the first prompt.
Stripe-style gradient hero
Build a gradient hero section that works in both light and dark mode.
SaaS templates
Complete SaaS landing page designs with built-in dark mode support.
