Skip to content

Commit df1e96a

Browse files
nicolethoennicolethoen
committed
update docs and clean up tests
1 parent 2b433bb commit df1e96a

File tree

14 files changed

+911
-354
lines changed

14 files changed

+911
-354
lines changed

‎COMPASS-THEME-DOCS-SUMMARY.md‎

Lines changed: 244 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,244 @@
1+
# Compass Theme Documentation Summary
2+
3+
## Overview
4+
5+
This document summarizes the AI agent guidance added to help with the Compass theme branch, which uses unpublished PatternFly Generative UI components.
6+
7+
## Problem Statement
8+
9+
- The `compass_theme` branch uses components not yet officially published
10+
- Component documentation is NOT on patternfly.org
11+
- Documentation IS available on staging.patternfly.org under "Generative UI"
12+
- AI agents (Cursor, Claude Code, etc.) need to know where to find these docs
13+
- PatternFly MCP server won't have Compass component documentation yet
14+
15+
## Solution: Comprehensive AI Guidance
16+
17+
Created multi-layered documentation to ensure AI agents can easily discover and reference the staging site.
18+
19+
## Files Created
20+
21+
### 1. Main Compass Theme Guide
22+
**Location**: `ai-documentation/guidelines/compass-theme-guide.md`
23+
24+
**Purpose**: Comprehensive guide for AI agents about:
25+
- What Compass theme components are
26+
- When to use staging vs production docs
27+
- Component discovery workflow
28+
- MCP and Context7 integration notes
29+
- Troubleshooting common issues
30+
- Best practices for AI-generated code
31+
32+
**Key Sections**:
33+
- Documentation sources (staging vs production)
34+
- Development workflow with decision tree
35+
- AI agent instructions with search strategy
36+
- MCP integration notes
37+
- Troubleshooting guide
38+
- Quick reference table
39+
40+
### 2. Quick Reference Card
41+
**Location**: `ai-documentation/COMPASS-QUICK-REF.md`
42+
43+
**Purpose**: Fast lookup for AI agents
44+
- TL;DR decision tree
45+
- Essential links table
46+
- Quick rules (DO/DON'T)
47+
- Component naming patterns
48+
- AI agent checklist
49+
- Common Q&A
50+
51+
## Files Updated
52+
53+
### 3. Main AI Documentation README
54+
**Location**: `ai-documentation/README.md`
55+
56+
**Changes**:
57+
- Added prominent warning section at top about Compass theme
58+
- Added Compass Theme Guide to Core Rules section
59+
- Added Quick Reference link
60+
- Linked to staging site documentation
61+
62+
### 4. PatternFly Guidelines
63+
**Location**: `ai-documentation/guidelines/README.md`
64+
65+
**Changes**:
66+
- Added Compass Theme Guide to Related Files (top of list)
67+
- Updated Documentation Requirements section
68+
- Added warning about MCP not having Compass docs
69+
- Added note to check staging site first
70+
71+
### 5. External Links Resource
72+
**Location**: `ai-documentation/resources/external-links.md`
73+
74+
**Changes**:
75+
- Added prominent "COMPASS THEME" section at top of documentation links
76+
- Included staging site links with clear descriptions
77+
- Added guidance on when to use staging vs production
78+
- Cross-referenced Compass Theme Guide
79+
80+
### 6. Main Project README
81+
**Location**: `README.md`
82+
83+
**Changes**:
84+
- Added "Compass Theme Branch" section under AI Documentation
85+
- Explained what Compass components are
86+
- Provided links to staging site
87+
- Added specific instructions for AI agents
88+
89+
## Documentation Strategy
90+
91+
### Multi-Level Approach
92+
93+
1. **Discovery Level**: Main READMEs prominently warn about Compass theme
94+
2. **Quick Reference**: Fast decision trees and checklists
95+
3. **Comprehensive Guide**: Full documentation with workflows
96+
4. **Context Integration**: Updated all related files to cross-reference
97+
98+
### AI Agent Journey
99+
100+
```
101+
AI Agent starts coding
102+
│
103+
├─ Reads README.md → Sees Compass warning
104+
│
105+
├─ Checks ai-documentation/README.md → Gets Quick Ref link
106+
│
107+
├─ Needs quick answer → COMPASS-QUICK-REF.md
108+
│
109+
├─ Needs details → compass-theme-guide.md
110+
│
111+
└─ Needs external link → external-links.md
112+
```
113+
114+
### Visibility Tactics
115+
116+
- 🚨 Emoji indicators for important sections
117+
- **Bold** and prominent placement in navigation
118+
- Multiple entry points to same information
119+
- Cross-references between all related docs
120+
- Clear decision trees and flowcharts
121+
- Practical examples and checklists
122+
123+
## Key Messages for AI Agents
124+
125+
### Primary Message
126+
"Compass components → staging.patternfly.org/ai/generative-uis"
127+
128+
### Secondary Messages
129+
1. MCP won't have Compass docs yet
130+
2. Always check staging site first for Compass components
131+
3. Standard components still on patternfly.org
132+
4. Use "View Code" sections on staging site
133+
134+
## Coverage
135+
136+
### Where Compass Guidance Appears
137+
138+
✅ Main project README
139+
✅ AI documentation main README
140+
✅ Guidelines main README
141+
✅ External links resource
142+
✅ Dedicated Compass theme guide
143+
✅ Quick reference card
144+
145+
### What Each Document Provides
146+
147+
- **README.md**: First alert and high-level overview
148+
- **ai-documentation/README.md**: AI-focused navigation hub
149+
- **COMPASS-QUICK-REF.md**: Fast lookups and decision trees
150+
- **compass-theme-guide.md**: Comprehensive instructions
151+
- **external-links.md**: Centralized link repository
152+
- **guidelines/README.md**: Integration with existing rules
153+
154+
## Usage for AI Agents
155+
156+
### Discovery Patterns
157+
158+
1. **Natural Discovery**: Reading any main README will show Compass warnings
159+
2. **Search Discovery**: Searching for "compass" finds all relevant docs
160+
3. **Link Discovery**: Following any Compass link leads to other Compass docs
161+
4. **Component Discovery**: MCP failure leads to staging site guidance
162+
163+
### Integration Points
164+
165+
- Works with existing PatternFly documentation strategy
166+
- Complements MCP and Context7 workflows
167+
- Provides fallback when automated tools can't find docs
168+
- Maintains consistency with project structure
169+
170+
## Benefits
171+
172+
### For AI Agents
173+
- Clear, discoverable instructions
174+
- Multiple entry points to information
175+
- Decision trees reduce confusion
176+
- Quick references speed up development
177+
- Comprehensive guide for complex scenarios
178+
179+
### For Human Developers
180+
- Understanding of Compass theme setup
181+
- Clear documentation hierarchy
182+
- Easy to update as Compass components publish
183+
- Consistent messaging across project
184+
185+
### For Project Maintainability
186+
- Centralized Compass documentation
187+
- Easy to remove/update when components publish
188+
- Clear separation of staging vs production
189+
- Version-specific guidance
190+
191+
## Next Steps
192+
193+
### When Compass Components Are Published
194+
195+
1. Update compass-theme-guide.md with migration notes
196+
2. Update all links to point to patternfly.org
197+
3. Add note about MCP now having docs
198+
4. Keep guide as reference for transition period
199+
5. Archive or remove after full migration
200+
201+
### Ongoing Maintenance
202+
203+
- Monitor staging site for updates
204+
- Update examples as APIs change
205+
- Track Compass component releases
206+
- Update links when components publish
207+
208+
## Testing the Guidance
209+
210+
### Manual Tests
211+
- [ ] Read through README.md - is Compass theme obvious?
212+
- [ ] Follow links from README to other docs
213+
- [ ] Use quick reference to make a decision
214+
- [ ] Follow decision tree in comprehensive guide
215+
- [ ] Search for "compass" or "staging" in project
216+
217+
### AI Agent Tests
218+
- [ ] Ask AI to use a standard PatternFly component
219+
- [ ] Ask AI to use a Compass component
220+
- [ ] See if AI checks staging site
221+
- [ ] Verify AI notes staging-only components
222+
- [ ] Check if AI references correct documentation
223+
224+
## Summary
225+
226+
Created comprehensive, multi-layered guidance for AI agents working with unpublished Compass theme components. Documentation provides:
227+
228+
- **Visibility**: Prominent warnings and navigation
229+
- **Clarity**: Clear decision trees and rules
230+
- **Accessibility**: Multiple entry points and formats
231+
- **Completeness**: Quick refs and detailed guides
232+
- **Integration**: Works with existing documentation
233+
- **Maintainability**: Easy to update when components publish
234+
235+
All AI agents working in this project will now be automatically directed to staging.patternfly.org for Compass components while maintaining proper use of patternfly.org for standard components.
236+
237+
---
238+
239+
**Created**: November 19, 2024
240+
**Branch**: compass_theme
241+
**Files Modified**: 6
242+
**Files Created**: 3
243+
**Total Documentation**: 9 files now reference Compass theme
244+

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,20 @@ If you are using an AI-enabled IDE, the AI agent will automatically leverage the
105105

106106
By following these rules—either directly or via your AI assistant—you'll ensure your app is maintainable, accessible, and consistent with PatternFly best practices.
107107

108+
### 🚨 Compass Theme Branch
109+
110+
This branch (`compass_theme`) uses **Compass theme components** from PatternFly's **Generative UI** initiative. These components are optimized for AI-assisted development but are **not yet published** on the main PatternFly website.
111+
112+
**Important for AI agents and developers:**
113+
- 📖 Compass component docs are on **[staging.patternfly.org/ai/generative-uis](https://staging.patternfly.org/ai/generative-uis/overview)**
114+
- 🔍 Standard PatternFly components remain on **[patternfly.org](https://www.patternfly.org/)**
115+
- 📝 See [Compass Theme Guide](./ai-documentation/guidelines/compass-theme-guide.md) for complete instructions
116+
117+
**AI agents should:**
118+
1. Check staging.patternfly.org for Compass/Generative UI components first
119+
2. Fall back to patternfly.org for standard components
120+
3. Note that PatternFly MCP won't have Compass docs yet
121+
108122
## Multi environment configuration
109123
This project uses [dotenv-webpack](https://www.npmjs.com/package/dotenv-webpack) for exposing environment variables to your code. Either export them at the system level like `export MY_ENV_VAR=http://dev.myendpoint.com && npm run start:dev` or simply drop a `.env` file in the root that contains your key-value pairs like below:
110124

‎ai-documentation/COMPASS-QUICK-REF.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# 🧭 Compass Theme Quick Reference
2+
3+
> **Quick guide for AI agents working with Compass theme components**
4+
5+
## TL;DR for AI Agents
6+
7+
```
8+
Component not found on patternfly.org?
9+
→ Go to staging.patternfly.org/ai/generative-uis
10+
```
11+
12+
## Documentation Decision Tree
13+
14+
```
15+
Need a component?
16+
│
17+
├─ Is it a pipeline/topology/workflow visualization?
18+
│ └─ YES → Use staging.patternfly.org/ai/generative-uis/react-flow
19+
│
20+
├─ Is it a standard PatternFly component?
21+
│ └─ YES → Use patternfly.org
22+
│
23+
├─ Has "Compass" in the name?
24+
│ └─ YES → Use staging.patternfly.org/ai/generative-uis
25+
│
26+
├─ Not found on patternfly.org?
27+
│ └─ YES → Use staging.patternfly.org/ai/generative-uis
28+
│
29+
└─ MCP returns no results?
30+
└─ YES → Use staging.patternfly.org/ai/generative-uis
31+
```
32+
33+
## Essential Links
34+
35+
| When | Use This Link |
36+
|------|---------------|
37+
| 🎯 **Compass/Generative UI** | [staging.patternfly.org/ai/generative-uis](https://staging.patternfly.org/ai/generative-uis/overview) |
38+
| 🔄 **React Flow (Pipelines/Topology)** | [staging.patternfly.org/ai/generative-uis/react-flow](https://staging.patternfly.org/ai/generative-uis/react-flow) |
39+
| 📘 **Standard Components** | [patternfly.org](https://www.patternfly.org/) |
40+
| 📖 **Full Guide** | [Compass Theme Guide](./guidelines/compass-theme-guide.md) |
41+
42+
## Quick Rules
43+
44+
### ✅ DO
45+
- Check staging site first for Compass components
46+
- Use "View Code" sections on staging site
47+
- Reference staging site in code comments
48+
- Test components thoroughly
49+
50+
### ❌ DON'T
51+
- Assume MCP has Compass docs (it doesn't yet)
52+
- Mix staging and production APIs
53+
- Skip checking staging site for new components
54+
- Use outdated examples
55+
56+
## Component Naming Patterns
57+
58+
Look for these patterns to identify staging-only components:
59+
60+
- `Compass*` → Staging site
61+
- `Generative*` → Staging site
62+
- Pipeline/topology/workflow needs → React Flow on staging site
63+
- Component not on patternfly.org → Staging site
64+
65+
## AI Agent Checklist
66+
67+
When generating code with Compass components:
68+
69+
- [ ] Checked staging.patternfly.org for component docs
70+
- [ ] Used latest API from staging site examples
71+
- [ ] Added comment noting staging-only component
72+
- [ ] Verified imports match staging examples
73+
- [ ] Tested component renders correctly
74+
75+
## Common Questions
76+
77+
**Q: Why isn't this component in the PatternFly MCP?**
78+
A: Compass components aren't published yet. Use staging.patternfly.org.
79+
80+
**Q: Should I use patternfly.org or staging.patternfly.org?**
81+
A: For Compass components → staging. For standard components → patternfly.org.
82+
83+
**Q: How do I know if a component is a Compass component?**
84+
A: If it's not on patternfly.org or has "Compass" in the name.
85+
86+
**Q: How do I build pipelines or topology visualizations?**
87+
A: Use React Flow with PatternFly. See [staging.patternfly.org/ai/generative-uis/react-flow](https://staging.patternfly.org/ai/generative-uis/react-flow).
88+
89+
## Status
90+
91+
- **Branch**: `compass_theme`
92+
- **Docs**: [staging.patternfly.org/ai/generative-uis](https://staging.patternfly.org/ai/generative-uis/overview)
93+
- **Status**: Active development, not yet published
94+
- **Updated**: November 2024
95+
96+
---
97+
98+
**Need more details?** See [Compass Theme Guide](./guidelines/compass-theme-guide.md)
99+

‎ai-documentation/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,14 @@
55
66
Essential rules and guidelines for AI coders working with PatternFly React applications.
77

8+
## 🚨 IMPORTANT: Compass Theme Branch
9+
10+
**This branch uses unpublished Compass components!**
11+
12+
→ **[Quick Reference for AI Agents](./COMPASS-QUICK-REF.md)**
13+
→ **[Complete Compass Theme Guide](./guidelines/compass-theme-guide.md)**
14+
→ **[Staging Site Documentation](https://staging.patternfly.org/ai/generative-uis/overview)**
15+
816
## Quick Navigation
917

1018
### 🚀 Setup & Environment
@@ -14,6 +22,7 @@ Essential rules and guidelines for AI coders working with PatternFly React appli
1422

1523
### 📚 Core Rules
1624
- [**PatternFly Guidelines**](./guidelines/README.md) - Core development principles
25+
- [**Compass Theme Guide**](./guidelines/compass-theme-guide.md) - **🚨 IMPORTANT: Generative UI & staging site documentation**
1726
- [**Component Rules**](./guidelines/component-architecture.md) - Component structure requirements
1827
- [**Styling Rules**](./guidelines/styling-standards.md) - CSS and styling requirements
1928
- [**Deployment Guide**](./guidelines/deployment-guide.md) - How to deploy prototypes

0 commit comments

Comments
 (0)