PatternFly CSS Distribution Size Audit & Optimization Roadmap

[jcmill]

Phase 1

1. Problem Statement & Goal

• What problem are we solving?

  The current PatternFly CSS distribution is heavy, specifically the patternfly.css file which sits at 1.9MB (38,289 lines). This creates network overhead and slow page initialization for developers and end-users. Which can leads to poor performance scores and difficulty managing CSS across our 6,000+ selectors.

• Main objective?

  To systematically audit and map CSS bloat (duplicates, custom properties, and selector complexity), and provide a data-driven roadmap for a 15%+ reduction in file size.

• How will we measure success?

  • Completion of a Modifier Usage Report and CSS Custom Property Map (mapping all 12,212 properties).
    • Looking for modifier combination mapping, used/unused validation, consolidation opportunities
    • Noting custom property inventory, unused/dead variables, duplication, over-specification
  • Identification of duplicate code across components to reduce by 5-15% in size.
  • Baseline metrics documented for all 80 components to track future reduction.

2. Scope & Completion

• High-Level Acceptance Criteria / Definition of Done:

  • Tooling Readiness: Custom analyzers for CSS property counting (identify unique custom properties and chain depth, unused/dead properties, unused/dead tokens, redundancies ), selector complexity, and duplicate detection (properties and blocks).
  • Audit Completion: Top 10 largest components (led by Table) fully audited.
  • Data Validation: A "Size Attribution" report that breaks down the 1.9MB file size by component.
  • Publish blog post with finds and projected approaches.

• Child Stories/Issues:

  • Build CSS Property Counter Script
  • Audit Table Component (1,828 selectors) for complexity
  • Map 12,212 CSS Custom Properties for redundancy
  • Execute Duplicate Code Detection audit

3. Risks & Testing

• Potential Risks:

  • Complexity Overload: The sheer volume of CSS variables (12,212) may make manual mapping prone to error or take longer than one sprint.
  • Tooling Inaccuracy: Custom scripts may flag "duplicates" that are functionally necessary for specific overrides or :where() specificity.

• Testing Strategy:

  • Baseline Validation: Run the full BackstopJS visual regression test against the current state to ensure the "Analysis" phase doesn't accidentally introduce changes.
  • Script Verification: Peer review of the logic within the "Duplicate Rule Detector" to ensure it identifies 90%+ similar blocks accurately.

4. Supporting Information & Communication

• Key Relevant Links:

  • Size Report Script (needs updating): /scripts/sizeReport/sizeReport.mjs
  • Component Index: src/patternfly/components/_index.scss
  • Build Pipeline: gulpfile.mjs

• Communication Plan:

  • Internal: Quarterly reviews of size metrics and audit findings with the Core Team.
  • External: Final Phase 1 report to be summarized in a "Size Reduction" blog post or community update once the strategy is validated.

5. Effort & Open Questions

• Estimated Level of Effort: 1-2 Sprints.

• Open Questions:

  • Are all 4,450 modifier combinations documented, or are some "ghost" modifiers that can be purged immediately?
  • Can we reduce some of the intermediate token references (token → token → value) without breaking the semantic structure?

---

Jira Issue: PF-4056