Content hierarchy

Quartz defines a hierarchical content model as the backbone of its visual language, providing robust visual consistency while remaining very flexible.

Quartz goes beyond components and patterns. It also provides an expressive visual hierarchy that allows you to quickly lay out the user interface.

Make sure you stick as much as you can to this content hierarchy. You will benefit from the prebuilt Figma templates and utility classes, which implement all the visual styles from the specifications (title hierarchy, paddings, spacings, colors, elevation, etc.). In other words, you will mainly copy and paste the templates, and everything will "just work" out of the box.

Embrace the content-first approach

Quartz is designed for the content-first approach. Don't pick a component or template because "it looks good". Follow the approach and use the proper Figma templates and utility classes.

Vertical hierarchy

Quartz organizes content into four distinct layers. Think of layers as transparent sheets stacked on top of each other:

The four layers of Quartz, from bottom to top: main layer, panel layer, primary navigation layer, and popup layer.

• The main layer holds most of the content. It is the central area of the screen where users will look at the most.
• The optional panel layer contains the secondary content floating above the main content. Panels are boxes always anchored to the sides or bottom of the application, visible at all times. Panels may be related to the main content; they may update depending on the focused content in the main layer.
• The primary navigation layer is floating above the panel layer. It contains the primary navigation bar to the left and the global application toolbar.
• The popup layer is the topmost layer. It displays dialog boxes, notifications, and onboarding popups. When a dialog box is modal, the background is blurred to prevent user action behind

The main and panel layers are the most useful for organizing content. The popup layer holds transient content.

Note

An accessory pseudo-layer also exists, which can float over any other layer. It displays tooltips, drop-downs, and menus.

Layers in practice

Layers are the root of many visual styles: background colors, spacings, elevation, and corner radius.

Tip

Designers: use the Figma templates The Figma templates implement the specifications for every layer. Use them to save time and avoid mistakes.

Tip

Developers: use the utility classes The utility classes implement all the relevant CSS variables. Use them to save time and avoid mistakes.

Utility classes use the layer name at their root:

• qds-main-*
• qds-panel-*
• qds-navigation-*
• qds-popup-*
• qds-accessory-*

In Figma, the layer name forms the root of style names:

