# Overlay

Your browser's best friend.

The goal for this tool is be something that enhances your web browser while you work directly with the HTML and CSS of a design. Everything shown inside the Overlay's black frame ignores mouse clicks and other interactions: they continue to be handled by the underlying browser. There are three items in the Overlay's frame that augment your browser: alignment marks, a mockup image, and grids with breakpoints.

## Overlay Setup

The first time you open the tool, you'll be presented with a setup window. The Overlay needs scripts and access permissions that help it integrate with your browser window. The setup window guides you through the process to get things running smoothly.

To begin using the Overlay tool, you need to first attach it to a browser window. You start the attachment process by clicking on the lock icon in the upper-left corner of the window. From that point, you'll be guided through the rest of the process.

Once attached, any changes to your browser width or position on screen will be tracked by xScope. The Overlay frame will follow your browser around on screen. Click the lock icon again and the Overlay will detach. Note that the Overlay tool will track your browser window even when the tool is hidden using the toolbar, menus or hot keys.

## Not Just for Browsers

The Overlay window can be used with any window on the desktop. This includes the iOS Simulator, which can be helpful if you're working on a mobile site and want to get a more accurate rendering of your page in Safari.

The image overlay can also be used with the simulator: handy if you're developing native applications and trying to get your views to match a Photoshop mockup. Since the simulator window is not resizable, the automatic resizing feature is disabled.

You can now start to explore the display modes. Each of the display modes it controlled by the icons to the right of the attachment icon in the Overlay's header. Each of these items is described below.

## Alignment Marks

The alignment marks allow you to measure the distance between elements in your design. The draggers along the left edge of the Overlay frame let you do height measurements and check vertical alignment. By default, the measurements are done in pixels, but the Options panel also let you use ems and points (where 16 px = 1.0 em = 12.0 pt.)

The draggers along the bottom edge of the frame let you do similar measurements. Percentages are also displayed, making measurements for responsive designs simpler. The measurements on the left and right are relative to the edge of the frame, while the one in the middle is the distance between the two vertical lines.

## Mockup Image

All great websites begin as a design in an image editor like Photoshop. The mockup image makes it easy to compare a your current HTML and CSS code with an image that contains the desired result.

To begin, drag an image from your desktop into the Options panel. The mockup will be displayed and centered in your browser window at 100%. The zoom controls allow you to change the size of the image to match your browser: for example, if your design was done at Retina scale and you're viewing it on a normal display.

While the image is displayed, another dragger is shown on the right edge of the Overlay frame. This control lets you fine tune the placement of the image with respect to your web content. A Rubylith control in the Options panel lets you colorize the image to help distinguish it from rendering in your browser.

Any changes to the file that's used in the Overlay, such as when you save a new version, will be reflected automatically in the Overlay. This behavior makes the tool useful for getting an early glimpse of how your design will look as the content scrolls.

## Grids with Breakpoints

Many developers are using grid systems in their responsive web designs. This final display mode lets you create grids that can be used to check content layout and alignment.

By default, five grids that spans 90% of the page width is displayed, with breakpoints at 480, 800, 1024 and 1200 pixels. The breakpoints at 800 px and 1024 px use two columns, while the widest one uses three columns. You can edit any grid by clicking on the > icon to the right of the name. New grids can be created by clicking on the + icon. The – icon deletes the currently selected grid.

The grid settings can be loaded from or saved to a file using the icons to the right. This is convenient when you're working on several different sites with different responsive characteristics.

Each grid can be given a breakpoint. When the browser window is greater than the breakpoint size, that grid will be selected and displayed automatically. This, combined with media queries in your CSS, allow the overlay grids and content to adapt to different browser widths simultaneously.

In the Grid options, there is a checkbox to Resize to selection. When this is enabled, your browser window will be resized automatically to the size specified in the selected breakpoint. For example, if you have a breakpoint set for 800 px, the browser window will be resized to 801 px (which satisfies a `@media screen and (max-width: 800px)` query.) This feature makes it very quick to check changes at a given breakpoint.

Grids do not have to be visible to get the automatic resizing feature. If you just want to check your design at different sizes and don't need the content edges or columns to be displayed, turn off the grid visibility, and select the breakpoint to resize the window.

Finally, if you have alignment marks turned on at the same time as grids, additional measurements are displayed. Similar to the ones described earlier, these new measurements are relative to the edge of the content, not the window.

## Cycle Breakpoints

The icon next to Grids in the Overlay header lets you cycle through the breakpoints. Combined with the Resize to selection setting, this button makes it very simple to cycle through the media queries in your CSS to make sure everything looks right at the various widths.

Clicking the icon advances to the next breakpoint (and wraps around when you reach the end.) If you hold the shift key down while clicking, the previous breakpoint is selected.

## Screenshot

The last icon in Overlay header is the camera: it allows you to take a screen shot of the entire web page. This full-page image is generated using the current URL: if your page is 10,000 pixels tall, you'll get an image with that many pixels.

Full-page screen shots can only be created with Safari, Chrome and Firefox (both official releases and nightly builds.) Internally, the screen shot is created using the WebKit framework provided by Safari, so don't rely on it to show subtle rendering errors.

## Overlay Options

The opacity of the various display modes can be adjusted using the opacity slider. Sometimes you need to see your content more clearly, and sometimes you need the Overlay to be more prominent.

Color wells in the Options panel let you tweak the settings so they contrast well with your design. There are separate colors for the measurements (such as the alignment marks and edges) and content (like the grid columns and mockup tinting.)

The Options panel was designed to get out of the way and minimize the extra chrome that's added to your browser. In many cases, you can set things up for your project and collapse the panel. The icons in the header will let you toggle things as needed. You can also hide the Overlay to remove the frame completely: it will be in the right place when it is next shown, even if you move or resize your browser window.