theme-guide

name

theme-guide

description

How the Fluent OLED Zed theme is built, its architecture, design principles, and how to modify it. Use this skill whenever the user wants to change any theme color, syntax highlighting capture, terminal color, UI surface color, or extension theme metadata for Fluent OLED in Zed. Also use when they mention Zed `style` keys, `syntax` captures, `themes/fluent-oled.json`, visual regressions, or palette consistency.

Fluent OLED Theme Guide (Zed)

The theme is defined in themes/fluent-oled.json using the Zed theme schema.

Architecture

themes/fluent-oled.json
├── Theme family metadata
│   ├── "$schema"
│   ├── "name"
│   └── "author"
└── "themes"[]
    └── Theme object
        ├── "name"
        ├── "appearance" ("dark")
        └── "style"
            ├── UI/workbench keys
            ├── terminal and git state keys
            ├── diagnostics/status keys
            └── "syntax" captures

Design Principles

Every change should preserve these rules:

1. Pure black foundations — Primary surfaces stay #000000 to preserve OLED behavior.
2. Monochrome chrome — UI structure remains grayscale; color emphasis belongs in syntax and semantic states.
3. Functional signals stay semantic — Added/modified/deleted, warnings/errors, and terminal colors remain distinct and meaningful.
4. GitHub-inspired syntax palette — Reuse the established Fluent OLED syntax colors.
5. Minimal visual noise — Keep borders and highlights subtle unless stronger contrast is required for usability.

Color Palette Reference

Core UI Colors

Hex	Role
#000000	Primary backgrounds
#0a0a0a	Elevated surfaces
#111111	Borders/dividers
#161616	Active/hover surfaces
#6e7681	Muted text
#8b949e	Secondary text
#c9d1d9	Primary foreground
#e6edf3	Emphasis text

Syntax Colors

Hex	Primary usage
#ff7b72	Keywords/operators
#ffa657	Types/enums/namespaces
#d2a8ff	Functions/constructors/variants
#79c0ff	Constants/properties/attributes/numbers
#a5d6ff	Strings/links
#7ee787	Tags/selectors/regex
#f85149	Error/special variables
#8b949e	Comments/hints
#c9d1d9	Variables/plain punctuation

Section 1: style (UI + system colors)

The style object controls Zed UI surfaces, editor chrome, terminal palette, git/diagnostic states, and syntax captures.

Common key groups

• Surfaces: background, surface.background, elevated_surface.background
• Text/icon: text.*, icon.*
• Editor: editor.* keys (line numbers, guides, highlights, gutter)
• Tabs and bars: tab.*, tab_bar.background, title_bar.*, status_bar.background, toolbar.background
• Panels/panes: panel.*, pane.focused_border
• Terminal: terminal.*, terminal.ansi.*
• VCS + diagnostics: version_control.*, created/*, modified/*, deleted/*, error/*, warning/*, info/*

Adding or changing a UI key

1. Check the Zed theme schema: https://zed.dev/schema/themes/v0.2.0.json.
2. Pick from existing Fluent OLED palette values first.
3. Keep OLED black defaults unless a specific contrast issue requires a change.
4. Prefer subtle alpha overlays for highlights (#RRGGBBAA) instead of adding new opaque grays.

Section 2: syntax (capture-based highlighting)

Zed syntax highlighting is capture-based (style.syntax) rather than TextMate scope arrays.

Example shape:

"syntax": {
  "keyword": { "color": "#ff7b72ff" },
  "function": { "color": "#d2a8ffff" },
  "comment": { "color": "#8b949eff", "font_style": "italic" }
}

Supported style attributes per capture:

• color
• background_color
• font_style (normal, italic, oblique)
• font_weight (100-900)

Typical captures used in Fluent OLED

• Core: keyword, string, number, constant, variable, type, function, operator
• Structural: punctuation.*, tag, property, namespace, constructor
• Markdown/diff emphasis: title, text.literal, emphasis, emphasis.strong, diff.plus, diff.minus

Editing guidance

1. Reuse existing capture names already present in themes/fluent-oled.json.
2. Add narrowly scoped captures only when a visual bug or readability issue is clear.
3. Keep comment styling and muted punctuation subtle to preserve the low-noise aesthetic.

Terminal and Functional Colors

Do not flatten these into grayscale; they carry semantic meaning:

• Success/added: green family (#3fb950, #238636)
• Warning/modified: amber family (#d29922, #9e6a03)
• Error/deleted: red family (#f85149, #da3633)
• Informational/accent: blue family (#79c0ff, #2f81f7)

Testing Changes

1. Run bun run check.
2. Install the repo as a dev extension in Zed (zed: install dev extension).
3. Select Fluent OLED in the theme selector.
4. Verify editor, panels, terminal, git indicators, and syntax across common languages.
5. Validate that the theme still looks pure black on primary surfaces.