diff --git a/.yarnrc.yml b/.yarnrc.yml index 3186f3f079..9c99859f73 100644 --- a/.yarnrc.yml +++ b/.yarnrc.yml @@ -1 +1,8 @@ nodeLinker: node-modules +packageExtensions: + "@patternfly/patternfly-doc-core@*": + peerDependenciesMeta: + astro: + optional: true + "@patternfly/react-icons": + optional: true diff --git a/package.json b/package.json index 77cf8db8cc..f67cd80722 100644 --- a/package.json +++ b/package.json @@ -77,6 +77,7 @@ "@patternfly/react-code-editor": "^6.5.1", "@patternfly/react-core": "^6.5.1", "@patternfly/react-table": "^6.5.1", + "@project-felt/ai-guidelines": "github:project-felt/ai-guidelines", "monaco-editor": "0.54.0" } } diff --git a/packages/documentation-framework/scripts/cli/generate.js b/packages/documentation-framework/scripts/cli/generate.js index ed37138d78..bf67c48ecf 100644 --- a/packages/documentation-framework/scripts/cli/generate.js +++ b/packages/documentation-framework/scripts/cli/generate.js @@ -8,7 +8,7 @@ function getSource(options) { async function generate(options) { const start = new Date(); console.log('write source files to patternfly-docs/generated'); - const sourceMDWithOptions = (glob, source, ignore) => sourceMD(glob, source, ignore, options._name); + const sourceMDWithOptions = (glob, source, ignore, mdOptions) => sourceMD(glob, source, ignore, options._name, mdOptions); getSource(options)(sourceMDWithOptions, sourceProps, sourceFunctionDocs); await waitForProps(); processMD(); diff --git a/packages/documentation-framework/scripts/md/parseMD.js b/packages/documentation-framework/scripts/md/parseMD.js index 49967e5460..c2c3ed3807 100644 --- a/packages/documentation-framework/scripts/md/parseMD.js +++ b/packages/documentation-framework/scripts/md/parseMD.js @@ -25,10 +25,15 @@ const globs = { md: [], }; -function toReactComponent(mdFilePath, source, buildMode) { +function toReactComponent(mdFilePath, source, buildMode, { frontmatterDefaults, frontmatterMapping } = {}) { // vfiles allow for nicer error messages and have native `unified` support const vfile = toVfile.readSync(mdFilePath); + // Normalize void HTML elements to self-closing for MDX compatibility + const voidElements = 'area|base|br|col|embed|hr|img|input|link|meta|param|source|track|wbr'; + const voidTagRegex = new RegExp(`<(${voidElements})(\\s[^>]*?)\\s*(?`, 'g'); + vfile.contents = String(vfile.contents).replace(voidTagRegex, '<$1$2 />'); + const relPath = path.relative(path.join(process.cwd(), '../..'), vfile.path).split(path.sep).join(path.posix.sep); let jsx; @@ -47,6 +52,23 @@ function toReactComponent(mdFilePath, source, buildMode) { } frontmatter = yaml.load(yamlNode.value); + // Apply frontmatter mapping (e.g., { title: "id" } maps title -> id) + if (frontmatterMapping) { + Object.entries(frontmatterMapping).forEach(([fromKey, toKey]) => { + if (frontmatter[fromKey] !== undefined && frontmatter[toKey] === undefined) { + frontmatter[toKey] = frontmatter[fromKey]; + } + }); + } + // Apply frontmatter defaults (e.g., { section: "AI" }) + if (frontmatterDefaults) { + Object.entries(frontmatterDefaults).forEach(([key, value]) => { + if (frontmatter[key] === undefined) { + frontmatter[key] = value; + } + }); + } + // Fail early if (!frontmatter.id) { file.fail('id attribute is required in frontmatter for PatternFly docs'); @@ -276,7 +298,7 @@ async function sourcePropsFile(file) { }); } -function sourceMDFile(file, source, buildMode) { +function sourceMDFile(file, source, buildMode, options) { if (path.basename(file).startsWith('_')) { return; } @@ -285,7 +307,7 @@ function sourceMDFile(file, source, buildMode) { if (source === 'design-guidelines' && file.includes('/accessibility/')) { return; } - const { jsx, pageData, outPath } = toReactComponent(file, source, buildMode); + const { jsx, pageData, outPath } = toReactComponent(file, source, buildMode, options); if (jsx) { fs.outputFileSync(outPath, jsx); @@ -352,12 +374,12 @@ module.exports = { async waitForProps() { await Promise.all(pendingProps); }, - sourceMD(glob, source, ignore, buildMode) { - globs.md.push({ glob, source, ignore, buildMode }); + sourceMD(glob, source, ignore, buildMode, options) { + globs.md.push({ glob, source, ignore, buildMode, options }); }, processMD() { - globs.md.forEach(({ glob, source, ignore, buildMode }) => { - globSync(glob, { ignore }).forEach(file => sourceMDFile(file, source, buildMode)); + globs.md.forEach(({ glob, source, ignore, buildMode, options }) => { + globSync(glob, { ignore }).forEach(file => sourceMDFile(file, source, buildMode, options)); }); }, sourceFunctionDocs, @@ -373,10 +395,10 @@ module.exports = { propWatcher.on('add', onPropFile); propWatcher.on('change', onPropFile); }); - globs.md.forEach(({ glob, source, ignore }) => { + globs.md.forEach(({ glob, source, ignore, options }) => { const mdWatcher = chokidar.watch(globSync(glob, { ignored: ignore, ignoreInitial: true })); function onMDFileChange(file) { - sourceMDFile(file, source, 'start'); + sourceMDFile(file, source, 'start', options); writeIndex(); } mdWatcher.on('add', onMDFileChange); diff --git a/packages/documentation-framework/scripts/md/styled-tags.js b/packages/documentation-framework/scripts/md/styled-tags.js index 015eff8ebd..07d2e4cc57 100644 --- a/packages/documentation-framework/scripts/md/styled-tags.js +++ b/packages/documentation-framework/scripts/md/styled-tags.js @@ -22,13 +22,35 @@ const styledMdTags = [ function styledTags() { return tree => { - visit(tree, 'element', node => { + visit(tree, 'element', (node, index, parent) => { node.properties.className = node.properties.className || ''; - - if (contentStyledMdTags.includes(node.tagName)) { + + const hasDataType = node.properties && (node.properties.dataType || node.properties['data-type']); + const parentHasDataType = parent && parent.properties && (parent.properties.dataType || parent.properties['data-type']); + if (contentStyledMdTags.includes(node.tagName) && !hasDataType && !parentHasDataType) { node.properties.className += `pf-v6-c-content--${node.tagName} pf-m-editorial`; } + // GitHub-style admonitions: > [!NOTE], > [!TIP], > [!WARNING], etc. + if (node.tagName === 'blockquote') { + const firstP = node.children && node.children.find(c => c.tagName === 'p'); + if (firstP && firstP.children) { + const firstText = firstP.children.find(c => c.type === 'text'); + if (firstText) { + const match = firstText.value.match(/^\[!(NOTE|TIP|WARNING|IMPORTANT|CAUTION)\]\s*/i); + if (match) { + const type = match[1].toLowerCase(); + node.properties['data-admonition'] = type; + node.properties.className += ` ws-admonition ws-admonition-${type}`; + firstText.value = firstText.value.slice(match[0].length); + if (!firstText.value.trim() && firstP.children.length === 1) { + node.children = node.children.filter(c => c !== firstP); + } + } + } + } + } + if (styledMdTags.includes(node.tagName)) { node.properties.className += node.properties.className ? ' ' : ''; node.properties.className += `ws-${node.tagName} `; diff --git a/packages/documentation-framework/templates/content-sources/ai-guidelines.css b/packages/documentation-framework/templates/content-sources/ai-guidelines.css new file mode 100644 index 0000000000..8306a45a4e --- /dev/null +++ b/packages/documentation-framework/templates/content-sources/ai-guidelines.css @@ -0,0 +1,154 @@ +/* Styles for @project-felt/ai-guidelines content */ + +/* Figure base styles */ +[data-content-source="ai-guidelines"] figure[data-type] { + margin: var(--pf-t--global--spacer--lg) 0; + padding: var(--pf-t--global--spacer--md); + border: 1px solid var(--pf-t--global--border--color--default); + border-radius: var(--pf-t--global--border--radius--small); + text-align: center; + max-width: 700px; + margin-inline: auto; + width: 100%; +} + +[data-content-source="ai-guidelines"] figure[data-type="example landscape"] { + max-width: 100%; +} + +[data-content-source="ai-guidelines"] figure[data-type] img { + max-width: 100%; + height: auto; +} + +[data-content-source="ai-guidelines"] figure[data-type] figcaption { + margin-top: var(--pf-t--global--spacer--sm); + font-size: var(--pf-t--global--font--size--sm); + color: var(--pf-t--global--text--color--subtle); + text-align: left; +} + +/* Inline icons in lists and paragraphs */ +[data-content-source="ai-guidelines"] li img, +[data-content-source="ai-guidelines"] p img { + height: 1em; + width: auto; + max-width: none; + vertical-align: middle; +} + +/* Do examples — green accent */ +[data-content-source="ai-guidelines"] figure[data-type="do"] { + border-color: var(--pf-t--global--color--status--success--default); + border-left-width: 4px; +} + +[data-content-source="ai-guidelines"] figure[data-type="do"]::before { + content: "Do"; + display: block; + text-align: left; + font-weight: var(--pf-t--global--font--weight--body--bold); + color: var(--pf-t--global--color--status--success--default); + margin-bottom: var(--pf-t--global--spacer--sm); +} + +/* Don't examples — red accent */ +[data-content-source="ai-guidelines"] figure[data-type="dont"] { + border-color: var(--pf-t--global--color--status--danger--default); + border-left-width: 4px; +} + +[data-content-source="ai-guidelines"] figure[data-type="dont"]::before { + content: "Don't"; + display: block; + text-align: left; + font-weight: var(--pf-t--global--font--weight--body--bold); + color: var(--pf-t--global--color--status--danger--default); + margin-bottom: var(--pf-t--global--spacer--sm); +} + +/* Figure groups */ +[data-content-source="ai-guidelines"] ul[data-type] { + list-style: none; + padding: 0; + margin: var(--pf-t--global--spacer--lg) 0; + display: grid; + gap: var(--pf-t--global--spacer--md); +} + +[data-content-source="ai-guidelines"] ul[data-type="dos-donts"] { + grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); +} + +[data-content-source="ai-guidelines"] ul[data-type="examples"] { + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); +} + +[data-content-source="ai-guidelines"] ul[data-type] > li { + list-style: none; + padding: 0; + margin: 0; +} + +[data-content-source="ai-guidelines"] ul[data-type] > li > figure[data-type] { + margin: 0; + height: 100%; +} + +/* GitHub-style admonitions */ +[data-content-source="ai-guidelines"] .ws-admonition { + border-left-width: 4px; + padding: var(--pf-t--global--spacer--md); + margin: var(--pf-t--global--spacer--md) 0; +} + +[data-content-source="ai-guidelines"] .ws-admonition::before { + display: block; + font-weight: var(--pf-t--global--font--weight--body--bold); + margin-bottom: var(--pf-t--global--spacer--xs); +} + +[data-content-source="ai-guidelines"] .ws-admonition-note { + border-left-color: var(--pf-t--global--color--status--info--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-note::before { + content: "Note"; + color: var(--pf-t--global--color--status--info--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-tip { + border-left-color: var(--pf-t--global--color--status--success--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-tip::before { + content: "Tip"; + color: var(--pf-t--global--color--status--success--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-warning { + border-left-color: var(--pf-t--global--color--status--warning--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-warning::before { + content: "Warning"; + color: var(--pf-t--global--color--status--warning--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-important { + border-left-color: var(--pf-t--global--color--status--danger--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-important::before { + content: "Important"; + color: var(--pf-t--global--color--status--danger--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-caution { + border-left-color: var(--pf-t--global--color--status--warning--default); +} + +[data-content-source="ai-guidelines"] .ws-admonition-caution::before { + content: "Caution"; + color: var(--pf-t--global--color--status--warning--default); +} diff --git a/packages/documentation-framework/templates/mdx.css b/packages/documentation-framework/templates/mdx.css index 097de563e6..2f40c92233 100644 --- a/packages/documentation-framework/templates/mdx.css +++ b/packages/documentation-framework/templates/mdx.css @@ -1,3 +1,5 @@ +@import './content-sources/ai-guidelines.css'; + p.pf-v6-c-content--p.ws-p { margin: 0; } diff --git a/packages/documentation-framework/templates/mdx.js b/packages/documentation-framework/templates/mdx.js index 108691086a..97d269d6c6 100644 --- a/packages/documentation-framework/templates/mdx.js +++ b/packages/documentation-framework/templates/mdx.js @@ -109,7 +109,7 @@ const MDXChildTemplate = ({ Component, source, toc = [], index = 0, id }) => { ); // Create dynamic component for @reach/router const ChildComponent = () => ( -
+
{toc.length > 1 && } {InlineAlerts} diff --git a/packages/documentation-site/patternfly-docs/content/AI/ai.md b/packages/documentation-site/patternfly-docs/content/AI/ai.md index 3f158aed86..5841beac11 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/ai.md +++ b/packages/documentation-site/patternfly-docs/content/AI/ai.md @@ -7,22 +7,67 @@ sortValue: 1 import { Alert, AlertActionLink, Accordion, AccordionItem, AccordionContent, AccordionToggle, Button, Card, CardHeader, CardTitle, CardBody, CardFooter, Checkbox, Divider, DescriptionList, DescriptionListTerm, DescriptionListGroup, DescriptionListDescription, Grid, GridItem} from '@patternfly/react-core'; import ExternalLinkSquareAltIcon from '@patternfly/react-icons/dist/esm/icons/external-link-square-alt-icon'; import DownloadIcon from '@patternfly/react-icons/dist/esm/icons/download-icon'; +import { Icon } from '@patternfly/react-core'; +import RhUiAiCreateIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-create-icon'; +import RhUiAiEditIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-edit-icon'; +import RhUiAiEnhanceIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-enhance-icon'; +import RhUiAiErrorIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-error-icon'; +import RhUiAiExperienceFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-experience-fill-icon'; +import RhUiAiExperienceIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-experience-icon'; +import RhUiAiFilterIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-filter-icon'; +import RhUiAiInfoIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-info-icon'; +import RhUiAiSearchIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-search-icon'; +import RhUiAiTroubleshootIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-troubleshoot-icon'; When used thoughtfully, **AI** can enhance user experiences through personalized interactions, increased efficiency, and innovative designs. Regardless of the AI resources or workflows you use, it's important to ensure that you're aligned with the compliance rules, ethical considerations, and best practices on this page. ## PatternFly AI resources -The following guides are intended to help you integrate AI into your workflows as you design and develop products with: +### Guidelines -- **[Design language](/ai/design-language):** The foundational design decisions that guide the use of AI features in products. -- **[Rapid prototyping](/ai/rapid-prototyping):** Guidance for generating and iterating AI features during early stages of design. -- **[Marketplace](/ai/marketplace):** Plugins that give AI coding assistants knowledge and skills to generate more accurate, PatternFly-compliant code. -- **[AI-assisted code migration](/ai/ai-assisted-code-migration):** Guidance for using AI to speed up and simplify codebase migrations. -- **[Conversational design principles](/ai/conversation-design):** Guidance for designing effective and human-centered AI conversations. +- **[Transparency notices](/ai/guidelines/transparency-notices):** Guidelines for communicating AI usage to users through visual and verbal indicators. +- **[Iconography](/ai/guidelines/iconography):** Guidelines for using AI-related icons, sparkles, and visual representations. +- **[Color](/ai/guidelines/color):** Color usage guidelines for AI-enabled features. +- **[Chatbot avatars](/ai/guidelines/chatbot-avatars):** Guidelines for chatbot avatar design, robot icons, and launch buttons. +- **[Animation](/ai/guidelines/animation):** Guidelines for AI-related animations and sparkle effects. +- **[Conversation design](/ai/guidelines/conversation-design):** Guidance for designing effective and human-centered AI conversations. + +### AI-assisted development + +- **[Marketplace](/ai/ai-assisted-development/marketplace):** Plugins that give AI coding assistants knowledge and skills to generate more accurate, PatternFly-compliant code. +- **[PatternFly CLI](/ai/ai-assisted-development/patternfly-cli):** A command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. +- **[PatternFly MCP](/ai/ai-assisted-development/patternfly-mcp):** An MCP server that gives AI coding tools PatternFly knowledge and capabilities. +- **[Rapid prototyping](/ai/ai-assisted-development/rapid-prototyping):** Guidance for generating and iterating AI features during early stages of design. +- **[AI-assisted code migration](/ai/ai-assisted-development/ai-assisted-code-migration):** Guidance for using AI to speed up and simplify codebase migrations. - **[Compass layout (org demos)](/components/compass/org-demos):** Full-page Compass layout examples for generative UI patterns. For React Flow integration, see the [React Flow guide](/developer-guides/react-flow). --- +## Using AI icons in React + +The following AI icons are available in the [@patternfly/react-icons](https://www.npmjs.com/package/@patternfly/react-icons) package. For detailed usage guidelines, see [Iconography](/ai/guidelines/iconography). + +| **Icon** | **React** | **Text label** | **Usage** | +| :---: | --- | --- | --- | +| | RhUiAiExperienceIcon | | General AI identification, or when no other AI icon is appropriate. | +| | RhUiAiExperienceFillIcon | | General AI identification, or when no other AI icon is appropriate. | +| | RhUiAiCreateIcon | "Create with AI" | Create something new with the help of AI. | +| | RhUiAiEditIcon | "Edit with AI" | Edit something with the help of AI. Typically used for editing text. | +| | RhUiAiEnhanceIcon | "Enhance with AI" | Enhance something with AI. | +| | RhUiAiErrorIcon | "Error found by AI" | A problem has been identified by AI. | +| | RhUiAiFilterIcon | "Filter with AI" | Filter data with the help of AI. | +| | RhUiAiInfoIcon | "Information by AI" | Information partially or completely generated by AI. | +| | RhUiAiSearchIcon | "Search with AI" | Search with the help of AI. | +| | RhUiAiTroubleshootIcon | "Troubleshoot with AI" | Receive help from AI when troubleshooting issues. | + +In Figma, these icons are available in the PatternFly components library via the Red Hat brand library. Using the icon wrapper component, you can swap the icons in the instance menu: + +
+![Menu in Figma showing how to switch between PatternFly and Red Hat icon libraries](./img/rh-icons-figma.png) +
+ +--- + ## What rules and best practices do I need to follow? All AI systems built with PatternFly must adhere to Red Hat's legal and ethical framework. diff --git a/packages/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md b/packages/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md index c24667e738..c52383c157 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md +++ b/packages/documentation-site/patternfly-docs/content/AI/conversation-design/conversation-design.md @@ -1,6 +1,7 @@ --- id: Conversation design section: AI +subsection: Guidelines --- import { Button, Flex, FlexItem} from '@patternfly/react-core'; diff --git a/packages/documentation-site/patternfly-docs/content/AI/design-language.md b/packages/documentation-site/patternfly-docs/content/AI/design-language.md deleted file mode 100644 index 39d0e03a83..0000000000 --- a/packages/documentation-site/patternfly-docs/content/AI/design-language.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -id: Design language -section: AI -sortValue: 2 ---- - -import { Icon } from '@patternfly/react-core'; -import RhUiAiCreateIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-create-icon'; -import RhUiAiEditIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-edit-icon'; -import RhUiAiEnhanceIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-enhance-icon'; -import RhUiAiErrorIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-error-icon'; -import RhUiAiExperienceFillIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-experience-fill-icon'; -import RhUiAiExperienceIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-experience-icon'; -import RhUiAiFilterIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-filter-icon'; -import RhUiAiInfoIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-info-icon'; -import RhUiAiSearchIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-search-icon'; -import RhUiAiTroubleshootIcon from '@patternfly/react-icons/dist/esm/icons/rh-ui-ai-troubleshoot-icon'; -import '../components/components.css'; - -This guide outlines the design language that should guide the implementation and communication of AI-enabled features at Red Hat, inlcuding common design patterns to follow in your UIs. Many of the linked resources require a Red Hat login. - -## Core principles - -1. **Be transparent:** Users want to know when they are interacting with AI, so use clear labels and visual cues. -2. **Make AI personable, but not human:** While AI should use a human-like voice and tone, it should never act as if it is a person. -3. **Stay within brand rules:** Adhere to [Red Hat brand standards](http://brand.redhat.com) and guidelines from both PatternFly and the [Red Hat design system ](http://ux.redhat.com). -4. **Complete internal reviews:** Follow all other required guidance and assessments for your products, such as an [AI Assessment (AIA)](https://source.redhat.com/departments/it/it_information_security/data_privacy/aia~2) or Privacy Impact Assessment. - -## AI disclosure - -Ensure that AI is clearly marked in multiple ways, including at least 1 visual and 1 text indicator. For example, an AI-generated search feature should be indicated with an AI-search icon and a "Search with AI" text label. Higher-risk interactions benefit from additional indicators, like a text notice placed at the beginning of an experience. Consult with the AIA Reviewers during your AIA review process as needed. - -
-![PatternFly token layer names for the same color value](./img/ai-icons-examples.svg) -
- -To avoid adding more distraction to an experience, **do not** label AI-generated images or ads individually. Instead, consider implementing a site-wide notice that outlines when users will (and won’t) encounter AI-generated images. - -Disclose any use of AI in chatbots, as outlined in our [ChatBot design guidelines](/extensions/chatbot/overview/design-guidelines). - -For more Red Hat-specific guidance AI disclosure, [refer to this guidance for tranparency notices in externally facing AI features (Red Had login required)](https://docs.google.com/document/d/1eVk8pMiSTqjfQSwU_h21BBXJ5PN8jbSLcU0wBtUt7bs/edit?tab=t.0#heading=h.dyq1r89dkf3e). - -## Color - -**Do not** use unique colors or gradients to indicate AI features. - -To ensure accessibility and proper status communication, AI-related icons and elements should still use standard [PatternFly colors](/foundations-and-styles/color). For example, AI-action buttons should use the appropriate color token that aligns with the button variant, like primary, secondary, and so on. - -## Iconography - -AI is represented by a sparkle icon, which is a diamond shape with concave sides. When the sparkle icon is added to the upper-left of another icon, it indicates an ai-enabled action or an action with an ai-generated result. For example, a sparkle placed beside a pencil icon indicates that a user can generate text with AI. - -AI icons **must** also be paired with a button label or tooltip text that says "[ Action ] with AI" or "[ Action ] by AI" to ensure there are multiple indicators that AI is being used. You can adapt this text label between tenses as appropriate. For example, "Search with AI" or "Search results generated by AI." - -The following AI-enabled icons are available for use: - -| **Icon** | **Name** | **React** | **Text label** | **Usage** | -| :---: | --- | --- | --- | --- | -| | rh-ui-ai-experience-icon | RhUiAiExperienceIcon | | Use for general AI identification or when no other AI icon is appropriate. | -| | rh-ui-ai-experience-fill-icon | RhUiAiExperienceFillIcon | | Use for general AI identification or when no other AI icon is appropriate. | -| | rh-ui-ai-create-icon | RhUiAiCreateIcon | "Create with AI" | Create something new with the help of AI. | -| | rh-ui-ai-edit-icon | RhUiAiEditIcon | "Edit with AI" | Use to edit something with the help of AI. Typically used for editing text. | -| | rh-ui-ai-enhance-icon | RhUiAiEnhanceIcon | "Enhance with AI" | Use AI to enhance something. | -| | rh-ui-ai-error-icon | RhUiAiErrorIcon | "Error found by AI" | Use when a problem has been identified by AI. | -| | rh-ui-ai-filter-icon | RhUiAiFilterIcon | "Filter with AI" | Use to filter data with the help of AI. | -| | rh-ui-ai-info-icon | RhUiAiInfoIcon | "Information by AI" | Use when provided information is partially or completely generated by AI.| -| | rh-ui-ai-search-icon | RhUiAiSearchIcon | "Search with AI" | Use to search for something with the help of AI. | -| | rh-ui-ai-troubleshoot-icon | RhUiAiTroubleshootIcon | "Troubleshoot with AI" | Use to receive help from AI when troubleshooting issues. | - -Like the rest of PatternFly's icons, these AI icons are available within the [@patternfly/react-icons package](https://www.npmjs.com/package/@patternfly/react-icons/v/6.4.0?activeTab=versions). - -In Figma, these icons are available in the PatternFly components library via the Red Hat brand library. Using the icon wrapper component you can swap the icons in the instance menu: - -
-![Menu in Figma showing how to switch between PatternFly and Red Hat icon libraries](./img/rh-icons-figma.png) -
- -### Icon usage guidelines - -- **Do not** use AI icons alongside information that was not generated by AI. Use the standard UI icon instead. -- **Do not** create new AI icons on your own. If you need a new icon, send a request via the [help-brand Slack channel](https://redhat.enterprise.slack.com/archives/C06D5Q0LZ6G) (Red Hat only). -- **Do not** change the colors of AI icons. -- **Do not** communicate the use of AI through icons alone. Ensure they are also paired with a text label or tooltip. -- **Do not** use the AI sparkle to label something as "new." Use rh-ui-icon-new instead. -- **Do not** use brains or robots to represent AI features. The existing brain UI icon represents learning and education. The robot icon should only be used for chatbot avatars (as described in the [robot icon guidelines](#robot-icon)). - -### Robot icon - -To align with user expectations of chat experiences, we offer a robot icon for use with chatbots that are created via our [ChatBot extension](/extensions/chatbot/overview). - -- **Do not** use other icons or robot images as your avatar. -- **Do not** use robot icons in place of the sparkle icon. -- **Do not** represent humans with the robot icons. - -There are 2 variants of the robot icon available within the Red Hat brand library in Figma, each with different uses: - -#### Standard icon - -The standard robot icon is intended to be used as an avatar in chatbot conversations. Because avatars have personality and don't have interactive state changes, there are a few background color options available. - -**Do not** use the standard robot icon for chatbot launch buttons. Instead, use the UI icon. - -
-![Variety of different color options for the robot avatar, which is a small circle.](./img/robot-avatar.svg) -
- -#### UI icon - -The UI robot icon is intended to be used within UI elements that launch chatbots, including buttons, menu toggles, and other access points. - -Because there are more specific accessibility and usability practices for UI elements to follow, there are no "emotion" variants for the UI robot icon. - -- **Do not** use the robot icon in place of the sparkle icon for other kinds of AI experiences. -- **Do not** use custom colors, gradients, or shadows with the UI icon. - -
-![A robot icon used in buttons and controls.](./img/ui-robot-icon.svg) -
\ No newline at end of file diff --git a/packages/documentation-site/patternfly-docs/content/AI/img/ai-icons-examples.svg b/packages/documentation-site/patternfly-docs/content/AI/img/ai-icons-examples.svg deleted file mode 100644 index 003048ea4b..0000000000 --- a/packages/documentation-site/patternfly-docs/content/AI/img/ai-icons-examples.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/packages/documentation-site/patternfly-docs/content/AI/img/robot-avatar.svg b/packages/documentation-site/patternfly-docs/content/AI/img/robot-avatar.svg deleted file mode 100644 index d32612a4dc..0000000000 --- a/packages/documentation-site/patternfly-docs/content/AI/img/robot-avatar.svg +++ /dev/null @@ -1,305 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/packages/documentation-site/patternfly-docs/content/AI/img/ui-robot-icon.svg b/packages/documentation-site/patternfly-docs/content/AI/img/ui-robot-icon.svg deleted file mode 100644 index 86a539990f..0000000000 --- a/packages/documentation-site/patternfly-docs/content/AI/img/ui-robot-icon.svg +++ /dev/null @@ -1,34 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/packages/documentation-site/patternfly-docs/content/AI/marketplace/marketplace.md b/packages/documentation-site/patternfly-docs/content/AI/marketplace/marketplace.md index 047dfc4118..a2d74764e6 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/marketplace/marketplace.md +++ b/packages/documentation-site/patternfly-docs/content/AI/marketplace/marketplace.md @@ -1,6 +1,7 @@ --- id: Marketplace section: AI +subsection: AI-assisted development sortValue: 3 --- diff --git a/packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md b/packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md index e87d393532..7890a0fbd3 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md +++ b/packages/documentation-site/patternfly-docs/content/AI/patternfly-cli.md @@ -2,6 +2,7 @@ id: PatternFly CLI title: PatternFly CLI section: AI +subsection: AI-assisted development --- The [PatternFly CLI](https://github.com/patternfly/patternfly-cli) is a command-line tool for scaffolding projects, performing code modifications, and running project-related tasks. It streamlines everyday development work and PatternFly upgrades, making it convenient and easy to work straight from the terminal. You can run it in the terminal on its own, or use it from an AI-enabled editor (such as [Cursor](https://www.cursor.com/)) so coding agents can rely on the same predictable commands for scaffolding, updates, and git workflows. The published package is [`@patternfly/patternfly-cli` on npm](https://www.npmjs.com/package/@patternfly/patternfly-cli). diff --git a/packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md b/packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md index 37df4cb59a..55d68a9022 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md +++ b/packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md @@ -1,6 +1,7 @@ --- id: PatternFly MCP section: AI +subsection: AI-assisted development --- import '../components/components.css'; diff --git a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/enhancing-existing-projects.md b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/enhancing-existing-projects.md index fb044cb00d..0bece135bd 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/enhancing-existing-projects.md +++ b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/enhancing-existing-projects.md @@ -1,6 +1,7 @@ --- id: Rapid prototyping section: AI +subsection: AI-assisted development source: enhancing-existing-projects sortValue: 2 --- diff --git a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/migrating-to-patternfly.md b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/migrating-to-patternfly.md index ac8fe8c61e..35977fa5fb 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/migrating-to-patternfly.md +++ b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/migrating-to-patternfly.md @@ -1,6 +1,7 @@ --- id: AI-assisted code migration section: AI +subsection: AI-assisted development --- This guide explores a workflow that enables developers to leverage AI to accelerate code migrations, with best practices and recommendations to follow when replicating the process. diff --git a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/new-prototypes.md b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/new-prototypes.md index 80b02d2653..671fe88cd1 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/new-prototypes.md +++ b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/new-prototypes.md @@ -1,6 +1,7 @@ --- id: Rapid prototyping section: AI +subsection: AI-assisted development source: new-prototypes sortValue: 2 --- diff --git a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/rapid-prototyping.md b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/rapid-prototyping.md index d02384a248..f015349ed8 100644 --- a/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/rapid-prototyping.md +++ b/packages/documentation-site/patternfly-docs/content/AI/rapid-prototyping/rapid-prototyping.md @@ -1,6 +1,7 @@ --- id: Rapid prototyping section: AI +subsection: AI-assisted development source: about-rapid-prototyping --- diff --git a/packages/documentation-site/patternfly-docs/patternfly-docs.source.js b/packages/documentation-site/patternfly-docs/patternfly-docs.source.js index 3bfd619d90..4f7bde9743 100644 --- a/packages/documentation-site/patternfly-docs/patternfly-docs.source.js +++ b/packages/documentation-site/patternfly-docs/patternfly-docs.source.js @@ -22,6 +22,18 @@ module.exports = (sourceMD, sourceProps, sourceFunctionDocs) => { sourceMD(path.join(contentBase, 'AI/**/*.md'), 'AI'); + // AI guidelines from @project-felt/ai-guidelines + const aiGuidelinesPath = require + .resolve('@project-felt/ai-guidelines/package.json') + .replace('package.json', 'content'); + const guidelinesPageOptions = { + frontmatterMapping: { title: 'id', order: 'sortValue' }, + frontmatterDefaults: { section: 'AI', subsection: 'Guidelines' } + }; + ['transparency-notices', 'iconography', 'color', 'chatbot-avatars', 'animation'].forEach(name => { + sourceMD(path.join(aiGuidelinesPath, `${name}.md`), 'ai-guidelines', undefined, guidelinesPageOptions); + }); + sourceMD(path.join(contentBase, 'get-help/**/*.md'), 'get-help'); sourceMD(path.join(contentBase, 'get-involved/**/*.md'), 'get-involved'); diff --git a/packages/site/package.json b/packages/site/package.json index df6081b868..c95a8e0340 100644 --- a/packages/site/package.json +++ b/packages/site/package.json @@ -19,6 +19,7 @@ "dependencies": { "@patternfly/patternfly-doc-core": "^1.22.0", "@patternfly/react-icons": "^6.5.0-prerelease.29", + "@project-felt/ai-guidelines": "github:project-felt/ai-guidelines", "astro": "^5.18.0" }, "devDependencies": { diff --git a/packages/site/pf-docs.config.mjs b/packages/site/pf-docs.config.mjs index 8939b08dcb..5e5ba418d5 100644 --- a/packages/site/pf-docs.config.mjs +++ b/packages/site/pf-docs.config.mjs @@ -89,6 +89,13 @@ export const config = { base: "../../node_modules/@patternfly/chatbot", pattern: "patternfly-docs/**/*.{md,mdx}", name: "chatbot-docs", + }, + { + base: "../../node_modules/@project-felt/ai-guidelines", + pattern: "content/{transparency-notices,iconography,color,chatbot-avatars,animation}.md", + name: "ai-guidelines", + frontmatterDefaults: { section: "AI", subsection: "Guidelines" }, + frontmatterMapping: { title: "id", order: "sortValue" }, } ], navSectionOrder: [], diff --git a/yarn.lock b/yarn.lock index 6293826fea..939725724a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5862,6 +5862,13 @@ __metadata: languageName: node linkType: hard +"@project-felt/ai-guidelines@github:project-felt/ai-guidelines": + version: 1.0.0 + resolution: "@project-felt/ai-guidelines@https://github.com/project-felt/ai-guidelines.git#commit=e6936a0bac547dd063277394d0ec23fa4a0d03dc" + checksum: 10c0/112f2153804d3458ef5fd48512b8f9f371ef3ebcd62887429b730253650df246562761c8c5c183407de2e977eb4cdf3ff0e0efd9267f221d9c444c8bb1ed2a51 + languageName: node + linkType: hard + "@puppeteer/browsers@npm:2.13.0": version: 2.13.0 resolution: "@puppeteer/browsers@npm:2.13.0" @@ -21345,6 +21352,7 @@ __metadata: dependencies: "@patternfly/patternfly-doc-core": "npm:^1.22.0" "@patternfly/react-icons": "npm:^6.5.0-prerelease.29" + "@project-felt/ai-guidelines": "github:project-felt/ai-guidelines" astro: "npm:^5.18.0" tsx: "npm:^4.21.0" wrangler: "npm:^4.69.0"