Skip to content

Compass: Design guidelines and demo updates #5051

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
andrew-ronaldson wants to merge 6 commits into
base: main
Choose a base branch
from
+331 −55
Open

Compass: Design guidelines and demo updates #5051

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
dee56af
refactor(docs): compass guidelines and demo cleanup
andrew-ronaldson Jul 2, 2026
27c3c3e
Refactor import statement for FeedbackButton in home.js to use the co…
andrew-ronaldson Jul 2, 2026
817e1c7
Merge branch 'main' into compass
andrew-ronaldson Jul 7, 2026
7f9fada
docs(Compass): add image and updates elements
andrew-ronaldson Jul 7, 2026
5dc19b5
docs(compass): docked nav content
andrew-ronaldson Jul 7, 2026
ad6624c
Update Webpack configuration by removing symlink settings
andrew-ronaldson Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 31 additions & 54 deletions ...documentation-site/patternfly-docs/content/components/compass/CompassIntegrationsDemo.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import React, { useState, useEffect } from 'react';
import React, { useState } from 'react';
import {
Compass,
CompassHeader,
Expand Down Expand Up @@ -45,15 +45,13 @@ import {
Avatar,
Icon,
SkipToContent,
Switch,
DrawerPanelContent,
DrawerHead,
DrawerActions,
DrawerCloseButton,
DrawerPanelBody
} from '@patternfly/react-core';
import { ActionsColumn } from '@patternfly/react-table';
import { DataViewToolbar } from '@patternfly/react-data-view/dist/dynamic/DataViewToolbar';
import { DataViewTextFilter } from '@patternfly/react-data-view/dist/dynamic/DataViewTextFilter';
import { DataViewTable } from '@patternfly/react-data-view/dist/dynamic/DataViewTable';
import { MessageBar } from '@patternfly/chatbot';
Expand All @@ -73,21 +71,12 @@ import { RHAiExperienceIcon } from './assets/RHAiExperienceIcon';
export const CompassIntegrationsDemo: React.FunctionComponent = () => {
const [isDropdownOpen, setIsDropdownOpen] = useState(false);
const [activeDisplay, setActiveDisplay] = useState<"table" | "card">("table");
const [isGlassTheme, setIsGlassTheme] = useState(true);
const [isDrawerOpen, setIsDrawerOpen] = useState(false);

const onDrawerToggle = () => {
setIsDrawerOpen(!isDrawerOpen);
};

useEffect(() => {
if (isGlassTheme) {
document.documentElement.classList.add('pf-v6-theme-glass');
} else {
document.documentElement.classList.remove('pf-v6-theme-glass');
}
}, [isGlassTheme]);

const integrations = [
{
id: 1,
Expand Down Expand Up @@ -554,33 +543,36 @@ export const CompassIntegrationsDemo: React.FunctionComponent = () => {

const tableViewContent = (
<>
<DataViewToolbar
clearAllFilters={() => { }}
filters={
<DataViewTextFilter
filterId="name"
title="Name"
placeholder="Filter by name"
/>
}
actions={
<ToggleGroup>
<ToggleGroupItem
icon={<ThIcon />}
aria-label="grid icon button"
isSelected={activeDisplay === "card"}
onChange={() => setActiveDisplay("card")}
></ToggleGroupItem>
<ToggleGroupItem
icon={<ListIcon />}
aria-label="list icon button"
isSelected={activeDisplay === "table"}
onChange={() => setActiveDisplay("table")}
></ToggleGroupItem>
</ToggleGroup>
}
pagination={<Pagination page={1} perPage={10} isCompact />}
/>
<Toolbar>
<ToolbarContent>
<ToolbarItem>
<DataViewTextFilter
filterId="name"
title="Name"
placeholder="Filter by name"
/>
</ToolbarItem>
<ToolbarItem>
<ToggleGroup>
<ToggleGroupItem
icon={<ThIcon />}
aria-label="grid icon button"
isSelected={activeDisplay === "card"}
onChange={() => setActiveDisplay("card")}
></ToggleGroupItem>
<ToggleGroupItem
icon={<ListIcon />}
aria-label="list icon button"
isSelected={activeDisplay === "table"}
onChange={() => setActiveDisplay("table")}
></ToggleGroupItem>
</ToggleGroup>
</ToolbarItem>
<ToolbarItem variant="pagination" align={{ default: "alignEnd" }}>
<Pagination page={1} perPage={10} isCompact />
</ToolbarItem>
</ToolbarContent>
</Toolbar>
<DataViewTable
aria-label="Integrations"
columns={columns}
Expand Down Expand Up @@ -685,21 +677,6 @@ export const CompassIntegrationsDemo: React.FunctionComponent = () => {
drawerContent={drawerContent}
drawerProps={{ isExpanded: isDrawerOpen, isPill: true }}
/>
<div
style={{
position: 'absolute',
bottom: '1rem',
right: '1rem',
zIndex: 1000
}}
>
<Switch
id="glass-theme-toggle"
label="Glass theme"
isChecked={isGlassTheme}
onChange={(_, checked) => setIsGlassTheme(checked)}
/>
</div>
</>
);
};
103 changes: 103 additions & 0 deletions ...on-site/patternfly-docs/content/components/compass/compass-design-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
---
id: Compass
section: components
source: design-guidelines
---

import '../components.css';

Use Compass to build AI-driven and generative UI experiences. It gives you a structured canvas that organizes navigation, content, and conversational inputs into a single, structured interface — well-suited to applications where your users interact with AI-generated content in real time.

## Elements

A Compass layout is made up of several distinct regions. You can use them independently or together.

<div class="ws-docs-content-img">
![Elements of the Compass copy component.](./img/compass-elements.svg)
</div>

1. Header
2. Sidebars
3. Main content
4. Footer

### Header

The header spans the full width of the viewport at the top of the page. It typically contains 3 areas:

- **Logo:** A brand image or product logo.
- **Navigation:** Primary navigation tabs or links, using the `Tabs` component with the `isNav` flag.
- **Profile:** A user account control, such as a dropdown with an avatar.

### Sidebars

Compass gives you 2 vertical sidebars — one at the start (left) and one at the end (right) of the page. Use them for contextual actions, secondary navigation, or persistent tooling that doesn't belong in the main content flow. Actions in the sidebars can trigger menus and drawers.

@phcox phcox Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Start" and "end" seem odd to use in this context. They could be interpreted as "top" and bottom" of the page. I suggest omitting them and just using left and right without parentheses.

@andrew-ronaldson andrew-ronaldson Jul 9, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

start/end also refers to RTL behaviour. For things like padding & margin we use start/end variables so they can flip when RTL is enabled. With the header & footer areas also defined my thought was that they would read as top/bottom.


### Main content

The main content region fills the center of the viewport. It typically contains:

- **Main header:** A title area or hero section that contextualizes the current view.

@phcox phcox Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest using the same names in this list as the ones that are used in the image above. That said, using "Main header" or "Header content" runs a risk of creating confusion with the distinct Header section. "Hero area" or "Hero section" might work.

- **Content area:** The primary body of generated content or interactive data.
- **Footer:** A persistent input area, typically housing a `MessageBar` for conversational AI interactions.

@phcox phcox Jul 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't seem like "Footer" belongs here, given that it's called out in the image and the supporting text beneath it as its own distinct section, and not in Main Content.


### Footer

The footer provides a stable, anchored input zone at the bottom of the viewport. Use it to hold a `MessageBar` or similar input control. You have 2 placement options:

- **Full-width footer** (via the `footer` prop): Spans the entire viewport and causes sidebars to adjust their height in response to footer height changes.
- **Inline footer** (via `CompassMainFooter`): Contained within the main content region, allowing sidebars to extend the full viewport height regardless of footer size changes.

## Usage

### When to use Compass

- **AI assistant pages:** Use Compass when building a dedicated experience for interacting with a conversational AI, where the message bar is a persistent, central affordance.
- **Generative dashboards:** Use Compass when displaying AI-generated content that is dynamically assembled and may update in real time.
- **Immersive full-page layouts:** Use Compass when the interface requires a structured, full-bleed canvas that goes beyond a standard page shell.

### When not to use Compass

- **Standard application pages:** For typical create, read, update, and delete (CRUD) pages, data tables, or form-driven workflows that don't involve generative or AI-driven content, use PatternFly's standard [Page](/components/page) component instead.
- **Embedded content:** Use Compass for top-level, full-page layouts only — not as a nested layout within another page.

@phcox phcox Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kind of a nit, but with the established flow of "Use Compass..." in the previous section, repeating that statement in the Do not use Compass section feels strange. Suggest "Do not use Compass as a nested layout within another page - it is to be used for top-level, full-page layouts only."


## Layout variations

### Default layout

The default Compass layout includes a header, optional sidebars, a main content area, and a footer message bar. This suits AI assistant applications where navigation and conversation input are always visible.

### Dashboard layout

For dashboard views, replace the main header with a `Hero` component and arrange content cards in a `Grid`. Each card should be wrapped in its own glass `Panel` to maintain visual separation between data regions.

### Docked navigation layout

Use the `dock` prop to consolidate all navigation into a single anchored vertical `[docked navigation]`(/components/navigation/react-demos#docked-nav). This layout works well when horizontal screen space is at a premium or when following a vertical-nav design convention.

## Visual style

### Glass theme

Compass is designed to work with the glass theme (`pf-v6-theme-glass`). When using the glass mode:

- The glass theme is typically applied globally to the `html` element, similar to enabling dark mode.
- Glass mode works best with a full-page background image.
- Wrap glass-styled containers in a `Panel` with the `isGlass` modifier.
- Do not nest glass-styled `Panel` stacks, as this can cause unintended visual artifacts.

@phcox phcox Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would "unintended visual artifacts" mean legibility and accessibility issues? If so, I would go ahead and just say that, or just add ", such as legibility and accessibility issues."


## Content considerations

- **Main header text:** Keep the main header or hero title concise and action-oriented. For generative UI, this area often reflects the user's current query or context.

@phcox phcox Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, I suggest using a consistent label for "main header" or "hero title"

- **Message bar placeholder text:** Write placeholder text that sets clear expectations. For example, "Ask a question or describe what you need."
- **Loading and thinking states:** When AI is processing a request, apply the thinking animation to indicate active generation. Ensure there is also a screen reader announcement so that assistive technology users are informed.
- **Empty states:** When no content has been generated yet, use a clear empty state in the main content area that guides the user toward their first interaction.

## Accessibility

- Ensure that the `MessageBar` region has an appropriate `aria-label` describing its purpose.
- Add a visually hidden `aria-live` region near the `MessageBar` to announce dynamic status changes (for example, when AI begins generating a response).
- Navigation landmarks (`<nav>`, `<main>`, `<header>`) should be present and correctly ordered so that keyboard and screen reader users can orient themselves within the layout.
- Avoid relying solely on color or animation to communicate AI processing state; always pair visual indicators with text or ARIA announcements.

For more information, visit the [Compass accessibility tab](/components/compass/accessibility).
Loading
Loading