App Frame

Our app’s backbone ensures a responsive, easy-to-use, and reliable experience.

Application Frame

Maturity

Alpha

FYQ2 target

Beta

Figma component

-

Repository

-

Storybook

-

Overview

The App Frame is the backbone of our app, providing a responsive, easy-to-use, reliable experience that can streamline your workflow, reduce errors, and easily make updates.

Clear presentation and labeling are crucial for easy navigation, and we ensure organized and consistent information to help people understand where they are and what to expect.

Related content

Types

Default

Default

Navigation-less

Navigation-less

The Default type contains App Navigation and App Main. The Home, Project page or Dashboard use this frame.

The Navigation-less type contains only the App Main and is for pages where people are not logged in. The Report page uses this frame.

Important terms

We use the following terms and definitions throughout this document.

Term

Description

App section

A top-level content category that forms our information hierarchy.

Page

A UI that is unique to a route and is typically part of an app section. — Next.js Pages and Layouts

Landmark

A type of region on a page to which people may want quick access. Content in such a region differs from other regions on the page. It is relevant to a specific user purpose, such as navigating, searching, perusing the primary content, etc. — ARIA specification

Live region

Live regions are perceivable regions of a page that are typically updated due to an external event when the user focus may be elsewhere. These regions are not always updated as a result of user interaction. — ARIA specification

A graphic visualization of each concept in context.

A graphic visualization of each concept in context.


Primary landmarks

Our Application Frame consists of four primary landmarks that provide quick access to specific areas of the page.

Landmark

HTML section element

ARIA landmark role

Z-index

Scroll

App Navigation

<nav>

navigation

0

Page

App Main

<main>

main

0

Page

App Dialog

<dialog>

dialog

2

Scoped

App Feedback

<aside> - TBD

complementary / alert

3

Scoped

App Dialog and App Feedback are hidden by default and can be triggered by a user action or the system.

App Navigation

App Frame - App Navigation

The App Navigation is a global navigation landmark that organizes content into distinct categories. Navigation Controls function as a tool to mirror our information hierarchy.

When designing the Navigation Controls, it’s essential to ensure they reflect a clear grouping and highlight the relationships between different app sections. The App Navigation should showcase our top-level content and be placed at the highest point of the app’s hierarchy. Pages should have a defined purpose and clear labels for specific content categories. This ensures efficient use of the navigation system and solid information architecture.

Here’s what you can typically find inside:

Placement

App Navigation lives on the left side of the screen and is essential for providing access to multiple hierarchies.

Don’t hide or remove it, as it allows for persistent access and the ability to toggle between different levels of our information hierarchy while maintaining context in each. For instance, while considering a new tester segment in the Tester Management app section, I can compare it to a study I’m building in the Projects app section, two levels deep into my hierarchy.

Behavior

App Frame - App Navigation height

The App Navigation takes up all available vertical space until it reaches the viewport’s height. It adapts to changes in the viewport.

Collapsed state (default) — 56px fixed width

Collapsed state (default) — 56px fixed width

Expanded state — 240px fixed width

Expanded state — 240px fixed width

It has two states: Collapsed and Expanded. When people hover or focus, the navigation expands, and overlaps the content instead of pushing it aside.

App Frame - App Navigation content

The content is divided into two regions that behave differently depending on their position:

  • The content at the top stays fixed at the top
  • The content at the bottom stays fixed at the bottom

App Main

App Frame - App Main

The App Main landmark represents the app experience's dominant content, comprising several secondary landmarks.

Behavior

App Frame - App Main dimensions

It takes up most of the screen area, if not all, and is always visible since it’s where the app is experienced. It takes the space left by the other landmarks adapting to the viewport changes.

App Dialog

App Frame - Modal Dialog

When browsing the app content, hierarchical navigation via the App Navigation is the typical and simple way. But when we need to guide someone through a specific workflow or task, Dialogs are more appropriate. Three types of tasks can be completed effectively through Dialogs:

  1. A simple task
  2. A multi-step task
  3. Full-screen content

Placement

The Dialog intentionally disrupts the typical information hierarchy by covering the App Navigation and App Main landmarks. This approach sharpens people’s focus and emphasizes the task’s primary function.

Behavior

Dialogs are Modal, hidden by default, and can be triggered by a user action or the system. Some will have a dismiss action, while others will require people to decide on something—to be defined.

App Feedback

App Frame - Notifications

App Feedback is a live region where we’ll present important information in a clear and easily digestible format: Notifications and Confirmations—both in definition.

Placement

App Frame - Notifications placement

App Feedback appears floating on the right side of the screen, right below the Page Header, to prevent covering its contents. They take up all available vertical space from there until it reaches the viewport’s height, and it adapts to its changes.

Contents will be aligned to the top of its container.

Behavior

App Feedback is hidden by default and can be triggered by a user action or the system. They will always have a dismiss action.


