Skip to content

Commit 051ade7

Browse files
nicolethoennicolethoen
committed
incorporate some feedback from workshop
1 parent b920ccc commit 051ade7

File tree

7 files changed

+740
-48
lines changed

7 files changed

+740
-48
lines changed

‎PF Prototyping workshop retrospective.csv‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
"What is working?"
2+
"What is not working?"
3+
"very specific prompting. had to avoid the word ""element"" when dealing with a basic paragraph... vs the content component"
4+
"Getting Cursor to add right-hand buttons to the Masthead. Maybe it had trouble reading the example?"
5+
"i tried several times to install the chatbot package and it kept applying cusotm styling, changing the container to a modal and removing all appropraite UI atyling. it had to rerun it twice to get to a place that wasnt horrible"
6+
"Quickly generated new base app with drawer - code compiled and ran, but inline styles were implemented and would not run correctly"
7+
"how to deploy and share a prototype (host it)"
8+
"many in the room got stuck when the code blew up.  Often, telling cursor to fix errors will help the user get past these errors."
9+
"more detailed instructions on installing node and git needed for non-developers.  Git - explain steps for setting up authentication. How to test that they are installed "
10+
"Deploying for preview is kinda difficult. Vercel gave me trouble. Surge too."
11+
"can we load cursor with the seed app from this workshop"
12+
"vague prompts do not really work. I had to be very specific for the application to be consistent and applied on the first ask"
13+
"with a dev base, up and running quickly. able to generate a basic charting and inventory display with minimal effort."
14+
"After first prompt, received multiple errors like export 'TextContent' (imported as 'TextContent') was not found in '@patternfly/react-core' no clue how to fix"
15+
"Issues with color applied to icons. Bot ended up hardcoding hex values"
16+
"Had to click multiple things within the chat ""open"", ""accept"", but it wasn't clear to me that it was waiting on my input"
17+
"During step 2: Set context. When I clicked the ""Follow this link to get to the MCP settings in Cursor"" link the popover would disappear before I could click ""open in cursor"". I had to get Erin to help me.","https://cursor.com/install-mcp?name=context7&config=eyJ1cmwiOiJodHRwczovL21jcC5jb250ZXh0Ny5jb20vbWNwIn0%3D"
18+
"UI did not build on first prompt due to generation of PF components that don't exist"
19+
"Able to add additional rules when prompted to avoid className={styles.blahblah}, etc. in future"
20+
"Jan told me to tell cursor to fix this and it did"
21+
"Able to create a basic page framework"
22+
"Correctly identified surge as a deployment option but commands didn't work"
23+
"App it generated was not keyboard-accessible - probably other issues"
24+
"when it first generated the page, there was a dropdown that was stuck open at the topleft corner of screen. i told cursor about it and it fixed it properly"
25+
"Added inline styles that were not formatted in an executable way. Asked it to switch and it created CSS module files, but used className={styles.blahblahBlah} instead of actual classNames. This did not compile. It was also using CSS modules, which this app doesn't support."
26+
"Installed react-charts & victory but build broke until I manually changed import paths to add /victory"
27+
"i told cursor to fix my error codes and provided the codes back. it was able to fix it quickly"
28+
"Got terminal error: ""Card: Clickable-only cards must have either the selectableActions.selectableActionAriaLabel or selectableActions.selectableActionAriaLabelledby prop passed in order to provide an accessible name to the clickable element. Error Component Stack"". Was not able to handle fixing it - hallucinated wrong solution."
29+
"Spacing was very off - asking it to correct that was very difficult. Would be faster to fix by hand."
30+
"First pass utilized a lot of inline styles and utility layout classes"
31+
"Once ChatBot components used, it wasn't setting up the layout properly. I pasted in a demo and it got further. Could maybe benefit from provided code examples, but may be easier to just copy and paste a demo tbh. Was really slow."
32+
"Asked it to add a PatternFly ChatBot and it made its own not using the extension. It did correctly add the CSS and install the package."
33+
"Does this spark any new ideas?"
34+
"What sort of manual intervention was required to correct the AI?"
35+
"Chart import paths needed to be manually appended with /victory, prompting did not fix this issue"
36+
"curious to see if this setup can be applied to other editors/ides"
37+
"how can each experiment like we did today add to or help train our PF MCP/rule sets?"
38+
"Possibly running a11y audits (maybe more as a cursory step rather than the only/an in-depth step)"
39+
"had to repeat my request to create a single page. it first created multiple pages/tabs, even though I originally said single page"
40+
"Generated component EmptyStateHeader which does not exist in PF, required correction to use EmptyState with EmptyStateBody"
41+
"Modal body vs dumping content right in"
42+
"had to send screenshots and links from the patternfly site to help it build what I needed"
43+
"Common layouts can be provided by default, for both dashboard and body content."
44+
"Are there tests we could include in the starter app or in other places to check that the produced code was using PF correctly?"
45+
"Can we encompass this starter tool into a one click download and open in cursor to avoid the 'complex set up'"
46+
"Had to ask it to fix 3 linter errors. Took a few minutes but was able to fix on it's own."
47+
"Asked to remove inline styles - needed to correct how it does class names after that and fix errors. It also tried to create CSS modules, which didn't compile - had to ask it to put styles in right file. Then it compiled again. It is sometimes using CSS variables correctly to style components."
48+
"Did not implement a table and used cards for visualization by default, had to prompt for a table"
49+
"how can we reuse what we created and share this with others. maybe a cursor template site with titles to each template. who knows if id find someone elses demo useful later - better to reuse than get a headache from recreating"
50+
"We could improve our hosting guidance to make it easier for people to share their solutions? maybe create a registry of solutions somewhere?"
51+
"If we provide a demo for user testing, maybe folks would be able to use Cursor to edit it if their user flow changed, etc. Cursor seems good at spitting out ""what it wants"" or making very specific, clearly defined changes that are easy for it to verify (linter or build errors, test failures, etc.)"
52+
"Can we create a template for prompts to be as specific as possible so the first attempt can be closer to our desired results?"
53+
"Had to ask again for it use the PF ChatBot extension for it to do it, but the types were wrong - had to ask it to fix them."
54+
"Colors were wrong, it was using invalid CSS tokens. It was guessing what the token name would be based on the docs instead of using tokens defined in the codebase."
55+
"Had to provide examples of successful ChatBot demo to get it to implement it as designed, but even then, it dropped pieces that were important."
56+
"Can PF provide specific guidance for certain data metrics that we can prompt with? e.g. which components to use for certain data"
57+
"Had to keep asking it to not use custom styling and instead rely on native PF styles"
58+
"Had to ask it several times to get chart colors to look better (black bar or text in dark theme)"
59+
"could be valuable to have general strong starter prompts for pf projects but could also see value in products having pre written prompts/rules for their own patterns"
60+
"PatternFly prototype quickstarts for common use cases"
61+
"Struggled to get it to use consistent styling across all cards in a single view. It would randomly change the styling even if my prompt had nothing to do with styling."
62+
"It sometimes helped to provide PF links to specific component examples"
63+
"Ability to select a selection or region on a page that would focus your prompt to only those elements. Sometimes Cursor would randomly change a section I was happy with."
64+
"Can we create a series of styling templates (maybe per product or fidelity) so Canvas uses a consistent style for elements?"
65+
"can we provide type-ahead for prompts that use the PF terms for elements."
66+
"Create cursor templates of validated designs so we can start with an existing design and iterate from there?"

