How to Troubleshoot CSS Customizations Not Applying in Islands Dark

CSS customizations in Islands Dark require the Custom UI Style extension to be enabled and properly configured in settings.json; most failures stem from disabled extensions, malformed JSON syntax, or conflicting CSS loaders.

Islands Dark is a Visual Studio Code theme that combines a dedicated color palette with custom CSS injections to achieve its distinctive rounded aesthetic. When your CSS customizations fail to apply, the issue typically lies in the integration between the theme extension and the Custom UI Style extension rather than the theme files themselves.

Understand the CSS Injection Architecture

Islands Dark operates through two cooperating systems:

• The theme extension – provides the color palette via themes/islands-dark.json
• The Custom UI Style extension – reads the custom-ui-style.stylesheet object from your settings.json and injects those CSS rules into VS Code's DOM

The extension rewrites the UI by applying your CSS variables (such as --islands-panel-radius) and selectors directly to VS Code's interface. If the UI does not reflect your changes, the injection chain has failed at some point.

Common Causes of CSS Failures

Extension Disabled or Not Installed

The most frequent cause is the Custom UI Style extension being disabled. Open the Command Palette and run Custom UI Style: Enable. If the UI remains unchanged, run Custom UI Style: Disable, reload VS Code, then re-enable it.

If the extension is missing entirely, open the Extensions view (Ctrl+Shift+X), search for Custom UI Style by subframe7536, and install it.

Malformed settings.json Configuration

The stylesheet lives under the key custom-ui-style.stylesheet in settings.json. If this key is missing or malformed, the extension silently ignores it. Open Preferences: Open Settings (JSON) and verify the structure matches the repository's example.

JSON syntax errors—such as stray commas or missing braces—prevent the file from parsing. VS Code displays red squiggles in the Settings editor when this occurs.

Conflicting CSS Extensions

If you previously used Custom CSS and JS Loader (be5invis.vscode-custom-css), its injected CSS may linger in workbench.html. The README warns that a complete reinstall of VS Code is required to clear these remnants when switching to Custom UI Style.

Cache and Stale Stylesheets

The extension caches the compiled stylesheet. Cycling the extension (disable, reload, enable, reload) forces a complete rebuild of the CSS injection.

Selector Specificity and !important

The Custom UI Style extension adds CSS as an inline stylesheet, but many VS Code UI rules use !important. If your selector lacks sufficient specificity or omits !important, native VS Code rules will override it. Always append !important to property values in your custom rules.

VS Code Security Restrictions

Recent VS Code versions may block UI-injecting extensions when the "Enable Custom UI Style" flag is unchecked. Verify this flag is enabled in the Command Palette.

Step-by-Step Diagnostic Workflow

Follow this precise sequence to isolate the issue:

1. Open the Command Palette → Custom UI Style: Disable → Reload VS Code
2. Open the Command Palette → Custom UI Style: Enable → Reload again
3. Verify that settings.json contains a valid custom-ui-style.stylesheet object with proper JSON syntax
4. Test with a minimal, highly visible change, such as setting "--islands-panel-radius": "32px" to confirm the pipeline works
5. If the change appears, your previous issue was likely a syntax error or overly specific selector
6. If nothing changes, check for conflicting extensions (specifically Custom CSS and JS Loader) and reinstall VS Code if necessary

Working Code Examples

Changing Panel Corner Radius

Modify the radius CSS variable in your settings.json:

{
  "custom-ui-style.stylesheet": {
    ".monaco-workbench": {
      "--islands-panel-radius": "32px",
      "background-color": "var(--islands-bg-canvas) !important"
    }
  }
}

After saving, run Custom UI Style: Reload (or restart VS Code) to apply the new curvature.

Styling the Activity Bar

{
  "custom-ui-style.stylesheet": {
    ".part.activitybar": {
      "background": "linear-gradient(to bottom, #111, #222) !important"
    }
  }
}

Debugging with a Visible Test Rule

{
  "custom-ui-style.stylesheet": {
    ".part.sidebar": {
      "border": "5px solid red !important"
    }
  }
}

If the red border appears, the stylesheet is loading correctly. Remove the rule and refine your intended selector.

Key Files Reference

Understanding these files helps diagnose where the chain breaks:

• README.md – Contains the installation steps and Troubleshooting section outlining the enable/disable reload cycle
• settings.json – Holds the custom-ui-style.stylesheet object where all CSS variables and selector rules are defined
• themes/islands-dark.json – The color-theme definition that VS Code loads; required for the overall look but unrelated to CSS customizations
• animations.css – Optional animation definitions referenced by the stylesheet if you add custom animation names
• install.sh and install.ps1 – Scripts that automatically install the theme and Custom UI Style extension, ensuring correct initial configuration

Summary

• Enable the extension: Use the Command Palette to toggle Custom UI Style off and on, reloading VS Code between each step
• Validate JSON: Ensure settings.json contains a properly formatted custom-ui-style.stylesheet object with no syntax errors
• Check for conflicts: Remove any remnants of Custom CSS and JS Loader or reinstall VS Code if previously used
• Use !important: Append !important to all CSS property values to override VS Code's native specificity
• Force reload: Changes require either Custom UI Style: Reload or a full VS Code restart to appear

Frequently Asked Questions

Why don't my CSS changes appear immediately after saving settings.json?

The Custom UI Style extension caches the compiled stylesheet and only rebuilds it during specific reload events. You must either run Custom UI Style: Reload from the Command Palette or completely restart VS Code. Simply saving the file does not trigger a DOM update.

Can I use Islands Dark with other CSS-injecting extensions?

No, Islands Dark specifically requires the Custom UI Style extension by subframe7536. Other extensions like Custom CSS and JS Loader (be5invis.vscode-custom-css) inject CSS differently and leave conflicting remnants in workbench.html. If you previously used other loaders, perform a clean reinstall of VS Code before switching to Islands Dark.

What should I do if the Custom UI Style extension commands are missing from the Command Palette?

This indicates the extension is either not installed or has been disabled by VS Code's security settings. First, verify the extension is installed from the marketplace. Then check that the "Enable Custom UI Style" flag is enabled in your VS Code settings, as newer versions may block UI-modifying extensions by default.

Where exactly should I place my custom CSS rules?

All CSS customizations belong inside the custom-ui-style.stylesheet object in your user settings.json file, not in the theme's repository files. Open Preferences: Open Settings (JSON) and ensure your rules are nested under this specific key, with selectors as keys and CSS property objects as values.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}