patternfly/patternfly-react

1. What this repo is

- This is a Lerna-managed monorepo for the PatternFly React design system.

- The main output is a set of published React packages plus supporting packages for docs, tests, styling, icons, tokens, and developer tooling.

2. Top-level package boundaries

- The repo is split into independently versioned packages such as react-core, react-table, react-charts, react-icons, react-styles, react-tokens, react-code-editor, react-templates, react-drag-drop, and react-docs.

- react-integration is a separate validation surface for browser-level testing, not a library package.

3. Core UI library (react-core)

- packages/react-core is the largest subsystem and contains the bulk of PatternFly components.

- Its internal structure is organized by components, layouts, helpers, styles, demos, and deprecated APIs.

- Most components are small compositional React primitives with dedicated tests, snapshots, and example files.

4. Component composition model

- Many core components are split into a primary container plus subcomponents, contexts, and utility modules.

- Examples include Modal, Wizard, Tabs, Menu, Page, Toolbar, Popover, Dropdown, DataList, Drawer, and Alert, each with supporting parts under the same folder.

- This makes the architecture mostly component-local, with shared helpers used only where cross-cutting behavior is needed.

5. Shared helpers and behavior

- react-core/src/helpers contains reusable infrastructure for cross-component concerns: focus trapping, resize observation, SSR-safe IDs, Popper positioning, keyboard handling, animation support, and OUIA metadata.

- These helpers are the main “behavior layer” beneath UI components and are the bridge to browser APIs like layout measurement, focus management, and positioning.

6. Layout primitives

- react-core/src/layouts contains low-level layout building blocks such as Flex, Grid, Stack, Split, Bullseye, Gallery, and Level.

- These are meant to be composed by higher-level components and demos, so they act as the spacing/alignment foundation for the UI system.

7. Styling and design tokens

- react-styles owns the CSS output and class map generation, while react-tokens owns the design token generation.

- react-core and other packages consume these layers through generated class maps, CSS imports, and token-driven styling utilities.

- The styling boundary is important: visual consistency comes from shared style artifacts rather than per-component ad hoc CSS.

8. Icon system

- react-icons is a generated icon package with scripts that pull from multiple icon sources and write React icon components.

- This package is a distinct asset pipeline: source icon definitions are transformed into reusable React components, then consumed by the UI packages.

9. Table and charts are separate specialized engines

- react-table is a dedicated table subsystem with its own base layer, decorators, formatters, transformers, and a deprecated table implementation alongside the current one.

- react-charts contains chart wrappers for both Victory-based and ECharts-based implementations, with shared chart theme utilities and component-specific examples/tests.

- These are not just “components”; they have internal rendering and data-shaping pipelines that are more specialized than the rest of react-core.

10. Template and extension packages

- react-templates provides precomposed dropdown/select patterns built on top of the core primitives.

- react-drag-drop provides drag-and-drop helpers and wrappers used by higher-level components like tables and dual list selectors.

- react-code-editor is a focused package for embedding and configuring code editor experiences.

11. Docs and example generation

- react-docs is a Gatsby-based documentation site with generated content under patternfly-docs/generated.

- The repo also keeps component examples and demos inside the packages, which serve as both documentation artifacts and integration examples.

- The docs pipeline consumes these generated examples to present live component usage rather than handwritten prose alone.

12. Testing strategy

- Most component packages use unit tests plus snapshot tests with Jest.

- react-integration adds Cypress coverage for end-to-end browser behavior across real demo scenarios.

- This creates a two-layer validation model: fast structural/component testing and slower runtime integration testing.

13. Generated and deprecated surfaces

- Several directories are explicitly generated or machine-maintained, such as icon sources, token outputs, class maps, subpath exports, and docs artifacts.

- Deprecated APIs are preserved under deprecated/ in packages like react-core and react-table, which helps maintain backward compatibility while separating them from current APIs.

14. Build, packaging, and release tooling

- The repo uses Yarn, Lerna, Rollup configs in individual packages, Babel/Jest/ESLint/Prettier, and multiple custom scripts under scripts/ and .github/.

- Important repo-wide scripts handle subpath export generation, single-package builds, changelog/release steps, and source transformation for CommonJS/ESM interop.

- Architecture-wise, this means the repo is optimized for multi-package publishing, not a single app deploy.

15. Overall flow

- Design tokens and styles are generated first, then consumed by component packages.

- Components and layout primitives are composed into demos/examples.

- Tests and Cypress specs validate the components against those demos.

- Docs generation turns the same examples into published documentation content.