nicolethoen · nicolethoen · Jul 1, 2025 · Jul 1, 2025
diff --git a/.cursor/rules/patternfly-vibe-coding.mdc b/.cursor/rules/patternfly-vibe-coding.mdc
@@ -13,8 +13,8 @@ This rule applies to all code generation, refactoring, and review tasks involvin
 
 ## Documentation to Reference
 - The root `README.md`
-- The `documentation/README.md` file, which serves as the table of contents for all documentation in the `documentation/` directory and its subdirectories. Use this file to discover and navigate all relevant rules, guidelines, and best practices for PatternFly development.
-- All markdown files referenced by `documentation/README.md`.
+- The `ai-documentation/README.md` file, which serves as the table of contents for all documentation in the `ai-documentation/` directory and its subdirectories. Use this file to discover and navigate all relevant rules, guidelines, and best practices for PatternFly development.
+- All markdown files referenced by `ai-documentation/README.md`.
 
 ## Rule
 - **Always consult the above documentation before generating or editing any PatternFly code.**

diff --git a/ai-documentation/charts/README.md b/ai-documentation/charts/README.md
@@ -15,6 +15,9 @@ npm install @patternfly/react-charts victory
 
 # ✅ ECharts-based charts (alternative)
 npm install @patternfly/react-charts echarts
+
+# ✅ Patternfly for charts css variables (recommended)
+npm install @patternfly/patternfly
 ```
 
 ### Import Rules
@@ -31,6 +34,12 @@ import { EChart } from '@patternfly/react-charts/echarts';
 import { ChartDonut } from '@patternfly/react-charts';
 ```
 
+### Import PatternFly Charts CSS
+   ```jsx
+   // In your main App.js or index.js
+   import '@patternfly/patternfly/patternfly-charts.css';
+   ```
+
 ### Critical Import Path Troubleshooting
 
 **⚠️ MOST COMMON ISSUE**: Chart components cannot be found
@@ -77,9 +86,9 @@ Module not found: Can't resolve '@patternfly/react-charts'
 ```jsx
 // ✅ Correct - Use PatternFly color tokens
 const chartColors = [
-  'var(--pf-v6-chart-color-blue-300)',
-  'var(--pf-v6-chart-color-green-300)',
-  'var(--pf-v6-chart-color-orange-300)'
+  'var(--pf-t--chart--color--blue--300)',
+  'var(--pf-t--chart--color--green--300)',
+  'var(--pf-t--chart--color--orange--300)'
 ];
 
 <ChartDonut data={data} colorScale={chartColors} />
@@ -210,6 +219,23 @@ const LazyChart = lazy(() => import('./HeavyChart'));
 - **Implement lazy loading**: For heavy chart components
 - **Optimize re-renders**: Use React.memo for chart components
 
+#### Issue: Chart colors not correct
+```bash
+# Symptoms: Chart color variables (--pf-v6-chart-color-blue-100, --pf-t--chart--color--blue--300) are not defined
+```
+
+**Solutions**:
+1. **Install patternfly package**:
+   ```bash
+   npm install @patternfly/patternfly
+   ```
+
+2. **Import PatternFly Charts CSS**:
+   ```jsx
+   // In your main App.js or index.js
+   import '@patternfly/patternfly/patternfly-charts.css';
+   ```
+
 ## Quick Reference
 - **[PatternFly Charts README](https://github.com/patternfly/patternfly-react/tree/main/packages/react-charts#readme)** - Installation and usage
 - **[Victory.js Documentation](https://formidable.com/open-source/victory/)** - Chart library documentation

diff --git a/ai-documentation/components/data-display/README.md b/ai-documentation/components/data-display/README.md
@@ -212,4 +212,11 @@ Key integration patterns from this example include:
 
 > **Note:** Always consult the latest PatternFly Data View documentation and demo source code for the most up-to-date usage patterns and best practices.
 - [PatternFly React Data View GitHub](https://github.com/patternfly/react-data-view)
-- [PatternFly Data View NPM](https://www.npmjs.com/package/@patternfly/react-data-view)
+- [PatternFly Data View NPM](https://www.npmjs.com/package/@patternfly/react-data-view)
+
+## Empty State Button Placement Rules
+
+- ✅ **Place all buttons in an EmptyState inside the `EmptyStateFooter` component.**
+- ✅ **Group each row of buttons within an `EmptyStateActions` container inside the `EmptyStateFooter`.**
+- ✅ **Use a separate `EmptyStateActions` for each row of actions if multiple rows are needed.**
+- ❌ **Do not place buttons directly inside `EmptyState` or `EmptyStateBody`.**
diff --git a/ai-documentation/guidelines/README.md b/ai-documentation/guidelines/README.md
@@ -22,6 +22,9 @@ Core development rules for AI coders building PatternFly React applications.
 - ✅ **Compose components** - Build complex UIs by combining PatternFly components
 - ❌ **Don't override component internals** - Use provided props and APIs
 
+### Tokenss
+- ✅ **ALWAYS use PatternFly tokens** - Use `pf-t-` prefixed classes over `pf-v6-` classes (e.g., `var(--pf-t--global--spacer--sm)` not `var(--pf-v6-global--spacer--sm)`)
+
 ### Text Components (v6+)
 ```jsx
 // ✅ Correct