Secondary landmarks

Secondary landmarks are part of App Main.

Landmark

HTML section element

ARIA landmark role

Z-index

Scroll

Page Header

<header>

1

Page

Page Tabs (optional)

<nav>

navigation

0

Page

Content

<section>

region

0

Page

Content Navigation (optional)

<nav>

navigation

0

Scoped

Action Bar (optional)

<footer> - TBD

contentinfo

1

Page

Side Panel (optional)

<aside>

complementary

2

Scoped

Page Header

App Frame - Global Header

The Page Header secondary landmark provides a natural place to showcase the page title <h1>, helping people find their way through our app and setting expectations. It can include controls that impact the overall page.

Here’s what you can typically find inside:

  • Back Navigation Control to let people go back over their steps through a hierarchy of information (if applicable).
  • Page title describing the current Page.
  • Essential global controls that affect the whole page (if applicable). Ideally, just one or two.

Placement

The Page Header has a fixed height and is permanently fixed at the top of the screen. Even when people scroll, it remains in place, providing easy access to the elements it holds.

Behavior

The Page Header fills all the available horizontal space until it reaches its container width. It adapts to viewport changes, dividing the space into three areas that behave differently depending on their location:

  • The content on the left side sticks to the left.
  • The content in the center remains centered.
  • The content on the right sticks to the right.

Also, the Page Header may be hidden via a specific control that toggles its visibility when people want to put their entire focus on the content.

Page Tabs (optional)

App Frame - Global Tabs

The Page Tabs secondary landmark uses Navigation Controls—in definition—to navigate between mutually exclusive content sub-pages inside the Content landmark.

An example of a Page divided into subpages using Page Tabs, like Settings.

An example of a Page divided into subpages using Page Tabs, like Settings.

Content

App Frame - Content

The Content secondary landmark holds the app experience, and its content is very diverse. It’s composed of regions that help to organize the information presented in different Grids. Regions go from one to multiple and should always have a <h2> heading when we have multiple, with very few exceptions.

Content can be displayed with padding—by default—and without.

With padding (default)

With padding (default)

Content displays full width until reaching some consistent padding constraints of 24 pixels surrounding the container.

Without padding

Without padding

The Content container displays without any limit, filling the whole area.

Content Navigation (optional)

App Frame - Content Navigation

The Content Navigation secondary landmark helps navigate through the Content region.

Behavior

App Frame - Content Navigation max width

It fills all available vertical space until it reaches its max-width.

Collapsed state — 90px fixed width

Collapsed state — 90px fixed width

Expanded state — 400px max-width

Expanded state — 400px max-width

It comes in two states: Collapsed and Expanded. This is based on user interaction—:hover or :focus in any of its elements—and the viewport breakpoint. When Expanded based on user interaction, it overlaps the content underneath.

Action Bar (optional)

App Frame - Action Bar

The Action Bar secondary landmark is a versatile tool that shows relevant information and actions based on the specific area of the Page you are on. lt serves various purposes, such as control panels and displaying metadata.

It can be used at any application level:

  1. Page level, when you enter an Edit or Selection mode
  2. Window level (Dialogs, Side Panel)
  3. Panel level (Choice Menu, etc.)

Let's focus on how it works at a page level.

Placement

The Action Bar has a fixed height and is permanently fixed at the bottom of the screen. Even when people scroll, it remains in place, providing easy access to the elements it holds.

Behavior

The Action Bar takes up all available horizontal space until it reaches its container’s width. It adapts to changes in the viewport.

Side Panel (optional)

App Frame - Side Panel

The Side Panel secondary landmark showcases additional content that complements the page’s main Content. They remain visible until dismissed, allowing people to interact with the rest of the page while open.

Some of the usual applications are:

  • Displaying a list of actions that affect the entire page entity, such as settings.
  • Displaying supplemental content and features, like element details.

Here’s what you can typically find inside a Side Panel:

  • A fixed <header> with:
    • A <h2> title
    • A Close action
    • A Back action (optional)
  • The Side Panel content
  • An Action Bar (optional)

Placement

The Side Panel appears floating on the right side of the screen, covering the rest of the App Main secondary landmarks. It takes up all available vertical space from there until it reaches the viewport’s height, and it adapts to its changes.

Behavior

The Side Panel is hidden by default and can be triggered by a user action. They will always have a dismiss action.


Quality checklist

This element passes the following requirements described in our Component lifecycle.

Maturity

Alpha

α · Design tokens

It uses Ariane design tokens.

α · Naming agreement

Its name is agreed upon and shared between design and development.

α · Responsive L1

Is responsive to different viewport sizes.

β · Responsive L2

The responsive behavior has been reviewed and validated by the team.

β · Docs L1

It has essential documentation with at least primary usage.

β · Use cases

All the uses are audited and refined.