PatternFly Elements v6 Migration Plan

Ordered PR plan for issue #3110. UPDATE PRs first (rename existing v5 elements
to v6 and port APIs), then CREATE PRs (new elements not in v5).

CRITICAL: All PRs MUST target staging/pfv6 branch, NOT main

Phase 0: Infrastructure (do first)

These PRs unblock everything else.

PR 0.1: Remove/replace dev server with cem serve (#3102)

• Issue #3110 calls out hardcoded tag names in dev server
• cem serve handles import maps, CSS transforms, chromeless testing
• Remove tools/pfe-tools/dev-server/ and wire up cem serve
• Update npm run dev / npm start scripts

PR 0.2: Rename tooling and config for v6 prefix (#3130)

• Update eslint.config.js ignore globs (icon demo path) to include pf-v6 as
  well as pf-v5 paths
• Update commitlint.config.js to handle pf- prefix (no v5)
• Audit elements/package.json exports for orphaned entries
• Update tsconfig paths if needed
• Update web-test-runner.config.js and playwright.config.ts globs

Keep v5 prefix until all elements are updated.

PR 0.3: Update docs scaffolding (#3131)

• Update docs/_snippets/ for v6 element names
• Update docs/framework-integration/ examples
• Update docs/components/ templates

Phase 1: UPDATE PRs (rename v5 -> v6, port to v6 API)

Existing v5 elements renamed to pf-v6-{name} and updated to v6 PatternFly
design tokens, CSS, and React API parity. Order by dependency graph:
leaf components first, then composites.

Tier 1: Zero-dependency leaf elements

These elements don't depend on other PF elements. Port first.

Tier 2: Single-dependency elements

Depend on one or more Tier 1 elements.

Tier 3: Composite elements

Depend on multiple Tier 1-2 elements.

Phase 2: CREATE PRs (new elements not in v5)

Components that exist in React v6 but have no v5 web component equivalent.
Order by dependency and complexity.

Tier 4: Simple new elements

Tier 5: Medium complexity new elements

Tier 6: Complex new elements

Tier 7: High-complexity

Layout Components (NOT converted to custom elements)

These use PatternFly CSS layout classes directly. Document usage, don't wrap.

• Bullseye, Flex, Gallery, Grid, Level, Split, Stack, List, Simple List, Divider

Per-PR Checklist

Use /update-element for Phase 1 PRs, /create-element for Phase 2 PRs.

For each PR:

1. API designed per .claude/ADVICE.md rules
2. CSS custom properties match computed CSS and Stylesheets of react demos on patternfly.org via chrome MCP
3. Element source with @summary, JSDoc
4. CSS with tokens, logical properties, nesting
5. Demos matching patternfly.org (name parity)
6. Tests (public API, a11ySnapshot, form submission if FACE)
7. /review-api audit
8. /review-demos audit
9. /review-a11y audit
10. Lint passes (eslint, stylelint)
11. Visual parity verified via Chrome MCP

Checklist for v6 rename (beyond element source files):

Dev Server

• tools/pfe-tools/dev-server/plugins/templates/index.html - element tag names hardcoded in shell UI (nav button, card). Update alongside rename.
• tools/pfe-tools/dev-server/bundle.ts - icon export hardcoded. Update.

Repo

• eslint.config.js ignore glob - icon demo path hardcoded with element name. Update.
• elements/package.json exports - orphaned entries from renamed elements linger silently. no-missing-package-exports catches missing but not extra. Audit manually.

Docs

• docs/_snippets/ - independent of component docs, easy to miss.
• docs/framework-integration/ - inline code examples with element names.