@@ -43,7 +46,7 @@ import { UserIcon } from '@patternfly/react-icons';
 ### Styling Rules
 
 - ✅ **Use PatternFly utilities** - Before writing custom CSS
-- ✅ **Use semantic design tokens** for custom CSS (e.g., `var(--pf-v6-global--primary-color--light)`), not base tokens with numbers (e.g., `--pf-v6-global--Color--100`) or hardcoded values
+- ✅ **Use semantic design tokens** for custom CSS (e.g., `var(--pf-t--global--text--color--regular)`), not base tokens with numbers (e.g., `--pf-t--global--text--color--100`) or hardcoded values
 - ❌ **Don't mix PatternFly versions** - Stick to v6 throughout
 
 ### Documentation Requirements

diff --git a/ai-documentation/guidelines/styling-standards.md b/ai-documentation/guidelines/styling-standards.md
@@ -11,16 +11,17 @@ Essential CSS and styling rules for PatternFly React applications.
 
 ### PatternFly v6 Requirements
 - ✅ **ALWAYS use `pf-v6-` prefix** - All PatternFly v6 classes
-- ❌ **NEVER use legacy prefixes** - No `pf-v5-`, `pf-v4-`, or `pf-c-`
+- ❌ **NEVER use legacy prefixes** - No `pf-v5-`, `pf-v4-`, `pf-u` or `pf-c-`
 
 ```css
 /* ✅ Correct v6 classes */
 .pf-v6-c-button          /* Components */
-.pf-v6-u-margin-md       /* Utilities */
+.pf-v6-u-m-md            /* Utilities */
 .pf-v6-l-grid            /* Layouts */
 
 /* ❌ Wrong - Don't use these */
 .pf-v5-c-button
+.pf-u-m-md
 .pf-c-button
 ```
 
@@ -39,8 +40,8 @@ Essential CSS and styling rules for PatternFly React applications.
 </PageSection>
 
 // ❌ Wrong - Utility classes for basic layout
-<div className="pf-v6-u-margin-md">
-  <div className="pf-v6-u-margin-bottom-sm">Dashboard</div>
+<div className="pf-v6-u-m-md">
+  <div className="pf-v6-u-mb-sm">Dashboard</div>
   <div>Dashboard content</div>
 </div>
 ```
@@ -62,8 +63,8 @@ Essential CSS and styling rules for PatternFly React applications.
 </ActionGroup>
 
 // ❌ Wrong - Utility classes when component props exist
-<Table className="pf-v6-u-margin-md">
-  <Button className="pf-v6-u-margin-right-sm">Save</Button>
+<Table className="pf-v6-u-m-md">
+  <Button className="pf-v6-u-mr-sm">Save</Button>
   <Button>Cancel</Button>
 </Table>
 ```
