DO NOT MERGE (POC): Pf doc core issue 14

.yarnrc.yml

@@ -1 +1,3 @@
 nodeLinker: node-modules
+nmHostingLimits:
+  "@patternfly/patternfly-doc-core": "workspace"

package.json

@@ -10,14 +10,16 @@
     "develop": "yarn workspace patternfly-org develop",
     "develop:extensions": "EXTENSIONS_ONLY=true PRERELEASE=true yarn develop",
     "build:analyze": "yarn workspace patternfly-org build:analyze && yarn copy",
-    "build": "yarn workspace patternfly-org build && yarn copy",
     "build:extensions": "EXTENSIONS_ONLY=true PRERELEASE=true yarn build",
+    "build:next": "yarn workspace patternfly-org-next build",
+    "dev": "yarn workspace patternfly-org-next dev",
     "copy": "rm -rf build/patternfly-org/site && mkdir -p build/patternfly-org && cp -r packages/documentation-site/public build/patternfly-org/site",
     "clean": "lerna run clean && rm -rf build",
     "serve": "npx pf-docs-framework serve build/patternfly-org/site",
     "test": "yarn workspace patternfly-org test:a11y:ci",
     "screenshots": "yarn workspace patternfly-org screenshots",
     "start": "yarn develop",
+    "sync:next": "yarn workspace patternfly-org-next sync",
     "start:extensions": "yarn develop:extensions",
     "uninstall": "find . -name node_modules | xargs rm -rf",
     "workflows": "node .github/generate-workflows",
@@ -26,11 +28,16 @@
   "workspaces": {
     "packages": [
       "packages/*"
+    ],
+    "nohoist": [
+      "**/@patternfly/patternfly-doc-core",
+      "**/@patternfly/patternfly-doc-core/**"
     ]
   },
   "devDependencies": {
     "@octokit/rest": "^19.0.7",
     "@patternfly/patternfly": "^6.1.0",
+    "@patternfly/patternfly-doc-core": "^1.0.7",
     "@patternfly/react-code-editor": "^6.1.0",
     "@patternfly/react-core": "^6.1.0",
     "@patternfly/react-table": "^6.1.0",

packages/patternfly-org/.gitignore

@@ -0,0 +1,24 @@
+# build output
+dist/
+
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
+
+# jetbrains setting folder
+.idea/

packages/patternfly-org/README.md

@@ -0,0 +1,7 @@
+# Patternfly Org Next
+This is the next version of the Patternfly Org site. It is built using the patternfly doc core framewok.
+The patternfly doc core framework is based off of [Astro](https://astro.build) and Patternfly.
+
+## Getting Started
+To get started, clone the repo and run the following commands:
+```yarn dev```

packages/patternfly-org/astro.config.mjs

@@ -0,0 +1,5 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+
+// https://astro.build/config
+export default defineConfig({});

packages/patternfly-org/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "patternfly-org-next",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "patternfly-doc-core start",
+    "build": "patternfly-doc-core build",
+    "sync": "tsc --config tsconfig.scripts.json scripts/sync.ts",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@patternfly/patternfly-doc-core": "^1.0.7",
+    "astro": "^5.3.0",
+    "fs-extra": "^11.3.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11",
+    "typescript": "^5.8.2"
+  }
+}

packages/patternfly-org/pf-docs.config.mjs

@@ -0,0 +1,10 @@
+export const config = {
+    content: [
+        {
+            base: './src/content',
+            pattern: "**/*.md",
+            name: 'content'      
+        }
+    ],
+    outputDir: 'dist'
+};

packages/patternfly-org/scripts/sync.ts

@@ -0,0 +1,19 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+const sourceDir = path.join(__dirname, 'packages/documentation-core/src/content');
+const destDir = path.join(__dirname, 'packages/org/src/content');
+
+async function copyFiles() {
+  try {
+    await fs.ensureDir(destDir);
+    console.log(`Ensured that the destination directory exists: ${destDir}`);
+
+    await fs.copy(sourceDir, destDir);
+    console.log(`Successfully copied files from ${sourceDir} to ${destDir}`);
+  } catch (error) {
+    console.error('Error copying files:', error);
+  }
+}
+
+copyFiles();

packages/patternfly-org/src/content/PatternFly-AI/about-ai.md

