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

> Learn how panel gap and top margin variables control spacing in Islands Dark. Customize sidebar, editor, and bottom panel layouts with CSS custom properties.

- Repository: [Bradley Wyatt/vscode-dark-islands](https://github.com/bwya77/vscode-dark-islands)
- Tags: deep-dive
- Published: 2026-05-06

---

**The `--islands-panel-gap` and `--islands-panel-top` CSS custom properties injected via `custom-ui-style.stylesheet` in [`settings.json`](https://github.com/bwya77/vscode-dark-islands/blob/main/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`](https://github.com/bwya77/vscode-dark-islands/blob/main/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`](https://github.com/bwya77/vscode-dark-islands/blob/main/settings.json) at lines 16–17, where the stylesheet object maps these custom properties to the root workbench element:

```json
{
  "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`](https://github.com/bwya77/vscode-dark-islands/blob/main/settings.json), the sidebar, editor, and auxiliary bar receive their positioning:

```css
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:

```css
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()`:

```css
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`](https://github.com/bwya77/vscode-dark-islands/blob/main/settings.json) define:

```css
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:

```css
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`](https://github.com/bwya77/vscode-dark-islands/blob/main/README.md) at lines 219–221, increasing both values creates a more spacious aesthetic:

```json
{
  "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:

```json
{
  "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:

```css
/* 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`](https://github.com/bwya77/vscode-dark-islands/blob/main/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`](https://github.com/bwya77/vscode-dark-islands/blob/main/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.