Claude Code desktop custom themes: have Claude apply Linear, Spotify, and other brand colors from a DESIGN.md

Translated from the original Traditional Chinese version.

Summary

Now that the Claude Code desktop app supports custom themes through mods, you don’t have to pick every color yourself. Give Claude the DESIGN.md of a design system, and Claude reads the colors and writes the theme for you. Most DESIGN.md files describe only one mode, so Claude derives the other one, and you check what it derived and borrowed before deciding what to change.

Table of contents

Since November 2026, the Claude Code desktop app lets you build custom themes with mods, so the background, text, and accent colors of the Code tab, where Claude Code runs inside the desktop app, can match any palette you like. A mod is plugin code that runs inside Claude Code. The desktop app won’t apply a theme whose background layers are in the wrong order or whose text contrast is too low, so picking colors by hand is harder than it looks. If you already have a DESIGN.md, a design spec file that describes colors, type, and spacing for AI agents, you can hand it to Claude. Claude reads the colors, writes the theme mod, and checks that the theme can apply. You review what it derived.

I tested on Windows 11 with the Claude desktop app, using three DESIGN.md files from the community collection awesome-design-md: Linear, Cursor, and Spotify. With the Linear dark theme, the sidebar, conversation, and right panel all turn near-black, and the toggles switch to Linear’s blue-violet. My app runs in Traditional Chinese, so the screenshots show Chinese labels:

The Code tab with the Linear theme: a near-black background and a blue-violet Remote Control toggle

When a theme applies

A theme applies only to local sessions that load the theme mod, and only when the Claude Code version bundled with the desktop app is 2.1.324 or later. To check the version, type /status in a local session in the Code tab and look at the Claude Code row:

Situation Theme applies What to do
Local session in the Code tab, 2.1.324 or later Yes Ask Claude to build the theme as in the next section
Version below 2.1.324 No Update the desktop app, then start a new local session
The new session screen and other sessions No Copy the mod into your skills directory (see below)

According to the official docs, Claude Code in the terminal keeps its own colors, and permission prompts always keep the app’s own look.

Ask Claude to build the theme mod

The official docs note that a mod runs with your permissions and isn’t sandboxed. A theme mod that Claude writes on your machine is one you can read before you trust it, unlike a theme from an unknown source. Here are the steps:

  1. Start a local session in the Code tab and paste this prompt, replacing the URL with the URL of your own DESIGN.md. I wrote it in Chinese; this is the English equivalent:

    1Read https://raw.githubusercontent.com/VoltAgent/awesome-design-md/main/design-md/spotify/DESIGN.md and use its colors to make a theme mod for the Claude Code desktop app. I want both light and dark modes. If the DESIGN.md has only one mode, derive the other one from its style.
    
  2. Claude loads the built-in plugin-authoring skill, reads the DESIGN.md, writes the mod, and checks it with claude plugin validate. With the Spotify file, it took about 50 seconds from sending the prompt to a finished mod, and Claude didn’t ask me any questions.

  3. The mod loads when Claude’s reply for that turn ends. My session used the Auto permission mode, so the desktop app turned the mod on right away. In other permission modes, the official docs say the app first asks whether to turn on the mods for that session, and the mod loads after you allow it.

  4. Once it loads, the conversation shows the line spotify-look This mod is now loaded. and the app switches to the new colors.

When Claude hands over the mod, it lists the colors it used for dark and light modes:

Claude’s reply with a color table: dark mode uses #121212 and other colors from the DESIGN.md, light mode is derived as #eeeeee and other light grays, and the line spotify-look This mod is now loaded appears below

Check the colors Claude derived

A DESIGN.md describes a website’s palette, while the desktop app needs more colors than that, so Claude derives or borrows some of them. In Claude’s color table (the screenshot above), check three things:

  • The derived mode: the Spotify DESIGN.md has only a dark mode, so Claude derived a light mode from three light grays, #eeeeee, #f6f6f6, and #fdfdfd. The Cursor DESIGN.md has only a light mode, and Claude derived a dark mode from the file’s note that the featured pricing tier switches to a dark background. If you want to keep the original single mode, ask Claude to build only that one. The Linear DESIGN.md says outright that Linear has no light mode, so I built only a dark theme.
  • The borrowed colors: a desktop theme has five role colors, accent, danger, success, warning, and pro, and code syntax highlighting draws from them too. For example, keywords use accent and strings use success. When the DESIGN.md has no matching color, Claude borrows another one. Spotify’s pro color, for instance, borrows Announcement Blue. Claude also pointed out that Spotify’s accent and success are both green, which makes keywords and strings in code look alike.
  • The contrast check: a theme mod builds its full palette from a few colors with a function called makeColors, which also lists any spots with too little contrast. A line that starts with Desktop won't paint this theme makes the desktop app skip the whole palette. Other lines are only warnings, and the theme still applies. When Claude finishes the mod, its reply says whether any line would block the theme. The last bullet in the screenshot above is that note.

