Documentation

Grid Notation

There are some grids that are just too complex for the form. That’s where grid notation comes in. Grid notation is a language that enables you to “write” grids.

| 20px | ~ | ~ | ~ | 20px | ( vlp, ~|100px|~ )

The grid above is a three column grid, with 20 pixel margins, that is 100 pixels wide, centered within the context. GuideGuide reads this notation from left to right, placing guides and adding spaces as directed.

First, it begins with a guide command |, which tells GuideGuide “Add a guide here”. Next is an explicit command that tells GuideGuide to move over 20px, then another guide command. Next come three wildcard commands ~ with guides between them. Wildcards divide space evenly between themselves. Next, another margin, and a final guide.

Lastly, there are options for the grid. The options here tell GuideGuide that the grid uses vertical guides v, that it should place any leftover pixels to into the last l (right) position, and that it should be pixel specific p. Next, it specifies that the guide should have equal spacing on the left and right side, and be 100px wide.

This is a complete grid notation string. You can combine more than one grid notation strings in the custom view to make unique or complicated guides. Fibonacci grid, anyone?

Grids

In grid notation, each line represents one orientation, allowing guides in a single direction. To include more than one grid, each grid needs its own line of grid notation. For example, if you need to create columns and rows in a single grid notation block, you will have to create two grids, each on their own line.

For example, a grid with three columns and two rows:

| ~ | ~ | ~ | (v)
| ~ | ~ | (h)

Spaces

Whitespace separates commands. While GuideGuide can tell the difference between some commands and will space them out for you, it gets confused if you combine more than one explicit commands. By convention, you should always place a space between commands. Whenever you unfocus the grid notation field, GuideGuide will automatically format your grid notation to follow this convention.

Commands

Commands are characters or groups of characters you use to write grid notation. GuideGuide processes each command in a grid notation string from left to right, doing whatever the command requires.

In the following format examples, elements wrapped in square brackets [] are optional. Elements wrapped in angle brackets <> describe what should appear in their place. Neither the square brackets nor the angle brackets are valid grid notation.

Guide commands

Format: |
In words: “Put a guide here”

The most important command to learn is the guide command. GuideGuide will place a guide when it comes across this character.

If you add more than one consecutive guide commands, GuideGuide will treat them as a single guide command to avoid duplicate guides.

||| 10px ||| is the same as | 10px |

While including the guide command is important, omitting it can be useful too. For example, if you wanted a guide placed at the 2/3 point of a document, you could do so by creating a three column grid with wildcard commands, placing a guide between the second and third column, like so: ~ ~ | ~

Explicit commands

Format: <number><unit>[*[<multiplier>]]
In words: “Move over this much”
Examples: 10px, 1in*, 2cm*3

Explicit commands are commands which specify an exact distance measure. GuideGuide will move over the specified distance when it comes across an explicit command.

Explicit commands support all unit types, and support multiples and fills.

For example:

  • Three ten pixel columns

    | 10px | 10px | 10px|
    
  • One half inch column, one inch column, one half inch column

    | .5in | 1in | .5in |
    

Note the guide commands on each side of the explicit commands. This tells GuideGuide to place a guide, move over, place a guide, move over, etc.

If you type an integer without a unit, a unit that GuideGuide doesn’t recognize, or gibberish, it will cause error 1.

Wildcard commands

Format: ~
In words: “Divide the leftover space between these evenly”

Wildcard commands are like explicit commands, in that they tell GuideGuide to move over a certain amount. Their size depends on how wide the grid is and the number of them that exist in the grid. This is the easiest way to create columns or rows based on the size of the context, to center something in the middle of your grid, or to push something to one side.

To determine the size of each wildcard, GuideGuide first subtracts the size of all explicit commands from the size of the grid, then divides the remaining space up between the wildcards. The result is that each wildcard command is the same size. If the grid options specify pixel calculation, GuideGuide distributes any pixels that remain after the division based on the remainder pixel distribution setting.

For example:

  • A guide on the left and right side of the context

    | ~ |
    
  • A three column grid

    | ~ | ~ | ~ |
    
  • A ten pixel column centered in the context

    | ~ | 10px | ~ |
    
  • A guide on the right side of the document

    ~ |
    

Note that you cannot use wildcards as fills. Doing so will cause error 3.

Variables

Variables enable you to define and reuse collections of commands within a grid. Variables need two parts: a definition and a call.

Define

Format: $[<ID>] = <commands>
In words: “This variable equals these commands”
Examples: $ = | 10px |, $A = | 1in | .25in |

When you define a variable, you tell GuideGuide to remember a group of commands for later use. You write a variable with by the dollar sign $ followed by an optional ID. Specifying an ID is useful when you need to use more than one variable.

Defining a variable does not add any guides, it just saves the commands for later use. To use the variable, you must call it.

Note that because you use variables more than once, you cannot use them as fills. Doing so will cause error 5.

Call

Format: $[<id>]
In words: “Replace this variable with the commands it represents”
Examples: | $ |, | 10px | $A | 10px |

Calling a variable tells GuideGuide to replace it with the commands that have been defined for that variable. You cannot call a variable if you do not define it. Doing so will cause error 6.

For example:

A three column Grid

$ = ~ |
| $*3

