diff --git a/.cursor/rules/patternfly-vibe-coding.mdc b/.cursor/rules/patternfly-vibe-coding.mdc index 52e0b078..015d38d3 100644 --- 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 index dbe28cb9..f819ada8 100644 --- 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)' ]; @@ -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 index 54c71d34..53d9cad2 100644 --- 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) \ No newline at end of file +- [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 index a8e9d11d..6e01a639 100644 --- 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 index 787e0244..3c4a2005 100644 --- 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. // ❌ Wrong - Utility classes for basic layout -
-
Dashboard
+
+
Dashboard
Dashboard content
``` @@ -62,8 +63,8 @@ Essential CSS and styling rules for PatternFly React applications. // ❌ Wrong - Utility classes when component props exist - - +
+
``` @@ -104,7 +105,7 @@ Use utility classes only when: ```jsx // ✅ Acceptable utility usage - when component props aren't sufficient - {/* Force card to full height */} + {/* Force card to full height */} {/* Center text when component doesn't provide prop */} Centered content @@ -116,18 +117,18 @@ 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; */ } ``` @@ -135,16 +136,16 @@ Use utility classes only when: ### 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. \ No newline at end of file +> **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 +
+``` + +**Incorrect:** +```jsx +
+``` + +## 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 +
+``` + +**Incorrect:** +```jsx +
+``` + +## 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'; + +``` + +**Incorrect:** +```jsx + +``` + +## 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 + + + Left content + Right-aligned content + + +``` + +**Incorrect:** +```jsx + + + Left content + + Right-aligned content + + + +``` \ No newline at end of file diff --git a/ai-documentation/resources/external-links.md b/ai-documentation/resources/external-links.md index 874262a8..5693f33a 100644 --- 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 index ce8cfea9..761b007b 100644 --- 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 -
+
``` #### 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
``` @@ -538,6 +538,38 @@ Module not found: Can't resolve '@patternfly/chatbot/dist/dynamic/Chatbot' ``` +#### 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