How Panel Gap and Top Margin Variables Control Spacing in Islands Dark

The --islands-panel-gap and --islands-panel-top CSS custom properties injected via custom-ui-style.stylesheet in settings.json govern all horizontal and vertical spacing between the sidebar, editor, and bottom panels.

In the bwya77/vscode-dark-islands repository, these two variables serve as the single source of truth for the Islands Dark theme’s distinctive "island" layout system. By adjusting these values, you control the breathing room around every major workbench component without touching individual selectors.

Understanding the Core Variables

The theme defines two complementary spacing tokens that work in tandem:

• --islands-panel-gap (default: 6px) – Controls horizontal spacing between panels and the vertical borders of the bottom panel. It also determines the clipping margins for notebooks and the offset of toast notifications.
• --islands-panel-top (default: 6px) – Sets the vertical margin between the top of the workbench window and the main panels (sidebar, editor, auxiliary bar). This value also influences the bottom panel’s top border thickness.

Both variables are declared inside the .monaco-workbench selector block within settings.json, making them globally available to all downstream CSS rules injected by the custom-ui-style extension.

Where the Variables Are Defined

The injection happens in settings.json at lines 16–17, where the stylesheet object maps these custom properties to the root workbench element:

{
  "custom-ui-style.stylesheet": {
    ".monaco-workbench": {
      "--islands-panel-gap": "6px",
      "--islands-panel-top": "6px"
    }
  }
}

From this central definition, the theme references these variables across multiple component rules to ensure consistent spacing throughout the interface.

How Spacing Is Applied Throughout the UI

Panel Margins

The primary layout grid uses a single margin declaration that consumes both variables. At lines 24–26 in settings.json, the sidebar, editor, and auxiliary bar receive their positioning:

margin: var(--islands-panel-top) var(--islands-panel-gap) 0 var(--islands-panel-gap);

This applies the top margin above the panels while creating symmetrical horizontal gutters between the window edges and the content areas.

Bottom Panel Borders

The bottom panel (terminal, output, debug console) uses the gap variable to create the illusion of floating islands. Lines 39–42 establish a top border that matches the gap thickness:

border-top: var(--islands-panel-gap) solid var(--islands-bg-canvas);

Left and right borders on the same element also reference --islands-panel-gap, ensuring the panel appears evenly inset from the window edges.

Rounded Corner Calculations

To maintain visual harmony, the theme reduces the border radius of bottom-panel content by the gap amount. Lines 49–53 implement this using calc():

border-radius: calc(var(--islands-panel-radius) - var(--islands-panel-gap));

This subtraction prevents the inner content from peeking beyond the outer container’s rounded corners when the panel gap is increased.

Notebook Clipping

Notebooks receive a custom clip-path that respects the horizontal gap. Lines 135–138 in settings.json define:

clip-path: inset(0 18px var(--islands-panel-gap) var(--islands-panel-gap) round ...);

The left and right inset values use --islands-panel-gap to ensure notebook cells align visually with the surrounding editor panels.

Toast Notifications

Even transient UI elements honor the spacing system. Lines 15–18 apply the gap variables to notification toasts:

margin-right: var(--islands-panel-gap);
margin-bottom: var(--islands-panel-gap);

This keeps alerts consistently inset from the window corners, matching the padding of permanent panels.

Customizing the Values

Because the variables cascade through every dependent rule, changing them in one place updates the entire layout.

Widen All Spacing to 8px

As documented in README.md at lines 219–221, increasing both values creates a more spacious aesthetic:

{
  "custom-ui-style.stylesheet": {
    ".monaco-workbench": {
      "--islands-panel-gap": "8px",
      "--islands-panel-top": "8px"
    }
  }
}

After reloading the window, horizontal gaps expand to 8px, the bottom panel’s top border thickens correspondingly, and all panels sit 8px lower from the title bar.

Adjust Only the Top Margin

To compress the vertical spacing while keeping the default horizontal breathing room:

{
  "custom-ui-style.stylesheet": {
    ".monaco-workbench": {
      "--islands-panel-top": "4px"
    }
  }
}

This tightens the layout vertically without affecting sidebar or terminal borders.

Using Variables in Custom Rules

When writing your own stylesheet overrides, reference the existing variables to remain compatible with future updates:

/* Add a left border to the terminal that matches the theme gap */
.part.panel.bottom .terminal-outer-container {
  border-left: var(--islands-panel-gap) solid var(--islands-bg-canvas) !important;
}

This ensures your customizations scale automatically if you later adjust the gap value.

Summary

• --islands-panel-gap controls horizontal spacing, bottom panel borders, and notification margins.
• --islands-panel-top sets the vertical offset of panels from the workbench top.
• Both variables are defined in settings.json and consumed by margins, borders, clip-paths, and radius calculations.
• Changing these values in the .monaco-workbench selector propagates changes across the entire island layout system instantly.
• The default value of 6px can be overridden to create tighter or more spacious layouts without editing individual component selectors.

Frequently Asked Questions

What happens if I set --islands-panel-gap to 0px?

Setting the gap to 0px collapses all horizontal spacing between panels and removes the top border from the bottom panel, causing the sidebar, editor, and terminal to sit flush against each other and the window edges. While functional, this eliminates the visual separation that defines the Islands Dark aesthetic.

Do these variables affect the terminal font size or sidebar width?

No. These variables control only spacing and positioning, not content dimensions. They affect margins, borders, and clipping regions, but they do not change the actual width of the sidebar, the height of the bottom panel, or the font size within the terminal. Those metrics remain controlled by VS Code’s native settings.

Why does the bottom panel border use --islands-panel-gap instead of a fixed value?

Using the variable ensures the border thickness always matches the visual spacing between panels. According to the theme’s implementation in settings.json lines 39–42, this creates the "floating island" effect where the bottom panel appears separated from the editor by a gap of consistent thickness on all sides. A fixed pixel value would break this alignment if you customized the gap later.

Can I use different values for horizontal and vertical spacing?

Yes. While the theme ships with both defaults set to 6px, you can decouple them by setting --islands-panel-gap to one value and --islands-panel-top to another. For example, using 8px for the gap and 4px for the top margin creates wide horizontal separation while keeping panels closer to the title bar.

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