@@ -104,7 +105,7 @@ Use utility classes only when:
 
 ```jsx
 // ✅ Acceptable utility usage - when component props aren't sufficient
-<Card className="pf-v6-u-height-100"> {/* Force card to full height */}
+<Card className="pf-v6-u-h-100"> {/* Force card to full height */}
   <CardBody>
     <Text className="pf-v6-u-text-align-center"> {/* Center text when component doesn't provide prop */}
       Centered content
@@ -116,35 +117,35 @@ Use utility classes only when:
 ## Design Token Rules
 
 ### Use Semantic PatternFly Tokens for Custom CSS
-- ✅ **Use semantic tokens** (e.g., `--pf-v6-global--primary-color--light`) for custom CSS. These tokens do not end in numbers and are intended for application-level styling.
-- ❌ **Don't use base tokens** (which end in numbers, e.g., `--pf-v6-global--Color--100`) for custom CSS. Base tokens are for internal PatternFly use and may change.
+- ✅ **Use semantic tokens** (e.g., `--pf-t--global--text--color--regular`) for custom CSS. These tokens do not end in numbers and are intended for application-level styling.
+- ❌ **Don't use base tokens** (which end in numbers, e.g., `--pf-t--global--text--color--100`) for custom CSS. Base tokens are for internal PatternFly use and may change.
 
 ```css
 .custom-component {
   /* ✅ Correct - Use semantic tokens */
-  color: var(--pf-v6-global--primary-color--light);
-  margin: var(--pf-v6-global--spacer--md);
+  color: var(--pf-t--global--text--color--regular);
+  margin: var(--pf-t-global--spacer--md);
 
   /* ❌ Wrong - Hardcoded values or base tokens */
   /* color: #333333; */
-  /* color: var(--pf-v6-global--Color--100); */
+  /* color: var`--pf-t--global--text--color--100); */
   /* margin: 16px; */
 }
 ```
 
 ### Essential Token Categories
 ```css
 /* Semantic Colors */
---pf-v6-global--primary-color--light
---pf-v6-global--primary-color--dark
---pf-v6-global--background-color--light
+--pf-t--global--text--color--regular
+--pf-t--global--text--color--subtle
+--pf-t--global--background--color--primary--default
 
 /* Spacing */
---pf-v6-global--spacer--{xs|sm|md|lg|xl}
+--pf-t-global--spacer--{xs|sm|md|lg|xl}
 
 /* Typography */
---pf-v6-global--FontFamily--text
---pf-v6-global--FontSize--md
+--pf-t--global--font--family--body	
+--pf-t--global--font--size--md	
 ```
 
 ## Responsive Design Rules
@@ -324,4 +325,95 @@ import { Title, Content } from '@patternfly/react-core';
 
 ---
 
-> **Note:** `PageHeader` is not a PatternFly component in v6+. Use `PageSection`, `Title`, and layout components instead.
+> **Note:** `PageHeader` is not a PatternFly component in v6+. Use `PageSection`, `Title`, and layout components instead.
+
+## Spacing and Inline Styles
+
+- ✅ **Always use PatternFly spacing variables (design tokens) for all spacing, including in inline style props.**
+- ❌ **Do not use hardcoded numbers for margin, padding, or other spacing in inline styles.**
+
+**Correct:**
+```jsx
+<div style={{ marginBottom: 'var(--pf-t--global--spacer-lg)' }} />
+```
+
+**Incorrect:**
+```jsx
+<div style={{ marginBottom: 24 }} />
+```
+
+## Utility Classes vs Inline Styles
+
+- ✅ **Prefer using PatternFly utility classes for spacing, alignment, and layout instead of inline styles.**
+- ❌ **Only use inline styles if a PatternFly utility class does not exist for the required spacing or layout.**
+
+**Correct:**
+```jsx
+<div className="pf-v6-u-mb-lg" />
+```
+
+**Incorrect:**
+```jsx
+<div style={{ marginBottom: 'var(--pf-t--global--spacer-lg)' }} />
+```
+
+## External Link Buttons
+
+- ✅ **Always add an external link icon to the right of the text for external link buttons.**
+- ❌ **Do not omit the external link icon for buttons that open external sites.**
+
+**Correct:**
+```jsx
+import { ExternalLinkAltIcon } from '@patternfly/react-icons';
+<Button
+  variant="link"
+  component="a"
+  href="https://patternfly.org"
+  target="_blank"
+  rel="noopener noreferrer"
+  icon={<ExternalLinkAltIcon />}
+  iconPosition="right"
+>
+  Learn more
+</Button>
+```
+
+**Incorrect:**
+```jsx
+<Button
+  variant="link"
+  component="a"
+  href="https://patternfly.org"
+  target="_blank"
+  rel="noopener noreferrer"
+>
+  Learn more
+</Button>
+```
+
+## Toolbar Alignment
+
+- ✅ **When right-aligning content in a PatternFly Toolbar, use the ToolbarItem align={{ default: 'alignEnd' }} prop.**
+- ❌ **Do not use custom Flex wrappers or utility classes to right-align Toolbar content.**
+
+**Correct:**
+```jsx
+<Toolbar>
+  <ToolbarContent>
+    <ToolbarItem>Left content</ToolbarItem>
+    <ToolbarItem align={{ default: 'alignEnd' }}>Right-aligned content</ToolbarItem>
+  </ToolbarContent>
+</Toolbar>
+```
+
+**Incorrect:**
+```jsx
+<Toolbar>
+  <ToolbarContent>
+    <ToolbarItem>Left content</ToolbarItem>
+    <Flex style={{ flex: 1 }} justifyContent={{ default: 'justifyContentFlexEnd' }}>
+      <FlexItem>Right-aligned content</FlexItem>
+    </Flex>
+  </ToolbarContent>
+</Toolbar>
+```
diff --git a/ai-documentation/resources/external-links.md b/ai-documentation/resources/external-links.md
@@ -29,6 +29,19 @@ External resources are essential for staying current with PatternFly updates, fi
 - **[Page Component](https://www.patternfly.org/components/page)** - Page layout and structure
 - **[Icon Component](https://www.patternfly.org/components/icon)** - Icon usage and sizing
 
+### Utility Classes Documentation
+- **[Accessibility](https://www.patternfly.org/utility-classes/accessibility)** - Accessibilty utility classes
+- **[Alignment](https://www.patternfly.org/utility-classes/alignment)** - Alignment utility classes
+- **[Background color](https://www.patternfly.org/utility-classes/background-color)** - Background utility classes
+- **[Box shadow](https://www.patternfly.org/utility-classes/box-shadow)** - Box shadow utility classes
+- **[Display](https://www.patternfly.org/utility-classes/accessibility)** - Display utility classes
+- **[Flex](https://www.patternfly.org/utility-classes/flex)** - Flex utility classes
+- **[Float](https://www.patternfly.org/utility-classes/float)** - Float utility classes
+- **[Sizing](https://www.patternfly.org/utility-classes/sizing)** - Sizing utility classes
+- **[Spacing](https://www.patternfly.org/utility-classes/spacing)** - Spacing utility classes
+- **[Text](https://www.patternfly.org/utility-classes/text)** - Text utility classes
+
+
 ### Specialized Features
 - **[PatternFly Charts](https://www.patternfly.org/charts/about)** - Data visualization guidelines
 - **[PatternFly AI - Chatbot](https://www.patternfly.org/patternfly-ai/chatbot/overview)** - AI chatbot components

diff --git a/ai-documentation/troubleshooting/common-issues.md b/ai-documentation/troubleshooting/common-issues.md
@@ -57,7 +57,7 @@ PatternFly development can present various challenges ranging from setup issues
 2. **Use CSS-in-JS for custom styles**:
    ```jsx
    // ✅ Alternative - Inline styles when utilities don't exist
