pf-component-structure

name	pf-component-structure
description	Audit PatternFly React component nesting, wrapper hierarchies, and layout structure. Use when scanning for hierarchy violations or debugging spacing caused by missing wrapper components.

Use this skill when you need a structural audit of PatternFly usage, or when fixing layouts caused by skipped wrappers. For day-to-day composition rules while writing UI, use the pf-component-structure-audit agent (react plugin) or your client’s equivalent subagent for PatternFly structure.

PatternFly MCP

If @patternfly/patternfly-mcp is available, use it for current props, examples, and new components. This skill and the reference files define nesting and wrapper rules; the MCP fills in API details.

Why structure matters

Layout CSS targets specific parent-child trees. Skipping wrappers (ToolbarContent, CardBody, PageSection, etc.) breaks spacing and alignment; custom CSS is usually papering over a wrong tree. Use every structural wrapper PatternFly provides for that region.

Where the hierarchies live

Reference files hold trees, props notes, examples, and anti-patterns — not duplicated here:

Area	File
Page, PageSection, PageGroup, PageSidebar, Masthead	references/page-layout.md
Card, Modal, Drawer, EmptyState, Sidebar	references/containers.md
Table, DataList, DescriptionList	references/data-components.md
Nav, Tabs, Toolbar	references/navigation-toolbar.md

Read the relevant file before suggesting structure for that family.

Auditing component structure

How to run

1. Ask the user which directory or files to audit. Default to the current working directory.
2. Search for files importing from @patternfly/react-core or @patternfly/react-table.
3. For each file, check for the violations below.
4. Report findings grouped by file, with line numbers and the specific violation.
5. If the user requests fixes, apply them. Only fix unambiguous structural issues — if a fix would change behavior or needs a design decision, report it and ask.

Violations to detect

Use the same structural rules as the pf-component-structure-audit agent; during a scan, flag the issues below. Anti-pattern examples live in the reference files for each family.

Area	Flag
Page layout	Direct <Page> children that aren’t <PageSection> / <PageGroup>; <PageSidebar> without <PageSidebarBody>; <PageSection hasBodyWrapper={false}> without <PageBody> (info)
Masthead	<MastheadBrand> / <MastheadToggle> not under <MastheadMain>; <MastheadLogo> outside <MastheadBrand>
Toolbar	<Toolbar> children aren’t <ToolbarContent>; controls in <ToolbarContent> / <ToolbarGroup> without <ToolbarItem>
Card	Raw content in <Card> outside <CardBody> / <CardHeader> / <CardFooter>; expandable card missing <CardExpandableContent>
Modal	Missing <ModalHeader> / <ModalBody> / <ModalFooter>; missing aria-labelledby or aria-label
Drawer	<DrawerPanelContent> as child of <DrawerContent> instead of panelContent; <DrawerContent> without <DrawerContentBody>; <DrawerCloseButton> not under <DrawerActions> in <DrawerHead>
Navigation	<NavItem> not under <NavList>; extra <NavList> inside <NavGroup>
Table	<Tr> direct under <Table>; <Th> in body rows or <Td> in header rows; <Td> without dataLabel (WARN)
DataList	Missing aria-label on <DataList>; item without <DataListItemRow>; row without <DataListItemCells>; <DataListContent> inside <DataListItemRow> (should be sibling)
Tabs	Tab label as children instead of title; <Tab> without eventKey
EmptyState	<EmptyStateIcon> directly under <EmptyState>; mixing titleText/icon with explicit <EmptyStateHeader>
DescriptionList	Terms/descriptions directly under <DescriptionList> without <DescriptionListGroup>

Report format

For each violation:

[ERROR|WARN] file/path.tsx:42 - <Toolbar> has direct children that are not <ToolbarContent>
  Found: <Button> as direct child of <Toolbar>
  Fix: Wrap children in <ToolbarContent><ToolbarItem>...</ToolbarItem></ToolbarContent>

Use ERROR for layout-breaking issues; WARN for best-practice gaps. End with a summary:

Scanned: 23 files
Errors: 7 (across 4 files)
Warnings: 3 (across 2 files)

Group by violation type so patterns are visible.

Applying fixes

1. Only fix structure when the correct hierarchy is unambiguous.
2. Preserve props, handlers, and content.
3. Do not reformat unrelated code.
4. Summarize what changed.

Usually safe: Wrapping in missing intermediates (ToolbarContent, ToolbarItem, CardBody, NavList, DescriptionListGroup, …); moving DrawerPanelContent to panelContent; adding <Thead> / <Tbody>.

Needs user input: New aria-label / aria-labelledby text; choosing titleText vs <EmptyStateHeader>; unclear nested intent.

Custom CSS

During an audit: If spacing or padding overrides sit next to a structural issue, add an info line, e.g.:

[INFO] file/path.tsx:42 - Custom CSS spacing override near structural violation
  .my-toolbar-fix { padding: 8px } may compensate for missing <ToolbarContent>

Before suggesting new overrides: Map the symptom to a missing wrapper when possible — page content → PageSection / PageBody; toolbar → ToolbarContent / ToolbarItem; card → CardBody; nav → NavList; description list → DescriptionListGroup; drawer panel → panelContent prop (see reference files for full trees).