PatternFly Compliance Checker for Figma Files (#19)

# PatternFly v6 Compliance Checker - Skill Summary

## Overview

An automated design system compliance validation tool that analyzes
Figma UI prototypes against PatternFly v6 standards. Generates detailed
HTML reports with actionable findings, deep links to violations, and
batch export capabilities.

## Purpose

Enable UX designers to validate their Figma designs against Red Hat's
PatternFly v6 design system before developer handoff, reducing
design-to-dev inconsistencies and ensuring brand compliance.

## Key Features

### 1. Comprehensive Component Validation (17 Types)
- **Buttons**: Height (36px), border-radius (999px pill), states,
padding
- **Form Inputs**: Height (36px), border-radius (6px), focus states,
labels
- **Cards**: Padding (24px), border-radius (16px), spacing
- **Navigation**: Item height (36px), active indicators, spacing
- **Tables**: Row height (48px standard, 36px compact), cell padding
- **Modals**: Width constraints, padding, header sizing
- **Tooltips**: Max width, padding, border-radius, arrow size
- **Pagination**: Button sizing, spacing
- **Breadcrumbs**: Item spacing, font size, separators
- **Badges**: Pill shape (30px radius), padding, font
- **Tabs**: Height (36px), active indicators, spacing
- **Accordions**: Padding, icons, borders
- **Wizards**: Step indicators, footer spacing
- **Drawers**: Width constraints, padding
- **Alerts**: Padding, icons, borders
- **And more**: Comprehensive coverage of PatternFly components

### 2. Advanced Analysis Features
- **Component States**: Validates hover, focus, disabled, error, and
loading states
- **Spacing Relationships**: Analyzes gaps between sibling elements
against 8px base scale
- **Typography Hierarchy**: Detects multiple H1 headings and validates
heading sequence
- **Microcopy Consistency**: Tracks Delete vs Remove, Cancel vs Close vs
Dismiss patterns
- **Component Library Tracking**: Identifies PatternFly library usage vs
custom/detached components
- **Smart Detection**: Filters out icons, containers, and edge cases to
reduce false positives

### 3. Interactive HTML Report
- **Executive Summary**: Overall compliance score, total violations,
breakdown by severity
- **Component Sources**: Percentage of PatternFly library usage
- **Top Priority Fixes**: Pattern-based grouping (fix 100 buttons at
once, not one at a time)
- **Collapsible Sections**: All major sections collapsed by default with
2-sentence summaries
- **Figma Deep Links**: Click any violation to jump directly to the
element in Figma
- **Batch Operations**:
  - Export all violations as JSON for developer handoff
  - Copy all Figma links to clipboard for team checklists

### 4. Accurate PatternFly v6 Token Validation
Updated March 2026 with official PatternFly v6 specifications:
- Button border-radius: 999px (pill-shaped)
- Card border-radius: 16px (medium)
- Form control border-radius: 6px
- Spacing scale: 4px, 8px, 16px, 24px, 32px, 48px, 64px, 80px
- Component heights, padding, and all design tokens verified against
official docs

## Technical Specifications

### Input
- **Format**: Figma file URL
- **URL types**:
  - `https://www.figma.com/design/FILE_ID/FILE_NAME`
  - `https://www.figma.com/file/FILE_ID/FILE_NAME`
- **Authentication**: Requires Figma Personal Access Token

### Output
- **Format**: Interactive HTML report
- **Location**:
`/Users/patrickcox/patternfly-compliance-report-[timestamp].html`
- **Size**: 2-5MB typical (scales with violations)
- **Auto-open**: Opens in default browser automatically

### Performance
- **Small files** (< 10K elements): ~10 seconds
- **Medium files** (10-100K elements): ~30 seconds
- **Large files** (100-300K elements): ~60 seconds
- **Tested on**: Files with 200K+ elements (239,752 elements in latest
test)

### Scoring
- **90%+**: Excellent - Ready for dev handoff
- **80-89%**: Good - Minor cleanup needed
- **70-79%**: Fair - Review critical violations
- **< 70%**: Needs work - Major compliance issues

## Usage

### Command Line
```bash
node /Users/patrickcox/.claude/projects/-Users-patrickcox/memory/patternfly-check.js "https://www.figma.com/design/ABC123/My-Dashboard"
```

### Via Claude Code (Natural Language)
```
Check this Figma design for PatternFly compliance:
https://www.figma.com/design/ABC123/My-Dashboard
```

### Via Alias (Optional)
```bash
# Add to ~/.zshrc or ~/.bashrc
alias pf-check='node /Users/patrickcox/.claude/projects/-Users-patrickcox/memory/patternfly-check.js'

# Then use:
pf-check "https://www.figma.com/design/ABC123/My-Dashboard"
```

## Report Structure

1. **Executive Summary**
   - Compliance score (percentage)
   - Total elements checked
   - Violation breakdown (critical, warning, compliant)

2. **Component Sources**
   - PatternFly library usage percentage
   - Custom component count
   - Detached instance warnings

3. **Top Priority Fixes**
   - Pattern-based grouping
   - Fix recommendations by issue type
   - Example instances

4. **Critical Violations** (Collapsed by default)
   - 2-sentence summary
   - Grouped by category
   - Figma deep links for each violation

5. **Minor Deviations** (Collapsed by default)
   - 2-sentence summary
   - Recommendations for improvement

6. **Typography Hierarchy** (Collapsed by default)
   - H1 count analysis
   - Heading sequence validation

7. **Spacing Consistency** (Collapsed by default)
   - Non-standard spacing usage
   - Recommendations for standard values

8. **Compliant Elements** (Collapsed by default)
   - Good examples to reference
   - What's working well

9. **Batch Operations**
   - Export JSON button
   - Copy Figma links button

## Dependencies

- **Node.js**: Required (tested with v16+)
- **node-fetch**: Auto-installed via npm
- **Figma API**: Requires valid Personal Access Token
- **Browser**: For viewing HTML reports

## Files

- `patternfly-check.js` - Main implementation (2000+ lines)
- `patternfly-check-skill.md` - Skill specification
- `SKILL-USAGE.md` - User guide
- `NEW-FEATURES-SUMMARY.md` - v2 features documentation
- `TOKEN-CORRECTIONS-2026-03.md` - Token accuracy changelog
- `figma-config.env` - Figma API token storage
- `MEMORY.md` - Project memory and preferences

## Version History

### Version 2.0 (March 2026)
- Added component state validation
- Added spacing relationship analysis
- Added typography hierarchy checking
- Added microcopy consistency tracking
- Added component library tracking
- Added collapsible report sections with summaries
- Added batch export operations
- Added Figma deep links
- Updated token values for PatternFly v6 accuracy
- Smart detection to reduce false positives

### Version 1.0 (Initial)
- Basic component validation
- Static HTML reports
- 17 component types

## Use Cases

### Design Review
Run before design reviews to catch violations early:
```bash
pf-check "https://figma.com/design/ABC123/Dashboard-V2"
# Score: 88% - Review critical violations before meeting
```

### Developer Handoff
Export violations as JSON for development tickets:
1. Run checker → 85% score
2. Click "Export JSON"
3. Import violations into Jira/GitHub issues
4. Developers have clear acceptance criteria

### Team Compliance Tracking
Track compliance improvements over time:
```bash
# Week 1
pf-check "https://figma.com/design/ABC123/Dashboard"
# Score: 75%

# Week 2 (after fixes)
pf-check "https://figma.com/design/ABC123/Dashboard"
# Score: 88%
```

### Pattern Library Audit
Check component library usage:
- 70%+ PatternFly library = Good
- < 50% PatternFly library = Too many custom components

## Success Metrics

### Excellent Compliance
- 90%+ overall score
- < 20 critical violations
- 70%+ PatternFly library usage
- No typography hierarchy issues
- Consistent spacing patterns

### Good Compliance
- 80%+ overall score
- < 50 critical violations
- No architectural issues
- Ready for dev handoff with minor notes

## Integration Opportunities

### With Jira
- Export JSON violations
- Create tickets per violation pattern
- Track resolution in sprints

### With CI/CD
- Run on Figma file updates (via webhooks)
- Block PRs if compliance < 80%
- Automated compliance tracking

### With Design System Updates
- Re-run on all files when PatternFly updates
- Identify breaking changes
- Bulk update recommendations

## Limitations

### Not Validated
- Interactive prototypes (clicks, flows)
- Animations and transitions
- Responsive breakpoints (design-time only)
- Dark mode (if not in separate artboard)

### Manual Review Needed
- Context-specific design decisions
- Brand-specific overrides
- Accessibility beyond component structure
- Content quality and microcopy tone

## Support

- **Documentation**: See SKILL-USAGE.md for detailed guide
- **PatternFly Docs**: https://www.patternfly.org/
- **Token Reference**:
https://www.patternfly.org/tokens/all-patternfly-tokens/
- **Figma API**: https://www.figma.com/developers/api

## License & Attribution

Built for Red Hat PatternFly Design Team
Uses official PatternFly v6 design tokens
Figma API integration via node-fetch


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added PatternFly Compliance Checker tool to analyze Figma designs and
generate detailed HTML compliance reports with scores, violation
categories, severity breakdowns, and suggested fixes.

* **Documentation**
* Added comprehensive usage guide covering workflows, report
interpretation, batch checking, filtering, version comparisons,
troubleshooting, and best practices.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Jeff Puzzo <jpuzzo@redhat.com>

Author: phcox

plugins/figma/skills/pf-compliance-checker/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: pf-compliance-checker
+description: Check Figma designs against PatternFly v6 design system standards. Use when a user provides a Figma URL and wants to validate compliance with PatternFly colors, typography, spacing, components, and UX patterns.
+---
+
+# PatternFly Compliance Checker
+
+Analyze Figma prototypes against PatternFly v6 design system standards — components, spacing, typography, colors, and UX patterns.
+
+## Requirements
+
+- Node.js 18+
+- `node-fetch` package (`npm install node-fetch`)
+- `FIGMA_TOKEN` environment variable (or a `figma-config.env` file in the scripts directory)
+- View access to the Figma file
+
+## Workflow
+
+### Step 1: Validate input
+
+Accept a Figma file URL from the user. Valid formats:
+- `https://www.figma.com/design/FILE_ID/FILE_NAME`
+- `https://www.figma.com/file/FILE_ID/FILE_NAME`
+
+### Step 2: Run the checker
+
+```bash
+node "$CLAUDE_SKILL_DIR/scripts/patternfly-check.js" "<figma-url>"
+```
+
+The script fetches the Figma file via API and analyzes all elements for PatternFly v6 compliance. An HTML report opens automatically in the browser.
+
+### Step 3: Present the summary
+
+After the script completes, summarize the results for the user:
+
+- Overall compliance score (percentage)
+- Critical violations count and top categories
+- Minor deviations count
+- Recommendations for priority fixes
+
+### Step 4: Suggest next steps
+
+- Focus on critical violations first — use pattern-based grouping to fix multiple issues at once
+- Use the "Export JSON" button in the report for developer handoff
+- Re-run after fixes to track improvement
+
+## What gets checked
+
+**Components** (17 types): buttons, form inputs, cards, alerts, navigation, tables, modals, tooltips, pagination, breadcrumbs, badges, tabs, accordions, wizards, drawers
+
+**Design tokens**: colors (PatternFly palette), typography (Red Hat fonts, sizes, weights), spacing (4px grid scale), border radius
+
+**Advanced checks**: component states (hover, focus, disabled), spacing relationships, typography hierarchy (H1 count), microcopy consistency (Delete vs Remove), component library usage (detached instances)