-   <div style={{ margin: 'var(--pf-v6-global--spacer--md)' }}>
+   <div style={{ margin: 'var(--pf-t--global--spacer--md)' }}>
    ```
 
 #### Issue: AI uses inline styles instead of PatternFly utilities
@@ -82,8 +82,8 @@ PatternFly development can present various challenges ranging from setup issues
    ```jsx
    // ✅ Only when component composition isn't sufficient
    <div style={{ 
-     margin: 'var(--pf-v6-global--spacer--md)',
-     color: 'var(--pf-v6-global--primary-color--light)'
+     margin: 'var(--pf-t--global--spacer--md)',
+     color: 'var(--pf-t--global--text--color--regular)'
    }}>
    ```
 
@@ -538,6 +538,38 @@ Module not found: Can't resolve '@patternfly/chatbot/dist/dynamic/Chatbot'
    <Button variant="primary">Click me</Button>
    ```
 
+#### Issue: PatternFly utility class styles not applied
+```bash
+# Symptoms: Adding utility classes (pf-v6-u-*) do not have any apparent effect
+```
+
+**Solutions**:
+1. **Install patternfly package**:
+   ```bash
+   npm install @patternfly/patternfly
+   ```
+
+2. **Import PatternFly Utility CSS**:
+   ```jsx
+   // In your main App.js or index.js
+   import '@patternfly/patternfly/patternfly-addons.css';
+   ```
+
+3. **Verify webpack CSS handling**:
+   ```javascript
+   // webpack.config.js
+   module.exports = {
+     module: {
+       rules: [
+         {
+           test: /\.css$/,
+           use: ['style-loader', 'css-loader']
+         }
+       ]
+     }
+   };
+   ```
+
 ### Layout and Responsive Issues
 
 #### Issue: Components not responsive