• main/*
• panel/*
• navigation/*
• popup/*
• accessory/*

Similarly, in code, the layer name is at the root of the CSS variables names:

• --qds[-theme]-main-*
• --qds[-theme]-panel-*
• --qds[-theme]-navigation-*
• --qds[-theme]-popup-*
• --qds[-theme]-accessory-*

Nested hierarchy

Depending on the layer, Quartz supports up to three levels of nested content hierarchy. These levels are composed of root, sections, and subsections:

Example of layer content breakdown into sections and subsections.

• the root of the layer holds introductory content and an optional top-level title (depending on the layer, see the allowed layer/level combinations).
• the sections are the primary content organization level. They may display titles that help the user scan through the high-level topics.
• within sections, subsections organize the content with more granularity. They may display titles and support special capabilities like importance levels and interactivity.

Because each layer has a specific purpose, not all levels make sense on every layer. See below the allowed layer/level combinations.

Note

The root/section/subsection hierarchy is an abstract organization of content. It does not presuppose how the content is laid out on the screen.

Levels in practice

Sections/subsections extend the layer styles and depict how content organizes on multiple levels.

Tip

Designers: use the Figma templates The Figma templates implement the specifications for every layer and level. Use them to save time and avoid mistakes.

Tip

Developers: use the utility classes The utility classes implement all the relevant CSS variables. Use them to save time and avoid mistakes.

Utility classes use level name just after the layer name:

• qds-main-section
• qds-main-subsection
• qds-panel-section
• qds-panel-subsection
• etc.

In Figma, the root level is omitted from the name of styles. For example:

• panel/title
• popup/subtitle
• accessory/kicker

Sections and subsections are appended just after the name of the layer. For example:

• main/section/title
• popup/subsection/subtitle
• accessory/section/kicker

Similarly, in code, the root level is omitted from the name of the CSS variables, and the section/subsection level is appended just after the name of the layer:

• --qds[-theme]-main-section-*
• --qds[-theme]-panel-*
• --qds[-theme]-panel-section-*
• --qds[-theme]-popup-subsection-*
• --qds[-theme]-accessory-section-*
• etc.

Allowed layer/level combinations

The root/section/subsection hierarchy is the foundation of the Quartz content organization. But those levels are not meaningful on all the layers. The following table shows which levels are allowed on the layers:

	Main	Panel	Primary navigation	Popup	Accessory
Root *	🚫	✅	🚫	✅	✅
Section	✅	✅	✅	✅	✅
Subsection	✅	✅	✅	✅	🚫

Note

Placing content at the root level is always allowed (for example, an introductory paragraph). But there must not be any title at the root level when specified with the 🚫 symbol.

Titles mimic the content hierarchy

The qds-title component mimics the content hierarchy through its layer and level properties. By keeping those properties coherent with their parent container, you will ensure all the styles respect the visual language of Quartz.

This is a panel subsection title

Don't

This is a main subsection title

Do

Importance hierarchy

The importance hierarchy is only available at the subsection level. Subsections support the three emphasis levels defined by the importance transversal principle:

This is a subdued subsection

Use the "subdued" importance level to reduce the emphasis of some subsections.

This is a standard subsection

Use the "standard" importance level for most subsections.

This is an emphasized subsection

Use the "emphasized" importance level to catch user's attention to a few subsections.

Examples of the three levels of subsection importance: subdued, standard, and emphasized.

Important

Subsections are not "cards"! It's tempting to see subsections like a card components. But they're not! They are the visual expression of the content hierarchy and importance. Please review the Subsection guidelines for do/don't examples.

Interactive subsections

A subsection as a whole can be an interactive content block:

This is a standard subsection

It can contain textual content as well as interactive elements like this button:

This is an interactive subsection

It reacts on mouse hover and click on the desktop platform.

Make sure the content and layout suggest it can be tapped on mobile.

Subsection examples: the regular subsection can contain a button, but the interactive subsection contains only static content.

Content hierarchy guidelines

Respect the layer/level combinations

Do not mix styles or titles from different layers. Breaking the hierarchy will lead to inconsistencies in the visual language and the overall rhythm of the UI.

Tip

Always use the Figma templates and utility classes to build a proper content hierarchy.

This is a main layer section

This is a panel layer subsection

Don't

This is a main layer section

This is a main layer subsection

Do

Sections are mandatory

Except for introductory material, all content must be wrapped in a section, even if you omit the title of that section. Sections don't have a visible background but have specific spacing rules that must be respected.

A quick introductory paragraph.

This is a main section title

Not wrapped into a section, leading to incorrect spacings.

Don't

A quick introductory paragraph.

This is the main content title

The title and the following content are wrapped in a section and properly spaced.

Do

Sometimes, a section contains nothing but subsections. This is okay, but you must still wrap those subsections into an empty parent section. This will ensure proper spacing between the main blocks of your content.

In this example, the first section only contains subsections without any other content. Wrapping them in a section is still required to apply proper spacing. The second section displays a title and sample content.

Titles are optional

Although titles play a significant role in organizing the content hierarchy, they're not strictly required on your content. For example, within a section, you may omit its title but still use titles for its subsections:

In this example, the first section only contains an introductory paragraph without a title. Wrapping them in a section is still required to apply proper spacing. The second section displays a title and sample content.

Subsections are optional

Subsections allow to break down the content into smaller parts within a section. Not all sections may need that, and it's perfectly valid for a section not to have subsections.

Important

If your content needs an additional level of breakdown, then you must use subsections. Don't customize the content hierarchy with a non-standard breakdown.

Don't nest subsections

Quartz provides three levels of content hierarchy (layer root, section, subsection). Don't nest sections within sections, or subsections within subsections, to add more levels.

This is a subsection

This is a nested subsection

It is artificially emphasized to add elevation to it, so we can distinguish it from its parent.

Don't

This is a section

This is a subsection

Do

Tip

If you need more than three levels, please let us know so we can suggest a solution tailored to your needs.

Subsection guidelines

Don't treat subsections as "cards"

Quartz does not provide a "card" component on purpose. Used inappropriately, cards can lead to a confusing visual hierarchy. Stick to following the content-first approach and use the proper Figma templates and utility classes.

Don't emphasize subsections to make them look elevated

Elevation is used to add emphasis to a subsection, meaning it emphasizes its content. Don't emphasize subsections for decorative purposes.

This is a standalone subsection

Don't

This is a standalone subsection

Do

Don't emphasize all the subsections from the same group

Follow the guidelines explained in the importance transversal concept. Typically, don't apply the same level of importance to all subsections from the same group.

This is an emphasized subsection

This is an emphasized subsection

This is an emphasized subsection

Don't

This is a subdued subsection

This is a subdued subsection

This is a subdued subsection

Don't

This is an emphasized subsection This content is very important and must catch the user's attention.

This is a standard subsection

This content is of normal importance.

This is another standard subsection

This content is of normal importance.

This is a subdued subsection

With secondary content that doesn't deserve as much attention as the other subsections.

Do

Don't include controls within interactive subsections

When a subsection is made interactive, treat it as a uniform content block. Don't add interactive elements inside an interactive subsection. This would create an inconsistent behavior depending on the location of the click/tap.

This is an interactive subsection

This static content is fine, as it does not change the click/tap behavior of the subsection.

But what about the following button? What will happen if you click on it?

Don't

This is an interactive subsection

This static content is fine, as it does not change the click/tap behavior of the subsection.

Do

Specifications

See the content hierarchy specifications page for detailed specifications.