From 3ad732cb4824813bf4c0b8b4e6df1ddc9304b853 Mon Sep 17 00:00:00 2001 From: Zoltan KADA Date: Sun, 15 Feb 2026 12:02:35 +0100 Subject: [PATCH] Fix documentation inconsistencies and PatternFly v6 compliance issues Fixes #8 - Replace deprecated Text component with Content - Fix CSS syntax error in design token example - Standardize design token naming to double-dash format - Clarify styling priority order (composition > props > utilities > inline styles) - Update EmptyState examples to use v6 simplified API - Replace drag-and-drop code with actual virtualization example - Replace hardcoded dimensions with design tokens - Fix incorrect chatbot API documentation link All issues identified by @evwilkin in their comprehensive documentation review. --- .pf-ai-documentation/charts/README.md | 24 +++++---- .pf-ai-documentation/chatbot/README.md | 4 +- .../guidelines/styling-standards.md | 34 +++++++------ .../troubleshooting/common-issues.md | 50 +++++++++++++++---- 4 files changed, 74 insertions(+), 38 deletions(-) diff --git a/.pf-ai-documentation/charts/README.md b/.pf-ai-documentation/charts/README.md index 1b85a4e..4931179 100644 --- a/.pf-ai-documentation/charts/README.md +++ b/.pf-ai-documentation/charts/README.md @@ -165,8 +165,8 @@ useEffect(() => { ```jsx // ✅ Required state handling if (isLoading) return ; -if (error) return ; -if (!data?.length) return ; +if (error) return ; +if (!data?.length) return ; const processedData = useMemo(() => { return rawData.map(item => ({ x: item.date, y: item.value })); @@ -180,14 +180,18 @@ const processedData = useMemo(() => { ```jsx // ✅ Required integration pattern -import { Card, CardTitle, CardBody } from '@patternfly/react-core'; - - - Chart Title - - - - +import { Card, CardTitle, CardBody, PageSection } from '@patternfly/react-core'; + + + + Chart Title + +
+ +
+ + + ``` ## Performance Rules diff --git a/.pf-ai-documentation/chatbot/README.md b/.pf-ai-documentation/chatbot/README.md index 3f2ca7b..fd9dccc 100644 --- a/.pf-ai-documentation/chatbot/README.md +++ b/.pf-ai-documentation/chatbot/README.md @@ -108,7 +108,7 @@ const createMessage = (content, role) => ({ ```jsx // ✅ Required integration pattern -
+
{/* Chatbot content */} @@ -192,5 +192,5 @@ const createMessage = (content, role) => ({ ### Further Reading - **[PatternFly Chatbot Docs](https://www.patternfly.org/chatbot/overview/)** -- **[Component API](https://github.com/patternfly/patternfly-react/tree/main/packages/react-core/src/components/ChipGroup)** - ChipGroup component API for tags +- **[Message Component API](https://www.patternfly.org/patternfly-ai/chatbot/messages/react)** - Message component API documentation - **[Accessibility Guide](https://www.patternfly.org/get-started/accessibility-guide)** \ No newline at end of file diff --git a/.pf-ai-documentation/guidelines/styling-standards.md b/.pf-ai-documentation/guidelines/styling-standards.md index 3c4a200..f23fc0d 100644 --- a/.pf-ai-documentation/guidelines/styling-standards.md +++ b/.pf-ai-documentation/guidelines/styling-standards.md @@ -107,9 +107,9 @@ Use utility classes only when: // ✅ Acceptable utility usage - when component props aren't sufficient {/* Force card to full height */} - {/* Center text when component doesn't provide prop */} + {/* Center text when component doesn't provide prop */} Centered content - + ``` @@ -124,11 +124,11 @@ Use utility classes only when: .custom-component { /* ✅ Correct - Use semantic tokens */ color: var(--pf-t--global--text--color--regular); - margin: var(--pf-t-global--spacer--md); + margin: var(--pf-t--global--spacer--md); /* ❌ Wrong - Hardcoded values or base tokens */ /* color: #333333; */ - /* color: var`--pf-t--global--text--color--100); */ + /* color: var(--pf-t--global--text--color--100); */ /* margin: 16px; */ } ``` @@ -141,7 +141,7 @@ Use utility classes only when: --pf-t--global--background--color--primary--default /* Spacing */ ---pf-t-global--spacer--{xs|sm|md|lg|xl} +--pf-t--global--spacer--{xs|sm|md|lg|xl} /* Typography */ --pf-t--global--font--family--body @@ -329,12 +329,18 @@ import { Title, Content } from '@patternfly/react-core'; ## 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.** +### Priority Order for Spacing and Layout +1. **Component composition first** - Use proper PatternFly component hierarchy +2. **Component props second** - Use built-in props for spacing/layout +3. **Utility classes third** - Use PatternFly utility classes when props aren't available +4. **Inline styles with tokens last** - Only when no other option exists -**Correct:** +### When You Must Use Inline Styles +If component composition, props, and utility classes don't provide what you need, use design tokens (not hardcoded values): + +**Correct (if no other option exists):** ```jsx -
+
``` **Incorrect:** @@ -342,19 +348,17 @@ import { Title, Content } from '@patternfly/react-core';
``` -## 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.** +### Prefer Utility Classes Over Inline Styles +When component composition and props aren't sufficient, use utility classes instead of inline styles: **Correct:** ```jsx
``` -**Incorrect:** +**Less preferred (but acceptable if utility class doesn't exist):** ```jsx -
+
``` ## External Link Buttons diff --git a/.pf-ai-documentation/troubleshooting/common-issues.md b/.pf-ai-documentation/troubleshooting/common-issues.md index db63357..24e40f0 100644 --- a/.pf-ai-documentation/troubleshooting/common-issues.md +++ b/.pf-ai-documentation/troubleshooting/common-issues.md @@ -27,12 +27,11 @@ PatternFly development can present various challenges ranging from setup issues 1. **Use correct v6 components**: ```jsx // ✅ Correct v6 components - import { Content, EmptyState, EmptyStateBody, EmptyStateHeader } from '@patternfly/react-core'; + import { Content, EmptyState } from '@patternfly/react-core'; Title - - + Description goes here ``` @@ -156,9 +155,9 @@ Module not found: Can't resolve '@patternfly/react-charts' ```jsx // ✅ Correct - Use design tokens const chartColors = [ - 'var(--pf-t-chart-color-blue-300)', - 'var(--pf-t-chart-color-green-300)', - 'var(--pf-t-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)' ]; ``` @@ -658,14 +657,43 @@ Module not found: Can't resolve '@patternfly/chatbot/dist/dynamic/Chatbot' const paginatedData = data.slice((page - 1) * perPage, page * perPage); ``` -2. **Use virtualization**: +2. **Use virtualization for large datasets**: ```jsx - import { DndProvider, useDrag, useDrop } from 'react-dnd'; - import { HTML5Backend } from 'react-dnd-html5-backend'; + import { useVirtual } from 'react-virtual'; import { Table, Thead, Tbody, Tr, Th, Td } from '@patternfly/react-table'; - const DraggableRow = ({ id, text, index, moveRow }) => { - // ... existing code ... + const VirtualizedTable = ({ data }) => { + const parentRef = useRef(); + const rowVirtualizer = useVirtual({ + size: data.length, + parentRef, + estimateSize: useCallback(() => 50, []), + }); + + return ( +
+ + + + + + + + + {rowVirtualizer.virtualItems.map(virtualRow => { + const item = data[virtualRow.index]; + return ( + + + + + ); + })} + +
NameEmail
{item.name}{item.email}
+
+ ); + }; ``` 3. **Optimize re-renders**: