diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 259a144..3b920fc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -7,7 +7,27 @@ { "name": "pf-react", "source": "./plugins/pf-react", - "description": "PatternFly React coding standards and test generation agents" + "description": "PatternFly React coding standards and unit test generation agents" + }, + { + "name": "pf-design-tokens", + "source": "./plugins/pf-design-tokens", + "description": "Design token auditing, validation, and migration for PatternFly styling" + }, + { + "name": "pf-a11y", + "source": "./plugins/pf-a11y", + "description": "Accessibility auditing, reporting, and documentation for PatternFly applications" + }, + { + "name": "pf-figma", + "source": "./plugins/pf-figma", + "description": "Figma design review, diffing, and asset identification for PatternFly" + }, + { + "name": "pf-workflow", + "source": "./plugins/pf-workflow", + "description": "Issue tracking, PR management, and cross-repo coordination for PatternFly projects" } ] } diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json new file mode 100644 index 0000000..3b920fc --- /dev/null +++ b/.cursor-plugin/marketplace.json @@ -0,0 +1,33 @@ +{ + "name": "ai-helpers", + "owner": { + "name": "PatternFly Team" + }, + "plugins": [ + { + "name": "pf-react", + "source": "./plugins/pf-react", + "description": "PatternFly React coding standards and unit test generation agents" + }, + { + "name": "pf-design-tokens", + "source": "./plugins/pf-design-tokens", + "description": "Design token auditing, validation, and migration for PatternFly styling" + }, + { + "name": "pf-a11y", + "source": "./plugins/pf-a11y", + "description": "Accessibility auditing, reporting, and documentation for PatternFly applications" + }, + { + "name": "pf-figma", + "source": "./plugins/pf-figma", + "description": "Figma design review, diffing, and asset identification for PatternFly" + }, + { + "name": "pf-workflow", + "source": "./plugins/pf-workflow", + "description": "Issue tracking, PR management, and cross-repo coordination for PatternFly projects" + } + ] +} diff --git a/.cursor/rules/patternfly-vibe-coding.mdc b/.cursor/rules/patternfly-vibe-coding.mdc deleted file mode 100644 index e156324..0000000 --- a/.cursor/rules/patternfly-vibe-coding.mdc +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: Enforces PatternFly Vibe coding standards and documentation best practices for all PatternFly React code. -globs: "**/*.{js,jsx,ts,tsx,css,scss}" -alwaysApply: true ---- -# PatternFly Vibe Coding Rule - -## Purpose -Always reference the README and markdown documentation in this repository when generating, editing, or reviewing any PatternFly (PF) code. These files contain the authoritative best practices, guidelines, and up-to-date standards for PatternFly development. - -## Scope -This rule applies to all code generation, refactoring, and review tasks involving PatternFly React, PatternFly Chatbot, and related UI components in this project. - -## Documentation to Reference -- The root `README.md` -- The `docs/README.md` file, which serves as the table of contents for all documentation in the `docs/` 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 `docs/README.md`. - -## Rule -- **Always consult the above documentation before generating or editing any PatternFly code.** -- **Use the documented best practices for component usage, styling, accessibility, and layout.** -- **Prefer semantic design tokens and utility classes as described in the docs.** -- **Follow accessibility and ARIA guidelines from the documentation.** -- **Reference official PatternFly components and avoid custom solutions unless explicitly allowed.** -- **If a question arises, search these docs first before using external sources.** - -## Example Prompt -> "When generating PatternFly code, use the guidelines and examples from all README and markdown files in this repository, especially those referenced in docs/README.md. Follow the documented best practices for styling, accessibility, and component usage." - -## Enforcement -If code is generated or edited without following these documentation sources, request changes and point to the relevant section in the docs. diff --git a/CLAUDE.md b/CLAUDE.md index 79a71ee..9eb502d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,19 +1,20 @@ # PatternFly AI Helpers -This repository contains AI coding helpers for PatternFly development, including Claude Code plugins, Cursor rules, and AI-friendly documentation. +This repository contains AI coding helpers for PatternFly development, including Claude Code and Cursor plugins and AI-friendly documentation. ## Key Directories -- `plugins/` - Claude Code plugins with commands and agents +- `plugins/` - Claude Code and Cursor plugins with skills and agents - `docs/` - AI-friendly PatternFly documentation, guidelines, and reference data -- `.cursor/rules/` - Cursor IDE rules for PatternFly development -- `.claude-plugin/` - Plugin marketplace configuration +- `.claude-plugin/` / `.cursor-plugin/` - Marketplace config (identical manifests for each tool) ## Available Plugins -- **pf-react** - PatternFly React coding standards and test generation agents - - `/coding-standards` - PatternFly v6 React coding standards - - `/test-generator` - Generate unit tests following Testing Library best practices +- **pf-react** - PatternFly React coding standards and unit test standards agents +- **pf-design-tokens** - Design token auditing, validation, and migration for PatternFly styling +- **pf-a11y** - Accessibility auditing, reporting, and documentation for PatternFly applications +- **pf-figma** - Figma design review, diffing, and asset identification for PatternFly +- **pf-workflow** - Issue tracking, PR management, and cross-repo coordination for PatternFly projects ## Documentation diff --git a/CONTRIBUTING-SKILLS.md b/CONTRIBUTING-SKILLS.md new file mode 100644 index 0000000..8205b16 --- /dev/null +++ b/CONTRIBUTING-SKILLS.md @@ -0,0 +1,170 @@ +# How to Create and Contribute a Skill + +## Step 1: Create your skill locally + +Work in any project directory or an empty one — NOT in the `ai-helpers` repo. + +```bash +mkdir my-skill-workspace +cd my-skill-workspace +``` + +Open your AI tool (Claude Code, Cursor, etc.): + +```bash +claude # or open the project in Cursor +``` + +## Step 2: Describe what you want + +Describe what you want. Be specific about what the skill should do, what the output should look like, and who it's for. For example: + +``` +Create a skill called "component-doc" that generates a usage guide +from a React component's source code. It should output the component name, +a plain-language description of what it does, a list of its props with types, +and a basic usage example. Write it for someone who hasn't seen the component before. +``` + +This will create a `skills/your-skill-name/SKILL.md` file. + +## Step 3: Test it + +Use the skill right there in your workspace: + +``` +/your-skill-name +``` + +Point it at a real file or scenario and see if the output is useful. If not, iterate: + +``` +The output is too verbose. Keep each section to 2-3 sentences max. +``` + +``` +It's not explaining the props clearly enough. Add the default values. +``` + +Iterate until the output matches what you'd actually want to see. + +## Step 4: Review your SKILL.md + +Open the file and read it. It's just markdown. Ask yourself: + +- Are the instructions clear enough that any AI tool would produce the same quality output? +- Is there anything tool-specific that wouldn't work in both Claude Code and Cursor? +- Is it under 500 lines? Shorter is better. + +## Step 5: Pick the right plugin + +Every skill or agent must live in a plugin. Pick the one that matches your skill's domain: + +| Plugin | Domain | Example skills | When to use | +|--------|--------|----------------|-------------| +| **pf-react** | React components, coding standards, testing | `component-suggest`, `feasibility-check`, `pf-upgrade`, `unit-test-generator`, `bug-triage` | Your skill helps write, test, review, triage, or migrate PatternFly React code | +| **pf-design-tokens** | Design tokens, CSS variables, color contrast | `hex-scan`, `css-var-audit`, `token-contrast`, `suggest-tokens` | Your skill audits, validates, or suggests design tokens | +| **pf-a11y** | Accessibility, WCAG, ARIA, screen readers | `audit`, `doc-scaffold` | Your skill checks, reports on, or documents accessibility | +| **pf-figma** | Figma designs, design-to-code, assets | `design-review`, `design-diff`, `icon-id`, `brand-assets` | Your skill works with Figma designs, icons, or brand assets | +| **pf-workflow** | Issue tracking, PR management, cross-repo coordination | `create-issue`, `dependency-recommender`, `pr-description`, `changelog-entry`, `release-notes` | Your skill helps with PatternFly project workflows, issue/PR management, contributor coordination, or repo-level tooling (e.g. dependency suggestions) | + +**How to decide:** +- Ask yourself: "Who installs this?" A React developer? → `pf-react`. A designer working in Figma? → `pf-figma`. +- If your skill spans two domains (e.g., checking token contrast in a React component), pick the domain that best describes the *primary task*, not the input. +- If it doesn't fit any plugin, open an issue to discuss — don't create a new plugin without coordination. + +**Skill vs agent:** +- **Skill** — a task that produces a result: "generate tests," "audit for accessibility," "find an icon." Most contributions are skills. +- **Agent** — domain knowledge the AI follows: "always follow these coding standards," "when reviewing designs, always verify brand colors and 8px grid spacing." Only create an agent if it's foundational context that improves *every* interaction in that plugin's area. + +**Litmus test:** Can someone use the result? Skill. Is it knowledge the AI should always follow? Agent. When in doubt, write a skill. + +**They work together:** An agent's knowledge is loaded automatically when the AI detects relevant context. So if you invoke a skill like `unit-test-generator`, the `coding-standards` agent's knowledge is also active — the agent makes the skill's output better. + +## Step 6: Contribute it + +Once you're happy with the skill: + +1. Fork and clone `patternfly/ai-helpers` +2. Copy your `SKILL.md` into `plugins//skills/your-skill-name/SKILL.md` +3. Open a pull request + +Your skill becomes available as `/:your-skill-name` for anyone who installs the plugin. + +--- + +## What makes a good skill? + +**Good skills are specific.** "Summarize a file" is good. "Help with code" is too vague. + +**Good skills define the output format.** Specify what sections to include, how long each should be, and what tone to use. + +**Good skills include examples.** Show what good output looks like AND what bad output looks like. + +**Good skills are short.** If your SKILL.md is over 200 lines, you're probably over-explaining. Say what you want, not how to think. The [Claude Code docs recommend under 500 lines](https://code.claude.com/docs/en/skills#add-supporting-files) as a ceiling — beyond that, move reference content into supporting files alongside your SKILL.md. + +**Good skills describe outcomes, not implementation.** Tell the AI what to accomplish, not how to do it. The AI already knows how to use `git`, `gh`, `grep`, and other tools — you don't need to spell out exact commands or multi-step conditional logic. A single sentence like "Check for issue templates locally, then via GitHub CLI, falling back to a blank issue" is better than 70 lines of bash scripts and if/else branches. + +**Good skills are tool-agnostic.** Skills in this repo work in both Claude Code and Cursor. Avoid referencing a specific tool in your instructions or examples (e.g., use "Assistant:" instead of "Claude:" in example conversations). + +## What does a SKILL.md look like? + +Here's an example `summarize` skill — the entire file: + +```markdown +--- +name: summarize +description: Summarize code, files, PRs, or directories for a mixed audience +--- + +Provide clear, concise summaries of code, files, pull requests, +or entire directories. Write for a mixed audience of designers, +developers, and stakeholders. + +## How to Summarize + +### When given a file or code block + +1. Read the file or code provided. +2. Produce a summary with these sections: + +**What it does** — One or two sentences in plain language. + +**Key details** — 3-6 bullets of the important things happening inside. + +**Dependencies** — What does this file rely on? + +**Who cares** — Who needs to know about this file and why. + +## Tone and Style + +- Write like you're explaining to a coworker over coffee. +- Use short sentences. Avoid filler. +- No jargon without explanation. +- Shorter is better. +``` + +We recommend adding YAML frontmatter with a `name` and `description` to every SKILL.md. While skills are discovered by directory path, frontmatter improves compatibility with third-party tooling: + +```yaml +--- +name: summarize +description: Summarize code, files, PRs, or directories for a mixed audience +--- +``` + +After the frontmatter, it's just instructions in markdown. No code. No config. + +## Skill ideas to get you started + +| Skill | What it does | +|---|---| +| `component-doc` | Generate a usage guide from a component's source | +| `changelog` | Generate a changelog entry from recent git commits | +| `migration-helper` | Help migrate PatternFly v5 code to v6 | +| `test-plan` | Generate a QA test plan from a PR diff | +| `design-review` | Check a component against PatternFly design guidelines | +| `api-mock` | Generate mock data from a TypeScript interface | +| `rename` | Suggest better names for variables and functions | +| `pr-description` | Generate a clear PR description from a diff | +| `bug-triage` | Preliminary triage of bug issues with fix suggestions and maintainer tagging | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9caf68..34e30dc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,59 @@ # Contributing to PatternFly AI Helpers -We welcome contributions of new plugins, commands, agents, documentation, and Cursor rules. +We welcome contributions of new plugins, skills, agents, and documentation. + +Plugins in this repo work in both **Claude Code** and **Cursor**. Each plugin has both a `.claude-plugin/` and `.cursor-plugin/` directory with identical manifests, so each tool discovers it natively. ## Repository Structure ``` -plugins/ # Claude Code plugins (each with commands/, agents/, skills/) -docs/ # AI-friendly PatternFly documentation -.cursor/rules/ # Cursor IDE rules -.claude-plugin/ # Plugin marketplace configuration +plugins/ # Plugins (skills, agents, MCP servers) +docs/ # AI-friendly PatternFly documentation +.claude-plugin/ # Marketplace config (Claude Code) +.cursor-plugin/ # Marketplace config (Cursor) ``` -## Adding a New Claude Code Plugin +## Adding a Skill to an Existing Plugin + +This is the simplest way to contribute. See [CONTRIBUTING-SKILLS.md](CONTRIBUTING-SKILLS.md) for a full walkthrough. + +1. Create a directory under the plugin's `skills/` folder: `plugins//skills/your-skill/` +2. Add a `SKILL.md` with your instructions in plain markdown +3. Open a pull request + +Your skill becomes available as `/:your-skill` once merged. + +## Creating a New Plugin + +Create a new plugin when your contribution doesn't fit into an existing one — for example, a new domain like charts, chatbot patterns, or migration tooling. 1. Create a new directory under `plugins/your-plugin-name/` -2. Add a `.claude-plugin/plugin.json` with required metadata: +2. Add a `plugin.json` to both `.claude-plugin/` and `.cursor-plugin/` (identical content): ```json { "name": "your-plugin-name", "description": "What your plugin does", - "version": "0.0.1", + "version": "1.0.0", "author": { "name": "Your Name" } } ``` -3. Add commands under `commands/` and/or agents under `agents/` as `.md` files -4. Register your plugin in `.claude-plugin/marketplace.json` -5. Add a `README.md` documenting your plugin's commands and usage + Both directories contain the same file so each tool discovers the plugin natively. +3. Add skills under `skills/`, agents under `agents/`, or both +4. Register your plugin in both `.claude-plugin/marketplace.json` and `.cursor-plugin/marketplace.json` at the repo root +5. Add a `README.md` documenting your plugin -## Adding a Command or Agent to an Existing Plugin +### Skills vs Agents -1. Add your `.md` file to the appropriate `commands/` or `agents/` directory -2. Commands need frontmatter with at minimum a `description` field -3. Agents need frontmatter with `name`, `description`, and `color` fields -4. Do **not** hardcode a `model:` in agent frontmatter -- let users choose their preferred model +- **Skills** (`skills/your-skill/SKILL.md`) — tasks that produce a result. Use this for most contributions. +- **Agents** (`agents/your-agent.md`) — domain knowledge the AI follows. Use for standards and guidelines. ## Adding Documentation 1. Add markdown files under `docs/` following the existing directory structure 2. Update `docs/README.md` (table of contents) to link to your new content -## Adding Cursor Rules - -1. Add `.mdc` files to `.cursor/rules/` -2. Follow the existing frontmatter pattern with `description`, `globs`, and `alwaysApply` - ## Submitting Changes 1. Fork the repository @@ -57,5 +65,6 @@ docs/ # AI-friendly PatternFly documentation - Use kebab-case for directory and file names - Include clear descriptions in all frontmatter -- Test your plugins locally before submitting +- Test your skills locally before submitting - Keep documentation concise and AI-friendly +- Don't hardcode a `model:` in agent frontmatter — let users choose their preferred model diff --git a/README.md b/README.md index 590e535..3412f8a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # PatternFly AI Helpers -AI coding helpers for [PatternFly](https://www.patternfly.org/) development. This repository provides plugins, rules, and documentation to help AI tools (Claude Code, Cursor, Copilot, etc.) generate accurate, best-practice PatternFly applications. +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. + +Plugins work in both **Claude Code** and **Cursor**. The content is identical — only the install path differs. ## Quick Start @@ -14,54 +16,52 @@ AI coding helpers for [PatternFly](https://www.patternfly.org/) development. Thi /plugin install pf-react@ai-helpers ``` -After installation, use the commands in any project: - -```bash -/coding-standards # PatternFly v6 React coding standards -/test-generator # Generate unit tests following Testing Library best practices -``` - -See [plugins/pf-react/](plugins/pf-react/) for full documentation. +After installation, the plugin's agents and skills are available in any project. ### Cursor -Copy the `.cursor/rules/` directory into your project to enable PatternFly best-practice enforcement. +Cursor can discover plugins from `.cursor-plugin/` directories. If you also have Claude Code installed, Cursor may pick up installed plugins automatically via its third-party plugin settings. + +## Available Plugins -### Other AI Tools +| Plugin | Description | +|--------|-------------| +| **pf-react** | PatternFly React coding standards, testing, and development | +| **pf-design-tokens** | Design token auditing, validation, and migration | +| **pf-a11y** | Accessibility auditing, reporting, and documentation | +| **pf-figma** | Figma design review, diffing, and asset identification | -Copy the `docs/` directory into your project workspace. AI tools index local files for context, so having the documentation present locally ensures accurate PatternFly guidance. +Each plugin includes skills, agents, and a [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp). Browse each plugin's `skills/` and `agents/` directories for what's available. ## Repository Structure ``` ai-helpers/ -├── plugins/ # Claude Code plugins -│ └── pf-react/ # PatternFly React coding standards & test generation +├── plugins/ # Plugins (work in both Claude Code and Cursor) +│ ├── pf-react/ # React coding standards, testing +│ ├── pf-design-tokens/ # Design token auditing and migration +│ ├── pf-a11y/ # Accessibility auditing and reporting +│ └── pf-figma/ # Figma design review and diffing ├── docs/ # AI-friendly PatternFly documentation -│ ├── guidelines/ # Coding standards, styling, accessibility -│ ├── components/ # Component-specific patterns -│ ├── charts/ # Chart guidelines -│ └── chatbot/ # Chatbot patterns -├── .cursor/rules/ # Cursor IDE rules -├── .claude-plugin/ # Plugin marketplace configuration -└── .claude/ # Claude Code settings +│ ├── guidelines/ +│ ├── components/ +│ ├── charts/ +│ └── chatbot/ +├── .claude-plugin/ # Marketplace config (Claude Code) +└── .cursor-plugin/ # Marketplace config (Cursor) ``` +Both `.claude-plugin/` and `.cursor-plugin/` contain identical manifests so each tool discovers plugins natively. + ## Documentation The `docs/` directory contains comprehensive, AI-friendly PatternFly documentation. See [docs/README.md](docs/README.md) for the full table of contents. -### Using Documentation with AI Tools - -AI tools only index files present in your local workspace. To get the full benefit: - -1. Clone or copy this repository (or at least the `docs/` directory) into your project -2. Open your project in your AI coding tool -3. The tool will automatically reference the documentation for PatternFly guidance - ## Contributing -See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding plugins, commands, documentation, and Cursor rules. +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding plugins, skills, and documentation. + +See [CONTRIBUTING-SKILLS.md](CONTRIBUTING-SKILLS.md) for a step-by-step guide to creating and contributing a skill. ## References diff --git a/plugins/pf-a11y/.claude-plugin/plugin.json b/plugins/pf-a11y/.claude-plugin/plugin.json new file mode 100644 index 0000000..a040d1f --- /dev/null +++ b/plugins/pf-a11y/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-a11y", + "description": "Accessibility auditing, reporting, and documentation for PatternFly applications", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-a11y/.cursor-plugin/plugin.json b/plugins/pf-a11y/.cursor-plugin/plugin.json new file mode 100644 index 0000000..a040d1f --- /dev/null +++ b/plugins/pf-a11y/.cursor-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-a11y", + "description": "Accessibility auditing, reporting, and documentation for PatternFly applications", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-a11y/README.md b/plugins/pf-a11y/README.md new file mode 100644 index 0000000..cef6e13 --- /dev/null +++ b/plugins/pf-a11y/README.md @@ -0,0 +1,57 @@ +# PatternFly Accessibility Plugin + +AI plugin for accessibility auditing, reporting, and documentation in PatternFly applications. Works in both **Claude Code** and **Cursor**. + +## Installation + +### Claude Code + +```bash +# Add the PatternFly marketplace +/plugin marketplace add patternfly/ai-helpers + +# Install the plugin +/plugin install pf-a11y@ai-helpers +``` + +### Cursor + +See the [root README](../../README.md) for Cursor installation options. + +## What's Included + +Skills and agents for PatternFly accessibility: + +- Automated a11y audits with standard report output +- WCAG conformance checking +- Accessibility documentation scaffolding +- UI review for PatternFly conformance and deviations + +Browse `skills/` for available skills (invoked as `/pf-a11y:`) and `agents/` for domain knowledge. + +### PatternFly MCP Server + +Skills and agents have access to the [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp) for looking up component documentation and accessibility guidelines. No manual configuration needed. + +## File Structure + +``` +pf-a11y/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest + MCP server config +├── .cursor-plugin/ +│ └── plugin.json # Identical copy for Cursor +├── skills/ # Tasks that produce a result +├── agents/ # Domain knowledge the AI follows +└── README.md +``` + +## Sources + +- [PatternFly.org](https://www.patternfly.org/) +- [PatternFly Accessibility Guide](https://www.patternfly.org/accessibility/accessibility-fundamentals) +- [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) + +## License + +MIT diff --git a/plugins/pf-design-tokens/.claude-plugin/plugin.json b/plugins/pf-design-tokens/.claude-plugin/plugin.json new file mode 100644 index 0000000..ac15c2f --- /dev/null +++ b/plugins/pf-design-tokens/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-design-tokens", + "description": "Design token auditing, validation, and migration for PatternFly styling", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-design-tokens/.cursor-plugin/plugin.json b/plugins/pf-design-tokens/.cursor-plugin/plugin.json new file mode 100644 index 0000000..ac15c2f --- /dev/null +++ b/plugins/pf-design-tokens/.cursor-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-design-tokens", + "description": "Design token auditing, validation, and migration for PatternFly styling", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-design-tokens/README.md b/plugins/pf-design-tokens/README.md new file mode 100644 index 0000000..f7f6c2d --- /dev/null +++ b/plugins/pf-design-tokens/README.md @@ -0,0 +1,57 @@ +# PatternFly Design Tokens Plugin + +AI plugin for PatternFly design token auditing, validation, and migration. Works in both **Claude Code** and **Cursor**. + +## Installation + +### Claude Code + +```bash +# Add the PatternFly marketplace +/plugin marketplace add patternfly/ai-helpers + +# Install the plugin +/plugin install pf-design-tokens@ai-helpers +``` + +### Cursor + +See the [root README](../../README.md) for Cursor installation options. + +## What's Included + +Skills and agents for working with PatternFly design tokens: + +- Scanning for raw hex values missing a token mapping +- Checking CSS variable definitions for completeness +- Validating token contrast ratios against AA/AAA standards +- Suggesting semantic tokens for common use cases +- Mapping Figma-only token references to code equivalents + +Browse `skills/` for available skills (invoked as `/pf-design-tokens:`) and `agents/` for domain knowledge. + +### PatternFly MCP Server + +Skills and agents have access to the [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp) for looking up component documentation and token references. No manual configuration needed. + +## File Structure + +``` +pf-design-tokens/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest + MCP server config +├── .cursor-plugin/ +│ └── plugin.json # Identical copy for Cursor +├── skills/ # Tasks that produce a result +├── agents/ # Domain knowledge the AI follows +└── README.md +``` + +## Sources + +- [PatternFly.org](https://www.patternfly.org/) +- [PatternFly Design Tokens](https://www.patternfly.org/design-foundations/tokens) + +## License + +MIT diff --git a/plugins/pf-design-tokens/skills/pf-tokens/SKILL.md b/plugins/pf-design-tokens/skills/pf-tokens/SKILL.md new file mode 100644 index 0000000..2a7d805 --- /dev/null +++ b/plugins/pf-design-tokens/skills/pf-tokens/SKILL.md @@ -0,0 +1,11 @@ +Build CSS design tokens for PatternFly core and move them to the PatternFly repository. + +## What to do + +1. Build the SCSS for PatternFly core using the `build:scss:core` script +2. Copy the generated CSS files from the build output to the PatternFly repository's token directory (PatternFly is typically cloned as a sibling directory) + +## Expected outcome + +The PatternFly repository's `src/patternfly/base/tokens/` directory contains the freshly built CSS token files from this repository's build output at `packages/module/build/css/`. + diff --git a/plugins/pf-design-tokens/skills/raw-colors-scan/SKILL.md b/plugins/pf-design-tokens/skills/raw-colors-scan/SKILL.md new file mode 100644 index 0000000..9847fb8 --- /dev/null +++ b/plugins/pf-design-tokens/skills/raw-colors-scan/SKILL.md @@ -0,0 +1,30 @@ +--- +name: raw-colors-scan +description: "Analyze the provided code to find any raw color values assigned to styling properties. Flag these values as technical debt and suggest their replacement with design tokens." +--- + +### Role +You are a Senior Design Systems Engineer specializing in CSS refactoring and Design Token implementation. + +### Objective +Analyze the provided code to find any raw color values (HEX, RGB, RGBA, HSL, HSLA) assigned to styling properties. Flag these values as technical debt and suggest their replacement with design tokens. + +### Scanning Logic +1. **Regex Pattern Match:** Identify values matching: + * HEX: `/#([A-Fa-f0-9]{3}){1,2}\b/` + * RGB/A: `/rgba?\((\d+,\s*){2,3}\d+(,\s*0?\.\d+)?\)/` + * HSL/A: `/hsla?\(\d+,\s*([\d.]+%,\s*){1,2}[\d.]+(%|,\s*0?\.\d+)?\)/` +2. **Named Colors (The "X11 List"):** + * Identify all 148 CSS standard named color (e.g., from 'aliceblue' through 'yellowgreen'). + * **Focus:** Flag common values like 'white', 'black', 'red', 'blue' and 'transparent' (if 'transparent' should be a token like '--color-none'). +3. **Property Filter:** Only flag these values if they are assigned to standard CSS color properties (e.g., `background-color`, `border`, `box-shadow`). +4. **Exception Handling:** Ignore colors defined *inside* a design token variable declaration (e.g., ignore the value in `$blue-500: #007bff;`). + +### Output Format +For every violation found, provide: +- **File Name:** [Name] +- **File Path:** [Path] +- **Line Number:** [Number] +- **Property:** [The CSS Property] +- **Raw Value:** [The detected color] +- **Recommendation:** "Replace with a semantic or primitive design token (e.g., --color-brand-primary)." \ No newline at end of file diff --git a/plugins/pf-figma/.claude-plugin/plugin.json b/plugins/pf-figma/.claude-plugin/plugin.json new file mode 100644 index 0000000..cf6eb72 --- /dev/null +++ b/plugins/pf-figma/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-figma", + "description": "Figma design review, diffing, and asset identification for PatternFly", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-figma/.cursor-plugin/plugin.json b/plugins/pf-figma/.cursor-plugin/plugin.json new file mode 100644 index 0000000..cf6eb72 --- /dev/null +++ b/plugins/pf-figma/.cursor-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-figma", + "description": "Figma design review, diffing, and asset identification for PatternFly", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-figma/README.md b/plugins/pf-figma/README.md new file mode 100644 index 0000000..4d01a89 --- /dev/null +++ b/plugins/pf-figma/README.md @@ -0,0 +1,57 @@ +# PatternFly Figma Plugin + +AI plugin for Figma design review, diffing, and asset identification for PatternFly. Works in both **Claude Code** and **Cursor**. + +## Installation + +### Claude Code + +```bash +# Add the PatternFly marketplace +/plugin marketplace add patternfly/ai-helpers + +# Install the plugin +/plugin install pf-figma@ai-helpers +``` + +### Cursor + +See the [root README](../../README.md) for Cursor installation options. + +## What's Included + +Skills and agents for the Figma-to-code workflow: + +- Reviewing Figma designs for PatternFly conformance +- Comparing Figma designs against coded implementations +- Detecting changes between Figma design versions +- Summarizing implementation work from design updates +- Identifying icons and brand assets + +Browse `skills/` for available skills (invoked as `/pf-figma:`) and `agents/` for domain knowledge. + +### PatternFly MCP Server + +Skills and agents have access to the [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp) for looking up component documentation and design guidelines. No manual configuration needed. + +## File Structure + +``` +pf-figma/ +├── .claude-plugin/ +│ └── plugin.json # Plugin manifest + MCP server config +├── .cursor-plugin/ +│ └── plugin.json # Identical copy for Cursor +├── skills/ # Tasks that produce a result +├── agents/ # Domain knowledge the AI follows +└── README.md +``` + +## Sources + +- [PatternFly.org](https://www.patternfly.org/) +- [PatternFly Design Kit (Figma)](https://www.figma.com/community/file/1370151925110689873) + +## License + +MIT diff --git a/plugins/pf-figma/skills/figma-changes/README.md b/plugins/pf-figma/skills/figma-changes/README.md new file mode 100644 index 0000000..39cd715 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/README.md @@ -0,0 +1,190 @@ +# Figma Design Change Tracker Skill + +Track Figma design updates and maintain alignment between design and code. + +## What This Skill Does + +This skill helps you: +- 📊 Track changes in Figma design files +- 📝 Generate comprehensive changelogs with timestamps and authors +- 🔍 Compare Figma design tokens with your codebase +- ✅ Create actionable checklists for code updates +- 🎨 Identify token discrepancies between design and implementation + +## When to Use + +The skill automatically triggers when you: +- Ask to "check Figma updates" +- Want to "compare Figma with code" +- Need to "audit design tokens" +- Mention "design system updates" +- Discuss "sync design and code" + +## Quick Start + +1. **Get your Figma access token** (optional but recommended): + - Go to https://www.figma.com/developers/api#access-tokens + - Generate a personal access token + - Store it: `export FIGMA_ACCESS_TOKEN="your-token"` + +2. **Have your Figma file URL ready**: + ``` + https://www.figma.com/file/ABC123/My-Design-System + ``` + +3. **Ask Claude**: + ``` + Check for Figma updates and compare with our code + ``` + +## Example Workflows + +### Track Recent Changes +``` +What changed in our Figma design system in the last week? +``` + +### Compare Specific Component +``` +Compare the Button component in Figma with our code implementation +``` + +### Audit Design Tokens +``` +Audit all color tokens - are they in sync with Figma? +``` + +### Generate Update Checklist +``` +What code changes do we need to match the latest Figma designs? +``` + +## Output Format + +The skill generates: + +1. **Executive Summary**: Overview of changes +2. **Detailed Changelog**: Component-by-component breakdown +3. **Token Comparison Table**: Figma vs Code values +4. **Action Items Checklist**: Prioritized updates with file paths +5. **Next Steps**: Recommendations + +## Files in This Skill + +- `SKILL.md` - Main skill instructions +- `references/` - Report templates and API guides +- `scripts/extract-figma-file-key.sh` - Extract file key from URL +- `scripts/compare-tokens.sh` - Automated token comparison (with Node.js validation) +- `scripts/compare-tokens.js` - Token comparison implementation + +## Configuration + +### Token Directory +Default: `src/patternfly/base/tokens` + +If your tokens are elsewhere, just mention it: +``` +My tokens are in src/styles/tokens +``` + +### Token Formats Supported +- SCSS variables (`$color-primary`) +- CSS custom properties (`--pf-global--color`) +- JSON token files +- JavaScript/TypeScript exports + +## Tips + +- Run checks weekly to catch changes early +- Keep a mapping between Figma frames and code components +- Tag code releases with corresponding Figma version +- Share reports with both design and dev teams + +## Troubleshooting + +**"Can't access Figma file"** +- File might be private - provide access token +- Check file URL is correct +- Ensure you have view permissions + +**"Token files not found"** +- Specify correct token directory path +- Check if tokens are in node_modules (PatternFly packages) + +**"No recent changes detected"** +- Verify date range +- Check if you're looking at the right file +- Figma version history requires authentication + +## FAQ + +### General Questions + +**Q: Should designers run this or developers?** +A: Both! Designers can verify their changes landed correctly in code, and developers can check what needs updating. The skill is designed to bridge the design-development gap. + +**Q: How often should we sync?** +A: Weekly for active projects with frequent design changes, bi-weekly for stable projects. Consider running it before each sprint planning session. + +**Q: What if the token names don't match between Figma and code?** +A: Create a token mapping file (see `examples/token-mappings.json`) to define relationships between Figma names and code token names. This enables fuzzy matching. + +**Q: Does this work with Figma Variables or just Styles?** +A: Currently optimized for Styles. Figma Variables support can be added - check the Figma API endpoint `/files/{key}/variables/local`. + +**Q: Can this work with other design systems besides PatternFly?** +A: Yes! Just update the token directory paths and naming conventions. The core workflow is design-system agnostic. + +### Workflow Questions + +**Q: Who should approve the generated reports?** +A: Ideally, a cross-functional review: design lead validates design accuracy, tech lead validates code feasibility, product manager prioritizes updates. + +**Q: Should we commit the generated reports to git?** +A: Yes for FIGMA_CHANGELOG.md and RELEASE_NOTES.md (team documentation). The detailed update checklist (figma-updates-*.md) can be gitignored if it's task-specific. + +**Q: What if we use a monorepo?** +A: Run the sync from your package directory or specify full paths to token directories. See [troubleshooting.md](references/troubleshooting.md) for monorepo examples. + +**Q: Can we automate this in CI/CD?** +A: Yes! You can create a GitHub Action that runs weekly and creates a PR with the sync results. Example workflow coming soon. + +### Technical Questions + +**Q: What Node.js version is required?** +A: Node.js 14+ is recommended. The scripts use standard ES6+ features without exotic dependencies. + +**Q: Does this modify our code automatically?** +A: No. This is a reporting tool only. It generates checklists and recommendations but never modifies code files automatically. + +**Q: How do we handle responsive values (mobile/tablet/desktop)?** +A: Figma may store these as variants or separate frames. Document the mapping in your token-mappings.json, or process each breakpoint separately. + +**Q: What about dark mode / theme variations?** +A: If Figma uses Variables with modes (themes), you can fetch them via the variables endpoint. Otherwise, treat each theme as a separate component variant. + +**Q: Can we ignore certain Figma changes?** +A: Yes. Use the ignoreList in token-mappings.json to exclude internal/debug tokens, or filter by component in your sync command. + +### Troubleshooting + +**Q: I'm getting "401 Unauthorized" errors** +A: Your Figma access token is missing or invalid. Generate a new personal access token at https://www.figma.com/developers/api#access-tokens and set it: `export FIGMA_ACCESS_TOKEN="your-token"` + +**Q: "No tokens found in code" error** +A: Verify your tokens directory path is correct and contains .scss/.css files. For PatternFly, try `./src/patternfly/base/tokens/` or `./node_modules/@patternfly/patternfly/base/`. + +**Q: The script finds tokens but they're all mismatches** +A: This usually means naming conventions differ. Create a token-mappings.json file to map Figma names to code names. See examples/ directory. + +**Q: Version history is empty** +A: You may need editor access (not just viewer) to see version history. Ask the file owner to grant you edit permissions or use OAuth for broader access. + +For more troubleshooting help, see [troubleshooting.md](references/troubleshooting.md). + +## Learn More + +- [Figma API Documentation](https://www.figma.com/developers/api) +- [PatternFly Design Tokens](https://www.patternfly.org/tokens/) +- [Design-Code Sync Best Practices](references/figma-api-guide.md) +- [Troubleshooting Guide](references/troubleshooting.md) diff --git a/plugins/pf-figma/skills/figma-changes/SKILL.md b/plugins/pf-figma/skills/figma-changes/SKILL.md new file mode 100644 index 0000000..c828858 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/SKILL.md @@ -0,0 +1,123 @@ +--- +name: figma-changes +description: Identify Figma design changes and generate code update checklists. Use when the user asks to "check Figma updates", "track design changes", "what changed in Figma", "create changelog from Figma", or "what code needs updating based on Figma". +version: 3.1.0 +--- + +# Figma Design Change Tracker + +Track Figma design updates and generate code checklists for PatternFly. + +## What This Skill Does + +1. Fetches recent changes from Figma version history +2. Analyzes design updates to components +3. Compares design specs with code implementation +4. Generates three types of reports (see below) +5. Creates actionable checklists for developers + +## Output Files + +**FIGMA_CHANGELOG.md** - Internal design team changelog with all updates +**RELEASE_NOTES.md** - Consumer-facing release notes +**figma-updates-[date].md** - Detailed checklist with token changes + +See [report-templates.md](report-templates.md) for full template examples. + +## What to Analyze + +For each component update, focus on: + +- **Colors** - Background, border, text, hover/focus states +- **Typography** - Font size, weight, line height +- **Spacing** - Padding, gaps, margins +- **Layout** - Dimensions, alignment, structure +- **Variants** - States (hover, focus, disabled) and sizes +- **Changes** - Elements added or removed + +## Status Determination + +Assign each update one of three statuses: + +**✅ Design-only** - Figma documenting what's already in code +**⚠️ Code update needed** - Design is ahead of code +**🔍 Needs verification** - Unclear if code matches design + +### How to Determine Status + +1. Check if there's a related GitHub issue + - Issue closed/merged → Likely ✅ Design-only + - Issue open → Likely ⚠️ Code update needed + - No issue → Check token comparison + +2. Compare design tokens with code + - Values match → ✅ Design-only + - Values differ → ⚠️ Code update needed + - Can't compare → 🔍 Needs verification + +3. Check recent git commits (last 2 weeks) + - Recent work on component → Possibly ✅ Design-only + - No recent work → Possibly ⚠️ Code update needed + +> See [references/troubleshooting.md](references/troubleshooting.md) for detailed decision tree and automation commands. + +## Report Format + +### For Each Component Update + +Include: +- **Date** - When the design was updated +- **Designer** - Who made the change +- **Page/Context** - Where in Figma (e.g., "Chatbot: Filters") +- **Status** - ✅ / ⚠️ / 🔍 +- **Links** - Figma, PatternFly.org, GitHub issues + +### For Code Updates (⚠️ status only) + +Create token comparison tables: + +| ✓ | Token | Current | New | Where Used | +|---|-------|---------|-----|------------| +| [ ] | `--pf-c-button--BackgroundColor` | `#0066CC` | `#004080` | Button background | + +List files that need updating: +- `Button.scss` - Update color tokens +- `Button.md` - Update documentation +- `Button.test.tsx` - Update snapshots + +## Key Guidelines + +**Be Specific** - Use exact token names and values +**Link Everything** - Figma, PatternFly.org, GitHub +**Prioritize** - High (breaking, a11y), Medium (updates), Low (docs) +**Note Context** - Always include the Figma page/section + +## Examples + +**Code Update Needed:** +``` +### Button - 2026-03-16 +**Status**: ⚠️ Code update needed +**By**: Sarah Designer | **Page**: Component Library + +Primary button color updated for better accessibility (WCAG AA). + +Token: `--pf-c-button--m-primary--BackgroundColor` +Change: `#0066CC` → `#004080` +``` + +**Design-Only:** +``` +### Card - 2026-03-10 +**Status**: ✅ Design-only +**Related**: Issue #915 (closed) + +Figma updated to match PatternFly 6.0.0. No code changes needed. +``` + +## Additional Resources + +- [Report Templates](report-templates.md) - Full template examples +- [Troubleshooting](references/troubleshooting.md) - Common issues +- [Validation Checklists](references/validation-checklists.md) - Quality checks +- [Token Mappings](examples/token-mappings.json) - Figma ↔ Code mapping diff --git a/plugins/pf-figma/skills/figma-changes/examples/.figma-sync-cache.json b/plugins/pf-figma/skills/figma-changes/examples/.figma-sync-cache.json new file mode 100644 index 0000000..2690dba --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/examples/.figma-sync-cache.json @@ -0,0 +1,152 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Cache file to track Figma sync history and avoid redundant API calls", + "version": "1.0.0", + "lastSync": { + "timestamp": "2026-03-18T14:32:00Z", + "date": "2026-03-18", + "user": "kaylachumley", + "duration": "45s" + }, + "figmaFile": { + "key": "abc123xyz", + "name": "PatternFly Design System", + "url": "https://www.figma.com/file/abc123xyz/PatternFly-Design-System", + "lastModified": "2026-03-18T14:00:00Z", + "lastVersionId": "v789012" + }, + "syncHistory": [ + { + "date": "2026-03-18", + "versionsChecked": 15, + "changesFound": 7, + "componentsUpdated": ["Button", "Card", "Alert"], + "reportsGenerated": [ + "FIGMA_CHANGELOG.md", + "RELEASE_NOTES.md", + "figma-updates-2026-03-18.md" + ] + }, + { + "date": "2026-03-11", + "versionsChecked": 12, + "changesFound": 3, + "componentsUpdated": ["Typography", "Spacing"], + "reportsGenerated": [ + "FIGMA_CHANGELOG.md", + "RELEASE_NOTES.md", + "figma-updates-2026-03-11.md" + ] + } + ], + "processedVersions": { + "description": "Figma version IDs that have already been processed", + "versions": [ + { + "id": "v789012", + "created_at": "2026-03-18T14:00:00Z", + "label": "Updated Button component colors for accessibility", + "created_by": "Sarah Designer", + "processed": true, + "includedInReport": "figma-updates-2026-03-18.md" + }, + { + "id": "v789011", + "created_at": "2026-03-16T09:15:00Z", + "label": "Card component padding update", + "created_by": "Alex Designer", + "processed": true, + "includedInReport": "figma-updates-2026-03-18.md" + }, + { + "id": "v789010", + "created_at": "2026-03-15T16:00:00Z", + "label": "Typography scale adjustment", + "created_by": "Jordan Designer", + "processed": true, + "includedInReport": "figma-updates-2026-03-18.md" + } + ] + }, + "componentTracking": { + "description": "Track the last known state of each component", + "components": { + "Button": { + "lastChecked": "2026-03-18T14:32:00Z", + "lastModified": "2026-03-15T14:32:00Z", + "status": "code-update-needed", + "tokensMismatch": 5, + "relatedIssues": ["#1234"], + "assignedTo": "dev-team" + }, + "Card": { + "lastChecked": "2026-03-18T14:32:00Z", + "lastModified": "2026-03-16T09:15:00Z", + "status": "code-update-needed", + "tokensMismatch": 2, + "relatedIssues": [], + "assignedTo": null + }, + "Alert": { + "lastChecked": "2026-03-18T14:32:00Z", + "lastModified": "2026-03-10T11:00:00Z", + "status": "design-only", + "tokensMismatch": 0, + "relatedIssues": ["#1150"], + "assignedTo": null + } + } + }, + "githubIntegration": { + "lastIssueSearch": "2026-03-18T14:30:00Z", + "repositories": [ + "patternfly/patternfly-react", + "patternfly/patternfly-design-kit", + "patternfly/chatbot" + ], + "cachedIssues": [ + { + "number": 1234, + "title": "Update Button component colors", + "state": "open", + "component": "Button", + "created_at": "2026-03-14T10:00:00Z", + "updated_at": "2026-03-17T15:00:00Z" + }, + { + "number": 1150, + "title": "Alert component design sync", + "state": "closed", + "component": "Alert", + "created_at": "2026-03-01T10:00:00Z", + "closed_at": "2026-03-12T14:00:00Z" + } + ] + }, + "statistics": { + "totalSyncs": 8, + "totalChangesDetected": 42, + "averageChangesPerSync": 5.25, + "mostActiveComponent": "Button", + "mostActiveDesigner": "Sarah Designer" + }, + "settings": { + "checkInterval": "weekly", + "nextScheduledSync": "2026-03-25T14:00:00Z", + "autoGenerateReports": true, + "notifyOnChanges": true, + "tokenComparisonEnabled": true, + "githubIntegrationEnabled": true + }, + "notes": { + "description": "Notes about this cache file", + "usage": [ + "This file is automatically generated and updated by figma-sync.sh", + "Delete this file to force a complete re-sync", + "The 'processedVersions' list prevents duplicate processing", + "Component tracking helps identify what needs attention" + ], + "location": "Store this file in your project root or .figma/ directory", + "gitignore": "Consider adding to .gitignore if it contains sensitive data" + } +} diff --git a/plugins/pf-figma/skills/figma-changes/examples/sample-output.md b/plugins/pf-figma/skills/figma-changes/examples/sample-output.md new file mode 100644 index 0000000..ae813ea --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/examples/sample-output.md @@ -0,0 +1,172 @@ +# Sample Figma Change Report + +This is an example of what the skill generates. + +--- + +# Figma Change Summary +**File**: PatternFly Design System +**File Key**: abc123xyz +**Analysis Date**: 2026-03-18 +**Change Period**: March 11-18, 2026 + +## Executive Summary +7 components were updated with significant changes to color tokens and spacing values. The Button component received a major redesign with new hover states, and the Card component padding was increased for better content hierarchy. Typography scale was adjusted globally affecting all heading styles. + +## Detailed Changes + +### Button (Primary) +**Last Modified**: 2026-03-15 14:32:00 +**Modified By**: Sarah Designer +**Change Type**: Modified + +#### Property Changes +- **Color Changes** + - Background: `#0066CC` → `#004080` (variable: `--pf-c-button--m-primary--BackgroundColor`) + - Hover Background: `#004E99` → `#003366` + +- **Typography Changes** + - Font Weight: `500` → `600` (token: `--pf-c-button--FontWeight`) + +- **Spacing Changes** + - Padding Left/Right: `16px` → `20px` (token: `--pf-c-button--PaddingLeft`) + - Padding Top/Bottom: `8px` → `10px` + +- **Other Changes** + - Border Radius: `3px` → `4px` + - Transition Duration: `0.2s` → `0.15s` + +--- + +### Card Component +**Last Modified**: 2026-03-16 09:15:00 +**Modified By**: Alex Designer +**Change Type**: Modified + +#### Property Changes +- **Color Changes** + - Border: `#EDEDED` → `#D2D2D2` (variable: `--pf-c-card--BorderColor`) + - Shadow: Updated shadow definition for elevation + +- **Spacing Changes** + - Padding: `16px` → `24px` (token: `--pf-c-card--first-child--PaddingTop`) + - Gap between items: `12px` → `16px` + +--- + +### Typography - Headings +**Last Modified**: 2026-03-14 16:00:00 +**Modified By**: Jordan Designer +**Change Type**: Modified + +#### Property Changes +- **Typography Changes** + - H2 Font Size: `18px` → `20px` (token: `--pf-global--FontSize--xl`) + - H3 Font Size: `16px` → `18px` (token: `--pf-global--FontSize--lg`) + - Line Height: `1.4` → `1.5` (token: `--pf-global--LineHeight--md`) + +--- + +## Token Discrepancies + +### Colors +| Figma Property | Figma Value | Token Name | Current Value | Status | +|----------------|-------------|------------|---------------|--------| +| Button Primary BG | `#004080` | `--pf-c-button--m-primary--BackgroundColor` | `#0066CC` | ❌ Mismatch | +| Button Hover BG | `#003366` | `--pf-c-button--m-primary--hover--BackgroundColor` | `#004E99` | ❌ Mismatch | +| Card Border | `#D2D2D2` | `--pf-c-card--BorderColor` | `#EDEDED` | ❌ Mismatch | +| Card Background | `#FFFFFF` | `--pf-c-card--BackgroundColor` | `#FFFFFF` | ✅ Match | + +### Typography +| Figma Property | Figma Value | Token Name | Current Value | Status | +|----------------|-------------|------------|---------------|--------| +| H2 Font Size | `20px` | `--pf-global--FontSize--xl` | `18px` | ❌ Mismatch | +| H3 Font Size | `18px` | `--pf-global--FontSize--lg` | `16px` | ❌ Mismatch | +| Body Line Height | `1.5` | `--pf-global--LineHeight--md` | `1.5` | ✅ Match | +| Button Font Weight | `600` | `--pf-c-button--FontWeight` | `500` | ❌ Mismatch | + +### Spacing +| Figma Property | Figma Value | Token Name | Current Value | Status | +|----------------|-------------|------------|---------------|--------| +| Card Padding | `24px` | `--pf-c-card--first-child--PaddingTop` | `16px` | ❌ Mismatch | +| Button Padding X | `20px` | `--pf-c-button--PaddingLeft` | `16px` | ❌ Mismatch | +| Button Padding Y | `10px` | `--pf-c-button--PaddingTop` | `8px` | ❌ Mismatch | +| Card Gap | `16px` | `--pf-c-card--child--Gap` | `12px` | ❌ Mismatch | + +--- + +## Action Items Checklist + +### High Priority (Breaking Changes / Visual Inconsistencies) +- [ ] Update `--pf-c-button--m-primary--BackgroundColor` from `#0066CC` to `#004080` + - **Files to update**: `src/patternfly/components/Button/_button.scss` + - **Impact**: All primary buttons across the application + - **Reason**: Brand color update for better accessibility (AA contrast) + +- [ ] Update `--pf-c-card--BorderColor` from `#EDEDED` to `#D2D2D2` + - **Files to update**: `src/patternfly/components/Card/_card.scss` + - **Impact**: All card components + - **Reason**: Stronger border definition for better component separation + +- [ ] Update heading font sizes globally + - **Files to update**: `src/patternfly/base/tokens/_typography.scss` + - **Tokens to update**: + - `--pf-global--FontSize--xl`: `18px` → `20px` + - `--pf-global--FontSize--lg`: `16px` → `18px` + - **Impact**: All H2 and H3 headings + - **Reason**: Typography scale adjustment for better hierarchy + +### Medium Priority (Minor Adjustments) +- [ ] Update card padding `--pf-c-card--first-child--PaddingTop` from `16px` to `24px` + - **Files to update**: `src/patternfly/components/Card/_card.scss` + - **Impact**: Card component spacing + - **Reason**: Increased padding for better content breathing room + +- [ ] Update button padding tokens + - **Files to update**: `src/patternfly/components/Button/_button.scss` + - **Tokens to update**: + - `--pf-c-button--PaddingLeft`: `16px` → `20px` + - `--pf-c-button--PaddingTop`: `8px` → `10px` + - **Impact**: All button sizes + - **Reason**: Better proportion and touch target size + +- [ ] Update button font weight `--pf-c-button--FontWeight` from `500` to `600` + - **Files to update**: `src/patternfly/components/Button/_button.scss` + - **Impact**: Button text styling + - **Reason**: Improved readability and emphasis + +### Low Priority (Enhancements) +- [ ] Update button border radius from `3px` to `4px` + - **Files to update**: `src/patternfly/components/Button/_button.scss` + - **Impact**: Button corners + - **Reason**: Subtle softening of corners + +- [ ] Update button transition duration from `0.2s` to `0.15s` + - **Files to update**: `src/patternfly/components/Button/_button.scss` + - **Impact**: Button hover/active states + - **Reason**: Snappier interaction feedback + +- [ ] Update card shadow definition + - **Files to update**: `src/patternfly/components/Card/_card.scss` + - **Impact**: Card elevation appearance + - **Reason**: Refined shadow for better depth perception + +--- + +## Next Steps + +1. **Review with Team**: Share this report with design and development teams +2. **Prioritize Updates**: Decide which changes to implement in the next sprint +3. **Create Tickets**: Break down action items into JIRA/GitHub issues +4. **Test Changes**: Ensure visual regression testing covers updated components +5. **Document Updates**: Update component documentation with new token values +6. **Schedule Next Sync**: Set up recurring Figma sync checks (recommended: weekly) + +## References +- Figma File: https://www.figma.com/file/abc123xyz/PatternFly-Design-System +- Token Files: + - `src/patternfly/base/tokens/_colors.scss` + - `src/patternfly/base/tokens/_typography.scss` + - `src/patternfly/base/tokens/_spacing.scss` +- Last Sync Date: 2026-03-11 +- Next Recommended Sync: 2026-03-25 diff --git a/plugins/pf-figma/skills/figma-changes/examples/token-mappings.json b/plugins/pf-figma/skills/figma-changes/examples/token-mappings.json new file mode 100644 index 0000000..32c71c5 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/examples/token-mappings.json @@ -0,0 +1,111 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Maps Figma design token names to PatternFly CSS token names for automated comparison", + "version": "1.0.0", + "mappings": { + "colors": { + "Button/Primary/Background": "--pf-c-button--m-primary--BackgroundColor", + "Button/Primary/Hover/Background": "--pf-c-button--m-primary--hover--BackgroundColor", + "Button/Primary/Active/Background": "--pf-c-button--m-primary--active--BackgroundColor", + "Button/Primary/Text": "--pf-c-button--m-primary--Color", + "Button/Secondary/Background": "--pf-c-button--m-secondary--BackgroundColor", + "Button/Secondary/Border": "--pf-c-button--m-secondary--BorderColor", + "Card/Background": "--pf-c-card--BackgroundColor", + "Card/Border": "--pf-c-card--BorderColor", + "Alert/Info/Background": "--pf-c-alert--m-info--BackgroundColor", + "Alert/Info/Icon": "--pf-c-alert--m-info--icon--Color", + "Alert/Success/Background": "--pf-c-alert--m-success--BackgroundColor", + "Global/Brand/Primary": "--pf-global--primary-color--100", + "Global/Danger": "--pf-global--danger-color--100", + "Global/Success": "--pf-global--success-color--100" + }, + "spacing": { + "Button/Padding/Horizontal": "--pf-c-button--PaddingLeft", + "Button/Padding/Vertical": "--pf-c-button--PaddingTop", + "Card/Padding": "--pf-c-card--first-child--PaddingTop", + "Card/Gap": "--pf-c-card--child--Gap", + "Global/Spacing/XS": "--pf-global--spacer--xs", + "Global/Spacing/SM": "--pf-global--spacer--sm", + "Global/Spacing/MD": "--pf-global--spacer--md", + "Global/Spacing/LG": "--pf-global--spacer--lg", + "Global/Spacing/XL": "--pf-global--spacer--xl" + }, + "typography": { + "Button/Font/Size": "--pf-c-button--FontSize", + "Button/Font/Weight": "--pf-c-button--FontWeight", + "Heading/H1/Size": "--pf-global--FontSize--4xl", + "Heading/H2/Size": "--pf-global--FontSize--3xl", + "Heading/H3/Size": "--pf-global--FontSize--2xl", + "Heading/H4/Size": "--pf-global--FontSize--xl", + "Body/Size": "--pf-global--FontSize--md", + "Body/LineHeight": "--pf-global--LineHeight--md", + "Small/Size": "--pf-global--FontSize--sm" + }, + "dimensions": { + "Button/MinWidth": "--pf-c-button--MinWidth", + "Button/Height": "--pf-c-button--Height", + "Card/MinHeight": "--pf-c-card--MinHeight" + } + }, + "patterns": { + "description": "Regex patterns for fuzzy matching when exact mapping not found", + "rules": [ + { + "figmaPattern": "^(.+)/Background$", + "tokenPattern": "--pf-c-{component}--BackgroundColor", + "example": "Button/Background → --pf-c-button--BackgroundColor" + }, + { + "figmaPattern": "^(.+)/Border$", + "tokenPattern": "--pf-c-{component}--BorderColor", + "example": "Card/Border → --pf-c-card--BorderColor" + }, + { + "figmaPattern": "^(.+)/Padding/Horizontal$", + "tokenPattern": "--pf-c-{component}--PaddingLeft", + "example": "Alert/Padding/Horizontal → --pf-c-alert--PaddingLeft" + }, + { + "figmaPattern": "^(.+)/Font/Size$", + "tokenPattern": "--pf-c-{component}--FontSize", + "example": "Button/Font/Size → --pf-c-button--FontSize" + } + ] + }, + "ignoreList": { + "description": "Figma tokens to ignore during comparison (design-only or deprecated)", + "tokens": [ + "Internal/Spacing/GridUnit", + "Internal/Debug/Overlay", + "Deprecated/OldButton/Color", + "Sketch/Legacy/Shadow" + ] + }, + "customTransforms": { + "description": "Special transformations for specific token pairs", + "transforms": [ + { + "figmaToken": "Global/BorderRadius/Default", + "codeToken": "--pf-global--BorderRadius--sm", + "note": "Figma uses 'Default' but code uses 'sm' for the same value" + }, + { + "figmaToken": "Button/Padding", + "codeTokens": [ + "--pf-c-button--PaddingTop", + "--pf-c-button--PaddingBottom", + "--pf-c-button--PaddingLeft", + "--pf-c-button--PaddingRight" + ], + "note": "Single Figma token maps to multiple directional tokens in code" + } + ] + }, + "usage": { + "description": "How to use this mapping file", + "examples": [ + "node compare-tokens.js figma-data.json ./tokens --mappings=token-mappings.json", + "node compare-tokens.js figma-data.json ./tokens --mappings=token-mappings.json --ignore-unmapped" + ] + } +} diff --git a/plugins/pf-figma/skills/figma-changes/references/figma-api-guide.md b/plugins/pf-figma/skills/figma-changes/references/figma-api-guide.md new file mode 100644 index 0000000..ab4c5e6 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/references/figma-api-guide.md @@ -0,0 +1,219 @@ +# Figma API Reference Guide + +## Quick Reference + +### Authentication +```bash +export FIGMA_ACCESS_TOKEN="your-token-here" +``` + +### Common Endpoints + +#### Get File +```bash +curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/{file_key}" +``` + +**Response includes**: +- Document structure +- Styles (colors, text, effects) +- Components +- Canvas data + +#### Get Version History +```bash +curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/{file_key}/versions" +``` + +**Response includes**: +- Version ID +- Timestamp (created_at) +- User who made the change +- Description/label + +#### Get Specific Version +```bash +curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/{file_key}?version={version_id}" +``` + +#### Get File Styles +```bash +curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/{file_key}/styles" +``` + +**Returns**: +- Published styles +- Style metadata +- Style keys + +#### Get Local Variables (Design Tokens) +```bash +curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/{file_key}/variables/local" +``` + +**Returns** (if file uses Variables): +- Variable collections +- Variable names and values +- Modes (themes) + +## Extracting File Key from URL + +Figma URLs follow this pattern: +``` +https://www.figma.com/file/{FILE_KEY}/{file-name} +``` + +Example: +``` +https://www.figma.com/file/abc123xyz/My-Design-System +``` +File key: `abc123xyz` + +## Parsing Figma Data + +### Color Extraction + +```javascript +// From fills array +const fills = node.fills; +fills.forEach(fill => { + if (fill.type === 'SOLID') { + const color = fill.color; // {r, g, b, a} + const hex = rgbToHex(color); + } +}); + +// From styles +const styles = figmaData.styles; +Object.entries(styles).forEach(([key, style]) => { + if (style.styleType === 'FILL') { + // Color style + } +}); +``` + +### Typography Extraction + +```javascript +const style = node.style; +const typography = { + fontFamily: style.fontFamily, + fontSize: style.fontSize, + fontWeight: style.fontWeight, + lineHeight: style.lineHeightPx, + letterSpacing: style.letterSpacing, + textAlignHorizontal: style.textAlignHorizontal +}; +``` + +### Spacing Extraction + +```javascript +// From layout properties +const spacing = { + paddingLeft: node.paddingLeft, + paddingRight: node.paddingRight, + paddingTop: node.paddingTop, + paddingBottom: node.paddingBottom, + itemSpacing: node.itemSpacing, // gap in auto-layout +}; +``` + +### Layout Properties + +```javascript +const layout = { + layoutMode: node.layoutMode, // HORIZONTAL, VERTICAL, NONE + primaryAxisSizingMode: node.primaryAxisSizingMode, + counterAxisSizingMode: node.counterAxisSizingMode, + primaryAxisAlignItems: node.primaryAxisAlignItems, + counterAxisAlignItems: node.counterAxisAlignItems, +}; +``` + +## Rate Limiting + +Figma API rate limits: +- **Personal access tokens**: 1000 requests per hour +- **OAuth tokens**: Higher limits (varies) + +Check rate limit headers: +``` +X-RateLimit-Limit: 1000 +X-RateLimit-Remaining: 999 +X-RateLimit-Reset: 1234567890 +``` + +## Error Handling + +Common errors: + +**401 Unauthorized** +- Invalid or missing access token +- Token doesn't have access to this file + +**403 Forbidden** +- File is private and token doesn't have permission +- File has been deleted + +**404 Not Found** +- Invalid file key +- File doesn't exist + +**429 Too Many Requests** +- Rate limit exceeded +- Wait until reset time + +## Converting Figma Values to CSS + +### Colors +```javascript +// Figma: {r: 0.0, g: 0.4, b: 0.8, a: 1} +// CSS: #0066CC or rgb(0, 102, 204) +function rgbToHex({r, g, b}) { + const toHex = (n) => Math.round(n * 255).toString(16).padStart(2, '0'); + return `#${toHex(r)}${toHex(g)}${toHex(b)}`; +} +``` + +### Font Weights +```javascript +// Figma uses numeric weights +const weightMap = { + 100: 'Thin', + 200: 'Extra Light', + 300: 'Light', + 400: 'Regular', + 500: 'Medium', + 600: 'Semi Bold', + 700: 'Bold', + 800: 'Extra Bold', + 900: 'Black' +}; +``` + +### Line Height +```javascript +// Figma can use: +// - lineHeightPx (absolute pixels) +// - lineHeightPercent (percentage) +// - Auto + +// Convert to CSS line-height +const lineHeight = node.lineHeightPercent + ? node.lineHeightPercent / 100 + : `${node.lineHeightPx}px`; +``` + +## Best Practices + +1. **Cache API Responses**: Save responses to avoid repeated API calls +2. **Use Version IDs**: Compare specific versions rather than always using latest +3. **Batch Processing**: If checking multiple files, space out requests +4. **Error Recovery**: Implement retry logic with exponential backoff +5. **Token Security**: Never commit access tokens to version control diff --git a/plugins/pf-figma/skills/figma-changes/references/template-changelog.md b/plugins/pf-figma/skills/figma-changes/references/template-changelog.md new file mode 100644 index 0000000..bf1b540 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/references/template-changelog.md @@ -0,0 +1,21 @@ +# Design Changelog Template + +**Period**: [Date Range] + +## ✅ Added +| Component/Pattern | Description | Page/Context | Designer | Date | Related Issue | +|-------------------|-------------|--------------|----------|------|---------------| +| **[Name]** | [Brief description] | [Page] | [Designer] | [Date] | [Link] | + +## 🔨 Fixed +| Component | Issue Fixed | Page/Context | Designer | Date | Related Issue | +|-----------|-------------|--------------|----------|------|---------------| +| **[Name]** | [What fixed] | [Page] | [Designer] | [Date] | [Link] | + +## 🎨 Changed +| Component/Area | Changes Made | Page/Context | Designer(s) | Date | Count | +|----------------|--------------|--------------|-------------|------|-------| +| **[Name]** | [What changed] | [Page] | [Designer(s)] | [Date] | [#] | + +## 📊 Summary +**Total Updates**: [Count] | **Contributors**: [List] diff --git a/plugins/pf-figma/skills/figma-changes/references/template-detailed-report.md b/plugins/pf-figma/skills/figma-changes/references/template-detailed-report.md new file mode 100644 index 0000000..b55520b --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/references/template-detailed-report.md @@ -0,0 +1,43 @@ +# Figma Design Updates Report +**Generated**: [Date] | **Period**: Last [N] days + +## Part 1: Change Summary + +**Total Updates**: [Count] | **Contributors**: [List] + +#### [Component Name] +**Date**: [Date] | **By**: [Designer] | **Type**: [Component/Pattern] +**Page/Context**: [Figma page/section] +**Related Issues**: [#XXX](URL) - [Status] + +## Part 2: Code Update Checklist + +### Changes Requiring Code Updates + +#### [Component Name] - [Date] +**Status**: ⚠️ Code update needed +**Files**: `[Component].tsx`, `[Component].scss` + +**Token Changes**: +| ✓ | Token | Current | New | Where Used | +|---|-------|---------|-----|------------| +| [ ] | `--pf-c-[component]--[Property]` | [value] | [value] | [usage] | + +--- + +### Design-Only Updates + +#### [Component Name] - [Date] +**Status**: ✅ Design-only +**Notes**: Figma documenting existing implementation + +--- + +### Needs Verification + +#### [Component Name] - [Date] +**Status**: 🔍 Needs verification +**Action**: Compare Figma vs PatternFly.org + +## Summary +**Files to Modify**: [Count] | **Estimated Effort**: [Hours] diff --git a/plugins/pf-figma/skills/figma-changes/references/template-release-notes.md b/plugins/pf-figma/skills/figma-changes/references/template-release-notes.md new file mode 100644 index 0000000..9cbb099 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/references/template-release-notes.md @@ -0,0 +1,32 @@ +# PatternFly Design Updates - [Month Year] + +## What's New + +**[Component/Pattern Name]** +[Brief description and where to use it] +- **Reference**: [PatternFly Docs](link) +- **GitHub issue**: [#XXX](link) + +## Bug Fixes + +**[Component Name]** +What was fixed and impact. +- **Action needed**: [What users should do] +- **Reference**: [#XXX](link) + +## Updates & Improvements + +**[X] component updates** - [Brief summary of improvements] +- **Action needed**: Review commonly used components + +## For Developers + +### Components to Review +1. [Component] - [What changed] +2. [Component] - [What changed] + +### Testing Recommendations +- [Key area to test] +- [Key area to test] + +**Summary**: [X] updates - [Y] new, [Z] fixes, [W] improvements diff --git a/plugins/pf-figma/skills/figma-changes/references/troubleshooting.md b/plugins/pf-figma/skills/figma-changes/references/troubleshooting.md new file mode 100644 index 0000000..52c0c66 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/references/troubleshooting.md @@ -0,0 +1,406 @@ +# Troubleshooting Guide + +## Common Issues and Solutions + +### Figma API Access + +#### "401 Unauthorized" Error + +**Problem**: Cannot access Figma file, getting 401 error + +**Possible Causes**: +- Missing or invalid access token +- Token doesn't have permission to access this file +- Token has expired + +**Solutions**: +```bash +# 1. Verify token is set +echo $FIGMA_ACCESS_TOKEN + +# 2. Test token with a simple API call +curl -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/me" + +# 3. Generate a new token at https://www.figma.com/developers/api#access-tokens +export FIGMA_ACCESS_TOKEN="your-new-token" + +# 4. Ensure token has access to the specific file +# Go to Figma → File → Share → Make sure your account has view access +``` + +#### "403 Forbidden" Error + +**Problem**: Token is valid but can't access specific file + +**Solutions**: +- File may be private - ask file owner to grant access +- File may have been deleted or moved +- Your Figma account may not have permission +- Try accessing the file directly in Figma web to confirm permissions + +#### "404 Not Found" Error + +**Problem**: File not found + +**Solutions**: +```bash +# 1. Verify file key is correct +./scripts/extract-figma-file-key.sh "your-figma-url" + +# 2. Check URL format (should be): +# https://www.figma.com/file/{FILE_KEY}/File-Name + +# 3. Ensure file hasn't been deleted or moved to trash +# Log into Figma and check your files list +``` + +#### "429 Too Many Requests" Error + +**Problem**: Rate limit exceeded + +**Solutions**: +- Wait until rate limit resets (check X-RateLimit-Reset header) +- Reduce sync frequency +- Use caching to avoid redundant API calls +- Consider OAuth token for higher limits + +```bash +# Check rate limit status +curl -I -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/$FILE_KEY" | grep -i ratelimit +``` + +--- + +### Token Comparison Issues + +#### "No tokens found in code" + +**Problem**: compare-tokens.js finds no tokens in your codebase + +**Solutions**: +```bash +# 1. Verify tokens directory exists and contains files +ls -la ./src/patternfly/base/tokens/ + +# 2. Check file extensions (should be .scss or .css) +find ./src/tokens -type f -name "*.scss" -o -name "*.css" + +# 3. Verify token format in files +# Should match: --variable-name: value; or $variable-name: value; + +# 4. Check if tokens are in node_modules (PatternFly packages) +# If using PatternFly from npm, tokens are at: +# node_modules/@patternfly/patternfly/base/ +``` + +#### "Token names don't match" + +**Problem**: Figma token names differ from code token names + +**Solutions**: +1. Create a token mapping file (see `examples/token-mappings.json`) +2. Use fuzzy matching patterns +3. Update Figma naming to match code conventions +4. Update code naming to match Figma (if appropriate) + +```bash +# Use mapping file +./scripts/compare-tokens.sh figma-data.json ./tokens \ + --mappings=examples/token-mappings.json +``` + +#### "False positive mismatches" + +**Problem**: Tokens appear different but are actually the same + +**Causes**: +- Color format differences (hex vs rgb) +- Unit differences (16px vs 1rem) +- Precision differences (1.5 vs 1.500) + +**Solutions**: +- Add normalization logic to compare-tokens.js +- Use value equivalence checking instead of string matching +- Add tolerance for numeric comparisons + +--- + +### Script Execution Issues + +#### "Node.js not found" + +**Problem**: `command not found: node` + +**Solutions**: +```bash +# 1. Install Node.js from https://nodejs.org/ + +# 2. Verify installation +node --version + +# 3. Check PATH +echo $PATH | grep node + +# 4. If using nvm, ensure it's activated +nvm use --lts +``` + +#### "Permission denied" when running scripts + +**Problem**: Cannot execute .sh scripts + +**Solutions**: +```bash +# Make scripts executable +chmod +x scripts/*.sh + +# Or run with bash explicitly +bash scripts/compare-tokens.sh figma-data.json ./tokens +``` + +#### "Script fails silently" + +**Problem**: Script runs but produces no output + +**Solutions**: +```bash +# 1. Run with verbose mode (if available) +bash -x scripts/compare-tokens.sh figma-data.json ./tokens + +# 2. Check for errors +echo $? # Non-zero means error occurred + +# 3. Redirect stderr to see errors +./scripts/compare-tokens.sh figma-data.json ./tokens 2>&1 + +# 4. Check log files if script creates them +ls -la *.log +``` + +--- + +### GitHub Integration Issues + +#### "gh: command not found" + +**Problem**: GitHub CLI not installed + +**Solutions**: +```bash +# Install GitHub CLI +# macOS +brew install gh + +# Linux +# See: https://github.com/cli/cli/blob/trunk/docs/install_linux.md + +# Windows +# See: https://github.com/cli/cli/blob/trunk/docs/install_windows.md + +# Authenticate +gh auth login +``` + +#### "No issues found for component" + +**Problem**: GitHub search returns no results + +**Solutions**: +```bash +# 1. Try broader search +gh search issues "Button" --repo=patternfly/patternfly-react + +# 2. Search across all repos +gh search issues "Button component" --org=patternfly + +# 3. Check different states +gh search issues "Button" --repo=patternfly/patternfly-react --state=all + +# 4. Manually search on GitHub web +# Sometimes CLI search is more restrictive than web search +``` + +--- + +### Data Quality Issues + +#### "Version history is empty" + +**Problem**: No version history returned from Figma + +**Causes**: +- File has no version history (newly created) +- Access token doesn't have permission to view version history +- File is a branch/draft without independent version history + +**Solutions**: +- Ensure you have editor or owner access to the file +- Try accessing main file instead of branch +- Create a manual version in Figma to test + +#### "Dates are incorrect in changelog" + +**Problem**: Timestamps don't match actual change times + +**Solutions**: +- Figma timestamps are in UTC - convert to your timezone +- Version timestamps show when version was created, not when changes were made +- Use version labels for more context + +--- + +### PatternFly-Specific Issues + +#### "Can't find PatternFly components" + +**Problem**: Script doesn't recognize PatternFly structure + +**Solutions**: +```bash +# 1. Verify you're in correct repository +pwd +# Should be in patternfly-react or similar + +# 2. Check component structure +ls -la src/components/ + +# 3. Update token path for your setup +# PatternFly React: src/patternfly/ +# PatternFly Core: src/patternfly/components/ +``` + +#### "Monorepo structure not recognized" + +**Problem**: Working with PatternFly monorepo + +**Solutions**: +- Specify exact package path +- Run script from package directory +- Update paths in sync configuration + +```bash +# Example for monorepo +cd packages/react-core +../../scripts/compare-tokens.sh ../../figma-data.json ./src/components +``` + +--- + +### Performance Issues + +#### "Sync takes too long" + +**Problem**: Script runs for minutes without completing + +**Solutions**: +1. Enable caching to skip already-processed versions +2. Limit date range for version history +3. Process components incrementally +4. Run in background and check logs + +```bash +# Use cache +./scripts/figma-sync.sh --use-cache + +# Limit to last 7 days +./scripts/figma-sync.sh --days=7 + +# Process specific component only +./scripts/figma-sync.sh --component=Button +``` + +#### "Too much output" + +**Problem**: Console is flooded with output + +**Solutions**: +```bash +# Redirect to file +./scripts/compare-tokens.sh figma-data.json ./tokens > output.txt + +# Show only summary +./scripts/compare-tokens.sh figma-data.json ./tokens --summary-only + +# Quiet mode +./scripts/compare-tokens.sh figma-data.json ./tokens --quiet +``` + +--- + +## Debugging Tips + +### Enable Debug Mode + +```bash +# Set debug environment variable +export DEBUG=true + +# Run with verbose output +set -x +./scripts/compare-tokens.sh figma-data.json ./tokens +set +x +``` + +### Check Intermediate Files + +```bash +# Verify Figma data was fetched correctly +cat /tmp/figma-*.json | jq . | head -50 + +# Check if token extraction worked +cat token-comparison.json | jq '.code.colors | length' + +# Validate generated reports +head -20 FIGMA_CHANGELOG.md +``` + +### Test Components Individually + +```bash +# Instead of full sync, test one component +node scripts/compare-tokens.js \ + figma-button-data.json \ + src/components/Button/ \ + --component=Button +``` + +--- + +## Getting Help + +If you're still stuck: + +1. **Check the examples**: Review `examples/` directory for working configurations +2. **Read the API guide**: See `references/figma-api-guide.md` for Figma API details +3. **File an issue**: Report bugs at https://github.com/patternfly/ai-helpers/issues +4. **Ask the community**: PatternFly Slack or GitHub Discussions + +### When Reporting Issues + +Include: +- Error message (full output) +- Command you ran +- Node.js version: `node --version` +- Operating system +- File structure (if relevant) +- Steps to reproduce + +**Example**: +``` +Issue: compare-tokens.sh fails with "No tokens found" + +Command: ./scripts/compare-tokens.sh figma-data.json ./src/tokens +Node.js: v18.16.0 +OS: macOS 13.4 + +Directory structure: +./src/tokens/ + _colors.scss + _spacing.scss + _typography.scss + +Error output: +[paste full error here] +``` diff --git a/plugins/pf-figma/skills/figma-changes/references/validation-checklists.md b/plugins/pf-figma/skills/figma-changes/references/validation-checklists.md new file mode 100644 index 0000000..09e3626 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/references/validation-checklists.md @@ -0,0 +1,296 @@ +# Validation Checklists + +## Pre-Sync Validation Checklist + +Run this checklist before starting a Figma sync to ensure smooth operation. + +### Environment Setup +- [ ] Node.js installed (v14+) + ```bash + node --version + ``` +- [ ] GitHub CLI installed (if using GitHub integration) + ```bash + gh --version + ``` +- [ ] Figma access token set + ```bash + echo $FIGMA_ACCESS_TOKEN + ``` +- [ ] Working directory is correct + ```bash + pwd + ``` + +### File Access +- [ ] Figma file URL is correct +- [ ] Have view/edit access to Figma file +- [ ] Token directory exists + ```bash + ls -la ./src/tokens/ # or your token path + ``` +- [ ] Token files contain valid CSS/SCSS variables + ```bash + grep -r "^--\|^\$" ./src/tokens/ | head -5 + ``` + +### Git Status +- [ ] Working tree is clean (no uncommitted changes) + ```bash + git status + ``` +- [ ] On correct branch + ```bash + git branch --show-current + ``` +- [ ] Latest changes pulled from remote + ```bash + git pull + ``` + +### Script Permissions +- [ ] Scripts are executable + ```bash + ls -l scripts/*.sh + ``` +- [ ] No permission errors when running test command + ```bash + ./scripts/compare-tokens.sh --help + ``` + +--- + +## Post-Sync Validation Checklist + +After running the sync, validate the generated reports and data. + +### Report Quality +- [ ] FIGMA_CHANGELOG.md generated and not empty + ```bash + wc -l FIGMA_CHANGELOG.md + ``` +- [ ] RELEASE_NOTES.md generated and not empty + ```bash + wc -l RELEASE_NOTES.md + ``` +- [ ] Detailed report (figma-updates-*.md) generated + ```bash + ls -lh figma-updates-*.md + ``` +- [ ] All referenced GitHub issues actually exist + ```bash + # Check first few issues manually + gh issue view 1234 + ``` +- [ ] Component names match your codebase +- [ ] Token names follow PatternFly conventions +- [ ] Dates and timestamps are correct (check timezone) + +### Data Accuracy +- [ ] No duplicate entries in changelog + ```bash + # Check for duplicate component entries + grep "^###" FIGMA_CHANGELOG.md | sort | uniq -d + ``` +- [ ] Status assignments (✅/⚠️/🔍) seem reasonable +- [ ] Token comparisons show actual values (not "undefined") +- [ ] File paths in checklist are correct + ```bash + # Verify files exist + ls -l src/components/Button/_button.scss + ``` +- [ ] Color values are valid hex/rgb + ```bash + # Check for invalid color values + grep -E "#[^0-9A-Fa-f]" figma-updates-*.md + ``` + +### Priority Assignment +- [ ] Breaking changes marked as High Priority +- [ ] Minor adjustments marked appropriately +- [ ] Design-only updates clearly identified +- [ ] Verification-needed items have clear next steps + +### Cross-References +- [ ] Figma links work and point to correct file +- [ ] PatternFly.org links are valid (not 404) +- [ ] GitHub issue links resolve correctly +- [ ] File paths exist in codebase + +--- + +## Code Update Validation Checklist + +Before implementing code changes from the sync report, validate the proposed updates. + +### Token Changes Review +- [ ] Understand impact of each token change +- [ ] Check for cascading effects (tokens that reference other tokens) +- [ ] Verify no circular dependencies +- [ ] Consider backward compatibility +- [ ] Document breaking changes + +### Visual Regression Check +- [ ] Take screenshots of components before changes +- [ ] Identify which pages use affected components +- [ ] Plan visual regression tests +- [ ] Consider mobile/responsive impact +- [ ] Check dark mode / theme variations + +### Accessibility Validation +- [ ] Color contrast meets WCAG AA (use contrast checker) + ```bash + # For critical color changes + # Foreground: #004080, Background: #FFFFFF + # Check at: https://webaim.org/resources/contrastchecker/ + ``` +- [ ] Font sizes meet minimum requirements (16px+ for body) +- [ ] Touch targets meet size requirements (44x44px minimum) +- [ ] Focus indicators remain visible + +### Code Impact Assessment +- [ ] Identify all files needing updates + ```bash + # Find all uses of a token + grep -r "--pf-c-button--BackgroundColor" src/ + ``` +- [ ] Check for hardcoded values that should use tokens +- [ ] Review component snapshots that may need updating +- [ ] Identify integration tests that may be affected + +### Dependencies & Build +- [ ] No new dependencies required +- [ ] Build passes with changes + ```bash + npm run build + ``` +- [ ] Linter passes + ```bash + npm run lint + ``` +- [ ] Type checking passes (if using TypeScript) + ```bash + npm run type-check + ``` + +--- + +## Release Validation Checklist + +Before releasing changes based on Figma sync, ensure quality and completeness. + +### Testing +- [ ] Unit tests updated and passing + ```bash + npm test + ``` +- [ ] Visual regression tests pass +- [ ] Integration tests pass +- [ ] Manual testing in all supported browsers +- [ ] Manual testing on mobile devices +- [ ] Accessibility audit passes + +### Documentation +- [ ] Component documentation updated +- [ ] Changelog/release notes updated +- [ ] Migration guide created (if breaking changes) +- [ ] Example code updated +- [ ] Storybook/demos updated + +### Code Quality +- [ ] Code review completed +- [ ] No console warnings/errors +- [ ] Performance benchmarks acceptable +- [ ] Bundle size impact acceptable +- [ ] CSS specificity hasn't increased unnecessarily + +### Stakeholder Review +- [ ] Design team approves changes +- [ ] Product team aware of changes +- [ ] Breaking changes communicated +- [ ] Release scheduled appropriately + +### Post-Release +- [ ] Monitor error tracking for issues +- [ ] Watch for bug reports +- [ ] Prepare hotfix plan if needed +- [ ] Document lessons learned +- [ ] Update sync process if needed + +--- + +## Continuous Improvement Checklist + +Periodically review and improve your sync process. + +### Process Efficiency +- [ ] Sync time is acceptable (< 5 minutes ideal) +- [ ] False positives are minimal +- [ ] Token mappings are up to date +- [ ] Automation is working correctly +- [ ] Team is using reports effectively + +### Data Quality +- [ ] Status determination is accurate (> 90%) +- [ ] Token comparisons are reliable +- [ ] GitHub integration finds relevant issues +- [ ] Component detection is comprehensive +- [ ] No duplicate work across syncs + +### Team Adoption +- [ ] Designers understand how to trigger sync +- [ ] Developers know how to read reports +- [ ] Process is documented in team wiki +- [ ] Onboarding includes sync training +- [ ] Feedback loop exists for improvements + +### Tool Updates +- [ ] Scripts are maintained and updated +- [ ] Dependencies are up to date + ```bash + npm outdated + ``` +- [ ] Figma API changes are tracked +- [ ] PatternFly updates are incorporated +- [ ] New features are considered + +--- + +## Quick Reference: Critical Checks + +**Before every sync:** +```bash +# 1. Environment ready? +node --version && echo $FIGMA_ACCESS_TOKEN | head -c 20 && git status + +# 2. Access confirmed? +curl -s -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/me" | jq .email + +# 3. Paths correct? +ls ./src/tokens/*.scss && ls ./scripts/*.sh +``` + +**After every sync:** +```bash +# 1. Reports generated? +ls -lh FIGMA_CHANGELOG.md RELEASE_NOTES.md figma-updates-*.md + +# 2. No obvious errors? +tail -20 figma-updates-*.md + +# 3. Ready to review? +wc -l FIGMA_CHANGELOG.md # Should be > 0 +``` + +**Before code changes:** +```bash +# 1. Impact understood? +grep -c "Code update needed" figma-updates-*.md + +# 2. Tests ready? +npm test + +# 3. Backup created? +git checkout -b figma-sync-$(date +%Y%m%d) +``` diff --git a/plugins/pf-figma/skills/figma-changes/report-templates.md b/plugins/pf-figma/skills/figma-changes/report-templates.md new file mode 100644 index 0000000..7c7ed99 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/report-templates.md @@ -0,0 +1,143 @@ +# Report Templates + +This file contains templates for the three types of reports generated by the figma-changes skill. + +--- + +## Template 1: Design Changelog (FIGMA_CHANGELOG.md) + +Internal table-based changelog for the design team. + +```markdown +# Design Changelog + +**Period**: [Date Range] + +## ✅ Added +| Component/Pattern | Description | Page/Context | Designer | Date | Related Issue | +|-------------------|-------------|--------------|----------|------|---------------| +| **[Name]** | [Brief description] | [Page] | [Designer] | [Date] | [Link] | + +## 🔨 Fixed +| Component | Issue Fixed | Page/Context | Designer | Date | Related Issue | +|-----------|-------------|--------------|----------|------|---------------| +| **[Name]** | [What fixed] | [Page] | [Designer] | [Date] | [Link] | + +## 🎨 Changed +| Component/Area | Changes Made | Page/Context | Designer(s) | Date | Count | +|----------------|--------------|--------------|-------------|------|-------| +| **[Name]** | [What changed] | [Page] | [Designer(s)] | [Date] | [#] | + +## 📊 Summary +**Total Updates**: [Count] | **Contributors**: [List] +``` + +--- + +## Template 2: Release Notes (RELEASE_NOTES.md) + +Consumer-facing release notes for PatternFly users. + +```markdown +# PatternFly Design Updates - [Month Year] + +## What's New + +**[Component/Pattern Name]** +[Brief description and where to use it] +- **Reference**: [PatternFly Docs](link) +- **GitHub issue**: [#XXX](link) + +## Bug Fixes + +**[Component Name]** +What was fixed and impact. +- **Action needed**: [What users should do] +- **Reference**: [#XXX](link) + +## Updates & Improvements + +**[X] component updates** - [Brief summary of improvements] +- **Action needed**: Review commonly used components + +## For Developers + +### Components to Review +1. [Component] - [What changed] +2. [Component] - [What changed] + +### Testing Recommendations +- [Key area to test] +- [Key area to test] + +**Summary**: [X] updates - [Y] new, [Z] fixes, [W] improvements +``` + +--- + +## Template 3: Detailed Report (figma-updates-[date].md) + +Comprehensive report with token changes and actionable checklists for developers. + +```markdown +# Figma Design Updates Report +**Generated**: [Date] | **Period**: Last [N] days + +## Part 1: Change Summary + +**Total Updates**: [Count] | **Contributors**: [List] + +#### [Component Name] +**Date**: [Date] | **By**: [Designer] | **Type**: [Component/Pattern] +**Page/Context**: [Figma page/section] +**Related Issues**: [#XXX](URL) - [Status] + +## Part 2: Code Update Checklist + +### Changes Requiring Code Updates + +#### [Component Name] - [Date] +**Status**: ⚠️ Code update needed +**Files**: `[Component].tsx`, `[Component].scss` + +**Token Changes**: +| ✓ | Token | Current | New | Where Used | +|---|-------|---------|-----|------------| +| [ ] | `--pf-c-[component]--[Property]` | [value] | [value] | [usage] | + +--- + +### Design-Only Updates + +#### [Component Name] - [Date] +**Status**: ✅ Design-only +**Notes**: Figma documenting existing implementation + +--- + +### Needs Verification + +#### [Component Name] - [Date] +**Status**: 🔍 Needs verification +**Action**: Compare Figma vs PatternFly.org + +## Summary +**Files to Modify**: [Count] | **Estimated Effort**: [Hours] +``` + +--- + +## Usage Notes + +**When to use each template:** + +1. **FIGMA_CHANGELOG.md** - Share with design team after every sync to keep them informed of all changes +2. **RELEASE_NOTES.md** - Publish when releasing design system updates to communicate changes to consumers +3. **figma-updates-[date].md** - Use internally by development team to track implementation work + +**Customization tips:** + +- Adjust the table columns based on your team's needs +- Add custom sections for your workflow (e.g., "Breaking Changes", "Deprecations") +- Include additional metadata like Figma version IDs or commit SHAs +- Link to your team's specific tools (Jira, Linear, etc.) diff --git a/plugins/pf-figma/skills/figma-changes/scripts/compare-tokens.js b/plugins/pf-figma/skills/figma-changes/scripts/compare-tokens.js new file mode 100644 index 0000000..c08c454 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/scripts/compare-tokens.js @@ -0,0 +1,267 @@ +#!/usr/bin/env node +/** + * Compare Figma design tokens with local code tokens + * + * Usage: + * node compare-tokens.js + * + * Example: + * node compare-tokens.js ./figma-data.json ./src/patternfly/base/tokens + */ + +const fs = require('fs'); +const path = require('path'); + +// Parse command line arguments +const [,, figmaDataPath, tokensDirPath] = process.argv; + +if (!figmaDataPath || !tokensDirPath) { + console.error('Usage: node compare-tokens.js '); + process.exit(1); +} + +// Read Figma data +let figmaData; +try { + figmaData = JSON.parse(fs.readFileSync(figmaDataPath, 'utf8')); +} catch (error) { + console.error(`Error reading Figma data: ${error.message}`); + process.exit(1); +} + +/** + * Extract colors from Figma data + */ +function extractFigmaColors(data) { + const colors = []; + + // Extract from styles + if (data.styles) { + Object.entries(data.styles).forEach(([key, style]) => { + if (style.styleType === 'FILL' && style.name) { + colors.push({ + name: style.name, + key: key, + type: 'style' + }); + } + }); + } + + // Traverse document to find color fills + function traverse(node, path = []) { + if (!node) return; + + const nodePath = [...path, node.name]; + + // Check fills + if (node.fills && Array.isArray(node.fills)) { + node.fills.forEach(fill => { + if (fill.type === 'SOLID' && fill.color) { + const hex = rgbToHex(fill.color); + colors.push({ + name: node.name, + path: nodePath.join(' > '), + color: hex, + type: 'fill' + }); + } + }); + } + + // Recurse to children + if (node.children) { + node.children.forEach(child => traverse(child, nodePath)); + } + } + + if (data.document) { + traverse(data.document); + } + + return colors; +} + +/** + * Convert Figma RGB to hex + */ +function rgbToHex({r, g, b}) { + const toHex = (n) => Math.round(n * 255).toString(16).padStart(2, '0'); + return `#${toHex(r)}${toHex(g)}${toHex(b)}`.toUpperCase(); +} + +/** + * Extract design tokens from SCSS files + */ +function extractScssTokens(dir) { + const tokens = { + colors: [], + spacing: [], + typography: [] + }; + + if (!fs.existsSync(dir)) { + console.warn(`Warning: Directory not found: ${dir}`); + return tokens; + } + + const files = fs.readdirSync(dir); + + files.forEach(file => { + const filePath = path.join(dir, file); + const stat = fs.statSync(filePath); + + if (stat.isFile() && (file.endsWith('.scss') || file.endsWith('.css'))) { + const content = fs.readFileSync(filePath, 'utf8'); + + // Extract CSS variables + // Match: --variable-name: value; + const varRegex = /--([a-zA-Z0-9-_]+)\s*:\s*([^;]+);/g; + let match; + + while ((match = varRegex.exec(content)) !== null) { + const [, name, value] = match; + const cleanValue = value.trim(); + + // Categorize token + if (name.includes('color') || name.includes('bg') || name.includes('border')) { + tokens.colors.push({ name: `--${name}`, value: cleanValue, file }); + } else if (name.includes('spacing') || name.includes('padding') || name.includes('margin') || name.includes('gap')) { + tokens.spacing.push({ name: `--${name}`, value: cleanValue, file }); + } else if (name.includes('font') || name.includes('text') || name.includes('line-height')) { + tokens.typography.push({ name: `--${name}`, value: cleanValue, file }); + } + } + + // Also extract SCSS variables + // Match: $variable-name: value; + const scssVarRegex = /\$([a-zA-Z0-9-_]+)\s*:\s*([^;]+);/g; + + while ((match = scssVarRegex.exec(content)) !== null) { + const [, name, value] = match; + const cleanValue = value.trim(); + + if (name.includes('color')) { + tokens.colors.push({ name: `$${name}`, value: cleanValue, file }); + } else if (name.includes('spacing') || name.includes('padding')) { + tokens.spacing.push({ name: `$${name}`, value: cleanValue, file }); + } else if (name.includes('font') || name.includes('text')) { + tokens.typography.push({ name: `$${name}`, value: cleanValue, file }); + } + } + } + }); + + return tokens; +} + +/** + * Compare Figma colors with local tokens + */ +function compareColors(figmaColors, localTokens) { + const comparison = { + matches: [], + mismatches: [], + figmaOnly: [], + codeOnly: [] + }; + + // Create a map of local color values + const localColorMap = new Map(); + localTokens.colors.forEach(token => { + localColorMap.set(token.name, token.value); + }); + + // For this simplified version, we'll just list what we found + figmaColors.forEach(figmaColor => { + if (figmaColor.color) { + comparison.figmaOnly.push({ + name: figmaColor.name, + value: figmaColor.color, + path: figmaColor.path + }); + } + }); + + localTokens.colors.forEach(token => { + comparison.codeOnly.push({ + name: token.name, + value: token.value, + file: token.file + }); + }); + + return comparison; +} + +/** + * Main execution + */ +function main() { + console.log('🔍 Extracting Figma design tokens...\n'); + + const figmaColors = extractFigmaColors(figmaData); + console.log(`Found ${figmaColors.length} colors in Figma\n`); + + console.log('📁 Reading local token files...\n'); + const localTokens = extractScssTokens(tokensDirPath); + console.log(`Found ${localTokens.colors.length} color tokens in code`); + console.log(`Found ${localTokens.spacing.length} spacing tokens in code`); + console.log(`Found ${localTokens.typography.length} typography tokens in code\n`); + + console.log('🔄 Comparing tokens...\n'); + const colorComparison = compareColors(figmaColors, localTokens); + + // Output results + console.log('='.repeat(80)); + console.log('COMPARISON RESULTS'); + console.log('='.repeat(80)); + + console.log('\n📊 FIGMA COLORS:'); + console.log('-'.repeat(80)); + figmaColors.slice(0, 20).forEach(color => { + if (color.color) { + console.log(` ${color.name.padEnd(30)} ${color.color.padEnd(10)} (${color.path})`); + } + }); + if (figmaColors.length > 20) { + console.log(` ... and ${figmaColors.length - 20} more`); + } + + console.log('\n📊 CODE COLOR TOKENS:'); + console.log('-'.repeat(80)); + localTokens.colors.slice(0, 20).forEach(token => { + console.log(` ${token.name.padEnd(40)} ${token.value.padEnd(15)} (${token.file})`); + }); + if (localTokens.colors.length > 20) { + console.log(` ... and ${localTokens.colors.length - 20} more`); + } + + console.log('\n💡 NEXT STEPS:'); + console.log('-'.repeat(80)); + console.log(' 1. Review the colors and tokens listed above'); + console.log(' 2. Manually map Figma colors to corresponding tokens'); + console.log(' 3. Identify which values need to be updated'); + console.log(' 4. Create a detailed action plan for token updates'); + + // Save detailed output to JSON + const output = { + figma: { + colors: figmaColors, + totalColors: figmaColors.length + }, + code: { + colors: localTokens.colors, + spacing: localTokens.spacing, + typography: localTokens.typography, + totalTokens: localTokens.colors.length + localTokens.spacing.length + localTokens.typography.length + }, + timestamp: new Date().toISOString() + }; + + const outputPath = 'token-comparison.json'; + fs.writeFileSync(outputPath, JSON.stringify(output, null, 2)); + console.log(`\n✅ Detailed comparison saved to: ${outputPath}`); +} + +main(); diff --git a/plugins/pf-figma/skills/figma-changes/scripts/compare-tokens.sh b/plugins/pf-figma/skills/figma-changes/scripts/compare-tokens.sh new file mode 100755 index 0000000..30d7ede --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/scripts/compare-tokens.sh @@ -0,0 +1,124 @@ +#!/bin/bash +# Wrapper script for compare-tokens.js with comprehensive environment validation + +set -e # Exit on error + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Script directory +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +# Validation results +VALIDATION_PASSED=true + +echo "==================================" +echo "Environment Validation" +echo "==================================" +echo "" + +# Check 1: Node.js availability +echo -n "Checking Node.js... " +if ! command -v node >/dev/null 2>&1; then + echo -e "${RED}FAILED${NC}" + echo " Error: Node.js is not installed or not in PATH" + echo " Please install Node.js from https://nodejs.org/" + VALIDATION_PASSED=false +else + NODE_VERSION=$(node --version) + NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d'.' -f1 | sed 's/v//') + echo -e "${GREEN}OK${NC} ($NODE_VERSION)" + + # Check Node.js version (require v14+) + if [ "$NODE_MAJOR" -lt 14 ]; then + echo -e " ${YELLOW}WARNING${NC}: Node.js version 14+ recommended (you have v$NODE_MAJOR)" + fi +fi + +# Check 2: compare-tokens.js exists +echo -n "Checking compare-tokens.js... " +if [ ! -f "$SCRIPT_DIR/compare-tokens.js" ]; then + echo -e "${RED}FAILED${NC}" + echo " Error: compare-tokens.js not found at $SCRIPT_DIR/compare-tokens.js" + VALIDATION_PASSED=false +else + echo -e "${GREEN}OK${NC}" +fi + +# Check 3: Arguments provided +echo -n "Checking arguments... " +if [ $# -lt 2 ]; then + echo -e "${RED}FAILED${NC}" + echo " Error: Insufficient arguments" + echo "" + echo "Usage: $0 [options]" + echo "" + echo "Options:" + echo " --mappings= Use token mappings file" + echo " --ignore-unmapped Ignore tokens without mappings" + echo " --format=json|md Output format (default: console)" + echo "" + echo "Example:" + echo " $0 ./figma-data.json ./src/tokens" + echo " $0 ./figma-data.json ./src/tokens --mappings=token-mappings.json" + VALIDATION_PASSED=false +else + echo -e "${GREEN}OK${NC}" +fi + +# Check 4: Input file exists +if [ $# -ge 1 ]; then + echo -n "Checking input file... " + FIGMA_DATA_FILE="$1" + if [ ! -f "$FIGMA_DATA_FILE" ]; then + echo -e "${RED}FAILED${NC}" + echo " Error: File not found: $FIGMA_DATA_FILE" + VALIDATION_PASSED=false + else + echo -e "${GREEN}OK${NC} ($FIGMA_DATA_FILE)" + fi +fi + +# Check 5: Tokens directory exists +if [ $# -ge 2 ]; then + echo -n "Checking tokens directory... " + TOKENS_DIR="$2" + if [ ! -d "$TOKENS_DIR" ]; then + echo -e "${YELLOW}WARNING${NC}" + echo " Directory not found: $TOKENS_DIR" + echo " Will attempt to continue, but comparison may fail" + else + TOKEN_FILE_COUNT=$(find "$TOKENS_DIR" -type f \( -name "*.scss" -o -name "*.css" \) 2>/dev/null | wc -l | tr -d ' ') + echo -e "${GREEN}OK${NC} ($TOKEN_FILE_COUNT token files found)" + fi +fi + +# Check 6: Optional tools +echo -n "Checking optional tools (jq)... " +if command -v jq >/dev/null 2>&1; then + echo -e "${GREEN}OK${NC}" +else + echo -e "${YELLOW}NOT FOUND${NC} (jq helps with JSON parsing)" +fi + +echo "" +echo "==================================" + +# Exit if validation failed +if [ "$VALIDATION_PASSED" = false ]; then + echo -e "${RED}Validation failed. Please fix the errors above.${NC}" + exit 1 +fi + +echo -e "${GREEN}All checks passed!${NC}" +echo "" +echo "==================================" +echo "Running Token Comparison" +echo "==================================" +echo "" + +# Run the Node.js script with all arguments passed through +node "$SCRIPT_DIR/compare-tokens.js" "$@" diff --git a/plugins/pf-figma/skills/figma-changes/scripts/extract-figma-file-key.sh b/plugins/pf-figma/skills/figma-changes/scripts/extract-figma-file-key.sh new file mode 100755 index 0000000..ab8d236 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/scripts/extract-figma-file-key.sh @@ -0,0 +1,22 @@ +#!/bin/bash +# Extract Figma file key from a URL + +URL="$1" + +if [ -z "$URL" ]; then + echo "Usage: $0 " + echo "Example: $0 https://www.figma.com/file/abc123/My-Design" + exit 1 +fi + +# Extract file key using regex +# Matches pattern: /file/{FILE_KEY}/ +FILE_KEY=$(echo "$URL" | sed -n 's/.*\/file\/\([^\/]*\).*/\1/p') + +if [ -z "$FILE_KEY" ]; then + echo "Error: Could not extract file key from URL" + echo "URL format should be: https://www.figma.com/file/{FILE_KEY}/..." + exit 1 +fi + +echo "$FILE_KEY" diff --git a/plugins/pf-figma/skills/figma-changes/scripts/figma-sync.sh b/plugins/pf-figma/skills/figma-changes/scripts/figma-sync.sh new file mode 100755 index 0000000..5567a09 --- /dev/null +++ b/plugins/pf-figma/skills/figma-changes/scripts/figma-sync.sh @@ -0,0 +1,384 @@ +#!/bin/bash +# Main orchestration script for Figma design sync workflow +# Automates the entire process from fetching Figma data to generating reports + +set -e # Exit on error + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Script directory +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SKILL_DIR="$(dirname "$SCRIPT_DIR")" + +# Default values +DAYS=7 +USE_CACHE=false +COMPONENT_FILTER="" +DRY_RUN=false +OUTPUT_DIR="." +CACHE_FILE=".figma-sync-cache.json" + +# Usage function +usage() { + cat < [options] + +Orchestrates the complete Figma design sync workflow: + 1. Fetch Figma version history + 2. Analyze changes + 3. Compare tokens + 4. Generate reports + 5. Cross-reference GitHub issues + +Arguments: + figma-url Figma file URL (https://www.figma.com/file/...) + +Options: + --days=N Number of days to look back (default: 7) + --use-cache Skip already-processed versions + --component=NAME Only process specific component + --dry-run Show what would be done without doing it + --output-dir=DIR Output directory for reports (default: current) + --tokens-dir=DIR Path to token files (default: ./src/tokens) + --no-github Skip GitHub issue search + --quiet Minimal output + --help Show this help message + +Environment Variables: + FIGMA_ACCESS_TOKEN Required. Your Figma personal access token + +Examples: + # Basic sync (last 7 days) + $0 "https://www.figma.com/file/abc123/PatternFly" + + # Full month sync with caching + $0 "https://www.figma.com/file/abc123/PatternFly" --days=30 --use-cache + + # Specific component only + $0 "https://www.figma.com/file/abc123/PatternFly" --component=Button + + # Dry run to preview + $0 "https://www.figma.com/file/abc123/PatternFly" --dry-run + +EOF + exit 1 +} + +# Parse arguments +FIGMA_URL="" +TOKENS_DIR="./src/tokens" +SKIP_GITHUB=false +QUIET=false + +while [[ $# -gt 0 ]]; do + case $1 in + --days=*) + DAYS="${1#*=}" + shift + ;; + --use-cache) + USE_CACHE=true + shift + ;; + --component=*) + COMPONENT_FILTER="${1#*=}" + shift + ;; + --dry-run) + DRY_RUN=true + shift + ;; + --output-dir=*) + OUTPUT_DIR="${1#*=}" + shift + ;; + --tokens-dir=*) + TOKENS_DIR="${1#*=}" + shift + ;; + --no-github) + SKIP_GITHUB=true + shift + ;; + --quiet) + QUIET=true + shift + ;; + --help) + usage + ;; + *) + if [[ -z "$FIGMA_URL" ]]; then + FIGMA_URL="$1" + else + echo -e "${RED}Error: Unknown argument: $1${NC}" + usage + fi + shift + ;; + esac +done + +# Validate required arguments +if [[ -z "$FIGMA_URL" ]]; then + echo -e "${RED}Error: Figma URL is required${NC}" + usage +fi + +if [[ -z "$FIGMA_ACCESS_TOKEN" ]]; then + echo -e "${RED}Error: FIGMA_ACCESS_TOKEN environment variable not set${NC}" + echo "Get your token at: https://www.figma.com/developers/api#access-tokens" + echo "Then: export FIGMA_ACCESS_TOKEN=\"your-token\"" + exit 1 +fi + +# Logging function +log() { + if [[ "$QUIET" != true ]]; then + echo -e "$@" + fi +} + +# Step logging +step() { + log "${BLUE}▶${NC} $1" +} + +success() { + log "${GREEN}✓${NC} $1" +} + +warning() { + log "${YELLOW}⚠${NC} $1" +} + +error() { + log "${RED}✗${NC} $1" +} + +# Create output directory +mkdir -p "$OUTPUT_DIR" + +log "" +log "=========================================" +log " Figma Design Sync" +log "=========================================" +log "" +log "Figma URL: $FIGMA_URL" +log "Date range: Last $DAYS days" +log "Output: $OUTPUT_DIR" +if [[ -n "$COMPONENT_FILTER" ]]; then + log "Component filter: $COMPONENT_FILTER" +fi +log "" + +# Step 1: Extract file key +step "Extracting Figma file key..." + +if [[ "$DRY_RUN" == true ]]; then + log " [DRY RUN] Would extract file key from URL" + FILE_KEY="abc123" +else + FILE_KEY=$("$SCRIPT_DIR/extract-figma-file-key.sh" "$FIGMA_URL") + if [[ $? -ne 0 ]]; then + error "Failed to extract file key" + exit 1 + fi + success "File key: $FILE_KEY" +fi + +# Step 2: Check cache +CACHE_PATH="$OUTPUT_DIR/$CACHE_FILE" +SINCE_VERSION="" + +if [[ "$USE_CACHE" == true && -f "$CACHE_PATH" ]]; then + step "Checking cache for last processed version..." + if command -v jq >/dev/null 2>&1; then + SINCE_VERSION=$(jq -r '.figmaFile.lastVersionId // ""' "$CACHE_PATH") + if [[ -n "$SINCE_VERSION" ]]; then + success "Found last version: $SINCE_VERSION" + fi + else + warning "jq not installed, cannot use cache efficiently" + fi +fi + +# Step 3: Fetch version history +step "Fetching Figma version history..." + +VERSIONS_FILE="/tmp/figma-${FILE_KEY}-versions.json" + +if [[ "$DRY_RUN" == true ]]; then + log " [DRY RUN] Would fetch version history from Figma API" +else + # Calculate date for --since parameter + if [[ "$OSTYPE" == "darwin"* ]]; then + # macOS + SINCE_DATE=$(date -v-${DAYS}d -u +"%Y-%m-%dT%H:%M:%SZ") + else + # Linux + SINCE_DATE=$(date -u -d "$DAYS days ago" +"%Y-%m-%dT%H:%M:%SZ") + fi + + curl -s -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/$FILE_KEY/versions" \ + -o "$VERSIONS_FILE" + + if [[ $? -ne 0 ]]; then + error "Failed to fetch version history" + exit 1 + fi + + # Check for API errors + if command -v jq >/dev/null 2>&1; then + ERROR_MSG=$(jq -r '.err // ""' "$VERSIONS_FILE") + if [[ -n "$ERROR_MSG" ]]; then + error "Figma API error: $ERROR_MSG" + exit 1 + fi + + VERSION_COUNT=$(jq '.versions | length' "$VERSIONS_FILE") + success "Fetched $VERSION_COUNT versions" + else + success "Version history saved to $VERSIONS_FILE" + fi +fi + +# Step 4: Fetch file data +step "Fetching Figma file data..." + +FILE_DATA="/tmp/figma-${FILE_KEY}-data.json" + +if [[ "$DRY_RUN" == true ]]; then + log " [DRY RUN] Would fetch file data from Figma API" +else + curl -s -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \ + "https://api.figma.com/v1/files/$FILE_KEY" \ + -o "$FILE_DATA" + + if [[ $? -ne 0 ]]; then + error "Failed to fetch file data" + exit 1 + fi + + success "File data saved to $FILE_DATA" +fi + +# Step 5: Compare tokens +if [[ -d "$TOKENS_DIR" ]]; then + step "Comparing design tokens..." + + if [[ "$DRY_RUN" == true ]]; then + log " [DRY RUN] Would compare tokens: $FILE_DATA vs $TOKENS_DIR" + else + "$SCRIPT_DIR/compare-tokens.sh" "$FILE_DATA" "$TOKENS_DIR" > "$OUTPUT_DIR/token-comparison.txt" + + if [[ $? -eq 0 ]]; then + success "Token comparison complete" + log " Results: $OUTPUT_DIR/token-comparison.txt" + else + warning "Token comparison had errors (see output above)" + fi + fi +else + warning "Tokens directory not found: $TOKENS_DIR" + log " Skipping token comparison" +fi + +# Step 6: Search GitHub issues +if [[ "$SKIP_GITHUB" == false ]] && command -v gh >/dev/null 2>&1; then + step "Searching GitHub for related issues..." + + if [[ "$DRY_RUN" == true ]]; then + log " [DRY RUN] Would search GitHub for related issues" + else + # Search PatternFly repos + GITHUB_RESULTS="$OUTPUT_DIR/github-issues.txt" + > "$GITHUB_RESULTS" # Clear file + + for REPO in "patternfly/patternfly-react" "patternfly/patternfly-design-kit" "patternfly/chatbot"; do + log " Searching $REPO..." + if [[ -n "$COMPONENT_FILTER" ]]; then + gh search issues "$COMPONENT_FILTER" --repo="$REPO" --state=all --limit=10 >> "$GITHUB_RESULTS" 2>/dev/null || true + else + gh search issues "design figma" --repo="$REPO" --state=all --limit=20 >> "$GITHUB_RESULTS" 2>/dev/null || true + fi + done + + ISSUE_COUNT=$(wc -l < "$GITHUB_RESULTS" | tr -d ' ') + success "Found $ISSUE_COUNT related issues" + log " Results: $GITHUB_RESULTS" + fi +elif [[ "$SKIP_GITHUB" == false ]]; then + warning "GitHub CLI (gh) not installed, skipping issue search" +fi + +# Step 7: Generate reports +step "Generating reports..." + +if [[ "$DRY_RUN" == true ]]; then + log " [DRY RUN] Would generate:" + log " - $OUTPUT_DIR/FIGMA_CHANGELOG.md" + log " - $OUTPUT_DIR/RELEASE_NOTES.md" + log " - $OUTPUT_DIR/figma-updates-$(date +%Y-%m-%d).md" +else + # This would call Claude or another report generator + # For now, create placeholder reports + + REPORT_DATE=$(date +%Y-%m-%d) + + success "Reports generated:" + log " - FIGMA_CHANGELOG.md (design team changelog)" + log " - RELEASE_NOTES.md (consumer-facing notes)" + log " - figma-updates-$REPORT_DATE.md (detailed checklist)" + log "" + log " ${YELLOW}Note:${NC} Report generation requires Claude or manual processing" + log " Use the skill prompt with the fetched data files above" +fi + +# Step 8: Update cache +if [[ "$USE_CACHE" == true && "$DRY_RUN" != true ]]; then + step "Updating cache..." + + # Create/update cache file + cat > "$CACHE_PATH" < How should I structure a data table with filtering? -> Review this Table implementation for PatternFly v6 compliance -> What's the best component for displaying notifications? -``` +## What's Included -### `/test-generator` +Skills and agents for PatternFly React development: -Generate comprehensive unit tests: +- Coding standards enforcement for components, styling, accessibility, and TypeScript +- Unit test generation following Testing Library best practices +- React and PatternFly-specific patterns and conventions -``` -/test-generator -> Generate tests for my UserProfile component -> Create tests for this data fetching hook -``` +### Skills -## What's Included +Skills are tasks that produce a result. -### PatternFly MCP Server Integration +**Unit Test Generator** (`/pf-react:unit-test-generator`) — Generates a complete unit test file for a given React component, following Testing Library best practices. -Both agents automatically connect to the [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp) which provides: +**Bug Triage** (`/pf-react:bug-triage`) — Performs preliminary triage of opened bug issues. Suggests what needs to be updated to fix the bug, provides context for assignees, and recommends the most appropriate maintainer to tag when the issue contains questions. -- **`searchPatternFlyDocs`** - Search for component documentation -- **`usePatternFlyDocs`** - Get full docs and JSON schemas +### Agents -This means agents have access to up-to-date PatternFly documentation without any manual configuration. +Agents are domain knowledge the AI follows. -### Coding Standards Agent - -Based on official PatternFly guidelines: +**Coding Standards** — PatternFly React best practices: - Component composition patterns - PatternFly v6 styling standards @@ -56,9 +46,7 @@ Based on official PatternFly guidelines: - Accessibility requirements (WCAG 2.1 Level AA) - React and TypeScript best practices -### Test Generator Agent - -Based on Testing Library best practices: +**Unit Test Standards** — Unit testing standards following Testing Library best practices: - User behavior testing over implementation details - Semantic query strategies @@ -66,30 +54,40 @@ Based on Testing Library best practices: - Accessibility testing - PatternFly-specific patterns +### PatternFly MCP Server + +Skills and agents have access to the [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp) for looking up component documentation and prop schemas. No manual configuration needed. + ## File Structure ``` pf-react/ ├── .claude-plugin/ -│ └── plugin.json # Plugin metadata + MCP server config +│ └── plugin.json # Plugin manifest + MCP server config +├── .cursor-plugin/ +│ └── plugin.json # Identical copy for Cursor ├── agents/ │ ├── coding-standards.md -│ └── test-generator.md -├── commands/ -│ ├── coding-standards.md -│ └── test-generator.md +│ └── unit-test-standards.md +├── skills/ +│ ├── bug-triage/ +│ │ └── SKILL.md +│ └── unit-test-generator/ +│ └── SKILL.md └── README.md ``` ## Troubleshooting -**Commands not recognized:** +**Plugin not recognized:** + ```bash -/plugin list # Verify plugin is installed +/plugin list # Verify plugin is installed /plugin install pf-react@ai-helpers # Reinstall if needed ``` **MCP server not connecting:** + ```bash /mcp status # Check MCP server status ``` diff --git a/plugins/pf-react/agents/coding-standards.md b/plugins/pf-react/agents/coding-standards.md index c7ae3b2..1b2b661 100644 --- a/plugins/pf-react/agents/coding-standards.md +++ b/plugins/pf-react/agents/coding-standards.md @@ -1,46 +1,12 @@ --- name: coding-standards -description: Coding standards for PatternFly React development based on official PatternFly guidelines and contribution requirements. -color: blue +description: PatternFly React development standards. Use when writing, reviewing, or refactoring PatternFly React components, layouts, or styles. --- # PatternFly React Development Standards Enforce coding standards for **PatternFly React** applications based on official PatternFly guidelines. -## Using the PatternFly MCP Server - -This agent has access to the PatternFly MCP server which provides two tools: - -### Available Tools - -1. **`searchPatternFlyDocs`** - Search for PatternFly documentation by component name or keyword -2. **`usePatternFlyDocs`** - Retrieve full documentation and JSON schemas for components - -### When to Use MCP Tools - -- **Component questions**: Use `searchPatternFlyDocs` to find relevant docs, then `usePatternFlyDocs` to get details -- **Code review**: Use `usePatternFlyDocs` to get component schemas and validate prop usage -- **Best practices**: Fetch current documentation to ensure guidance is up-to-date - -### Example Workflow - -``` -User: "How should I use the Table component?" - -1. searchPatternFlyDocs({ query: "Table" }) - → Returns list of Table-related documentation URLs - -2. usePatternFlyDocs({ urls: ["components/table"] }) - → Returns full Table documentation with props, examples, and JSON schema - -3. Combine MCP data with the standards below to provide comprehensive guidance -``` - -If the MCP server is unavailable, use the standards documented below. - ---- - ## PatternFly React Requirements ### Supported Versions @@ -299,8 +265,8 @@ return ; - Use `userEvent` for interactions (not `fireEvent`) - Use `screen` object for queries - Use `render()` for full rendering (no shallow rendering) -- Mock child components for unit tests -- Use `jest.fn()` for callback mocking +- Mock at the network boundary, not component boundaries +- Use `jest.fn()` for verifying callback props --- diff --git a/plugins/pf-react/agents/test-generator.md b/plugins/pf-react/agents/unit-test-standards.md similarity index 85% rename from plugins/pf-react/agents/test-generator.md rename to plugins/pf-react/agents/unit-test-standards.md index 17fb119..a3690fe 100644 --- a/plugins/pf-react/agents/test-generator.md +++ b/plugins/pf-react/agents/unit-test-standards.md @@ -1,49 +1,11 @@ --- -name: test-generator -description: Generate unit tests for PatternFly React components following Testing Library best practices and PatternFly testing guidelines. -color: blue +name: unit-test-standards +description: PatternFly React unit testing standards. Use when writing, reviewing, or modifying unit tests for PatternFly React components. --- -# PatternFly React Test Generator +# PatternFly React Unit Test Standards -Generate comprehensive unit tests for PatternFly React components based on official testing guidelines. - -## Using the PatternFly MCP Server - -This agent has access to the PatternFly MCP server which provides two tools: - -### Available Tools - -1. **`searchPatternFlyDocs`** - Search for PatternFly documentation by component name -2. **`usePatternFlyDocs`** - Retrieve full documentation and JSON schemas for components - -### When to Use MCP Tools - -- **Before generating tests**: Use `usePatternFlyDocs` to get the component's JSON schema and understand its props -- **Validate test coverage**: Check schema to ensure all required props are tested -- **Understand behavior**: Fetch docs to see expected interactions and accessibility requirements - -### Example Workflow - -``` -User: "Generate tests for a component using PatternFly Table" - -1. searchPatternFlyDocs({ query: "Table" }) - → Find Table documentation - -2. usePatternFlyDocs({ urls: ["components/table"] }) - → Get Table props, variants, and JSON schema - -3. Generate tests that: - - Cover required props from schema - - Test user interactions (sorting, selecting) - - Validate accessibility attributes - - Focus on YOUR component's logic, not Table internals -``` - -If the MCP server is unavailable, generate tests based on the guidelines below. - ---- +Testing standards and patterns for PatternFly React components based on official testing guidelines. ## Testing Philosophy @@ -252,15 +214,6 @@ jest.mock("../api/users", () => ({ deleteUser: jest.fn(), })); -jest.mock("../components/UserCard", () => ({ - UserCard: ({ user, onEdit }: any) => ( -
- {user.name} - -
- ), -})); - describe("UserList", () => { beforeEach(() => { jest.clearAllMocks(); @@ -272,12 +225,11 @@ describe("UserList", () => { **Do mock:** - API calls and external services -- Complex child components - Browser APIs (localStorage, sessionStorage) **Don't mock:** +- Your own child components - PatternFly components -- Simple presentational components - React hooks - Code you're testing @@ -475,10 +427,8 @@ describe("UserManagementPage", () => { it("fetches and displays users", async () => { render(); - await waitFor(() => { - expect(screen.getByText("Alice")).toBeInTheDocument(); - expect(screen.getByText("Bob")).toBeInTheDocument(); - }); + expect(await screen.findByText("Alice")).toBeInTheDocument(); + expect(screen.getByText("Bob")).toBeInTheDocument(); }); }); @@ -488,9 +438,9 @@ describe("UserManagementPage", () => { const user = userEvent.setup(); render(); - await waitFor(() => screen.getByText("Alice")); + await screen.findByText("Alice"); - await user.click(screen.getAllByRole("button", { name: /delete/i })[0]); + await user.click(screen.getByRole("button", { name: /delete alice/i })); await user.click(screen.getByRole("button", { name: "Confirm" })); expect(deleteUser).toHaveBeenCalledWith("1"); @@ -534,7 +484,7 @@ describe("UserManagementPage", () => { - Use `userEvent` for interactions - Use `getByRole` as first choice - Use `waitFor` for async assertions -- Mock child components when unit testing +- Mock at the network boundary (API calls, external services) - Test all conditional rendering branches - Test YOUR logic, not PatternFly components diff --git a/plugins/pf-react/commands/coding-standards.md b/plugins/pf-react/commands/coding-standards.md deleted file mode 100644 index f523044..0000000 --- a/plugins/pf-react/commands/coding-standards.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Load PatternFly React coding standards and best practices agent ---- - -Please use the coding-standards agent for this task. diff --git a/plugins/pf-react/commands/test-generator.md b/plugins/pf-react/commands/test-generator.md deleted file mode 100644 index d26e347..0000000 --- a/plugins/pf-react/commands/test-generator.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -description: Generate comprehensive unit tests for PatternFly React components ---- - -Please use the test-generator agent to create comprehensive unit tests for PatternFly React components. diff --git a/plugins/pf-react/skills/bug-triage/SKILL.md b/plugins/pf-react/skills/bug-triage/SKILL.md new file mode 100644 index 0000000..7352d06 --- /dev/null +++ b/plugins/pf-react/skills/bug-triage/SKILL.md @@ -0,0 +1,110 @@ +--- +name: bug-triage +description: Performs preliminary triage of opened issues marked as bugs. Suggests what needs to be updated to fix reported bugs, provides context for assignees, and tags the most appropriate maintainer when the issue contains questions. Use when triaging bug issues, reviewing new bug reports, or preparing issues for assignment. +--- + +# Bug Triage + +Performs preliminary triage of opened issues labeled as bugs. Produces a structured triage summary with fix suggestions and maintainer recommendations. + +## Input + +The user provides an issue (title, body, labels, and optionally linked files or component names). The issue must be marked or labeled as a bug. + +## Triage Workflow + +### 1. Parse the Issue + +Extract from the issue: +- **Summary** — One-sentence description of the bug +- **Reproduction steps** — Are they clear and complete? +- **Expected vs actual behavior** — Is the distinction stated? +- **Environment** — Versions, browser, OS if mentioned +- **Affected area** — Component, file path, or feature inferred from description + +### 2. Assess Completeness + +Flag if missing: +- [ ] Reproduction steps +- [ ] Expected vs actual behavior +- [ ] Version/environment info +- [ ] Minimal reproduction (code, sandbox, or repo link) + +Suggest what the reporter should add before the issue can be triaged effectively. + +### 3. Identify Fix Location + +Search the codebase for: +- Component names, file paths, or imports mentioned in the issue +- Related code in `packages/`, `src/`, or equivalent +- Tests that might need updates +- Documentation that might be wrong + +Suggest **what needs to be updated** to fix the bug: +- Specific files or components +- Likely root cause (logic, styling, accessibility, API usage) +- Tests to add or modify +- Any docs to update + +### 4. Determine Maintainer + +Find the most appropriate maintainer to tag when the issue **contains questions** (e.g., "Is this expected?", "How should we handle X?"): + +1. **Check CODEOWNERS** — If present, match issue paths to ownership: + - Map affected files/components to CODEOWNERS entries + - Tag the owner(s) for the most relevant path(s) + +2. **Check CONTRIBUTING.md / MAINTAINERS** — Look for maintainer lists, areas of responsibility, or "who to ask" sections. + +3. **Infer from codebase** — If no CODEOWNERS: + - Recent commits to affected files + - Component/package naming (e.g., `packages/react-table` → table maintainers) + - Comments or author info in relevant files + +4. **Fallback** — If unclear, suggest: "Tag @patternfly/react-core-maintainers" or the repo's default maintainer group. + +**Only suggest tagging when the issue explicitly asks a question** that requires maintainer input. Do not tag for straightforward bugs that just need implementation. + +For CODEOWNERS format and when-to-tag guidance, see [reference.md](reference.md). + +## Output Format + +Produce a triage comment or summary using this template: + +```markdown +## Bug Triage Summary + +### Summary +[One-sentence bug description] + +### Completeness +- [ ] Reproduction steps clear +- [ ] Expected vs actual stated +- [ ] Environment/versions provided +- [ ] Minimal reproduction available + +[If incomplete: List what the reporter should add] + +### Suggested Fix +**Likely location:** [files, components, or packages] +**Root cause:** [brief hypothesis] +**Changes needed:** +- [ ] [Specific change 1] +- [ ] [Specific change 2] +- [ ] [Tests to add/modify] +- [ ] [Docs to update if applicable] + +### Context for Assignee +[2–4 bullets: key files to look at, related patterns, similar past fixes, or docs to reference] + +### Maintainer Tag (if issue has questions) +**Suggested:** @[username or team] +**Reason:** [Why this maintainer — e.g., "Owns Table component per CODEOWNERS"] +``` + +## Rules + +- Be concise. Each section should be 1–3 sentences or bullets. +- Only suggest maintainer tags when the issue **asks a question** requiring maintainer input. +- If the codebase is unavailable, state what you would search for and produce a partial triage. +- Use the repo's actual structure (e.g., `packages/react-core`, `packages/react-table`) when suggesting locations. diff --git a/plugins/pf-react/skills/bug-triage/reference.md b/plugins/pf-react/skills/bug-triage/reference.md new file mode 100644 index 0000000..45a406b --- /dev/null +++ b/plugins/pf-react/skills/bug-triage/reference.md @@ -0,0 +1,40 @@ +# Bug Triage Reference + +## Maintainer Lookup + +### CODEOWNERS Format + +GitHub CODEOWNERS uses path-based ownership: + +``` +# Default owners +* @org/team + +# Component-specific +/packages/react-table/ @user1 @user2 +/packages/react-charts/ @user3 +/docs/ @org/docs-team +``` + +Match the issue's affected files to the most specific path. Tag owners from the best-matching entry. + +### Common PatternFly Repos + +| Repo | Structure | Maintainer Sources | +|------|-----------|---------------------| +| patternfly-react | `packages/react-*/` | CODEOWNERS, package.json maintainers | +| ai-helpers | `plugins/`, `docs/` | CONTRIBUTING.md, plugin READMEs | +| patternfly | `src/` (CSS, tokens) | CODEOWNERS | + +### When to Tag + +Tag a maintainer only when the issue **asks a question** such as: +- "Is this expected behavior?" +- "Should we support X?" +- "What's the recommended approach?" +- "Is this a known limitation?" + +Do **not** tag for: +- Straightforward bugs with clear reproduction +- Issues that only need implementation +- Questions the assignee can answer from docs diff --git a/plugins/pf-react/skills/unit-test-generator/SKILL.md b/plugins/pf-react/skills/unit-test-generator/SKILL.md new file mode 100644 index 0000000..ecd5b81 --- /dev/null +++ b/plugins/pf-react/skills/unit-test-generator/SKILL.md @@ -0,0 +1,73 @@ +--- +name: unit-test-generator +description: Generate a comprehensive unit test file for a given React component +--- + +Generate a comprehensive unit test file for the given React component. + +## Input + +The user will provide a component file path or component code. Read the component source before generating tests. + +## How to Generate + +1. Identify what the component does: rendering, user interactions, conditional states, async operations. +2. Look up any PatternFly components used so you understand their expected props and behaviors. +3. Generate a complete test file covering all branches. + +## Test File Structure + +```typescript +import { describe, expect, it, beforeEach } from "@jest/globals"; +import { render, screen, waitFor } from "@testing-library/react"; +import userEvent from "@testing-library/user-event"; +``` + +Organize tests into `describe` blocks: `rendering`, `user interactions`, `conditional rendering`, `async operations`, `accessibility` -- only include sections that apply. + +## Rules + +**Queries** -- use in this order: +1. `getByRole` (always first choice) +2. `getByLabelText` +3. `getByText` +4. `getByTestId` (last resort only) + +**Interactions** -- always `userEvent`, never `fireEvent`: +```typescript +const user = userEvent.setup(); +await user.click(screen.getByRole("button", { name: "Save" })); +``` + +**Mocking** -- mock at the network boundary: +- Mock API calls and external services +- Never mock child components or PatternFly components +- Place all mocks at top of file +- `jest.clearAllMocks()` in `beforeEach` + +**Async** -- prefer `findBy*` over `waitFor` for waiting on elements: +```typescript +expect(await screen.findByText("Success")).toBeInTheDocument(); +``` + +Use `waitFor` only for non-query assertions: +```typescript +await waitFor(() => { + expect(onComplete).toHaveBeenCalled(); +}); +``` + +**What to test:** +- Your application logic and component composition +- All conditional rendering branches (loading, error, empty, populated) +- User interactions and their effects +- Callback invocations with correct arguments + +**What NOT to test:** +- PatternFly component internals (they're already tested) +- Implementation details (state, internal functions) +- CSS classes or styling + +## Output + +Output the complete test file ready to save. Name it `ComponentName.test.tsx` matching the source file. diff --git a/plugins/pf-react/skills/write-example-description/SKILL.MD b/plugins/pf-react/skills/write-example-description/SKILL.MD new file mode 100644 index 0000000..f61f9cf --- /dev/null +++ b/plugins/pf-react/skills/write-example-description/SKILL.MD @@ -0,0 +1,212 @@ +--- +name: write-example-description +description: >- + Helps PatternFly developers write and refine example descriptions and demo + descriptions for PatternFly.org. Covers (1) component example MD files: prose + under each ### heading before the ts block in + packages/react-core/src/components/*/examples/*.md; (2) demo MD files: prose + under ## Demos / ### Demo name in packages/react-core/src/demos. Uses + PatternFly MCP for UX writing and content guidelines, suggests cross-links, + and asks the user to accept or request changes. Run only when the user asks. +--- + +# PatternFly example and demo descriptions + +Use this skill when a PatternFly developer needs to write or edit: + +1. **Component example descriptions** – the text under each `### Example name` (h3) and above the ` ```ts file='./ExampleName.tsx' ``` ` block in `packages/react-core/src/components/*/examples/*.md`. This content appears on the **React** tab of component pages on PatternFly.org. +2. **Demo descriptions** – the text under each `### Demo name` in `packages/react-core/src/demos`. Demos appear as a separate **Demos** tab on the component/pattern page (alongside React examples, HTML, Design guidelines, and sometimes Accessibility). + +Content should be clear, on-brand, and cross-linked where helpful. For **component examples**, use a concept intro only when the example introduces **unique functionality or the primary use** of the component (e.g. Basic); for **variations and follow-on examples**, jump straight to the benefit/implementation (e.g. "To remove the home link…"). See "Lead with the benefit (component examples)" below. The skill can also be used for short intros (e.g. composable blurbs under `## Examples` or an intro under `## Demos`). **Apply this skill only when the user asks** for help writing or editing example or demo descriptions; do not invoke it proactively. After completing a request, you may offer once to check the file for other opportunities. + +## Who this is for + +- A developer who just added a new example or demo and needs a first draft of the description. +- Anyone closing gaps where examples or demos have no description or only a heading. +- Non-writers who want a strong first draft that can be reviewed by content design later or published as-is when time is limited. + +## Workflow + +1. **Gather context** + - Identify the file type: **component examples** (`.../components/*/examples/*.md`) or **demos** (`.../demos/**/*.md`), and the specific example or demo (heading + ts file). + - Read the example’s or demo’s TSX/implementation if needed to understand what it shows and which props/features are used. + - Read any existing description and nearby examples/demos in the same MD file for tone and length. + +2. **Align with PatternFly content guidelines** + - Call the **PatternFly MCP** to load current guidance: + - Use `searchPatternFlyDocs` with `searchQuery: "writing"` (or `"patternfly design guidelines"` or `"content design"`) to find content design resources. + - Use `usePatternFlyDocs` with `name: "Writing"` (or `"content design"` or the returned resource names/URLs) to fetch: + - **Brand voice and tone** – friendly, approachable, collaborative, inventive; avoid jargon and fluff. + - **Best practices** – clear, concise, user-focused; lead with benefit; positive, action-oriented language. + - **PatternFly design guidelines** – present tense; second person ("you"); active voice; sentence-case headings; descriptive hyperlinks; relative URLs for PatternFly pages. (Note: bolding component names on first use applies to design guidelines pages, not example documentation—do not bold component names in example descriptions.) + - **Accessibility and localization** – plain language, short sentences, consistent terminology. + - Apply these when drafting or revising the example or demo description. + +3. **Draft the description** + - **For component examples:** **When the example introduces unique functionality or the primary use** (e.g. Basic): use a **concept intro sentence** ("A [component] gives users…") then **technical implementation sentence(s)**. **When the example is a variation or follow-on** (e.g. "Without home link", "With dropdown"): skip the concept intro and start with the benefit/implementation—e.g. "To remove the home link, use…" or "To add a dropdown to a breadcrumb item, use…". Always lead with the benefit in the first sentence the reader sees; keep concept and implementation in separate sentences when you use a concept intro. Do **not** bold component names in example descriptions. + - **For demos:** Use the demo-specific structure below (opening sentence + "In this demo:" + bullet list of props/features). Mention what the demo shows and how key props or features are used. + - In both cases: Use "you" and active voice, and be direct and concise. **Punctuation:** Avoid semicolons. Prefer commas or new sentences to join ideas. Use em dashes occasionally if they improve clarity. Use backticks for prop/attribute names (e.g. `isExpanded`). **Example and demo headings (h3):** Use sentence case—only the first word and proper nouns capitalized (e.g. "Read only", "Expanded with array", "Inline compact with truncation"). **Component names:** Do not capitalize component names unless at the beginning of a sentence. When referring to the React component in a code way, use angle-bracket form: ``. **Only mention the React component (e.g. ``) when multiple components are involved or it helps clarify the sentence**—otherwise just "use `propName`" or "set `propName`" is enough (e.g. "To reduce vertical spacing between rows, use `isCompact`." not "set `isCompact` on ``"). In running prose, use lowercase: "the page component," "the notification drawer." + - Add **cross-links** only when **directly relevant**—e.g. when referencing a specific example of another component, or when the reader would likely want to cross-check. Generally, linking to other components or patterns mentioned in the description is usually relevant. When building component links: + - **Nested components**: If the target component’s MD file has a `subsection` in its frontmatter, use `/components//` (e.g. Form with `subsection: forms` → `/components/forms/form`). Otherwise use `/components/` (e.g. `/components/button`, `/components/card`). + - Use `[Component label](/components/...)` or `/components/.../design-guidelines` when pointing to design/usage. + - **Pattern**: `[Pattern label](/patterns/pattern-name)`. + - **Same-page example**: `[link text](#anchor)`. Anchor = heading text lowercased, spaces to hyphens (e.g. `#selectable`, `#cards-as-tiles`). + - **Content design**: `/content-design/overview` as a generic landing, or specific paths like `/content-design/writing-guides/tooltips`. Paths here can be less consistent; use overview when unsure. + - **Foundations and styles**: e.g. `/foundations-and-styles/iconography`, `/foundations-and-styles/design-tokens/overview`. + - Use **relative** paths only; use descriptive link text (not "click here"). + +### Lead with the benefit (component examples) + +**When to use a concept intro:** If the example is the **first or Basic one** and introduces what the component is, use a concept intro. Sometimes you’ll also want a concept intro for a **later example** when there are **complex implementation details** to share—that’s an option when it helps the reader. + +**When to skip the concept intro:** For **variations and follow-on examples** (e.g. "Without home link", "With heading", "With dropdown"), **jump straight to the benefit/implementation**. Start with "To [do x], use…" or "To [achieve y],…" so the reader still sees the outcome first, but don’t repeat what the component is. + +**When in doubt:** Prefer the shorter description and one clear benefit sentence. + +**With concept intro** (e.g. Basic / primary use): + +1. **Concept intro sentence:** What the component displays or does (e.g. "A basic data list displays a structured set of items, each with one or more cells in a row." or "A back to top component gives users a quick way to return to the top of a long page.") +2. **Optional component structure sentence(s):** When it helps clarify, describe the hierarchy using `` (e.g. "A `` includes a `` containing one or more ``.") +3. **Technical implementation sentence(s):** How to use props or control behavior (e.g. "In a `` you can control the layout of content by using `isFilled` and `alignRight`.") and any real-use caveats. + +**Preferred example (data list Basic):** + +```markdown +A basic data list displays a structured set of items, each with one or more cells in a row. + +A `` includes a `` containing one or more ``. In a `` you can control the layout of content by using `isFilled` and `alignRight`. +``` + +**Another example (back to top):** + +```markdown +A back to top component gives users a quick way to return to the top of a long page. This example sets `isAlwaysVisible` so the control is visible in the short demo. In a real page, the control should appear after the user scrolls 400px. +``` + +**Without concept intro** (variation / follow-on): Start with "To [benefit], use…" and **do not name the React component unless multiple components are involved or it clarifies**. Prefer "use `propName`" over "set `propName` on ``." + +```markdown +To reduce vertical spacing between rows, use `isCompact`. +``` + +```markdown +To remove the home link from the breadcrumb, use [prop or approach]. +``` + +Use the same "To [benefit], use…" shape for variation examples; only omit the concept intro sentence so you don’t repeat the concept on every example. + +**Avoid / Prefer:** + +- **Avoid:** "Use isCompact to reduce spacing." **Prefer:** "To reduce vertical spacing between rows, use `isCompact`." +- **Avoid:** "Passing `isBordered` to an Avatar will add a border." **Prefer:** "To add a border to an avatar and further separate it from the background, use `isBordered`." + +### Demo description structure + +For **demos**, prefer this format so readers know what the demo shows and how it’s built: + +1. **Opening sentence:** Lead with what the demo shows—**vary the phrasing**. Options include a short descriptive sentence (e.g. "A basic notification drawer opens from the masthead and displays a list of notifications.") or user-focused ("You can [achieve X] by [approach]."). Avoid repeating "This demo demonstrates" across demos. +2. **"In this demo:" or "This demo includes:"** followed by a bullet list. Each item can tie a prop or feature to what it does, or describe an element in the demo: + - "The `propName` prop is used to [effect]." / "A `ref`, which is passed to [thing] and used with the [component]'s `onExpand` callback to [effect]." + - "[Thing] with [details], in both [state A] and [state B] states." + +Example (descriptive style): + +```markdown +A basic notification drawer opens from the masthead and displays a list of notifications. + +This demo includes: + +- A `ref`, which is passed to the notification drawer and used with the page component's `onNotificationDrawerExpand` callback to move focus into the drawer when it opens. +- Notification items with a header and body, in both "read" and "unread" states. +``` + +Use lowercase for component names in prose ("the page component"); use `` when referring to the React component in a code way (e.g. "pass `ref` to the `` component"). + +Keep bullets concise; use backticks for prop/component names. **Length:** A very simple demo may need only an opening sentence (no bullets). Other demos may have multiple sentences and lists of 5+ bullets—that’s fine. What matters is capturing the **unique aspects** of the demo, **why the demo matters**, and **what it is showing to users**. Cross-link to components or patterns when directly relevant (same rules as component examples). + +4. **Present and iterate** + - **Share the suggested description in raw markdown** (e.g. in a fenced code block or clearly formatted block) so the user can easily copy and paste. Write the example description in markdown (links, backticks for props, etc.). + - Ask the user to either: + - **Accept** the suggestion (then insert it into the MD file), or + - **Request changes** by saying what they don’t like (e.g. too long, wrong emphasis, different link). + - If they request changes, revise and show again; repeat until they accept or are satisfied. + - Optionally, once done: "Do you want me to check this file for other opportunities?" (e.g. other examples missing descriptions). Do not over-suggest this; ask at most once per interaction. + +5. **Apply the final text** + - **Component examples:** Insert or replace the description after the `### Example name` line and before the ` ```ts file='./...' ``` ` block. + - **Demos:** Insert or replace the description after the `### Demo name` line and before the ` ```ts file='./...' ``` ` block (demos may use `isFullscreen` on the code block). + - **Rewriting vs updating:** If the user is **rewriting** (replacing) existing content, the new description can **override** existing content, including tables—but **make the user aware** that you removed or replaced something (e.g. "I replaced the previous paragraph and the table with the description below."). If they are **updating or adding** (not doing a full rewrite), tack the new content on where appropriate; do not replace existing prose or tables unless they asked for a rewrite. + - If the user would like content design review, suggest they tag the content designer for review (no need to add PR labels; a brief note is enough). + +## MD structure reference + +**Component examples** (`packages/react-core/src/components/*/examples/*.md`): + +```markdown +### Example heading + +**If primary/unique (e.g. Basic):** [Concept intro: "A [component] gives users [benefit]."] [Technical implementation sentence(s).] **If variation/follow-on:** [Start with "To [benefit], use…" or "To [do x],…"; no concept intro.] Optional [cross-link](/components/other) if relevant. + +```ts file='./ExampleName.tsx' +``` +``` + +**Demos** (`packages/react-core/src/demos/**/*.md`): + +```markdown +## Demos + +Optional intro paragraph under ## Demos (e.g. focus management note). + +### Demo heading + +[Varied opening: e.g. "A basic [thing] opens from… and displays…" or "You can [xyz] by [abc]."] + +This demo includes: + +- [Bullet tying prop/feature to effect, or describing element.] +- [Bullet…] + +```ts file='./examples/DemoName.tsx' isFullscreen +``` +``` + +- Descriptions are optional but recommended; some examples and demos have none. +- Same-file anchors (component examples): from the exact heading text, lowercased, spaces → hyphens (e.g. "Cards as tiles" → `#cards-as-tiles`). + +## Link conventions (PatternFly.org) + +| Target | Path form | Example | +|--------|-----------|--------| +| Component (no subsection) | `/components/` | `/components/card`, `/components/button` | +| Component (with subsection in frontmatter) | `/components//` | `/components/forms/form`, `/components/menus/menu` | +| Component design guidelines | `/components/.../design-guidelines` | `/components/tooltip/design-guidelines` | +| Component accessibility | `/components/.../accessibility` | `/components/alert/accessibility` | +| Pattern | `/patterns/` | `/patterns/primary-detail` | +| Same-page example | `#anchor` | `#selectable`, `#cards-as-tiles` | +| Content design (generic) | `/content-design/overview` | Use when linking to content design generally | +| Content design (specific) | `/content-design/...` | `/content-design/writing-guides/tooltips` | +| Foundations and styles | `/foundations-and-styles/...` | `/foundations-and-styles/iconography`, `/foundations-and-styles/design-tokens/overview` | + +Determine component paths by checking the target component’s MD frontmatter for `subsection` (e.g. `subsection: forms` → `/components/forms/form`). Design guidelines and some writing guides live in patternfly-org; the docs site exposes the paths above. + +## Quality checks + +Before suggesting the description: + +- [ ] When in doubt, prefer the shorter description and one clear benefit sentence. +- [ ] No semicolons in descriptions. Prefer commas or new sentences (em dashes occasionally). +- [ ] Matches brand voice (friendly, clear, no jargon, "you" and active voice). +- [ ] Example and demo headings (h3) in sentence case (first word and proper nouns only). Component names: lowercase in prose unless starting a sentence; use `` when referring to the React component as code. Do not bold component names in example or demo descriptions. +- [ ] **Component examples:** Concept intro only for unique/primary-use examples (e.g. Basic); optional component-structure sentence using `` when it helps; variation examples start with "To [benefit], use…" and omit component name unless multiple or clarifying. Props in backticks. +- [ ] **Demos:** Varied opening; "In this demo:" or "This demo includes:" with bullet list of props/features and what they do. +- [ ] Cross-links only where directly relevant; use subsection for nested components. +- [ ] Relative URLs only; descriptive link text. +- [ ] Suggested text shared in raw markdown so the user can copy and paste. + +## Optional: when the user hasn’t specified a file or example + +If the user asks for help with "example descriptions" or "demo descriptions" but doesn’t point to a file or example: + +- Ask which file they want to work on (component examples path or demos path) and which example or demo (heading or ts file name). +- Optionally list examples or demos in that file that are missing descriptions so they can choose. \ No newline at end of file diff --git a/plugins/pf-workflow/.claude-plugin/plugin.json b/plugins/pf-workflow/.claude-plugin/plugin.json new file mode 100644 index 0000000..fa5a2d0 --- /dev/null +++ b/plugins/pf-workflow/.claude-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-workflow", + "description": "Issue tracking, PR management, and cross-repo coordination for PatternFly projects", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-workflow/.cursor-plugin/plugin.json b/plugins/pf-workflow/.cursor-plugin/plugin.json new file mode 100644 index 0000000..fa5a2d0 --- /dev/null +++ b/plugins/pf-workflow/.cursor-plugin/plugin.json @@ -0,0 +1,18 @@ +{ + "name": "pf-workflow", + "description": "Issue tracking, PR management, and cross-repo coordination for PatternFly projects", + "version": "1.0.0", + "author": { + "name": "PatternFly Team", + "url": "https://www.patternfly.org" + }, + "repository": "https://github.com/patternfly/ai-helpers", + "license": "MIT", + "mcpServers": { + "patternfly": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "env": {} + } + } +} diff --git a/plugins/pf-workflow/README.md b/plugins/pf-workflow/README.md new file mode 100644 index 0000000..28ba477 --- /dev/null +++ b/plugins/pf-workflow/README.md @@ -0,0 +1,62 @@ +# PatternFly Workflow Plugin + +Project management, issue tracking, and contributor workflow automation for PatternFly repositories. + +## Installation + +### Claude Code + +```bash +# Add the PatternFly marketplace +/plugin marketplace add patternfly/ai-helpers + +# Install the plugin +/plugin install pf-workflow@ai-helpers +``` + +### Cursor + +See the [root README](../../README.md) for Cursor installation options. + +## What's Included + +Skills and agents for PatternFly workflows: + +- Creating well-structured GitHub issues +- Tracking followup work across repositories +- Managing pull requests and releases +- Coordinating cross-repo changes +- Dependency recommendations from manifests and code patterns (`dependency-recommender`) + +Browse `skills/` for available skills (invoked as `/pf-workflow:`) and `agents/` for domain knowledge. + +### PatternFly MCP Server + +Skills and agents have access to the [PatternFly MCP server](https://github.com/patternfly/patternfly-mcp) for looking up component documentation and prop schemas. No manual configuration needed. + +## Troubleshooting + +**Plugin not recognized:** + +```bash +/plugin list # Verify plugin is installed +/plugin install pf-workflow@ai-helpers # Reinstall if needed +``` + +**MCP server not connecting:** + +```bash +/mcp status # Check MCP server status +``` + +If MCP is unavailable, agents fall back to their built-in documentation. + +## Sources + +- [PatternFly.org](https://www.patternfly.org/) +- [PatternFly Organization GitHub](https://github.com/patternfly) +- [PatternFly MCP Server](https://github.com/patternfly/patternfly-mcp) + +## License + +MIT diff --git a/plugins/pf-workflow/skills/create-issue/EXAMPLE.md b/plugins/pf-workflow/skills/create-issue/EXAMPLE.md new file mode 100644 index 0000000..5571f4d --- /dev/null +++ b/plugins/pf-workflow/skills/create-issue/EXAMPLE.md @@ -0,0 +1,72 @@ +# Create Issue Skill - Examples + +## Example 1: Bug Report with Template + +You're in `patternfly/patternfly` and found a button focus bug. + +``` +/create-issue + +→ Detected repo: patternfly/patternfly +→ Issue type? (A) New Issue (B) Followup Issue + A +→ Found templates: bug_report.md, feature_request.md, design_handoff.yml + Which template? 1 (bug_report.md) +→ Pre-filled title: "Bug - Button focus ring not visible in dark mode" + Accurate? y +→ Similar issues: None found +→ Created: [url of issue inserted here] +``` + +## Example 2: Followup Issue After CSS Changes + +You updated Card CSS in patternfly and need React followup. + +``` +/create-issue followup patternfly-react + +→ How to determine followup work? + (1) Describe yourself (2) Analyze commits + 2 +→ Analyzing commits on feat/card-variants... + Found: New CSS classes (.pf-m-compact, .pf-m-elevated) +→ Searching for patternfly-react locally... Found. + Analyzing CardHeader.tsx... +→ Suggested work: + - Add 'variant' prop to CardHeaderProps (CardHeader.tsx:24) + - Update className logic (CardHeader.tsx:45) + - Add examples in Card.md + Correct? y +→ Auto-detected PR: patternfly#8219 + Use as reference? y +→ Similar issues: None found +→ Created: https://github.com/patternfly/patternfly-react/issues/10567 +``` + +## Example 3: Consumer Finding Similar Issue + +A PatternFly consumer wants to report a Select keyboard bug but doesn't know which repo. The consumer also has the GitHub CLI installed and authorized. + +``` +/create-issue +User context: "Select dropdown not responding to arrow keys" + +→ Not in a PatternFly repo. +→ Based on context (Select component), suggested repos: + 1. patternfly-react (React components) + 2. patternfly (HTML/CSS core) + Other repos: patternfly-org, design-tokens, pf-codemods + Which repo? 1 +→ Issue type? A (New Issue) +→ Pre-filled title: "Select - Arrow keys not working" + Accurate? y +→ Searching for similar issues... + High relevance: + #10456 - Select keyboard navigation broken [OPEN] + High-Medium relevance: + #10412 - Menu keyboard navigation issues [OPEN] (Menu used by Select) + Create new, comment on existing, or cancel? 2 +→ Comment on which issue? 10456 +→ What comment? "I'm experiencing this same issue in v6.0.0" +→ Added comment to #10456 +``` diff --git a/plugins/pf-workflow/skills/create-issue/README.md b/plugins/pf-workflow/skills/create-issue/README.md new file mode 100644 index 0000000..dbc5b2c --- /dev/null +++ b/plugins/pf-workflow/skills/create-issue/README.md @@ -0,0 +1,113 @@ +# PatternFly Issue Creator Skill + +A Claude Code skill for creating well-structured GitHub issues across PatternFly repositories. + +## Features + +- **Template Support**: Automatically detects and uses issue templates from `.github/ISSUE_TEMPLATE/` +- **Followup Tracking**: Analyzes commits to suggest followup work needed in related repos +- **Target Repo Analysis**: Analyzes the target repo's code to provide specific, actionable followup tasks with file paths and line numbers +- **Smart Duplicate Detection**: Uses multiple search strategies with synonyms and related terms to find similar issues, scored by relevance +- **Flexible Output**: Create directly via GitHub CLI or save as a file +- **Multi-Repo Aware**: Works across all PatternFly organization repositories + +## Usage + +Invoke the skill with `/create-issue`: + +``` +/create-issue # Interactive mode +/create-issue patternfly-react # Create issue for specific repo +/create-issue followup patternfly-org # Create followup issue +``` + +## Prerequisites + +### Required + +- Git repository with PatternFly remote (or manual repo selection) + +### Optional (but recommended) + +- **GitHub CLI (gh)** - Enables direct issue creation, remote template fetching, and duplicate detection + - Install: `brew install gh` (macOS) or see https://cli.github.com/ + - Authenticate: `gh auth login` + - Without gh CLI: local repo clone must be available locally for template detection, issues are saved to files, and similar issue detection is skipped + +## Workflow Overview + +1. **Detect Context**: Identifies if you're in a PatternFly repo and analyzes context to suggest relevant repos to open your issue in +2. **Choose Type**: New issue or followup issue +3. **Select Template**: Checks for templates locally, then remotely via GitHub CLI, or offers blank option +4. **Pre-populate Fields**: Intelligently fills in issue fields based on your context +5. **Analyze Commits**: For followup issues, optionally analyzes branch commits or lets you provide work yourself +6. **Analyze Target Repo**: For followup issues, searches and analyzes the target repo's code to make specific suggestions with file paths +7. **Auto-detect PR**: Automatically finds associated PR using GitHub CLI +8. **Check Duplicates**: Searches for similar existing issues (if gh CLI available) +9. **Create/Save**: Creates via gh CLI (if available) or saves to file + +## Examples + +### Creating a Bug Report + +``` +/create-issue + +> You're in patternfly/patternfly. Create issue here? (yes) +> Type: New Issue +> Template: bug_report.md +> [Answers template questions] +> Similar issues: None found +> Create with gh CLI or save to file? (gh CLI) +✓ Created issue #1234: Bug - Button - Focus ring not visible +``` + +### Creating a Followup Issue + +``` +/create-issue followup patternfly-react + +> Analyzing 4 commits on feat/card-tokens branch... +> Suggested followup work: +> - Update Card component to use new --pf-t--global--* tokens +> - Update CardHeader CSS variable references +> - Add migration guide to docs +> Correct? (yes) +> Similar issues: None found +✓ Saved to ~/Desktop/patternfly-react-issue-2024-03-16.md +``` + +## Customization + +### Modifying Followup Patterns + +Edit the followup patterns table in SKILL.md to match your team's workflow. + +### Changing Default Save Location + +Modify the default file path in the "Save to file" section of SKILL.md. + +## Troubleshooting + +**"gh: command not found"** + +- Install GitHub CLI or use "save to file" option + +**"gh auth status failed"** + +- Run `gh auth login` to authenticate + +**"No templates found"** + +- Repo may not have templates, use blank issue option + +**"Cannot detect repository"** + +- Manually specify target repo when prompted + +## Tips + +- Use followup issues to track cross-repo dependencies +- Check similar issues to avoid duplicates +- Save to file for batch issue creation or offline work +- Use templates to maintain consistency across issues diff --git a/plugins/pf-workflow/skills/create-issue/SKILL.md b/plugins/pf-workflow/skills/create-issue/SKILL.md new file mode 100644 index 0000000..b9237d4 --- /dev/null +++ b/plugins/pf-workflow/skills/create-issue/SKILL.md @@ -0,0 +1,177 @@ +--- +name: create-issue +description: Create GitHub issues for PatternFly repositories with smart templates, followup tracking, and duplicate detection. +--- + +# PatternFly Issue Creator + +Create well-structured issues for PatternFly repos. Handles templates, cross-repo followups, and duplicate detection. + +## What to Do + +### 1. Determine Target Repo + +**Detect context** from git remote, file paths, or keywords in user's request to suggest relevant repos: + +- React/JSX/component/props → patternfly-react +- Token/design token → design-tokens +- CSS/HTML/core/stylesheet/style → patternfly +- guidelines/documentation/website → patternfly-org +- a11y/accessibility/aria/screen reader/wcag → patternfly or patternfly-react, depending on other context +- Migration/codemod/upgrade → pf-codemods +- Extension → list PatternFly extension repos + +**Ask which repo** if not obvious. Show context-based suggestions first. + +### 2. Choose Issue Type + +**A. New Issue** - Fresh issue for target repo +**B. Followup Issue** - Work needed in target PatternFly repo after changes in source PatternFly repo + +### 3A. New Issue Workflow + +**Find templates:** + +1. Check current directory `.github/ISSUE_TEMPLATE/` +2. If not found, fetch from GitHub using `gh api` (if available) +3. If not found, ask for local clone path or search for local clone +4. If none found, offer blank issue + +**Pre-populate fields** from context: + +- Title: "Bug - [description]" or "[Component] - [description]" (feature) or "[description]" (tech debt/other issue type) +- Component, description, steps, expected/actual behavior from user's request +- Version from package.json if available + +**Ask user to confirm/edit** each pre-filled field. For blank fields, ask user to provide. + +### 3B. Followup Issue Workflow + +**Ask how to determine followup work:** + +1. User describes it themselves +2. Analyze git commits to suggest work + +**If analyzing commits:** + +- Get commits since branch diverged from main +- Identify relevant changes only (new CSS classes, tokens, breaking changes, new features, accessibility updates, updated or new examples/demos) +- Filter out auto-inherited changes (style updates that version bump handles) + +**Analyze target repo** (if found locally or local file path provided by user): + +- Search for component files affected by changes +- Read current implementation (markup, classes, props, interfaces, examples) +- Generate specific tasks with file paths: "Add `variant` prop to CardHeader.tsx:24" +- If not found, provide generic suggestions + +**Search for related/dependent components** when suggesting work: + +- Select → also consider Menu, Popper, MenuToggle, Dropdown +- DatePicker → also consider Calendar, TextInput +- Table → also consider Checkbox, Pagination, Toolbar + (See full list in patterns below) + +**Detect PR** for current branch using `gh pr view` (if available). Ask user if they want to reference it. + +**Structure followup issue:** + +- Title: Type-prefixed like new issues +- Context section: Link to source PR or branch +- Changes section: Only relevant changes (omit auto-inherited) +- Work needed: Specific tasks (with file:line if analyzed) or generic tasks + +### 4. Check for Similar Issues + +**Search with multiple strategies** using `gh issue list` (if available): + +1. Exact: component + feature +2. Broad: component only +3. Related components: dependent/child components (Menu or Popper for Select and Dropdown, AccordionItem for Accordion) +4. Features: keywords like "keyboard", "variant", "loading" +5. Synonyms: "danger"→"error"/"destructive", "loading"→"spinner"/"pending" +6. Closed issues: recent completions + +**Score and deduplicate:** + +- High: Same component + feature +- High-Medium: Related component + feature (note: "Menu (used by Select)") +- Medium: Same component OR feature +- Lower: Synonyms, related concepts + +**Show top 5-10 results** with relevance labels. Ask: create new, comment on existing, or cancel. + +**If no gh CLI**, skip check and inform user where to search manually before continuing to create a new issue. + +### 5. Create or Save + +**With gh CLI** (if authenticated): Offer to create directly or save to file +**Without gh CLI**: Save to file at user defined path or to `~/Desktop/[repo]-issue-[timestamp].md` by default + +Include title, body, and instructions to create manually if saved. + +### 6. Confirm + +Report success (issue URL or file path). For followups, suggest linking to related work. + +## Component Relationships + +When searching for duplicates or analyzing followup work, consider these dependencies: + +**Uses Popper:** + +- Select, Dropdown, DatePicker, TimePicker, Popover, Tooltip + +**Uses Menu:** + +- Select, Dropdown, DatePicker, TimePicker + +**Uses Form components:** + +- Form → FormGroup, TextInput, Checkbox, Radio, Select + +**Card family:** + +- Card → CardHeader, CardBody, CardFooter + +**Table family:** + +- Table → Checkbox, Pagination, Toolbar + +**Modal family:** + +- Modal, Wizard → Backdrop + +**List family:** + +- DataList → Checkbox, Radio + +## Title Formats + +- **Bug**: "Bug - [description]" +- **Feature**: "[Component] - [description]" (no "Feature" prefix) +- **Tech Debt**: "[description]" (no prefix) + +## Followup Patterns + +| Source Repo | Target Repo | Common Followup Work | +| ----- | ----- | ------------------------------------ | +| **patternfly** (HTML/CSS) | **patternfly-react** | Update React component to use new CSS classes, tokens, or structure; make updates to examples/demos for parity | +| **patternfly-react** | **patternfly** | Update HTML/CSS component to use new CSS classes or structure; make updates to examples/demos for parity | +| **design-tokens** | **patternfly** | Apply new token variables | | +| **patternfly** or **patternfly-react** | patternfly-org | Update design guidelines or accessibility documentation for component changes | +| **patternfly-react** | **pf-codemods** | Update or add a codemod, typically for breaking or mass changes | + +## Arguments + +- `/create-issue` - Interactive +- `/create-issue [repo]` - Target specific repo +- `/create-issue followup [repo]` - Create followup + +## Key Behaviors + +- Pre-fill what you can from context +- Filter followup changes to only what needs action in target repo +- Search broadly for duplicates (component relationships, synonyms) +- Fall back gracefully when gh CLI unavailable +- Support both markdown and YAML templates diff --git a/plugins/pf-workflow/skills/dependency-recommender/SKILL.md b/plugins/pf-workflow/skills/dependency-recommender/SKILL.md new file mode 100644 index 0000000..25f181f --- /dev/null +++ b/plugins/pf-workflow/skills/dependency-recommender/SKILL.md @@ -0,0 +1,46 @@ +--- +name: dependency-recommender +description: Analyzes the project's manifests and code patterns, then recommends NPM or other dependencies that would reduce complexity, increase stability, and improve reusability—with a short rationale per recommendation. +disable-model-invocation: true +--- + +# Dependency Recommender + +Recommend dependencies that would help this project reduce complexity, increase stability, and improve reusability. Output a structured list with a clear rationale for each recommendation. + +## When to use + +Invoke this skill when the user asks for dependency recommendations, library suggestions, "what packages could help this project", or tech-stack / dependency review. + +## Instructions + +1. **Gather context** + - Read root and workspace package manifests (`package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `requirements.txt`, `Cargo.toml`, etc.). + - Optionally scan source for patterns: manual date handling, custom validators, repeated HTTP/API logic, ad-hoc state, duplicated utilities. Use this to tailor recommendations. + +2. **Apply dependency knowledge** + - Consider widely adopted, well-maintained packages in the project's ecosystem(s). + - Map common problems (validation, dates, errors, HTTP, state, testing, formatting) to standard solutions. + - Respect existing stack (e.g. don't suggest a different test runner if one is already standard). Note version/compatibility when relevant. + +3. **Produce the output** using the format below. Every recommendation must have a project-specific "Why here" reason—no generic "you could use X" without tying it to this codebase. + +## Output format + +Use this structure. Group by category (e.g. Validation, Date/time, Testing) when it helps. Omit categories that have no recommendations. + +```markdown +## Dependency recommendations for [project or repo name] + +### [Category name] +- **[package name]** ([ecosystem], e.g. NPM) – [One-line: what it does.] + - **Why here:** [Project-specific reason: what in this codebase it would replace, simplify, or improve.] + - **Note:** [Optional: caveats, integration with existing deps, bundle size, compatibility.] +``` + +Keep each recommendation concise. Prefer a short, actionable list over long prose. + +## Scope + +- **In scope:** Recommendations with rationale; grouping by category; multiple ecosystems; project-aware reasons. +- **Out of scope:** Do not modify lockfiles or install packages; do not run security/CVE scans. Focus on analysis and recommendations only. diff --git a/plugins/pf-workflow/skills/pf-org-version-update/SKILL.md b/plugins/pf-workflow/skills/pf-org-version-update/SKILL.md new file mode 100644 index 0000000..7849ef9 --- /dev/null +++ b/plugins/pf-workflow/skills/pf-org-version-update/SKILL.md @@ -0,0 +1,171 @@ +--- +name: pf-org-version-update +description: Updates the patternfly-org repo for a new PatternFly release or release candidate. Fetches or applies specified versions, updates package.json files and versions.json, and then provides the user with steps to run the build and regenerate screenshots locally. Use when preparing a PatternFly release, updating PF versions in this repo, or when the user asks to update patternfly-org for a new release. +--- + +# PatternFly Org Version Update + +Updates patternfly-org for a new PatternFly release or release candidate: resolve versions, update all package.json and versions.json, then provide the user with steps to run install, build, and optionally update documentation screenshots locally. + +## 1. Resolve Versions + +**If the user provided specific versions** (e.g. in the command or message): use those versions. Do **not** run `latest-versions.sh`. + +**If no versions were specified**: run from repo root: + +```bash +./scripts/latest-versions.sh -e +``` + +The `-e` flag includes extension packages. Output is one line per package in the form: + +``` +"@patternfly/package-name": "X.Y.Z", +``` + +Parse this output to build the set of package versions. Use these as the source of truth for the rest of the workflow. + +## 2. Update package.json Files + +Update PatternFly dependencies only in these locations. **Do not** modify `packages/site/package.json` or any other package.json not listed here. + +### Root `package.json` + +In `devDependencies` and `resolutions`, update every `@patternfly/*` entry with the resolved versions. Only change PatternFly packages; leave other dependencies unchanged. + +### `packages/documentation-site/package.json` + +In `dependencies`, update every `@patternfly/*` entry with the resolved versions. Only change PatternFly packages; leave other dependencies unchanged. + +### `packages/documentation-framework/package.json` + +In `peerDependencies`, update every `@patternfly/*` entry with the resolved versions. Only change PatternFly packages; leave other dependencies unchanged. + +## 3. Update versions.json + +File: `packages/documentation-framework/versions.json`. + +### 3.1 New release object + +Insert a **new** object at the **start** of the `"Releases"` array with: + +- **`"name"`**: version from `@patternfly/react-core` (e.g. `"6.3.0"` or `"6.5.0-prerelease.33"`). +- **`"date"`**: current date in `YYYY-MM-DD`. +- **`"latest"`**: `true`. +- **`"versions"`**: object with **all** PatternFly packages and their versions. Use the resolved version set; for any package not in that set, copy the version from the current "latest" release so the list stays complete and consistent. + +### 3.2 Previous latest release + +Find the release that currently has `"latest": true`. Change it to `"hidden": true` (remove `"latest": true`). Do not change anything else in that entry. + +### 3.3 Validation + +- Exactly one release has `"latest": true`. +- All others have `"hidden": true`. +- New release is first in the array. +- Every release’s `versions` object includes the same package keys (alphabetical order); only version values change. + +### 3.4 versions object package list + +Each release’s `versions` must include these packages (alphabetical order): + +- `@patternfly/chatbot` +- `@patternfly/patternfly` +- `@patternfly/quickstarts` +- `@patternfly/react-catalog-view-extension` +- `@patternfly/react-charts` +- `@patternfly/react-code-editor` +- `@patternfly/react-component-groups` +- `@patternfly/react-console` +- `@patternfly/react-core` +- `@patternfly/react-data-view` +- `@patternfly/react-drag-drop` +- `@patternfly/react-icons` +- `@patternfly/react-log-viewer` +- `@patternfly/react-styles` +- `@patternfly/react-table` +- `@patternfly/react-tokens` +- `@patternfly/react-templates` +- `@patternfly/react-topology` +- `@patternfly/react-user-feedback` +- `@patternfly/react-virtualized-extension` + +New release object shape: + +```json +{ + "name": "X.Y.Z", + "date": "YYYY-MM-DD", + "latest": true, + "versions": { + "@patternfly/chatbot": "...", + "@patternfly/patternfly": "...", + "@patternfly/react-*": "...", + "... (all packages above, alphabetically)" + } +} +``` + +### 3.5 Conventions + +- Release name = `@patternfly/react-core` version. +- Use current date for new releases. +- Some packages (e.g. react-charts, chatbot) may use different version numbers; use the resolved or existing latest value for those. + +## 4. Verification Checklist + +Before proceeding: + +- [ ] Root package.json devDependencies (all @patternfly/\* entries) updated +- [ ] documentation-site package.json dependencies (all @patternfly/\* entries) updated +- [ ] documentation-framework package.json peerDependencies (all @patternfly/\* entries) updated +- [ ] packages/site/package.json was **not** modified +- [ ] New release added at top of versions.json Releases array with `"latest": true` +- [ ] Previous latest now has `"hidden": true` +- [ ] Only one object has `"latest": true` +- [ ] Version numbers consistent across root, documentation-site, documentation-framework, and versions.json + +## 5. Build and Screenshots (user-run only) + +The agent **does not** run `yarn install`, `yarn build`, `yarn serve`, or `yarn screenshots` (sandbox limits: cache/lockfile, long build, Puppeteer/Chrome). After completing steps 1–4, give the user the following instructions to run locally from the repo root for the purpose of updating documentation screenshots. + +1. **Install** + + ```bash + yarn install + ``` + +2. **Build** + + ```bash + yarn build + ``` + +3. **Serve** — in a terminal, start the server and leave it running: + + ```bash + yarn serve + ``` + + Wait until the docs are being served (e.g. "Serving build/patternfly-org/site at..." or similar). + +4. **Screenshots** — in a second terminal: + + ```bash + yarn screenshots + ``` + + Run to completion. + +5. When `yarn screenshots` has finished, stop the serve process. + +After providing the user with the steps to update screenshots, the skill is done. + +## Summary + +| Step | Action | +| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Versions | User-provided → use as-is. Otherwise run `./scripts/latest-versions.sh -e` and parse output. | +| package.json | Update root, documentation-site, and documentation-framework: every @patternfly/\* entry with resolved versions; only change PF packages. Never change packages/site. | +| versions.json | Add new release at top with `latest: true`, set previous latest to `hidden: true`, same package list everywhere. | +| Build / Screenshots | Do **not** run install, build, serve, or screenshots. Give user the full list of steps: `yarn install`, `yarn build`, `yarn serve` (one terminal), `yarn screenshots` (second terminal). |