‎ai-documentation/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Essential rules and guidelines for AI coders working with PatternFly React appli
1616
- [**PatternFly Guidelines**](./guidelines/README.md) - Core development principles
1717
- [**Component Rules**](./guidelines/component-architecture.md) - Component structure requirements
1818
- [**Styling Rules**](./guidelines/styling-standards.md) - CSS and styling requirements
19+
- [**AI Prompt Guidance**](./guidelines/ai-prompt-guidance.md) - How to write effective AI prompts
1920
- [**Deployment Guide**](./guidelines/deployment-guide.md) - How to deploy prototypes
2021

2122
### 🧩 Component Rules
@@ -42,6 +43,17 @@ Essential rules and guidelines for AI coders working with PatternFly React appli
4243
5. **Use utility classes** - Prefer PatternFly utilities over custom CSS
4344
6. **Handle states** - Always implement loading, error, and empty states
4445

46+
## ⚠️ Common AI Coding Issues Addressed
47+
48+
Based on feedback, these rules prevent frequent AI-generated errors:
49+
50+
- **❌ No CSS modules syntax** - `className={styles.x}` doesn't work in this project
51+
- **❌ No non-existent components** - Verify components exist before using
52+
- **❌ No inline styles for layout** - Use PatternFly utilities instead
53+
- **✅ Chart imports must include `/victory`** - Critical for chart components
54+
- **✅ Always include accessibility attributes** - Keyboard navigation and ARIA labels
55+
- **✅ Use specific, detailed prompts** - See [AI Prompt Guidance](./guidelines/ai-prompt-guidance.md)
56+
4557
## Documentation Structure
4658

