Introduction

    The Forge grid dictates the horizontal and vertical relationship between and within web page sections, and how the layout varies by window size. Spacing guidelines provide consistent positioning between page sections and among components. Used together, a grid framework with consistent spacing establishes information hierarchy and predictable structure that set the foundation for a consistent, familiar user experience.  

    This page introduces the building blocks of the Forge grid, rows and columns, and explains how to use them to lay out content. It also documents our suggested screen sizes, space constants and provides guidelines for combining the grid, spacers, and components to create responsive layouts for user interfaces.  

    Key takeaways

    • The Forge grid regulates the hierarchy and arrangement of web page sections, and how they behave in different viewports.
    • Space constants apply to the smallest scale of UX design, dictating the number of pixels between single elements on the page.
    • Combined, these 2 elements have a profound impact on how users experience and interact with page content.
    • To implement the Forge grid and space constants, developers should use CSS and Sass variables.
    • Desktop designs should be optimized for 1920x1080 resolutions.
    • When considering alternate desktop screen sizes, the minimum resolution suggested for design consideration is 1024x764. 

    Grid basics

    Grids are a powerful tool for creating web pages that resize fluidly for the best layout on different devices. This fluidity is a cornerstone of responsive web design, and it relies on breakpoints, or set viewport widths.

    • When the page renders, it uses CSS to display the content in the layout that best fits the available width.
    • If users resize the window, and the viewport width hits a breakpoint, the layout refreshes automatically to accommodate the new width. This can involve changing container shapes, rearranging page sections, or even hiding some content completely.

    Mobile-friendly sites often use fluid layouts to automatically rearrange content for the best user experience on different devices without having to code multiple versions of the page. For example:

    • Desktops often display content sections horizontally.
    • Mobile phones often stack the content sections vertically.

    Screen Size

    For desktop apps, Forge designs should be optimized to 1920x1080 resolution screens. This size should be used as a reference size for all screen states and workflow illustrations.

    Designers may consider how designs will appear in popular alternate resolutions such as 1280x720 or 1024x764. The minimum resolution suggested for design consideration is 1024x764. Designers should work with developers and use breakpoint guidelines to determine how elements will resize to alternate screen sizes.

    Breakpoints

    Forge has 5 breakpoints:

    • Small: viewports narrower than 640px (mobile devices)
    • Medium: viewports between 640 and 1024px (tablets in portrait mode)
    • Large: viewports between 1024 and 1200px (tablets in landscape mode and laptops)
    • XLarge: viewports between 1200 and 1440px (laptops and desktops)
    • XXLarge: viewports over 1440px (desktops)
    Breakpoints

    Rows and columns

    Forge’s Grid consists of 2 components: GridRow and GridCol. Each GridRow is divided into columns: 12 equal vertical sections that span the full available width. The content is then laid out inside GridRow, using GridCol to define how many columns the content should span. A GridRow can contain one or more GridCols.

    Rows and columns

    Consider this example desktop page layout:

    • A lefthand navigation panel, defined by a GridCol that spans 3 columns across (out of the total 12)
    • The main body of content, defined by a GridCol that takes up the remaining 9 columns

    On narrow, mobile screens, a lefthand navigation panel doesn’t work well, so in small viewports, the page layout might change to:

    • The main body of content, now defined by a GridCol that takes up the full width of the page, 12 of 12 columns across
    • An overflow menu that contains the navigation content, which is hidden until users tap to open it

     

    Example of responsive layout

    Space constants

    Forge has 6 space constants that are based on UI design best practices and screen density considerations. They mainly come in multiples of 8 and help create a predictable rhythm across all athenahealth apps.

    Space constants

    Forge components and patterns are built using these space constants, as shown below. For visual consistency and efficient development, we recommend using Forge components as designed and avoiding custom spacing.

     

    NameValueLabelUsageExamples
    Extra small4pxXSUse for elements that are closely related
    • Between a heading and its description underneath it
    • Between a heading and a divider line underneath it
    • Between a label and an input field
    Small8pxSUse to separate parts of a component
    • Between a checkbox and its description text
    • Between a section header and its content
    Medium16pxMUse to separate components within a group
    • Between paragraphs, form fields, or cards
    Large24pxLUse to divide groups of content
    • Between subsections of information
    • Padding in a container
    Extra large40pxXLUse to divide large content sections
    • Between page sections
    • Padding in a container
    Extra extra large64pxXXLLargest spacing unit possible; use for custom layout
    • Charts and graphs

    Space constant examples

    Use caseExampleSpacers
    Heading and descriptionScreenshot showing extra small space between heading and description.XS
    ButtonScreenshot showing small space between two buttons.S
    CheckboxScreenshot showing small space between checkbox list elements.S
    Heading and divider lineScreenshot showing small space between heading and dividing line.S
    Headings and textScreenshot showing extra small and medium space between headings and text.S, M
    FormScreenshot showing small, medium, and large space between form elements.S, M, L
    CardScreenshot showing small, medium, large, and extra large spacing used in a card.S, M, L, XL

     

    If Forge components don’t fit your use case as designed, contact us on Teams to discuss options.

    Page layout

    Use the Forge grid and space constants together to lay out content for new page designs as follows:

    1. Place common elements like a top or left nav to start defining the overall page layout.  For example, a persistent left nav might occupy the leftmost 2-3 columns of the grid.
    2. If it makes sense for some content blocks to appear next to each other in the main content area, place and size them according to relative priority. This sets the number of grid columns for each section.
    3. Divide the main page content into high-level sections and subsections to establish discrete groups of related information.
    Page layout
    1. Use XL spacers to create separation between the highest-level groups (level 1). 
    2. Use L spacers to visually group the next largest sections (level 2). 
    3. Use M, S, and XS spacers within each group to create logical subsections of more closely related elements (level 3). 
    4. Review the page for any sections that seem out of place or separated from related sections.  
    5. [Optional] For a responsive design, create a narrower artboard (usually 375px wide, following mobile design best practices) and rearrange your content blocks for the best mobile experience. This helps developers set behavior at different breakpoints.
    Page layout

    Information density

    Information density refers to how close page elements are to each other. Consider how users will interact with the page or component to determine the best density for your design.

    Moderate density layouts

    Forge is designed for moderate density layouts. For most users, these layouts provide enough information in a single view, but not so much that it’s crowded or overwhelming. For moderate density layouts, use the default version of our components.

    High density layouts

    Use a higher density layout for use cases that require more content to fit in a single view, or when users need to browse and interact with a large amount of content, like repetitive data entry or analyzing a large dataset.

    To achieve higher density:

    • Use the more compact versions of Table or Form (combined with default versions of other components).
    • Use smaller space constants between sections.
    • Remove any column offsets that create additional white space between grid columns and use gutters instead.

    Don’t:

    • Reduce the size of Forge components or decrease the spacing within components.
    • Decrease the line height. Forge uses 1.2px line height by default, and using less makes content harder to read.
    • Decrease the size of icons below 16px (see the Icons page for specifications).

    If you make adjustments to increase density, make sure your design maintains these minimum target sizes:

    • For non-touch UIs: 24px clickable target
    • For touch devices: 48px tappable target

    CSS classes and Sass variables

    To use Sass variables related to spacing and layout, import these files:

    // Access Forge Sass variables
    @use '@athena/forge/sass/forge-abstracts';
    // Access Foundation mixins like breakpoint
    @use'@athena/forge/sass/_vendor/foundation-sites/scss/util/util' as forge-util;

    Implementing breakpoints

    Breakpoints are the set points at which the layout refreshes automatically to fit the new width, to provide the best user experience for that viewport. Forge defines several breakpoints you can use to create responsive layouts:

    • small for viewports narrower than 640px (mobile devices)
    • medium for viewports between 640 and 1024px (tablets in portrait mode)
    • large for viewports between 1024 and 1200px (tablets in landscape mode and laptops)
    • xlarge for viewports between 1200 and 1440px (laptops and desktops)
    • xxlarge for viewports over 1440px wide (desktops)

    To implement a breakpoint, use the breakpoint mixin. This wraps a media query around your desired styles so that they appear only on certain screen sizes.

    // medium breakpoint example
    @include forge-util.breakpoint(medium) {
    // desired styles
    }

    Javascript constants

    Layout constants can be imported from @athena/forge-shared

    import { layout } from @athena/forge-shared

    Resources

    Utilities

    The utility classes map to certain CSS properties and are applied with the highest level of specificity. You can use them to override default component styling without having to resort to custom CSS or inline styles.

    Padding

    ClassSassDescription
    • fe_u_padding--none
    • fe_u_padding--top-none
    • fe_u_padding--bottom-none
    • fe_u_padding--left-none
    • fe_u_padding--right-none
    map-get(forge-abstracts.$global-padding, none)Sets the specified padding to none
    • fe_u_padding--xsmall
    • fe_u_padding--top-xsmall
    • fe_u_padding--bottom-xsmall
    • fe_u_padding--left-xsmall
    • fe_u_padding--right-xsmall
    map-get(forge-abstracts.$global-padding, xsmall)Sets the specified padding to xsmall
    • fe_u_padding--small
    • fe_u_padding--top-small
    • fe_u_padding--bottom-small
    • fe_u_padding--left-small
    • fe_u_padding--right-small
    map-get(forge-abstracts.$global-padding, small)Sets the specified padding to the small value
    • fe_u_padding--medium
    • fe_u_padding--top-medium
    • fe_u_padding--bottom-medium
    • fe_u_padding--left-medium
    • fe_u_padding--right-medium
    map-get(forge-abstracts.$global-padding, medium)Sets the specified padding to the medium value
    • fe_u_padding--large
    • fe_u_padding--top-large
    • fe_u_padding--bottom-large
    • fe_u_padding--left-large
    map-get(forge-abstracts.$global-padding, large)Sets the specified padding to the large value
    • fe_u_padding--xlarge
    • fe_u_padding--top-xlarge
    • fe_u_padding--bottom-xlarge
    • fe_u_padding--left-xlarge
    • fe_u_padding--right-xlarge
    map-get(forge-abstracts.$global-padding, xlarge)Sets the specified padding to xlarge
    • fe_u_padding--xxlarge
    • fe_u_padding--top-xxlarge
    • fe_u_padding--bottom-xxlarge
    • fe_u_padding--left-xxlarge
    • fe_u_padding--right-xxlarge
    map-get(forge-abstracts.$global-padding, xxlarge)Sets the specified padding to xxlarge

    Margin

    ClassSassDescription
    • fe_u_margin--none
    • fe_u_margin--top-none
    • fe_u_margin--bottom-none
    • fe_u_margin--left-none
    • fe_u_margin--right-none
    map-get(forge-abstracts.$global-margin, none)Sets the specified margin to none
    • fe_u_margin--xsmall
    • fe_u_margin--top-xsmall
    • fe_u_margin--bottom-xsmall
    • fe_u_margin--left-xsmall
    • fe_u_margin--right-xsmall
    map-get(forge-abstracts.$global-margin, xsmall)Sets the specified margin to xsmall
    • fe_u_margin--small
    • fe_u_margin--top-small
    • fe_u_margin--bottom-small
    • fe_u_margin--left-small
    • fe_u_margin--right-small
    map-get(forge-abstracts.$global-margin, small)Sets the specified margin to the small value
    • fe_u_margin--medium
    • fe_u_margin--top-medium
    • fe_u_margin--bottom-medium
    • fe_u_margin--left-medium
    • fe_u_margin--right-medium
    map-get(forge-abstracts.$global-margin, medium)Sets the specified margin to the medium value
    • fe_u_margin--large
    • fe_u_margin--top-large
    • fe_u_margin--bottom-large
    • fe_u_margin--left-large
    • fe_u_margin--right-large
    map-get(forge-abstracts.$global-margin, large)Sets the specified margin to the large value
    • fe_u_margin--xlarge
    • fe_u_margin--top-xlarge
    • fe_u_margin--bottom-xlarge
    • fe_u_margin--left-xlarge
    • fe_u_margin--right-xlarge
    map-get(forge-abstracts.$global-margin, xlarge)Sets the specified margin to xlarge
    • fe_u_margin--xxlarge
    • fe_u_margin--top-xxlarge
    • fe_u_margin--bottom-xxlarge
    • fe_u_margin--left-xxlarge
    • fe_u_margin--right-xxlarge
    map-get(forge-abstracts.$global-margin, xxlarge)Sets the specified margin to xxlarge

    Height and width

    ClassSassDescription
    fe_u_fill--heightn/aSets the height to 100% of the parent element
    fe_u_fill--widthn/aSets the width to 100% of the parent element
    fe_u_fill--parentn/aSets the height and width to 100% of the parent element

    Flexbox

    ClassDescription
    fe_u_flex-containerSets the element to display: flex
    • fe_u_flex-justify-content--flex-start
    • fe_u_flex-justify-content--flex-end
    • fe_u_flex-justify-content--center
    • fe_u_flex-justify-content--space-between
    • fe_u_flex-justify-content--space-around
    Sets justify-content to the respective value when applied to any flex element
    • fe_u_flex-align-items--flex-start
    • fe_u_flex-align-items--flex-end
    • fe_u_flex-align-items--center
    • fe_u_flex-align-items--stretch
    Sets align-items to the respective value when applied to any flex element
    • fe_u_flex-align-self--flex-start
    • fe_u_flex-align-self--flex-end
    • fe_u_flex-align-self--center
    • fe_u_flex-align-self--stretch
    Sets align-self to the respective value when applied to any flex element child
    fe_u_flex--shrinkFlex item will only take up the space of its content when applied to any flex element child
    fe_u_flex--growFlex item will take up the maximum space it can when applied to any flex element child