Folie

Live demo →

Lightweight column grid overlay for the browser. Same columns, gutter, and margin as your Figma layout grid. Toggle it while you build.

How it works

Figma's Layout Grid panel defines a grid with columns, gutter, and margin — folie uses those exact values. It mounts a fixed, semi-transparent CSS Grid overlay on top of your page, updated on resize for each breakpoint. Toggle it with Ctrl+G or an optional button.

Install

npm install folie-grid
# or
yarn add folie-grid

Usage

Minimal — built-in defaults

import Folie from "folie-grid";

new Folie().mount();

Top-level shorthand

Pass columns, gutter, and margin directly — applies at all viewport widths.

// mirror the Figma layout grid
new Folie({
  columns: 12,
  gutter: "10px",
  margin: "20px",
}).mount();

Per-breakpoint config

Use numeric min-width keys. Top-level columns/gutter/margin becomes the base (0px+) config and can be combined with breakpoints. All fields are optional — unspecified fields inherit from the base.

new Folie({
  columns: 6, gutter: "10px", margin: "20px", // base: 0px+
  breakpoints: {
    768:  {columns: 8}, // gutter/margin inherited
    1024: {columns: 12, gutter: "20px", margin: "20px"},
  },
}).mount();

If breakpoints is provided without shorthand, DEFAULTS (columns: 12, gutter: 20px, margin: 20px) are used as the base config.

Row overlay

Add a horizontal row overlay alongside the column grid:

new Folie({
  columns: 12, gutter: "20px", margin: "20px",
  rows: 8, rowsGutter: "20px", rowsMargin: "20px",
  rowsColor: "#0000ff", rowsOpacity: 0.05,
}).mount();

Row count can also be overridden per breakpoint:

new Folie({
  columns: 6, gutter: "20px", margin: "20px",
  rows: 6, rowsGutter: "20px", rowsMargin: "20px",
  breakpoints: {
    1024: {columns: 12, rows: 10},
  },
}).mount();

Options

| Option | Type | Default | Description | | -------------- | --------- | ------------ | --------------------------------------------------------------------------------- | | columns | number | 12 | Column count at 0px+ (base). Acts as the catch-all when no breakpoints are set. | | gutter | Spacer | 20px | Gutter at 0px+ (base). | | margin | Spacer | 20px | Margin at 0px+ (base). | | breakpoints | object | — | Per-breakpoint config keyed by numeric min-width (px). Can be combined with shorthand. | | showOnStart | boolean | true | Whether the grid is visible immediately on mount() | | toggleButton | boolean | false | When true, mounts a 40×40 button fixed to the bottom-left that toggles the grid | | rows | number | — | Number of rows. If omitted, no row overlay is rendered. | | rowsGutter | Spacer | — | Vertical gap between rows. | | rowsMargin | Spacer | — | Top/bottom padding of the row overlay. | | rowsColor | Color | #ff0000 | Row background color (global, not per-breakpoint) | | rowsOpacity | number | 0.1 | Row opacity (global, not per-breakpoint) | | color | Color | #ff0000 | Column background color | | opacity | number | 0.1 | Column opacity | | zIndex | number | 2147483647 | z-index of the overlay | | shortcut | string | ctrl+g | Keyboard shortcut to toggle visibility | | mode | 'fill' \| 'outline' | 'fill' | 'outline' renders columns as inset box-shadow borders instead of filled rectangles. When mode is 'outline' and opacity is not set, opacity defaults to 0.5 |

Spacer

Any CSS length value, a CSS custom property, or a var() reference:

20px · 1.5rem · 2vw · clamp(10px, 2vw, 24px) · var(--my-gutter) · --my-token

Color

Any CSS color value accepted by background / box-shadow:

#ff0000 · rgb(255,0,0) · rgba(255,0,0,0.5) · hsl(0,100%,50%) · transparent · currentColor · var(--brand)

Breakpoint config

Keys are numeric min-widths in px. Ranges are inferred from adjacent keys. columns, gutter, and margin match the Layout Grid fields in Figma's design panel.

| Key | Type | Required | Description | | ------------- | -------- | -------- | ----------------------------------------------------------------------- | | columns | number | no | Number of columns — inherits from base if omitted | | gutter | Spacer | no | Gap between columns — inherits from base if omitted | | margin | Spacer | no | Left/right padding — inherits from base if omitted | | rows | number | no | Number of rows — inherits from base if omitted | | rowsGutter | Spacer | no | Vertical gap between rows — inherits from base if omitted | | rowsMargin | Spacer | no | Top/bottom padding of the row overlay — inherits from base if omitted |

Default base config

When no shorthand is provided, the following is used as the base (0px+):

| columns | gutter | margin | | ------- | ------ | ------ | | 12 | 20px | 20px |

CSS custom properties

The overlay is driven by CSS custom properties set on .fl-wrapper. You can override them in your own CSS if needed.

| Property | Description | | ------------------- | ------------------------ | | --fl-columns | Number of columns | | --fl-gutter | Gap between columns | | --fl-margin | Left/right padding | | --fl-color | Column color | | --fl-opacity | Column opacity | | --fl-rows | Number of rows | | --fl-rows-gutter | Vertical gap between rows | | --fl-rows-margin | Top/bottom padding | | --fl-rows-color | Row color | | --fl-rows-opacity | Row opacity |

API

| Method | Description | | ------------------- | ------------------------------------------------------ | | mount(container?) | Attach overlay to container (default: document.body) | | destroy() | Remove overlay, toggle button, and all listeners |

Keyboard shortcut

Default: Ctrl+G. Toggle visibility. Customise via the shortcut option:

new Folie({shortcut: "ctrl+shift+g"});

TypeScript

The package ships type declarations — no @types/ package needed.

The import works exactly like JavaScript:

import Folie from "folie-grid";

const grid = new Folie({
  columns: 12,
  gutter: "20px",
  margin: "clamp(16px, 5vw, 80px)",
}).mount();

If you want to define the config object separately, you can import the FolieOptions type:

import Folie, { type FolieOptions } from "folie-grid";

const config: FolieOptions = {
  columns: 12,
  gutter: "20px",
  margin: "20px",
  breakpoints: {
    768:  { columns: 8 },
    1280: { columns: 12, gutter: "30px" },
  },
};

new Folie(config).mount();

HMR teardown (Vite / Nuxt / SvelteKit)

Call destroy() on hot reload to prevent the overlay from duplicating:

const grid = new Folie({ columns: 12 }).mount();

if (import.meta.hot) {
  import.meta.hot.dispose(() => grid.destroy());
}

License

MIT