4759
Each file contains:

‎ai-documentation/charts/README.md‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,23 +18,55 @@ npm install @patternfly/react-charts echarts
1818
```
1919

2020
### Import Rules
21-
- ✅ **Use specific import paths** - Import from `/victory` or `/echarts` subdirectories
21+
- ✅ **CRITICAL: Use specific import paths** - Import from `/victory` or `/echarts` subdirectories
2222
- ❌ **Don't use general imports** - Avoid importing from main package
23+
- ⚠️ **Common Error**: AI assistants often forget the `/victory` path
2324

2425
```jsx
25-
// ✅ Correct imports
26+
// ✅ Correct imports - MUST include /victory
2627
import { ChartDonut, ChartLine, ChartBar } from '@patternfly/react-charts/victory';
2728
import { EChart } from '@patternfly/react-charts/echarts';
2829

29-
// ❌ Wrong imports
30+
// ❌ Wrong imports - Missing /victory will cause "Module not found" errors
3031
import { ChartDonut } from '@patternfly/react-charts';
3132
```
3233

33-
### Troubleshooting Import Issues
34-
If "module not found" errors occur:
35-
1. **Clear cache**: `rm -rf node_modules package-lock.json`
36-
2. **Reinstall**: `npm install`
37-
3. **Verify paths**: Check import paths match installed version
34+
### Critical Import Path Troubleshooting
35+
36+
**⚠️ MOST COMMON ISSUE**: Chart components cannot be found
37+
38+
```bash
39+
# Error message you'll see:
40+
Module not found: Can't resolve '@patternfly/react-charts'
41+
```
42+
43+
**Solutions in order:**
44+
1. **Fix import paths** - Add `/victory` to your imports:
45+
```jsx
46+
// Change this:
47+
import { ChartDonut } from '@patternfly/react-charts';
48+
49+
// To this:
50+
import { ChartDonut } from '@patternfly/react-charts/victory';
51+
```
52+
53+
2. **Install Victory dependency**:
54+
```bash
55+
npm install victory
56+
```
57+
58+
3. **Clear cache and reinstall**:
59+
```bash
60+
rm -rf node_modules package-lock.json
61+
npm install
62+
```
63+
64+
4. **Verify installation**:
65+
```bash
66+
# Check if both packages are installed
67+
npm list @patternfly/react-charts
68+
npm list victory
69+
```
3870
3971
## Chart Implementation Rules
4072

‎ai-documentation/guidelines/ai-prompt-guidance.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# AI Prompt Guidance for PatternFly Development
2+
3+
Guidelines for creating effective prompts when using AI coding assistants with PatternFly React applications.
4+
5+
## Why Specific Prompts Matter
6+
7+
Based on workshop feedback, AI coding assistants work best with PatternFly when given specific, detailed prompts. Vague prompts often result in:
8+
- Non-existent component usage → See [Common Issues](../troubleshooting/common-issues.md#ai-coding-specific-issues)
9+
- Incorrect styling approaches → See [Styling Standards](./styling-standards.md)
10+
- Missing accessibility features → See [Guidelines](./README.md#accessibility-requirements)
11+
12+
## Essential Prompt Template
13+
14+
```
15+
Create a [FEATURE] using PatternFly v6 React components. Requirements:
16+
- Follow PatternFly component composition patterns (see styling-standards.md)
17+
- Use component props for spacing/layout before considering utility classes
18+
- Ensure keyboard accessibility with proper ARIA labels
19+
- Verify all components exist in PatternFly packages before using
20+
- [SPECIFIC_FEATURE_REQUIREMENTS]
21+
- Reference: [LINK_TO_RELEVANT_DOCS]
22+
```
23+
24+
## Prompt Strategy by Use Case
25+
26+
### Dashboard/Data Pages
27+
**Key prompt additions:**
28+
```
29+
- Use proper component hierarchy: PageSection > Stack > Grid > Card
30+
- For tabular data, use PatternFly Table component (see data-display/table.md)
31+
- For charts, follow charts/README.md import requirements (/victory path)
32+
```
33+
34+
### Forms
35+
**Key prompt additions:**
36+
```
37+
- Follow form structure: PageSection > Form > FormGroup > ActionGroup
38+
- Use ActionGroup component for button spacing (see styling-standards.md)
39+
```
40+
41+
### Navigation/Layout
42+
**Key prompt additions:**
43+
```
44+
- Use existing AppLayout structure in src/app/AppLayout/
45+
- Follow routing patterns in src/app/routes.tsx
46+
- Reference layout/README.md for proper component usage
47+
```
48+
49+
### Charts Integration
50+
**Key prompt additions:**
51+
```
52+
- CRITICAL: Import from @patternfly/react-charts/victory (see charts/README.md)
53+
- Follow chart color guidance in charts/README.md
54+
```
55+
56+
### Chatbot Integration
57+
**Key prompt additions:**
58+
```
59+
- Follow dynamic import patterns from chatbot/README.md
60+
- Reference official PatternFly chatbot demos (links in chatbot/README.md)
61+
```
62+
63+
## Error Prevention Strategies
64+
65+
### Component Existence
66+
**Prompt addition:**
67+
```
68+
"Before using any component, verify it exists by checking:
69+
- Core components: @patternfly/react-core documentation
70+
- Tables: @patternfly/react-table documentation
71+
- Charts: @patternfly/react-charts documentation
72+
See troubleshooting/common-issues.md for common non-existent components to avoid."
73+
```
74+
75+
### Styling Approach
76+
**Prompt addition:**
77+
```
78+
"Follow the component-first approach from styling-standards.md:
79+
1. Use proper component composition first
80+
2. Use component props second
81+
3. Use utility classes only as last resort
82+
Do NOT use CSS modules syntax (className={styles.*}) - this project doesn't support them."
83+
```
84+
85+
### Import Paths
86+
**Prompt addition:**
87+
```
88+
"Use correct import paths as documented in:
89+
- Charts: charts/README.md (must include /victory)
90+
- Chatbot: chatbot/README.md (dynamic imports)
91+
- Core: standard @patternfly/react-core imports"
92+
```
93+
94+
## Deployment Prompting
95+
96+
**When requesting deployment guidance:**
97+
```
98+
"After creating the prototype, provide deployment instructions following deployment-guide.md.
99+
Include build command and choose appropriate service (Surge for quick sharing, Vercel for professional demos)."
100+
```
101+
102+
## Complete Example Prompt
103+
104+
```
105+
Create a user management page using PatternFly v6 with these requirements:
106+
107+
Component Structure:
108+
- Follow component hierarchy from styling-standards.md: PageSection > Stack > Toolbar + Table
109+
- Use Table component with proper props (borders, gridBreakPoint) - see data-display/table.md
110+
- Use ActionGroup for buttons (provides spacing automatically)
111+
112+
Technical Requirements:
113+
- Verify all components exist in PatternFly packages before using
114+
- Follow accessibility guidelines from guidelines/README.md
115+
- Handle loading/error/empty states as shown in troubleshooting/common-issues.md
116+
117+
Project Integration:
118+
- Follow existing routing patterns in src/app/routes.tsx
119+
- Integrate with existing AppLayout structure
120+
- Match patterns from existing pages in src/app/
121+
122+
References:
123+
- Component patterns: styling-standards.md
124+
- Table specifics: data-display/table.md
125+
- Accessibility: guidelines/README.md
126+
- Error handling: troubleshooting/common-issues.md
127+
```
128+
129+
## Quick Reference for Prompts
130+
131+
- **Component composition patterns**: [styling-standards.md](./styling-standards.md)
132+
- **Table usage**: [data-display/table.md](../components/data-display/table.md)
133+
- **Chart requirements**: [charts/README.md](../charts/README.md)
134+
- **Chatbot implementation**: [chatbot/README.md](../chatbot/README.md)
135+
- **Common errors to avoid**: [common-issues.md](../troubleshooting/common-issues.md)
136+
- **Deployment options**: [deployment-guide.md](./deployment-guide.md)
137+
138+
## Best Practices Summary
139+
140+
1. **Reference documentation** - Include links to relevant .md files in your prompts
141+
2. **Be specific about structure** - Mention component hierarchy requirements
142+
3. **Prevent common errors** - Reference troubleshooting guide proactively
143+
4. **Verify existence** - Ask AI to confirm components exist before using
144+
5. **Include context** - Reference existing project files when applicable
145+
146+
The key is combining specific prompting with references to the detailed guidance already documented in this project's other files.

0 commit comments

Comments
 (0)