diff --git a/CONTRIBUTING-SKILLS.md b/CONTRIBUTING-SKILLS.md index 47203f1..83ee036 100644 --- a/CONTRIBUTING-SKILLS.md +++ b/CONTRIBUTING-SKILLS.md @@ -70,7 +70,7 @@ Every skill or agent must live in a plugin. Pick the one that matches your skill | **migration** | Upgrade PatternFly versions | Does this help me upgrade PF versions? | `pf-class-migration-scanner` | | **patternfly-mcp** | Connect AI tools to PatternFly documentation and component data | | | | **pf-workshop** | Team tools and skill incubation | Is this a team workflow tool, or a new skill that isn't ready for a consumer plugin yet? | `analytics-repo-pruning`, `css-var-analyzer`, `duplicate-epic` | -| **react** | Develop and test React components | Does this help me write or test a React component? | `pf-component-structure`, `pf-design-comments`, `pf-github-pages-deploy` | +| **react** | Develop and test React components | Does this help me write or test a React component? | `pf-component-reuse-check`, `pf-component-structure`, `pf-design-comments` | **How to decide:** diff --git a/PLUGINS.md b/PLUGINS.md index f040e77..a095cfe 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -99,7 +99,7 @@ PatternFly team tools and skill incubation — issue triage, release management, | `icon-finder` | Find Red Hat Design System icons (@rhds/icons) by keyword or use case with visual previews. | | `pf-analyze-modifiers` | Analyze PatternFly modifier class (pf-m-*) usage across SCSS files and generate usage reports. | | `pf-bug-triage` | Triage PatternFly bug reports — assess completeness, suggest fixes, identify affected components, and recommend assignees. | -| `pf-content-review` | Audit and rewrite content to match PatternFly and Red Hat voice and tone standards. | +| `pf-content-review` | Review content against PatternFly and Red Hat voice and tone standards. | | `pf-create-issue` | Create well-structured GitHub issues for PatternFly repositories with templates, follow-up tracking, and duplicate detection. | | `pf-org-version-update` | Update patternfly-org for a new PatternFly release — resolve versions, update package.json and versions.json, and provide build steps. | | `pf-tokens` | Build CSS design tokens for PatternFly core and copy them to the PatternFly repository. | @@ -123,6 +123,7 @@ React component development — coding standards, testing, and structure | Skill | Description | |-------|-------------| +| `pf-component-reuse-check` | Detects custom React components in newly created or modified (uncommitted) code that overlap with PatternFly React components, suggests the PatternFly equivalent, and can replace the custom component then build to verify. | | `pf-component-structure` | Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. | | `pf-design-comments` | Integrate @patternfly/design-comments into React apps for on-page design feedback, pinned comment threads, GitHub Issues sync, and Jira linking. | | `pf-github-pages-deploy` | Deploy a PatternFly React project to GitHub Pages using pfcli deploy. | diff --git a/README.md b/README.md index 5a8cc2c..386c0ef 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ [![License](https://img.shields.io/github/license/patternfly/ai-helpers)](./LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) [![Plugins](https://img.shields.io/badge/plugins-8-blueviolet)](./PLUGINS.md) -[![Skills](https://img.shields.io/badge/skills-31-blue)](./PLUGINS.md) +[![Skills](https://img.shields.io/badge/skills-32-blue)](./PLUGINS.md) AI coding helpers for [PatternFly](https://www.patternfly.org/) development. This repository provides plugins and documentation to help AI tools generate accurate, best-practice PatternFly applications. @@ -33,12 +33,12 @@ Cursor can discover plugins from `.cursor-plugin/` directories. If you also have | Plugin | Description | |--------|-------------| | **a11y** | Accessibility auditing, reporting, and documentation | -| **code‑review** | Code review and quality — adversarial review, security patterns | -| **design‑audit** | Design audit — validate existing code and designs against PatternFly standards | -| **design‑guide** | Design guide — component selection, interaction patterns, AI experience patterns, Figma design creation | +| **code-#8209;review** | Code review and quality — adversarial review, security patterns | +| **design-#8209;audit** | Design audit — validate existing code and designs against PatternFly standards | +| **design-#8209;guide** | Design guide — component selection, interaction patterns, AI experience patterns, Figma design creation | | **migration** | PF version migration — breaking change detection, class scanning, upgrade planning | -| **patternfly‑mcp** | PatternFly MCP server — provides component documentation, design token lookup, and accessibility guidance via the Model Context Protocol | -| **pf‑workshop** | PatternFly team tools and skill incubation — issue triage, release management, codebase auditing, new skill development | +| **patternfly-#8209;mcp** | PatternFly MCP server — provides component documentation, design token lookup, and accessibility guidance via the Model Context Protocol | +| **pf-#8209;workshop** | PatternFly team tools and skill incubation — issue triage, release management, codebase auditing, new skill development | | **react** | React component development — coding standards, testing, and structure | diff --git a/plugins/code-review/agents/pf-assist.md b/plugins/code-review/agents/pf-assist.md index 0e32b57..efc2729 100644 --- a/plugins/code-review/agents/pf-assist.md +++ b/plugins/code-review/agents/pf-assist.md @@ -15,6 +15,7 @@ Identify the current context from the developer's recent activity, then apply th | Sub-skill | What it checks | Plugin | |-----------|---------------|--------| +| `/pf-component-reuse-check` | Custom components in uncommitted changes that overlap PatternFly React APIs | react | | `/pf-component-structure` | Component nesting, wrapper hierarchies, layout composition | react | | `/pf-import-checker` | Import paths across `@patternfly/*` packages | react | | `/pf-raw-colors-scan` | Hardcoded hex/rgb/hsl values that should use design tokens | design-audit | @@ -47,7 +48,7 @@ Identify the current context from the developer's recent activity, then apply th Determine which contexts apply based on observable signals: -- **Validation**: changed or new `.tsx`, `.jsx`, `.css`, `.scss` files that import from `@patternfly/*` +- **Validation**: changed or new `.tsx`, `.jsx`, `.css`, `.scss` files; uncommitted custom React components that may duplicate PatternFly; files that import from `@patternfly/*` - **Testing**: recently implemented or modified components without corresponding test updates - **Scaffolding**: empty or new project directory, `package.json` just created, user asked to scaffold - **Design**: Figma URLs in conversation, design-related user requests, `.figma` references diff --git a/plugins/pf-workshop/README.md b/plugins/pf-workshop/README.md index e95fa7a..58d532e 100644 --- a/plugins/pf-workshop/README.md +++ b/plugins/pf-workshop/README.md @@ -15,7 +15,7 @@ PatternFly team tools and skill incubation — issue triage, release management, - **Icon Finder** (`/pf-workshop:icon-finder`) — Find Red Hat Design System icons (@rhds/icons) by keyword or use case with visual previews. - **PF Analyze Modifiers** (`/pf-workshop:pf-analyze-modifiers`) — Analyze PatternFly modifier class (pf-m-*) usage across SCSS files and generate usage reports. - **PF Bug Triage** (`/pf-workshop:pf-bug-triage`) — Triage PatternFly bug reports — assess completeness, suggest fixes, identify affected components, and recommend assignees. -- **PF Content Review** (`/pf-workshop:pf-content-review`) — Audit and rewrite content to match PatternFly and Red Hat voice and tone standards. +- **PF Content Review** (`/pf-workshop:pf-content-review`) — Review content against PatternFly and Red Hat voice and tone standards. - **PF Create Issue** (`/pf-workshop:pf-create-issue`) — Create well-structured GitHub issues for PatternFly repositories with templates, follow-up tracking, and duplicate detection. - **PF Org Version Update** (`/pf-workshop:pf-org-version-update`) — Update patternfly-org for a new PatternFly release — resolve versions, update package.json and versions.json, and provide build steps. - **PF Tokens** (`/pf-workshop:pf-tokens`) — Build CSS design tokens for PatternFly core and copy them to the PatternFly repository. diff --git a/plugins/react/README.md b/plugins/react/README.md index 77ab081..7b2dff1 100644 --- a/plugins/react/README.md +++ b/plugins/react/README.md @@ -8,6 +8,7 @@ React component development — coding standards, testing, and structure. ### Skills +- **PF Component Reuse Check** (`/react:pf-component-reuse-check`) — Detects custom React components in newly created or modified (uncommitted) code that overlap with PatternFly React components, suggests the PatternFly equivalent, and can replace the custom component then build to verify. - **PF Component Structure** (`/react:pf-component-structure`) — Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. - **PF Design Comments** (`/react:pf-design-comments`) — Integrate @patternfly/design-comments into React apps for on-page design feedback, pinned comment threads, GitHub Issues sync, and Jira linking. - **PF Github Pages Deploy** (`/react:pf-github-pages-deploy`) — Deploy a PatternFly React project to GitHub Pages using pfcli deploy. diff --git a/plugins/react/skills/pf-component-reuse-check/SKILL.md b/plugins/react/skills/pf-component-reuse-check/SKILL.md new file mode 100644 index 0000000..3f50bf8 --- /dev/null +++ b/plugins/react/skills/pf-component-reuse-check/SKILL.md @@ -0,0 +1,151 @@ +--- +name: pf-component-reuse-check +description: >- + Detects custom React components in newly created or modified (uncommitted) + code that overlap with PatternFly React components, suggests the PatternFly + equivalent, and can replace the custom component then build to verify. + Use when creating UI components, reviewing uncommitted React changes, or when + the user asks to prefer PatternFly instead of a custom component. +--- + +# PF Component Reuse Check + +Prefer existing PatternFly React components over custom ones that reinvent the same UI role. + +## Scope — uncommitted changes only + +Analyze **only** files that are newly created or currently modified and not yet committed. The user has already decided on committed code — do not scan or refactor it. + +Identify scope with git: + +```bash +git status --short +git diff --name-only HEAD +git ls-files --others --exclude-standard +``` + +Include: + +- Modified tracked files (`M`, `A`, staged or unstaged) +- Untracked new files + +Exclude: + +- Unchanged committed files +- Deleted files (unless they only remove a custom component you are replacing) +- Generated/vendor directories (`node_modules`, `dist`, `build`, coverage) + +If there is no git repo, ask the user which new/changed files to check. Never invent a whole-repo audit. + +Limit analysis to component-relevant extensions: `.tsx`, `.jsx`, `.ts`, `.js` (and co-located styles only when tied to a candidate component). + +## Workflow + +Track progress: + +``` +- [ ] 1. Collect uncommitted candidates +- [ ] 2. Match against PatternFly React +- [ ] 3. Report suggestions (ask before replacing) +- [ ] 4. Replace (only if requested) +- [ ] 5. Build and verify +``` + +### 1. Collect uncommitted candidates + +From scoped files, find **custom components** being introduced or substantially changed: + +- Exported `function` / `const` components and default exports +- New JSX structures that implement a known UI role (button, modal, alert, table, tabs, empty state, form controls, etc.) +- Local wrappers that mostly re-skin or re-compose primitives into something PatternFly already ships + +Skip: + +- Components that already wrap/compose PatternFly correctly (thin app shells, domain layouts) +- Pure utility hooks, non-UI helpers, test fixtures +- Page/route containers whose job is orchestration, not a reusable UI control + +For each candidate, capture: name, file path, props surface, and intended UI role (1 short sentence). + +### 2. Match against PatternFly React + +Use the PatternFly MCP as the source of truth: + +1. `searchPatternFlyDocs` with role keywords from the candidate (name, props, visual behavior). Try synonyms from [references/role-aliases.md](references/role-aliases.md). +2. `usePatternFlyDocs` for promising matches (schema + examples) to confirm prop/API fit. +3. Prefer `@patternfly/react-core`, `@patternfly/react-table`, `@patternfly/react-charts`, `@patternfly/chatbot`, and `@patternfly/react-component-groups` as appropriate. + +Match confidence: + +| Level | Meaning | +|-------|---------| +| High | Same UI role and enough prop coverage to replace without inventing a new abstraction | +| Medium | Same role, but some custom behavior needs PatternFly props, composition, or a small wrapper | +| Low | Related family only — mention as optional alternative, do not push replacement | + +Do not suggest a match on name similarity alone. Confirm role + interaction model from docs/examples. + +### 3. Report suggestions + +For each High/Medium match, present before changing anything: + +``` +### [ComponentName] → PatternFly [PFComponent] + +- File: path/to/file.tsx +- Confidence: High | Medium +- Why: +- Import: `import { PFComponent } from '@patternfly/...'` +- Docs: +- Gaps: + +Replace with PatternFly? (yes / no / adjust) +``` + +End with a short summary: candidates checked, matches found, no-match custom components kept. + +If no matches: say so briefly and stop. Do not force PatternFly onto domain-specific UI. + +### 4. Replace (only when the user asks) + +When the user confirms replacement (or says to replace / use PatternFly instead): + +1. Replace custom component usage with the PatternFly component API from MCP docs/examples. +2. Map props intentionally; do not invent unsupported props. +3. Add or fix imports (follow `pf-import-checker` rules for charts, chatbot, component-groups). +4. Remove the custom component definition and dead exports when fully replaced. +5. Update call sites in **scoped** files. If a committed file still imports the removed custom component, report it and ask before editing outside scope. +6. For Medium confidence, prefer PatternFly composition first; keep a thin wrapper only if truly required, and say why. + +### 5. Build and verify + +After replacement: + +1. Detect the package manager (`package-lock.json` → npm, `yarn.lock` → yarn, `pnpm-lock.yaml` → pnpm). +2. Ensure required `@patternfly/*` dependencies exist; install only what the replacement needs. +3. Run the project's build script from `package.json` (`build`, else `compile` / `tsc` as available). + +```bash +# examples — use the project's actual scripts +npm run build +# or: yarn build | pnpm run build +``` + +4. If the build fails due to the replacement, fix those errors and rebuild. +5. Report: build command used, pass/fail, files changed, remaining gaps. + +Do not claim success without a successful build (or a clear blocker outside the replacement, such as pre-existing project failures — distinguish those). + +## Guardrails + +- Never expand the audit into committed, untouched components. +- Never replace without an explicit user yes (or an explicit “replace with PatternFly” request in the prompt). +- Never invent PatternFly APIs — confirm with MCP docs/schemas. +- Prefer one clear PatternFly component (or standard composition) over a large custom rewrite. +- If PatternFly coverage is incomplete, recommend keep-custom or hybrid and explain the gap. + +## Related skills + +- `pf-import-checker` — after adding/changing `@patternfly/*` imports +- `pf-component-structure` — when composing nested PatternFly wrappers +- `pf-project-scaffolder` — when the project is missing PatternFly setup diff --git a/plugins/react/skills/pf-component-reuse-check/references/role-aliases.md b/plugins/react/skills/pf-component-reuse-check/references/role-aliases.md new file mode 100644 index 0000000..ddab8f3 --- /dev/null +++ b/plugins/react/skills/pf-component-reuse-check/references/role-aliases.md @@ -0,0 +1,48 @@ +# Role → PatternFly search aliases + +Use these synonyms when `searchPatternFlyDocs` with the custom component name returns nothing useful. Prefer the PF component name that matches **role**, not the local class name. + +| Custom role / wording | Search terms | Likely PatternFly | +|----------------------|--------------|-------------------| +| Primary / secondary / danger click target | button, action | Button | +| Icon-only control | button, plain | Button (`variant="plain"`) | +| Link styled as button | button, link | Button (`variant="link"`) | +| Banner / toast / inline message | alert, notification | Alert, NotificationDrawer, AlertGroup | +| Confirm / dialog / popup | modal, dialog | Modal | +| Side panel / slide-over | drawer, panel | Drawer | +| Card / tile / info box | card | Card | +| Empty list / no data | empty state | EmptyState | +| Tabs / tabbed panel | tabs | Tabs, Tab | +| Nav item / side nav | navigation, nav | Nav, NavItem, NavList | +| Top bar / header bar | masthead, page | Masthead, Page | +| Page body section | page section | PageSection | +| Data table / grid table | table | Table, Thead, Tbody, Tr, Th, Td | +| Description / term list | description list | DescriptionList | +| List of records | data list | DataList | +| Toolbar / filter bar | toolbar | Toolbar, ToolbarItem, ToolbarContent | +| Form field / input | form, text input | Form, FormGroup, TextInput, TextArea | +| Checkbox / radio | checkbox, radio | Checkbox, Radio | +| Select / dropdown select | select, menu | Select, Menu, Dropdown | +| Chip / tag / label pill | label, chip | Label, LabelGroup | +| Badge / count | badge | Badge | +| Spinner / loading | spinner, progress | Spinner, Progress | +| Skeleton placeholder | skeleton | Skeleton | +| Switch / toggle | switch | Switch | +| Tooltip / hint | tooltip, popover | Tooltip, Popover | +| Accordion / expand section | accordion, expand | Accordion, ExpandableSection | +| Wizard / multi-step | wizard | Wizard | +| Pagination | pagination | Pagination | +| Search input | search, text input | SearchInput, TextInput | +| Breadcrumb | breadcrumb | Breadcrumb | +| Truncate / overflow menu | overflow menu | OverflowMenu, Menu | +| Dual list / transfer | dual list | DualListSelector | +| Tree | tree | TreeView | +| Chart / graph | chart | Chart* (`@patternfly/react-charts`) | +| Chat / assistant UI | chatbot | Chatbot (`@patternfly/chatbot`) | +| Bulk select | bulk select | BulkSelect (`@patternfly/react-component-groups`) | + +## Matching notes + +- Domain names (`VmPowerButton`, `ClusterStatusAlert`) still map by **role** (Button, Alert), not by domain nouns. +- A custom component that only adds business logic around a PF primitive is usually a keep; suggest composing PatternFly instead of replacing the domain logic. +- If several PF components fit, pick the one whose examples closest match interaction (e.g. modal confirm vs inline Alert).