expands to:

| ~ | ~ | ~ |

Multiples and Fills

You can add a duplication modifier to explicit, wildcard, and variable commands that will repeat the associated command a specified number of times. You can do this by suffixing the command with the asterisk symbol *. Depending on the number of duplications specified, the result will either be a multiples or a fills.

Multiples

Format: <command>*<number>
In words: “Repeat this command this many times”
Examples: $*4, 10px*2, ~*3

Multiples are commands followed by an asterisk *, followed by a number. When GuideGuide parses the command, it will repeat the command the given number of times.

For example:

~*3

will expand to:

~ ~ ~

Because explicit and wildcard commands do not add guides, multiples are primarily useful in association with variables.

For example, to create three columns with margins:

$ = 10px | ~ | 10px |
| $*3

will expand to:

| 10px | ~ | 10px | 10px | ~ | 10px | 10px | ~ | 10px |

Note that because grid notation treats duplicate guide commands as single guides, will ignore any duplication created by multiples.

Fills

Format: <command>*
In words: “Repeat this command until there is no space left”
Examples: 10px*, $*

A fill is a command followed by an asterisk *. GuideGuide will repeat a fill command as until it fills the entire context. This is useful for creating baseline grids, or filling space columns and gutters.

To calculate this, GuideGuide subtracts the size of all explicit commands from the size of the grid, then divides the remaining space by the size of the fill. The number of iterations is the absolute value of the result.

Because a fill requires unspecified (not explicit) space, you cannot use fills with wildcards in a single grid. Doing so will cause error 3. Because fills will fill empty space, you cannot use more than one fill in a single grid. Doing so will cause error 4.

Options

Format: ([<modifiers>][, <adjustments>])
In words: “Do the grid this way in this place”
Examples: ( h, 100px ), ( vl, ~ | ~ ), ( hlp, 10px | 100px | ~ )

Grid notation options let you specify two types of global options for each grid: modifiers, which affect how GuideGuide renders the grid, and adjustments, which affect where GuideGuide renders it. Place options between parentheses, with a comma between the modfiers and the adjustments.

Modifiers

Single characters represent modifier options, which sit to the left of the comma (or by themselves if you do not provide adjustments).

Orientation

Use one of these values per grid:

  • h (default) horizontal
  • v vertical

Determines whether the guides are horizontal or vertical.

Calculation

Use one of these values per grid:

  • n (default) normal
  • p pixel snap

Determines whether GuideGuide rounds guide coordinates to whole numbers. If set to p, remainder pixel distribution will apply.

Remainder pixel distribution

Use one of these values per grid:

  • f first; left/top
  • c center
  • l (default) last; right/bottom

Determines to which wildcard commands GuideGuide will add remainder pixels. This is applicable when you set the calculation option to p.

Adjustments

Format: [<first offset>][ | <size> ][ | <last offset>]
In words: This far from the left, this wide, this far from the right.”
Examples: ( 100px ), ( 10px | 100px ), ( ~ | ~ ), ( ~ | 100px | ~)

Modifier options sit to the right of the comma (or by themselves if do not provide modifiers). The format for modifier options is three commands separated by pipe | characters.

When all values are not used, the fields will take precedence like so:

  • ( <first offset> )
  • ( <first offset> | <last offset> )
  • ( <first offset> | <size> | <last offset>>)

First offset

A single explicit or wildcard command. Determines how far from the left/top the grid will start. A wildcard as a first offset pushes the grid to the bottom/right side. When used with a wildcard in the last offset, a wildcard in the first offset will center the grid.

Size

A single explicit or wildcard command. Determines the height or width of the grid.

Last offset

A single explicit or wildcard command. Determines how far from the right side the grid will end. A wildcard as a last offset pushes the grid to the top/left side. When used with a wildcard in the first offset, a wildcard in the last offset will center the grid.

Errors

Format: {foo [1]}
In words: “The value ‘foo’ has caused error code 1”

When you unfocus the grid notation field or click the Add guides button, GuideGuide will check to make sure what you’ve written is valid. If there are errors, GuideGuide will mark them with curly brackets, with a error number in square brackets. GuideGuide will explain the error codes below the grid notation field.

When you refocus the field, GuideGuide will clear away the errors to let you edit your grid notation.

The following errors are possible:

Error: 1 — Unrecognized command

GuideGuide does not recognize the command, or you did not specify a unit.

Error: 2 — No grids

GuideGuide found no grids in the grid notation field.

Error: 3 — Wildcards cannot be fills

Because wildcards have no inherent size, to use them as a fills would divide by infinity. This error exists for the safety of the universe.

Error: 4 — Grids can only contain one fill

Because you cannot use fills to fill space, no more than one can exist.

Error: 5 — Variables cannot contain fills

Because you use variables more than once, a fills in a variable would cause more than one fill.

Error: 6 — You must define variables before you call them

You cannot call variables unless you define them first.

Limitations

Grid notation tries to avoid telling you how to live your life. If you want to use percent commands that add up to more than 100%, that’s fine. If you want to specify a grid that is wider than the context, that’s fine too. Just keep in mind, what you are doing is beyond the logical bounds of the conventional grid math and may have unpredictable results.


Need help?

Contact support