After reviewing the table, open Settings > General in the desktop app and switch Theme under Appearance to light and then to dark, looking at the app in each mode. The screenshot shows the Traditional Chinese labels for these settings:

The General page in Settings, with System, Light, and Dark buttons for Theme under Appearance

With the Cursor light theme, the background turns warm off-white and the toggles turn orange:

The Code tab with the Cursor light theme: an off-white background and an orange Remote Control toggle

The dark mode Claude derived for Cursor uses a warm brown background and keeps Cursor’s orange toggles:

The Code tab with the derived Cursor dark theme: a warm brown background and an orange Remote Control toggle

Change the theme colors

To swap a color, the official docs suggest simply telling Claude what to change. If you ask Claude to set the surface colors in the order the DESIGN.md lists them, though, the theme may fail to apply. The desktop app has four surface layers: the page is surface-0, and cards, panels, and menus are surface-1 through surface-3. The page has to be the darkest, and each layer above it has to be as light or lighter. Websites often put gray cards on a white page, which reverses that order. Linear’s DESIGN.md has no light mode, but it does list a set of inverse colors in exactly that order. When I had Claude fill light mode with those colors in their original order, makeColors threw the error In light mode surface-0 (gray-20, #ffffff) is lighter than surface-1:

Left: Linear’s inverse colors, where the page #ffffff is lighter than the card #f5f6f6 and makeColors throws an error. Right: Cursor’s light colors, page #f7f7f4, card #fafaf7, and panel #ffffff, each lighter than the one below, so the theme applies

If you hit this error, ask Claude to make the page the darkest of the four surfaces and have cards, panels, and menus get lighter in turn. In dark mode, keep the four surfaces close to each other. When they spread too far apart, makeColors reports more contrast warnings, and you can ask Claude to pull the four surfaces closer together.

Apply the theme to every session

Claude saves the mod under ~/.claude/dev-mods/<session ID>/<mod name>/, and only the session that built it loads it. To apply the theme to every session you open from now on, copy the mod into your personal skills directory. According to the official docs, Claude Code loads every plugin in that directory that contains a .claude-plugin/plugin.json whenever a session starts:

  1. Copy the whole mod folder from ~/.claude/dev-mods/<session ID>/ to ~/.claude/skills/<mod name>/. It needs .claude-plugin/plugin.json and the hooks folder.

  2. Run claude plugin list in a terminal. The mod appears under Skills-directory plugins with the status ✔ loaded:

    1Skills-directory plugins (.claude/skills/*):
    2
    3  ❯ spotify-look@skills-dir
    4    Version: 0.1.0
    5    Scope: user
    6    Path: ~\.claude\skills\spotify-look
    7    Status: ✔ loaded
    
  3. Start a new local session in the Code tab and send any message. The message doesn’t need to ask Claude for anything, and the theme applies once it’s sent.

After the Spotify theme applied in a new session, the Remote Control toggle in the right panel turned Spotify green:

A new session after sending a test message, with a green Remote Control toggle in the right panel

According to the official docs, when two mods in the same session set a theme, the later one replaces the earlier one, so keep only one theme mod in the skills directory.

Remove a theme

Move the mod folder out of ~/.claude/skills/, or out of its session folder under ~/.claude/dev-mods/, then start a new local session. The app returns to its default colors. While a theme mod in another session is still running, a new session may pick up that theme’s colors. In my test, after I removed the Spotify theme from the skills directory, a new session showed the Cursor dark theme from another session. Only after I removed the theme mods from every session did new sessions return to the default dark gray background and blue toggles.

Test notes

The Claude Code version bundled with the Code tab was 2.1.325. I built the Linear and Cursor themes step by step with Claude in one session, while the Spotify theme came from a new session where I pasted only the prompt above:

DESIGN.md Format Original mode Approach makeColors warnings Warnings that block the theme
Linear YAML front matter Dark Dark mode only 10 0
Cursor YAML front matter Light Derived dark mode, surfaces tightened 32 0
Spotify Free-form Markdown Dark One prompt, Claude derived light mode 27 0

All three theme mods passed claude plugin validate. In the first version of the Cursor dark mode, the four surfaces went from #1d1c17 all the way up to #38372f, and makeColors listed 55 contrast warnings. After I pulled the four surfaces into the #1d1c17 to #2a2922 range, 32 warnings remained, and only eight of them were in dark mode. The Spotify DESIGN.md has no YAML front matter, and its colors are scattered through free-form prose, and Claude still found them.

Summary

Give Claude your DESIGN.md, and Claude reads the colors, derives the missing mode, and writes the theme mod. What’s left for you is checking the colors Claude derived and borrowed. In my tests, all three DESIGN.md files, Linear, Cursor, and Spotify, applied to the Code tab, whether the colors lived in YAML or in prose.

Further reading

Ted Liou

Ted Liou

Software engineer writing about Unity and AI development.

Comments