@@ -0,0 +1,81 @@
+---
+id: About AI
+section: PatternFly-AI
+--- 
+
+**Artificial intelligence (AI)** is transforming experiences, enabling more personalized, efficient, and innovative digital interactions. When used thoughtfully and intentionally, AI can enhance the user experience of products designed with PatternFly. 
+
+To guide the use of AI in design practices, we have developed AI-driven design principles and guidelines that consider how:
+
+- The way that we design is just as important as what we design.
+- AI experiences can impact people in both desired and undesired ways.
+
+## AI principles 
+
+These design principles build an ethics-first framework and guide the use of AI with PatternFly. AI systems should be: 
+- Accountable. 
+- Explainable.
+- Transparent. 
+- Fair. 
+- Human-centered.
+
+### Accountable
+Clear responsibilities are defined for AI design, development, and deployment processes—including policies and the documentation of design decisions and processes​.
+
+Accountability includes:
+
+- **Accessible policies:** Company policies should be readily accessible to all team members.
+
+- **Legal compliance:** All necessary laws, regulations, and ethical guidelines must be followed throughout the development process.
+
+### Explainable
+AI systems are easy to explain and comprehend. Our users can understand who is making decisions and how these decisions are made.
+
+Explainability includes: 
+
+- **Understandable outcomes:** To build trust and help users make use of AI conclusions, clear explanations of how these conclusions are reached should be provided.
+
+### Transparent
+Processes, decisions, and practices involved in AI systems are transparent.
+
+Transparency includes: 
+
+- **Transparent processes and decisions:** To help users understand intentions and decision-making methods, design processes and decisions should be well documented.
+
+- **Data transparency:** Informed consent must be obtained to collect and use data. The ways that user data is collected, stored, and used should be shared.
+
+### Fair
+AI systems are inclusive, accessible, and do not amplify bias.
+
+Fairness includes: 
+
+- **Bias mitigation:** To prevent discriminatory outcomes, potential biases should be identified and reduced.
+
+- **Inclusive design:** To avoid systemic bias, designs should be inclusive and accommodating of various user demographics.
+
+- **Equal access:** Access to AI technologies should be available and beneficial to most users and communities.
+
+### Human-centered 
+AI systems are human-centered and focus on accessibility, transparency, and user empowerment. 
+
+Human-centered design considers:
+
+- **Value and need alignment:** AI systems should be aligned with user needs and values. They should be continuously refined based on user feedback and ethical considerations.
+
+- **Cultural sensitivity:** Cultural differences should be considered and respected.
+
+- **Data rights and control:** Users should have control over their data, including the ability to access, modify, and delete their information.
+
+- **Privacy protection:** Personally identifiable information must be protected and used responsibly.
+
+## Red Hat policies
+
+If you are using PatternFly to design Red Hat products, adhere to AI-related policies that Red Hat has previously outlined. 
+
+Currently, Red Hat:
+- Requires approval before using AI technology for business related to Red Hat.
+- Requires approval before certain information can be used as input for AI technology.
+- Requires review, testing, and validation of generative AI model output.
+- Provides a few exceptions to this policy.
+
+[View policy details (requires Red Hat login).](https://source.redhat.com/?signin&r=%2fdepartments%2flegal%2fglobal_legal_compliance%2fcompliance_folder%2fpolicy_on_the_use_of_ai_technologypdf)

packages/patternfly-org/src/content/PatternFly-AI/ai-design-guidelines.md

@@ -0,0 +1,57 @@
+---
+id: AI guidelines
+section: PatternFly-AI
+--- 
+
+import {Alert} from '@patternfly/react-core';
+
+<Alert variant="info" title="Data privacy" ouiaId="AIInfoAlert" >
+Always consider data privacy when entering company or personal information into AI resources, and ensure compliance with all company data protection policies and rules around AI usage.   
+</Alert>
+
+Before designing, developing, and using AI, consider the following ethical and best-practice guidelines.
+
+## Determine if AI adds value.
+
+Not all uses of AI are good for your UX strategy. To make sure that AI enhances the user experience, consider the following practices:
+
+- Identify real user needs to ensure that AI features will solve real issues to improve the user experience. 
+- Leverage AI to increase productivity and efficiency.
+- Personalize user experience with AI to make engagements more personal and relevant.
+- Make design processes more sustainable to save time, effort, and prepare for the future.
+
+For example, it would be valuable to add features like:
+- AI-driven search, to tailor search results to a user's unique needs. 
+- AI that helps streamline onboarding, data entry, or routine job tasks. 
+- AI that makes product recommendations based on a user's history. 
+
+It is not valuable to add AI features simply because they are new, trendy, or fun. They need to matter to the user.
+
+## Enhance human ability with AI: don't replace it.
+
+AI is best when it enhances human abilities, not when it's used to replace humans. It cannot exist in a silo&mdash;humans help bring the value of AI to life.
+
+To ensure that the design of AI systems is human-centered, follow these practices: 
+
+- Nurture collaboration and cross-team alignment.
+- Welcome multiple perspectives to encourage creativity and help mitigate bias. 
+- Check AI output for accuracy and identify areas where meaning is lost, language isn't inclusive, or information isn't true. Ask peers to review your AI-generated deliverables to help fact-check and catch mistakes.
+
+## Be transparent with users. 
+
+Transparency is essential for ethical AI usage. To help users understand and trust AI features: 
+
+- Tell users when AI is being used.
+- Make its capabilities and limitations clear to set appropriate expectations.
+- Explain how AI makes decisions.
+- Keep users in control and let them decide how they interact with AI.
+- Be clear and honest when AI fails or hallucinates.
+
+## Be prepared for something to go wrong. 
+
+Errors and failure are inevitable when working with AI, so it is essential that you are prepared to handle undesired outcomes. You should understand the risk involved in AI and the impact that an error may have. 
+
+To create a plan for issues, start by following these guidelines: 
+
+- When AI fails, be explicit about errors and let users regain control as they want.
+- Provide easy access to human support.

packages/patternfly-org/src/content/PatternFly-AI/conversation-design/conversation-design.md

@@ -0,0 +1,75 @@
+---
+id: Conversation design
+section: PatternFly-AI
+---
+
+import { Button, Flex, FlexItem } from '@patternfly/react-core';
+import ArrowRightIcon from '@patternfly/react-icons/dist/esm/icons/arrow-right-icon';
+
+
+# Conversation design guidelines
+
+**Conversation design** is a method of writing for conversational interfaces, like chatbots or voicebots. The goal of conversation design is to create an interactive experience that resembles human-to-human conversation as much as possible. Like traditional content design, conversation design is focused on using words to make experiences clear, concise, and well-timed.
+
+Good conversation design combines content strategy, writing, and design to ensure that the development and use of chatbots is centered on real user needs. This includes making sure that all text related to the conversational UI supports easy engagement with chatbots, while staying aligned with brand standards.
+
+When designing AI conversations alongside PatternFly-based projects, it is important to align with our established [brand voice and tone](/ux-writing/brand-voice-and-tone), as well as our [ethical guidelines for AI.](/patternfly-ai/ai-guidelines)
+
+## Best practices 
+
+Following these best practices to help ensure that your users can complete their goals through an AI-based conversation: 
+
+- Be transparent about AI use. 
+- Be direct, brief, and consistent. 
+- Frame questions in terms of value for the user.
+- If you ask for personal info, tell users "why" you're asking first. 
+- Always have the last word.
+
+## Writing for chatbots
+
+When chatbots are designed to meet the needs of your users, they can improve the overall UX of your product. They are convenient, efficient, and persistent. 
+
+[Our chatbot extension](/patternfly-ai/chatbot/about-chatbot) utilizes PatternFly components to create a foundation for an AI-based chatbot, with additional customization options.
+
+<Flex>
+<FlexItem>
+<Button component="a" href="/patternfly-ai/chatbot/about-chatbot" target="_blank" variant="primary" size="lg">Use the chatbot extension <ArrowRightIcon /></Button>
+</FlexItem>
+</Flex>
+
+Chatbots are only as good as the writing that goes into them. The language they use must build trust, clearly establish the “rules” of the conversation, and support users' goals. 
+
+In addition to general microcopy, like headings or buttons, you will need to write:
+- Welcome and goodbye messages. 
+- Bot prompts. 
+- AI disclosures.
+
+### Welcome and goodbye messages 
+
+It is important to always welcome users to the chatbot experience, and (if applicable) to say goodbye when they've ended the chat. A goodbye message isn't always necessary, like in instances where users can "minimize" a chat window to come back to it later. 
+
+When you know your user's name, address them directly. 
+
+![Chatbot welcome message with user's name](./img/chatbot-welcome.png)
+
+### Bot prompts 
+
+When writing your bot's prompts: 
+
+- Keep messages short and simple. Try to stick to 3 lines of text in a message and only send 3 messages at most before allowing a user to provide input. 
+- Be direct and limit choices for users as much as possible. 
+- Unlike traditional content design, *don't lead with the benefit.* End with the benefit to be sure that it's read and acted upon. Users should be able to complete an action solely based on a chatbot's last sentence. 
+- Frame any questions from the bot in terms of value for the user.
+- Provide examples when relevant.
+- Avoid open-ended questions. If you ask any, make them very simple, increase pause time between messages, and tell users when they should type. 
+- Utilize different methods of presenting information, like cards or buttons. You don't have to always use plain text in your messages; sometimes different message types can be more convenient and engaging.
+
+![Chatbot prompt examples](./img/chatbot-prompts.png)
+
+### AI disclosure 
+
+Make sure to disclose any use of AI in chatbots. Our users should be able to trust that we are honest and transparent with them as much as possible.
+
+- Use labels and other visual styling cues to clearly identify AI features. 
+- Add necessary legal disclosures where you can, like in the chatbot footer. 
+- Display an indicator when the bot is "thinking" or "typing," so that users know to expect feedback.