From dee56afde7e5116348f9fc4e21c6e807b33cbf26 Mon Sep 17 00:00:00 2001 From: Andrew Ronaldson Date: Thu, 2 Jul 2026 09:59:18 -0300 Subject: [PATCH 1/2] refactor(docs): compass guidelines and demo cleanup --- .../scripts/webpack/webpack.base.config.js | 2 + .../compass/CompassIntegrationsDemo.tsx | 85 ++++++---------- .../compass/compass-design-guidelines.md | 98 +++++++++++++++++++ 3 files changed, 131 insertions(+), 54 deletions(-) create mode 100644 packages/documentation-site/patternfly-docs/content/components/compass/compass-design-guidelines.md diff --git a/packages/documentation-framework/scripts/webpack/webpack.base.config.js b/packages/documentation-framework/scripts/webpack/webpack.base.config.js index dda3a1b2b0..cc6c9e39c4 100644 --- a/packages/documentation-framework/scripts/webpack/webpack.base.config.js +++ b/packages/documentation-framework/scripts/webpack/webpack.base.config.js @@ -42,6 +42,7 @@ module.exports = (_env, argv) => { path.resolve(process.cwd(), 'patternfly-docs'), path.resolve(process.cwd(), 'examples'), path.resolve(__dirname, '../..'), // Temporarily compile theme using webpack for development + path.resolve(process.cwd(), 'node_modules/@patternfly/documentation-framework'), // symlink path for workspace builds /react-[\w-]+\/src\/.*\/examples/, /react-[\w-]+\\src\\.*\\examples/, // fix for Windows /react-[\w-]+\/patternfly-docs\/.*\/examples/, //fixes for extensions @@ -106,6 +107,7 @@ module.exports = (_env, argv) => { ] }, resolve: { + symlinks: false, // Allow importing client routes alias: { 'client-styles': path.resolve(process.cwd(), 'patternfly-docs/patternfly-docs.css.js'), diff --git a/packages/documentation-site/patternfly-docs/content/components/compass/CompassIntegrationsDemo.tsx b/packages/documentation-site/patternfly-docs/content/components/compass/CompassIntegrationsDemo.tsx index be92d5c9b1..3df6913403 100644 --- a/packages/documentation-site/patternfly-docs/content/components/compass/CompassIntegrationsDemo.tsx +++ b/packages/documentation-site/patternfly-docs/content/components/compass/CompassIntegrationsDemo.tsx @@ -1,4 +1,4 @@ -import React, { useState, useEffect } from 'react'; +import React, { useState } from 'react'; import { Compass, CompassHeader, @@ -45,7 +45,6 @@ import { Avatar, Icon, SkipToContent, - Switch, DrawerPanelContent, DrawerHead, DrawerActions, @@ -53,7 +52,6 @@ import { 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'; @@ -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, @@ -554,33 +543,36 @@ export const CompassIntegrationsDemo: React.FunctionComponent = () => { const tableViewContent = ( <> - { }} - filters={ - - } - actions={ - - } - aria-label="grid icon button" - isSelected={activeDisplay === "card"} - onChange={() => setActiveDisplay("card")} - > - } - aria-label="list icon button" - isSelected={activeDisplay === "table"} - onChange={() => setActiveDisplay("table")} - > - - } - pagination={} - /> + + + + + + + + } + aria-label="grid icon button" + isSelected={activeDisplay === "card"} + onChange={() => setActiveDisplay("card")} + > + } + aria-label="list icon button" + isSelected={activeDisplay === "table"} + onChange={() => setActiveDisplay("table")} + > + + + + + + + { drawerContent={drawerContent} drawerProps={{ isExpanded: isDrawerOpen, isPill: true }} /> -
- setIsGlassTheme(checked)} - /> -
); }; diff --git a/packages/documentation-site/patternfly-docs/content/components/compass/compass-design-guidelines.md b/packages/documentation-site/patternfly-docs/content/components/compass/compass-design-guidelines.md new file mode 100644 index 0000000000..82647f3cd1 --- /dev/null +++ b/packages/documentation-site/patternfly-docs/content/components/compass/compass-design-guidelines.md @@ -0,0 +1,98 @@ +--- +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. + +### 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. + +### Docked navigation + +As an alternative to a top header with sidebars, a `[docked navigation]`(/components/navigation/react-demos#docked-nav) anchors all navigation into a single vertical sidebar. This is a good fit for applications that emphasize content density or that follow a more traditional side-nav convention. + +### 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. +- **Content area:** The primary body of generated content or interactive data. +- **Footer:** A persistent input area, typically housing a `MessageBar` for conversational AI interactions. + +### 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. + +## 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 sidebar. 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. + +## 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. +- **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 (`