-
+
+
+
We use cookies on our websites to deliver our online services.
Details about how we use cookies and how you may disable them are set out in our Privacy Statement .
By using this website you agree to our use of cookies.
diff --git a/packages/documentation-framework/components/inlineAlert/inlineAlert.js b/packages/documentation-framework/components/inlineAlert/inlineAlert.js
index b91939dcfb..0b8c8aa041 100644
--- a/packages/documentation-framework/components/inlineAlert/inlineAlert.js
+++ b/packages/documentation-framework/components/inlineAlert/inlineAlert.js
@@ -9,7 +9,7 @@ export const InlineAlert = ({
(
{title}
-
+
- {description && {description}
}
+ {description && {description}
}
* required
@@ -64,7 +64,7 @@ export const PropsTable = ({ title, description, rows, allPropComponents }) => (
{row.beta && (
Beta
diff --git a/packages/documentation-framework/components/sectionGallery/sectionDataListLayout.js b/packages/documentation-framework/components/sectionGallery/sectionDataListLayout.js
index a82d2c70fc..92446bf0d7 100644
--- a/packages/documentation-framework/components/sectionGallery/sectionDataListLayout.js
+++ b/packages/documentation-framework/components/sectionGallery/sectionDataListLayout.js
@@ -7,7 +7,7 @@ export const SectionDataListLayout = ({ galleryItems, layoutView, hasListText, h
if (layoutView !== 'list') {
return null;
}
-
+
return (
{}}>
{galleryItems.map(({ idx, slug, illustration, itemName, title, isBeta, isDeprecated, isDemo, id, galleryItemsData }) => (
@@ -23,7 +23,7 @@ export const SectionDataListLayout = ({ galleryItems, layoutView, hasListText, h
),
-
+
@@ -32,7 +32,7 @@ export const SectionDataListLayout = ({ galleryItems, layoutView, hasListText, h
-
+
{isBeta && (Beta )}
{!isBeta && isDeprecated && (Deprecated )}
diff --git a/packages/documentation-framework/components/sideNav/sideNav.js b/packages/documentation-framework/components/sideNav/sideNav.js
index 0c6d56d576..e55828159e 100644
--- a/packages/documentation-framework/components/sideNav/sideNav.js
+++ b/packages/documentation-framework/components/sideNav/sideNav.js
@@ -96,7 +96,7 @@ const ExpandableNav = ({groupedRoutes, location, section, subsection = null}) =>
source.source === "react-deprecated" || source.source === "html-deprecated")
&& !navObj.sources.some(source => source.source === "react" || source.source === "html")
),
- isBeta: navObj.sources.some(source => source.beta),
+ isBeta: navObj.sources.some(source => source.beta && source.source !== 'react-next'),
isDemo: navObj.sources.some(source => (
source.source === "react-demos" || source.source === "html-demos")
&& !navObj.sources.some(source => source.source === "react" || source.source === "html")
diff --git a/packages/documentation-framework/layouts/sideNavLayout/sideNavLayout.js b/packages/documentation-framework/layouts/sideNavLayout/sideNavLayout.js
index aeff8ae279..3179504ae1 100644
--- a/packages/documentation-framework/layouts/sideNavLayout/sideNavLayout.js
+++ b/packages/documentation-framework/layouts/sideNavLayout/sideNavLayout.js
@@ -59,7 +59,7 @@ const HeaderTools = ({
const getDropdownItem = (version, isLatest = false) => (
- {`Release ${version.name}`}
+ {`Current ${version.name}`}
);
@@ -93,7 +93,7 @@ const HeaderTools = ({
)}
{hasDarkThemeSwitcher && (
@@ -163,12 +163,21 @@ const HeaderTools = ({
)}
-
+
+
+ PatternFly 5
+
-The [full list of global CSS variables](#global-css-variables) can be found below.
-
-### Component variables
-
-Component variables are used to define custom properties at the component-level. Component variables are always defined by global variables.
-
-Component variables follow this formula:
-
-`--pf-v6-c-block__element--modifier--state--breakpoint--['child'|tag|c-component]pseudo-element--PropertyCamelCase`
-
-Where...
-
-- `pf-v6-c-block` refers to the block, usually the component or layout name, like `pf-v6-c-alert`.
-- `__element` refers to the element inside of the block, like `__title`.
-- `modifier` is prefixed with`-m` and refers to a modifier class such as `.pf-m-danger`.
-- `state` is something like `hover` or `active`.
-- `breakpoint` is a media query breakpoint such as `sm` for `$pf-v6-global--breakpoint--xs`.
-- `pseudo-element` is either `before` or `after`.
-- `child`, `tag`, or `c-component` refers to a child element. It could be a tag or component name, like `svg` or `c-menu`, or it could use `child` to refer to any child element. If any modifiers, states, breakpoints, or pseudo-elements are on the child, include those after this portion of the name.
-
-Example:
-- Note: component variables are scoped to the top-level component selector
- ```css
- .pf-v6-c-button {
- /* Default, primary, and primary hovered button background colors */
- --pf-v6-c-button--BackgroundColor: transparent;
- --pf-v6-c-button--m-primary--BackgroundColor: var(--pf-v6-global--primary-color--100);
- --pf-v6-c-button--m-primary--hover--BackgroundColor: var(--pf-v6-global--primary-color--200);
- }
- ```
-
-
-Component variables are listed at the bottom of each component page (for example, [button css variables](/components/button#css-variables)).
-
-Note that all component variables are declared at the top component level (for example, `.pf-v6-c-button`). The component variable table linked above also shows all usages of each variable and the values they evaluate to in each case - expand any component variable row to view the global variable it is mapped to.
-
-![Component variable mapping](./img/component-variable-mapping.png)
-
-### Breakpoint variables and class suffixes
-
-PatternFly defines a number of standard breakpoints. These are always used as a `min-width` breakpoint; i.e. using the `-md` breakpoint would apply to everything at the `-md` width and wider. (There is one exception to this, which is in the responsive behavior of the [table component](/components/table).)
-
-Breakpoint suffixes are used in utility classes and layouts as well as in many components as a way to apply class styles at a specified breakpoint. When available, `{-on-[breakpoint]}` will be shown as an available suffix for the class in the usage section of the documentation. The breakpoint suffix is optional and if not specified, the base class will be used. There are breakpoints for `sm`, `md`, `lg`, `xl`, and `2xl`, and the values for the corresponding breakpoints are defined below in the global variables `—pf-v6-global—breakpoint—[breakpoint]`.
-
-### Using the variable system
-
-PatternFly 4 styles provide a default starting point. You can use the variable system to make adjustments to that default styling. When you change one or more elements, you should package those values into a new SCSS stylesheet to replace the default styling.
-
-Overrides to PatternFly variables should be made at the `:root` level for global variables or at the top-level component selector for component variables (for example, `.pf-v6-c-button`), as these overrides will cascade down to children elements accordingly.
-
-Example:
-- Change the global primary color to red, but keep the original primary blue color as the background for primary buttons.
- ```css
- /* Override global primary color 100 to red */
- :root {
- --pf-v6-global--primary-color--100: var(--pf-v6-global--palette--red-400);
- }
-
- /* Override the above override for only the primary button background color */
- .pf-v6-c-button {
- --pf-v6-c-button--m-primary--BackgroundColor: var(--pf-v6-global--palette--blue-400);
- }
- ```
-
-## Global CSS variables
-
-
-
-## Chart CSS variables
-
-
diff --git a/packages/documentation-framework/pages/img/component-variable-mapping.png b/packages/documentation-framework/pages/img/component-variable-mapping.png
deleted file mode 100644
index 476c9ab822..0000000000
Binary files a/packages/documentation-framework/pages/img/component-variable-mapping.png and /dev/null differ
diff --git a/packages/documentation-framework/scripts/md/parseMD.js b/packages/documentation-framework/scripts/md/parseMD.js
index 1e02e8653f..78fbf50747 100644
--- a/packages/documentation-framework/scripts/md/parseMD.js
+++ b/packages/documentation-framework/scripts/md/parseMD.js
@@ -105,6 +105,7 @@ function toReactComponent(mdFilePath, source, buildMode) {
section: frontmatter.section || '',
subsection: frontmatter.subsection || '',
deprecated: frontmatter.deprecated || false,
+ template: frontmatter.template || false,
beta: frontmatter.beta || false,
demo: frontmatter.demo || false,
newImplementationLink: frontmatter.newImplementationLink || false,
@@ -295,6 +296,7 @@ function sourceMDFile(file, source, buildMode) {
...(pageData.hideNavItem && { hideNavItem: pageData.hideNavItem }),
...(pageData.beta && { beta: pageData.beta }),
...(pageData.deprecated && { deprecated: pageData.deprecated }),
+ ...(pageData.template && { template: pageData.template }),
...(pageData.demo && { demo: pageData.demo }),
...(pageData.sortValue && { sortValue: pageData.sortValue }),
...(pageData.subsectionSortValue && { subsectionSortValue: pageData.subsectionSortValue })
diff --git a/packages/documentation-framework/scripts/webpack/webpack.base.config.js b/packages/documentation-framework/scripts/webpack/webpack.base.config.js
index 668c520a84..2b076d12c2 100644
--- a/packages/documentation-framework/scripts/webpack/webpack.base.config.js
+++ b/packages/documentation-framework/scripts/webpack/webpack.base.config.js
@@ -2,7 +2,6 @@ const path = require('path');
const webpack = require('webpack');
const { CleanWebpackPlugin } = require('clean-webpack-plugin');
const CopyWebpackPlugin = require('copy-webpack-plugin');
-const MonacoWebpackPlugin = require('monaco-editor-webpack-plugin');
module.exports = (_env, argv) => {
const {
@@ -156,9 +155,6 @@ module.exports = (_env, argv) => {
patterns: [
{ from: path.join(__dirname, '../../assets'), to: 'assets' }
]
- }),
- new MonacoWebpackPlugin({
- globalAPI: true,
})
],
stats: 'minimal'
diff --git a/packages/documentation-framework/scripts/writeScreenshots.js b/packages/documentation-framework/scripts/writeScreenshots.js
index dda8e66b78..a7ce317b97 100644
--- a/packages/documentation-framework/scripts/writeScreenshots.js
+++ b/packages/documentation-framework/scripts/writeScreenshots.js
@@ -32,7 +32,7 @@ async function writeScreenshots({ urlPrefix, allRoutes, filterTerm }) {
concurrency: Cluster.CONCURRENCY_CONTEXT,
maxConcurrency: os.cpus().length,
puppeteerOptions: {
- headless: true, // set to false for testing...
+ headless: 'new', // set to false for testing...
args: ["--no-sandbox", "--disable-setuid-sandbox"],
defaultViewport: {width: 1920, height: 1080}
}
diff --git a/packages/documentation-framework/templates/mdx.css b/packages/documentation-framework/templates/mdx.css
index d87ddaae06..c861b57cb8 100644
--- a/packages/documentation-framework/templates/mdx.css
+++ b/packages/documentation-framework/templates/mdx.css
@@ -1,7 +1,7 @@
#ws-page-content-router {
display: flex;
flex-direction: column;
- height: 100%;
+ flex-shrink: 0;
}
.ws-release-notes-toc {
@@ -74,6 +74,11 @@
width: 100%;
}
+.ws-image {
+ text-align: center;
+ width: "600px";
+}
+
.ws-table td > code,
.ws-table th > code,
.ws-table tr > code {
diff --git a/packages/documentation-framework/templates/mdx.js b/packages/documentation-framework/templates/mdx.js
index 19e1815958..ff2f7916f0 100644
--- a/packages/documentation-framework/templates/mdx.js
+++ b/packages/documentation-framework/templates/mdx.js
@@ -23,6 +23,7 @@ const MDXChildTemplate = ({
optIn,
beta,
deprecated,
+ template,
newImplementationLink,
functionDocumentation = []
} = Component.getPageData();
@@ -84,6 +85,11 @@ const MDXChildTemplate = ({
{' '}To learn more about the process, visit our about page.
)}
+ {(template || source === 'react-template') && (
+
+ {`This page showcases templates for the ${id.toLowerCase()} component. A template combines a component with logic that supports a specific use case, with a streamlined API that offers additional, limited customization.`}
+
+ )}
);
// Create dynamic component for @reach/router
@@ -152,7 +158,7 @@ export const MDXTemplate = ({
componentsData
}) => {
const isDeprecated = sources.some(source => source.source === "react-deprecated" || source.source === "html-deprecated") && !sources.some(source => source.source === "react" || source.source === "html");
- const isBeta = sources.some(source => source.beta)
+ const isBeta = sources.some(source => source.beta && source.source !== 'react-next')
const isDemo = sources.some(source => source.source === "react-demos" || source.source === "html-demos") && !sources.some(source => source.source === "react" || source.source === "html");
// Build obj mapping source names to text displayed on tabs
const tabNames = sources.reduce((acc, curSrc) => {
diff --git a/packages/documentation-framework/versions.json b/packages/documentation-framework/versions.json
index 52339601fd..99d2511d8b 100644
--- a/packages/documentation-framework/versions.json
+++ b/packages/documentation-framework/versions.json
@@ -18,10 +18,84 @@
"@patternfly/react-tokens": "5.1.0",
"@patternfly/react-topology": "5.1.0",
"@patternfly/quickstarts": "5.1.0",
- "@patternfly/react-virtualized-extension": "5.1.0"
+ "@patternfly/react-virtualized-extension": "5.1.0",
+ "@patternfly/react-templates": "^1.0.0-alpha.0"
+ }
+ },{
+ "name": "5.2.2",
+ "date": "2024-03-12",
+ "hidden": true,
+ "versions": {
+ "@patternfly/patternfly": "5.2.1",
+ "@patternfly/react-charts": "7.2.2",
+ "@patternfly/react-code-editor": "5.2.2",
+ "@patternfly/react-core": "5.2.2",
+ "@patternfly/react-icons": "5.2.1",
+ "@patternfly/react-styles": "5.2.1",
+ "@patternfly/react-table": "5.2.2",
+ "@patternfly/react-drag-drop": "5.2.2",
+ "@patternfly/react-tokens": "5.2.1",
+ "@patternfly/react-catalog-view-extension": "5.0.0",
+ "@patternfly/react-component-groups": "5.1.0",
+ "@patternfly/react-console": "5.0.0",
+ "@patternfly/react-log-viewer": "5.2.0",
+ "@patternfly/react-topology": "5.2.1",
+ "@patternfly/react-user-feedback": "5.0.0",
+ "@patternfly/react-virtualized-extension": "5.0.0",
+ "@patternfly/quickstarts": "5.0.0",
+ "@patternfly/react-templates": "^1.0.0-alpha.0"
}
},
{
+ "name": "5.2.1",
+ "date": "2024-03-01",
+ "hidden": true,
+ "versions": {
+ "@patternfly/patternfly": "5.2.1",
+ "@patternfly/react-charts": "7.2.2",
+ "@patternfly/react-code-editor": "5.2.1",
+ "@patternfly/react-core": "5.2.1",
+ "@patternfly/react-icons": "5.2.1",
+ "@patternfly/react-styles": "5.2.1",
+ "@patternfly/react-table": "5.2.1",
+ "@patternfly/react-drag-drop": "5.2.1",
+ "@patternfly/react-tokens": "5.2.1",
+ "@patternfly/react-catalog-view-extension": "5.0.0",
+ "@patternfly/react-component-groups": "5.1.0",
+ "@patternfly/react-console": "5.0.0",
+ "@patternfly/react-log-viewer": "5.2.0",
+ "@patternfly/react-topology": "5.2.1",
+ "@patternfly/react-user-feedback": "5.0.0",
+ "@patternfly/react-virtualized-extension": "5.0.0",
+ "@patternfly/quickstarts": "5.0.0",
+ "@patternfly/react-templates": "^1.0.0-alpha.0"
+ }
+ },
+ {
+ "name": "5.2.0",
+ "date": "2024-01-17",
+ "hidden": true,
+ "versions": {
+ "@patternfly/patternfly": "5.2.0",
+ "@patternfly/react-charts": "7.2.0",
+ "@patternfly/react-code-editor": "5.2.0",
+ "@patternfly/react-core": "5.2.0",
+ "@patternfly/react-icons": "5.2.0",
+ "@patternfly/react-styles": "5.2.0",
+ "@patternfly/react-table": "5.2.0",
+ "@patternfly/react-drag-drop": "5.2.0",
+ "@patternfly/react-tokens": "5.2.0",
+ "@patternfly/react-catalog-view-extension": "5.0.0",
+ "@patternfly/react-component-groups": "5.1.0",
+ "@patternfly/react-console": "5.0.0",
+ "@patternfly/react-log-viewer": "5.2.0",
+ "@patternfly/react-topology": "5.2.1",
+ "@patternfly/react-user-feedback": "5.0.0",
+ "@patternfly/react-virtualized-extension": "5.0.0",
+ "@patternfly/quickstarts": "5.0.0",
+ "@patternfly/react-templates": "^1.0.0-alpha.0"
+ }
+ },{
"name": "5.1.0",
"date": "2023-10-06",
"hidden": true,
diff --git a/packages/documentation-site/package.json b/packages/documentation-site/package.json
index d482a9b3c4..9447b24924 100644
--- a/packages/documentation-site/package.json
+++ b/packages/documentation-site/package.json
@@ -17,17 +17,17 @@
"screenshots": "pf-docs-framework screenshots"
},
"dependencies": {
- "@patternfly/documentation-framework": "6.0.0-alpha.12",
- "@patternfly/quickstarts": "5.1.0",
+ "@patternfly/documentation-framework": "6.0.0-alpha.17",
+ "@patternfly/quickstarts": "^5.1.0",
"@patternfly/react-catalog-view-extension": "5.0.0",
"@patternfly/react-console": "5.0.0",
- "@patternfly/react-docs": "7.0.0-alpha.37",
- "@patternfly/react-log-viewer": "5.1.0-prerelease.1",
- "@patternfly/react-topology": "5.2.0-prerelease.3",
+ "@patternfly/react-docs": "7.0.0-alpha.45",
+ "@patternfly/react-log-viewer": "5.1.0",
+ "@patternfly/react-topology": "5.2.1",
"@patternfly/react-user-feedback": "5.0.0",
- "@patternfly/react-component-groups": "5.0.0-prerelease.10",
+ "@patternfly/react-component-groups": "5.1.0",
"@patternfly/react-virtualized-extension": "5.0.0",
- "@patternfly/design-tokens": "1.0.2",
+ "@patternfly/design-tokens": "1.0.3",
"react": "^17.0.0 || ^18.0.0",
"react-dom": "^17.0.0 || ^18.0.0",
"showdown": "^2.1.0"
@@ -40,24 +40,5 @@
"react-router": "^6.3.0",
"react-router-dom": "^6.3.0",
"classnames": "^2.2.5"
- },
- "resolutions": {
- "victory-area": "36.6.11",
- "victory-axis": "36.6.11",
- "victory-bar": "36.6.11",
- "victory-box-plot": "36.6.11",
- "victory-chart": "36.6.11",
- "victory-core": "36.6.11",
- "victory-create-container": "36.6.11",
- "victory-cursor-container": "36.6.11",
- "victory-group": "36.6.11",
- "victory-legend": "36.6.11",
- "victory-line": "36.6.11",
- "victory-pie": "36.6.11",
- "victory-scatter": "36.6.11",
- "victory-stack": "36.6.11",
- "victory-tooltip": "36.6.11",
- "victory-voronoi-container": "36.6.11",
- "victory-zoom-container": "36.6.11"
}
}
diff --git a/packages/documentation-site/patternfly-docs/content/accessibility/skip-to-content/skip-to-content.md b/packages/documentation-site/patternfly-docs/content/accessibility/skip-to-content/skip-to-content.md
index 7423f0396b..a3a55a1775 100644
--- a/packages/documentation-site/patternfly-docs/content/accessibility/skip-to-content/skip-to-content.md
+++ b/packages/documentation-site/patternfly-docs/content/accessibility/skip-to-content/skip-to-content.md
@@ -3,12 +3,46 @@ id: Skip to content
section: components
---
-A **skip to content** is a component that allows screen reader and keyboard users to bypass navigation rather than tabbing through it.
+import { Checkbox, List, ListItem } from '@patternfly/react-core';
-**Keyboard users** should be able to find the skip to content using **Tab** at the start of a page with navigation. They should be able to select the skip to content using **Enter**. A skip to content does not trap tab focus. It is the first tabbable element on a page, but can be tabbed past and into the navigation of a page if the user prefers.
+## Accessibility
-**Screen reader users** should also be able to navigate to skip to content using **Tab** and select it to skip past the navigation of a page.
+To implement an accessible PatternFly **skip to content**:
-## To make skip to content accessible:
+- Render the skip to content as the first focusable element on the page.
- Ensure that the skip to content href is properly linked to the main content of the page. You may have to add context to the href if there are any query parameters in the URL.
-- If you're using the page component with the skip to content, we add a tabindex="-1" for you. If you are using the skip to content on its own, give the target of the skip to content link a tabindex of -1. Some browsers require this attribute to make this component work consistently.
+
+## Testing
+
+At a minimum, a skip to content should meet the following criteria:
+
+
+
+
+
+
+ The skip to content's href
is linked to the main content of the page.} />
+
+
+ Depending on where focus is on the page, Tab navigates to the skip to content or the next focusable element, and Shift + Tab navigates to the previous focusable element or the skip to content. Since the skip to content should be the first focusable element on a page, the previous focusable element may typically be an item in the browser toolbar.} />
+
+
+ Enter is typically the only key that activates links.} />
+
+
+
+## React customization
+
+The following React props have been provided for more fine-tuned control over accessibility.
+
+| Prop | Applied to | Reason |
+|---|---|---|
+| `href="[id of the main content container]"` | `SkipToContent` | Links the skip to content to the main content. Typically this will be a jump link, e.g. `href="#main"`. |
+
+## HTML/CSS customization
+
+The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.
+
+| Attribute or class | Applied to | Reason |
+|---|---|---|
+| `href="[id of the main content container]"` | `.pf-v5-c-skip-to-content > a.pf-v5-c-button` | Links the skip to content to the main content. Typically this will be a jump link, e.g. `href="#main"`. |
diff --git a/packages/documentation-site/patternfly-docs/content/accessibility/title/title.md b/packages/documentation-site/patternfly-docs/content/accessibility/title/title.md
index 577a6392e1..3b9573b2c0 100644
--- a/packages/documentation-site/patternfly-docs/content/accessibility/title/title.md
+++ b/packages/documentation-site/patternfly-docs/content/accessibility/title/title.md
@@ -3,11 +3,46 @@ id: Title
section: components
---
-A **title** component applies top and bottom margins, font-weight, font-size, and line-height to titles.
+import { Checkbox, List, ListItem } from '@patternfly/react-core';
-**Keyboard users** should not be able to reach a title using **Tab**, as titles are not interactive.
+## Accessibility
-**Screen reader users** should be able to navigate to the title and read its text. Titles should be clear, descriptive, and make sense out of context (such as when a screen reader navigates by headings).
+To implement an accessible PatternFly **title**:
-## To make title accessible:
-- Choose appropriate headings to indicate sections and subsections of content rather than choosing heading levels for their formatting. A common practice is to use a single **h1** for the primary headline or logo on a page, **h2**s to designate major sections, and **h3**s for supporting subsections.
\ No newline at end of file
+- Ensure no heading levels are skipped. For example, a title as a level 4 heading should not come immediately after a level 2 heading.
+- Do not choose a heading level size solely for its font styling.
+- Ensure the font size of any titles are consistent, and that a title with a lower heading level does not have a larger font size than one with a higher heading level.
+- Provide descriptive text content to the title that will make sense when taken out of context.
+
+## Testing
+
+At a minimum, a title should meet the following criteria:
+
+
+
+
+
+
+ For example, a title with a level 2 heading should not have a larger font size than a title with a level 1 heading or an h1
element. Visually this would make the level 1 heading look like a sub-heading.} />
+
+
+ Users that navigate via screen reader may use a rotor menu to view all of the headings on a page, without any other surrounding text. The title's text content must still make sense in this context.} />
+
+
+
+## React customization
+
+The following React props have been provided for more fine-tuned control over accessibility.
+
+| Prop | Applied to | Reason |
+|---|---|---|
+| `headingLevel="[h1, h2, h3, h4, h5, or h6]"` | `Title` | Sets the internal heading element level. |
+| `size="[md, lg, xl, 2xl, 3xl, or 4xl]"` | `Title` | Sets the font size of the component. |
+
+## HTML/CSS customization
+
+The following HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.
+
+| Attribute or class | Applied to | Reason |
+|---|---|---|
+| `.pf-m-4xl`, `.pf-m-3xl`, `.pf-m-2xl`, `.pf-m-xl`, `.pf-m-lg`, and `.pf-m-md` | `.pf-v5-c-title` | Sets the font size of the component. |
diff --git a/packages/documentation-site/patternfly-docs/content/contribute/design/design.md b/packages/documentation-site/patternfly-docs/content/contribute/design/design.md
index 665812afc1..6db887b312 100644
--- a/packages/documentation-site/patternfly-docs/content/contribute/design/design.md
+++ b/packages/documentation-site/patternfly-docs/content/contribute/design/design.md
@@ -24,8 +24,11 @@ __Example__
You may open an issue in our [patternfly-org repo](https://github.com/patternfly/patternfly-org) to propose a new design guideline page or update an existing guideline, and work with the PatternFly team and stakeholders to author and publish your new content. Visit [Contributing to patternfly org for designers](https://github.com/patternfly/patternfly-org/wiki/Contributing-to-patternfly-org-for-designers) for detailed instructions about how to author and contribute design guideline content.
-### PatternFly design kit
-The [PatternFly design kit](https://www.patternfly.org/v4/get-started/design) is a [Sketch](https://www.sketch.com) library that makes it easy for designers to create high-fidelity mockups using PatternFly components.
+### PatternFly Sketch design kit
+
+**Note:** We have migrated the PatternFly design system to Figma and no longer maintain or update our Sketch design kits. The following information may be out of date as a result. For information on how to migrate to Figma, read our ["Design with PatternFly" guide.](/get-started/design)
+
+The [PatternFly design kit](/design#sketch-design-kit) is a [Sketch](https://www.sketch.com) library that makes it easy for designers to create high-fidelity mockups using PatternFly components.
__Example__
*I want to implement a new component in the PatternFly Sketch symbol library.*
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md
index bf78ab98b5..62b3527ff2 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/charts/about/about.md
@@ -1,5 +1,5 @@
---
-id: About
+id: About charts
section: charts
---
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/breadcrumb.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/breadcrumb.png
index e3ca91c579..fe5597255f 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/breadcrumb.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/breadcrumb.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/placement.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/placement.png
index a5cf97f8f4..6bae80c4b5 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/placement.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/breadcrumb/img/placement.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/best-practices.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/best-practices.png
index 7ce8a0655d..8c31afac9e 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/best-practices.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/best-practices.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/elements.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/elements.png
index c606a9223e..323c14b537 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/elements.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/elements.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/loading-states.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/loading-states.png
index f5a592b685..4b246e576c 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/loading-states.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/loading-states.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-button.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-button.png
index 88b6999d09..be92464e13 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-button.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-button.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-drag-drop.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-drag-drop.png
index dbeaad8d2c..c79d42c3b0 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-drag-drop.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/upload-via-drag-drop.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/validation.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/validation.png
index 4b03bbf7a8..633fd8ba33 100644
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/validation.png and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/file-upload-multiple/img/validation.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/img/secondary-destructive-action.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/img/secondary-destructive-action.png
new file mode 100644
index 0000000000..1630f6d301
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/img/secondary-destructive-action.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/modal.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/modal.md
index 29b6e65974..1cf1c6312c 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/modal.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/modal/modal.md
@@ -40,6 +40,8 @@ Modals serve several functions in a UI and appear in four main types:
* [Confirmation dialogs](#confirmation-dialogs)
+* [Edit dialogs](#edit-dialogs)
+
* [Error dialogs](#error-dialogs)
* [Passive dialogs](#passive-dialogs)
@@ -71,6 +73,15 @@ When a text input field is added to a confirmation dialog, the danger button wil
+### Edit dialogs
+
+Use an edit dialog for managing assets. Edit dialogs contain multiple actions which can include, but are not limited to, saving your changes or deleting the asset. The primary action in the dialog should use a primary button, the secondary should use a secondary button, and the cancel button should remain a link button.
+
+For example, and edit dialogue might contain a "Save" button as the primary action, and a "Delete" button as a secondary action. If the secondary action is destructive, the button should be styled as a [secondary danger button](/components/button/#variant-examples). Additionally, it should be aligned to the right-side of the modal, directly across from the primary action and cancel buttons.
+
+
+
+When using destructive actions, ensure that the user is informed about the consequences of taking this action. Review the general guidelines for [danger button](/components/button/design-guidelines#danger-button) and destructive actions for additional guidance.
### Error dialogs
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/truncate/truncate.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/truncate/truncate.md
index b5b2d1329d..9d3aa4da26 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/components/truncate/truncate.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/components/truncate/truncate.md
@@ -10,7 +10,7 @@ section: components
* **Ellipsis**: indicates a truncate is used
## Usage
-Truncated items are indicated by an ellipsis (...) and are used when trying to avoud multiple lines of text or when a container is being overflowed by content. Truncation should only be used when 3 or more characters are being represented and there are still at least 4 non-truncated characters displayed. Truncated items should always incldue a tooltip on hover, showcasing the full string sequence.
+Truncated items are indicated by an ellipsis (...) and are used when trying to avoid multiple lines of text or when a container is being overflowed by content. Truncation should only be used when 3 or more characters are being represented and there are still at least 4 non-truncated characters displayed. Truncated items should always include a tooltip on hover, showcasing the full string sequence.
* **Breadcrumbs**: Use a breadcrumbs truncate when there isn’t enough room to display the entire breadcrumbs list, or as a way of managing relevance.
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/about.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/about.md
index f083776ca3..5384fe7cd0 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/about.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/about.md
@@ -1,5 +1,5 @@
---
-id: About
+id: About UX writing
section: UX writing
sortValue: 1
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/capitalization.md b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/capitalization.md
index 467426de1b..72817a5cfe 100644
--- a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/capitalization.md
+++ b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/capitalization.md
@@ -3,79 +3,69 @@ id: Capitalization
section: UX writing
---
-Consistent capitalization adds clarity and creates unity across your products' UIs.
+# Capitalization guidelines
-## Capitalization types
+Consistent capitalization adds clarity and creates unity across product UIs. PatternFly recommends writing in sentence case for all titles, headings, subtitles, or subheadings. **Sentence case** capitalizes only the first letter of the first word. The only exceptions to this are proper nouns, product names, acronyms, and initialisms, all of which should be capitalized.
-We recommend using title and sentence case as appropriate:
+For example: “When you use PatternFly’s design resources, you get helpful tips and best practices.”
-- **Title case** capitalizes only the first letter of each word in a sentence, except for smaller words with fewer than four letters, like articles and conjunctions.
+**Above all else, your main goal should be consistency.** You may need to use different capitalization standards depending on what you're designing, but be sure to keep the capitalization within your product area consistent.
- - For example: "PatternFly Design Resources with Tips and Best Practices."
+## Red Hat product UIs
- - **Note:** Hyperlinked articles in a UI are not displayed as titles. Instead, the copy typically reads something like, "Learn more about [tool name]."
+When you write for a product, make sure you adhere to the following capitalization patterns.
-- **Sentence case** only capitalizes the first letter of the first word in a title, heading, subtitle, or subheading except for proper nouns, product names, acronyms, and initialisms.
-
- - For example: “PatternFly’s design resources with tips and best practices.”
+- Default to sentence case across all UI elements, including navigation items, page titles, buttons, and so on.
-## Capitalization across PatternFly
+
-Follow these guidelines for PatternFly content, including documentation, UX copy, blog articles, and more.
+- Keep capitalization for custom resources the same as the capitalization style used during creation.
+ - For example, if a custom resource name was created with all lowercase letters, don't change any of the letters to uppercase when referencing this resource.
+- Capitalize product feature names when they’re used as proper nouns or when they refer to a capitalized UI term (like a navigation item). Write them in lowercase when they’re used to describe generic concepts. For example:
-- Use **sentence case** for page titles, menu items, navigation items, headings, subtitles, and subheadings.
+
- - For example, on PatternFly's website, all navigation items, button text, and headings are written in sentence case:
+ | **Feature name** | **UI text** | **Reasoning** |
+ |------------------|--------------|------------------|
+ | Compliance | “Check your system **compliance** using Red Hat Insights **Compliance**.” | The first “compliance” is lowercase since it refers to a concept. The second “compliance” refers to a specific feature offered on cloud.redhat.com, so it is capitalized. |
+ | Sources | “Add a *source* by going to **Settings > *Sources*.**” "Check the *Sources* table for status." Button text: "Add *source*" | “Sources” is only capitalized when it directly refers to a subsection, feature, or location in the UI. "Source" is lowercase in the button text because button labels should always be in sentence case. |
+
-
+### Capitalization in breadcrumb trails
-- **Capitalize** proper nouns, product names, acronyms, and initialisms.
-
- - **Note**: “React” is always capitalized, even when referring to a component (such as “React component”). It’s the official name of a JavaScript library, and it’s written as a proper noun across the react.js org site .
+It is common for page titles to appear as an item in a breadcrumb trail. Match the capitalization of the original page title in the corresponding breadcrumb item even when the item does not use sentence case, or when a breadcrumb trail contains mixed capitalization standards.
-- Write all components in **lowercase** unless they start a sentence.
-
- - For example, "Card, button, and banner components are my favorites."
+
-## Capitalization across Red Hat UIs
+Sometimes, user-named items will appear in a breadcrumb trail. If a custom resource name (for example, "customResource-name") is included in the breadcrumb trail, you should match the capitalization of the users' original entry.
-Similar to PatternFly, sentence case is the standard across Red Hat products. However, capitalization varies depending on each product area's context.
+
-Keep in mind that your main goal should be consistency. You may need to use different capitalization standards depending on what you're designing, but be sure to keep the capitalization within your product area consistent.
+### Tools outside your product portfolio
-In general, follow these guidelines:
+If you’re referencing tools that aren't part of your company’s product portfolio, write the product names as they appear in the respective company’s documentation.
-- **Capitalize** proper nouns, acronyms, initialisms, product names, services, and features.
-- Keep capitalization for custom resources the same as the capitalization used during creation. For example, if a custom resource was created in all lowercase letters, don't change any of the letters to uppercase.
-- Capitalize **Red Hat feature names** when they’re used as proper nouns or when they refer to a capitalized UI term (like a navigation item). Write them in lowercase when they’re used to describe generic concepts. For more specifics, reference the following table:
-
-
+For example, if you’re referencing a product in Amazon Web Services that Amazon capitalizes, then you should also capitalize it in your writing.
- | **Feature name** | **UI text** | **Reasoning** |
- |------------------|--------------|------------------|
- | Compliance | “Check your system compliance using Red Hat Insights Compliance.” | The first “compliance” is lowercase since it refers to compliance as a concept. The second “compliance” refers to a specific feature offered on cloud.redhat.com, so it is capitalized. |
- | User Access | “Manage user access for your organization using the User Access feature.” | The first “user access” is lowercase because it refers to user access as a concept. The second “user access” is capitalized because it refers to the User Access feature offered on cloud.redhat.com. |
- | Sources | “Add a source by going to **Settings > Sources.**” "Check the **Sources** table for status." Button text: "Add source" | “Sources” is only capitalized when it directly refers to a subsection, feature, or location in the UI. Always write buttons in sentence case. |
-
-
+## PatternFly website documentation
-A UI that adheres to these guidelines may resemble the following image:
+There are additional capitalization guidelines that you should follow if you contribute to any PatternFly content, like documentation or microcopy.
-
+- Use sentence case for page titles, menu items, navigation items, headings, subtitles, and subheadings.
-1. **Navigation**: Navigation items are in title case.
-1. **Menu**: Menu items are in sentence case.
+- Capitalize proper nouns, product names, acronyms, and initialisms. For example: React, PatternFly, and HTML.
-## Capitalization in breadcrumb trails
+Take the PatternFly website as an example, where all navigation items, button text, and headings are written in sentence case and all proper nouns are in title case:
-Usually, page titles appear in a breadcrumb trail. If all page titles are in title case then they should also appear in title case in the breadcrumb trail. If all page titles are in sentence case, they should also appear in sentence case in the breadcrumb trail.
+
+
-However, breadcrumb trails aren’t limited to page titles alone. If a name entered by a user (such as “vagrant-host”) is included in the breadcrumb trail, then use the same case that the name appears in.
+- Write all components in lowercase unless they start a sentence.
-For example, this may look like: *Rules* > *Systems* > *System Tool* > *vagrant-host*
+- Format any code snippets according to the standards used for their language.
-## Capitalization for tools outside your product portfolio
+For example, the following image from our component documentation uses lowercase for the component name ("card") and capitalizes code appropriately ("isCompact" and "isLarge").
-If you’re referencing tools outside your company’s product portfolio, write the product names as they appear in the respective company’s documentation.
+
+
-For example, if you’re referencing a product in Amazon Web Services and Amazon capitalizes it, you should also capitalize it in your writing.
\ No newline at end of file
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/Testing.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/Testing.png
new file mode 100644
index 0000000000..7cdfac952b
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/Testing.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/basic-breadcrumb.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/basic-breadcrumb.png
new file mode 100644
index 0000000000..d95cb33ea2
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/basic-breadcrumb.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/breadcrumb-custom-item.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/breadcrumb-custom-item.png
new file mode 100644
index 0000000000..10df62fff9
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/breadcrumb-custom-item.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/component-docs.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/component-docs.png
new file mode 100644
index 0000000000..0886c70489
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/component-docs.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/component-example-text.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/component-example-text.png
new file mode 100644
index 0000000000..970220d398
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/component-example-text.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/navigation-capitalization.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/navigation-capitalization.png
new file mode 100644
index 0000000000..9974ee85da
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/navigation-capitalization.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/patternfly-sentence-case.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/patternfly-sentence-case.png
deleted file mode 100644
index 50fefd881f..0000000000
Binary files a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/patternfly-sentence-case.png and /dev/null differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/pf-component-caps.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/pf-component-caps.png
new file mode 100644
index 0000000000..e3a5485c82
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/pf-component-caps.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/pf-home-caps.png b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/pf-home-caps.png
new file mode 100644
index 0000000000..85ebf1b851
Binary files /dev/null and b/packages/documentation-site/patternfly-docs/content/design-guidelines/content/img/pf-home-caps.png differ
diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md
new file mode 100644
index 0000000000..5a571853a9
--- /dev/null
+++ b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-design.md
@@ -0,0 +1,51 @@
+---
+id: Design for accessibility
+section: accessibility
+---
+
+import { Card, CardBody, Grid, GridItem } from '@patternfly/react-core';
+
+As described in our [accessibility fundamentals](/accessibility/accessibility-fundamentals), users may interact with your product through a variety of assistive technologies. In addition to [developing for accessibility](/accessibility/accessibility-development), you must also incorporate it into your product's visual design.
+
+## Color and contrast
+
+Color and contrast go hand-in-hand for visual design accessibility.
+
+For example, you should consider contrast when using colors commonly affected by color perception deficiency (such as those described in ["Overview of Low Vision" by W3C](https://www.w3.org/WAI/GL/low-vision-a11y-tf/wiki/Overview_of_Low_Vision#Color_Perception)). Different colors in a UI should be distinguishable for users across the color perception deficiency spectrum, typically by ensuring that each color has a different contrast weight.
+
+Designing with contrast in mind also benefits users with light sensitivity.
+
+PatternFly components use [our color palettes](/design-foundations/colors) to pass color contrast tests. As long as you follow our recommendations, any UI built with PatternFly components should have proper contrast between colors, making them distinguishable for users with different types of color perception and light sensitivity.
+
+It's important not to solely rely on color for conveying information. Even though PatternFly components pass color contrast tests, they also use icons to further help with identification, which can be especially helpful for users with a form of color blindness.
+
+
+
+
+
+
+If you go beyond our recommendations to combine PatternFly colors in other ways, please be sure to check your color contrast with a contrast checker. When you alter the colors and/or icons used in PatternFly components, know that they may no longer be accessible for all users.
+
+
+
+
+## Content
+
+The text in your UI should also be accessible to users with low vision. For example, links should be descriptive and concise, essential content should not be hidden in the UI, and text should scale appropriately as the UI window is resized or magnified.
+
+To help simplify and strengthen the way that users process content, it is important to carefully consider your text size, font, letter spacing, margins, and spacing. PatternFly supports accessibility in these areas through our [typography](/design-foundations/typography) and [spacing](/design-foundations/spacers) guidelines.
+
+## Understanding low vision
+
+In addition to following the previous recommendations, it is helpful to develop an understanding of low-vision users, so that their needs are a key concern as you design.
+
+**Low vision** refers to any visual impairment that impedes a person’s ability to perform everyday tasks, which cannot be corrected with glasses, contacts, medicine, or surgery.
+
+There are 4 types of limitations as a result of low vision.
+
+1. **Visual acuity**: A measure of a person's visual sharpness, with 20/20 being the standard.
+1. **Field of vision**: The area of vision that people can see clearly when their eyes are in a fixed position. Some users have a restricted field of vision, such as central or peripheral field loss.
+1. **Color perception**: How people see colors. Some of your users may have deficiencies in color perception that affects their ability to see certain colors. This is commonly called "color blindness", but many people with color perception deficiencies can still see most colors.
+1. **Contrast and light sensitivity**: The way that people perceive luminance (the contrast of foreground and background).
+
+We do our best to make PatternFly accessible for low-vision users by default, but it is important that you consciously design with these needs in mind to ensure that your final design has proper color, contrast, and content accessibility.
\ No newline at end of file
diff --git a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md
index 9f923719ef..860f128c01 100644
--- a/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md
+++ b/packages/documentation-site/patternfly-docs/content/developer-resources/accessibility-testing.md
@@ -2,104 +2,111 @@
id: Testing your accessibility
section: accessibility
---
+import { Checkbox } from '@patternfly/react-core';
-## General testing
+# Testing your product's accessibility
-Many accessibility issues can be found by doing a few simple checks:
+This guide contains instructions and recommendations that you can use to robustly test your product's accessibility, in order to identify accessibility issues and opportunities for improvement.
-1. **Validate your HTML.** Structural, semantic HTML is the key starting point toward good accessibility practices. When a screen reader (or any sort of assistive device) scans a web page, it gets information about the Document Object Model (DOM), or the HTML structure of the page. No styles or JavaScript will be read by a screen reader.
+**Keep in mind that this guide will not cover every scenario.**
- - Screen reader software like Voice Over, NVDA, or JAWS doesn’t just turn text into speech. It can use information in the HTML to list all of the headings on a page, give extra navigation controls to data tables, or announce how many items are in a list, among other things. This makes semantic HTML essential.
+## Standard testing procedures
- - There are many tools you can use to validate your HTML, such as [W3C’s markup validation service](https://validator.w3.org/).
+Many accessibility issues can be found by doing a few standard checks.
+### Validate your HTML
-2. **Use an accessibility audit tool to check for violations.** If you are using PatternFly in your project, we recommend using [aXe: The Accessibility Engine](//www.deque.com/axe/) to check for accessibility violations locally. To make it even easier for you, we've created the [patternfly-a11y script](https://github.com/patternfly/patternfly-a11y) which reports any axe accessibility violations from a set of pages. A configuration file can be set to customize to specific needs like authentication, waiting for any specific items to finish loading (like a loading spinner), etc. When used as a report, it will give an output [similar to this example](http://a11y-os.surge.sh/). The UI should be built first in the CI workflow and then a job created to run the a11y script against that build. The a11y script assumes that there is a webserver running somewhere that is serving up the pages, i.e. in localhost:8000, that it can reach. If you want to test a step before deployment, you could follow the path of integrating axe with cypress. If you are contributing to PatternFly, refer to our [README.md](//github.com/patternfly/patternfly/blob/main/README.md#testing-for-accessibility) on how to run this tool.
+Good accessibility practices start with structural, semantic HTML. When a screen reader (or any sort of assistive technology) scans a web page, it gets information about the Document Object Model (DOM), or the HTML structure of the page. No styles or JavaScript will be read by a screen reader.
+Screen readers (like Voice Over (VO), NVDA, or JAWS) don't just turn text into speech. They also use information in the HTML to list all of the headings on a page, give extra navigation controls to data tables, announce how many items are in a list, and more. This makes semantic HTML essential.
-3. **Test keyboard accessibility, and check that these requirements are met:**
- - All functionality is keyboard accessible.
- - Elements in the HTML and in the layout follow a logical order.
- - Elements with focus are clearly visible.
+You can use an HTML validation tool to test your product, such as [W3C’s markup validation service](https://validator.w3.org/).
+### Check for accessibility violations with an audit tool
-4. **Disable styles**, then test the information architecture and presence of adequate text labels. The [WAVE browser extension from WebAIM](//wave.webaim.org/extension/) provides this feature if it isn't available in the browser you are using.
+When using PatternFly, we recommend checking for accessibility violations locally via aXe: The Accessibility Engine (using [aXe DevTools](https://www.deque.com/axe/devtools/), the [Chrome extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd), or the [Firefox extension](https://addons.mozilla.org/en-US/firefox/addon/axe-devtools/)). If you want to test prior to deployment, you can integrate aXe with [Cypress](https://www.cypress.io/).
+
+#### Bulk testing with the patternfly-ally script
+We offer the [patternfly-a11y script](https://github.com/patternfly/patternfly-a11y) for bulk testing, which reports any aXe accessibility violations from a set of pages. You can adapt this script to your needs by creating a configuration file that includes authentication, waits for specific items to finish loading (like a loading spinner), or addresses other items relevant to your use case. As a report, this script will deliver an [accessibility report via surge](http://a11y-os.surge.sh/).
-5. **Test with any screen reader available in your operating system.** We target these screen readers to test PatternFly:
- - JAWS with Chrome, Windows ([JAWS keyboard shortcuts](//dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts))
- - Voiceover with Safari, Mac ([Voiceover keyboard shortcuts](//dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts))
- - NVDA with Firefox, Windows ([NVDA keyboard shortcuts](//dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts))
+Before using this script, your UI should be built in the CI workflow. Once built, create a job to run the script against that build. The script assumes that a web server is running and serving your product somewhere that the script can reach (for example, in `localhost:8000`).
+### Test keyboard accessibility
+The keyboard is an essential accessibility tool, so it is necessary to ensure that the following requirements are met:
-6. **Check color contrast for the following:**
- - Text color against background color ([Understanding WCAG 1.4.3](//www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html))
- - Text color against link color ([Technique G183](//www.w3.org/TR/WCAG20-TECHS/G183.html))
- - Visible boundaries of buttons and form elements against adjacent background color ([Understanding WCAG 1.4.11](//www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html))
+- All functionality is keyboard accessible.
+- Elements in the HTML and in the layout follow a logical order.
+- Elements with focus are clearly visible.
+
+### Test without styles
+
+Screen readers cannot access style information, so you should disable styles for your product to test that your information architecture is effective and that elements have adequate text labels.
+The [WAVE browser extension from WebAIM](/wave.webaim.org/extension/) allows you to disable styles if this isn't available in the browser you are using.
+### Test with a screen reader
-## Screen readers
-Just as front-end developers use their browser to see how their changes look, you should use a screen reader to see how your accessibility looks (we use Voice Over).
+You can test with any screen reader that is available in your operating system. In PatternFly, we target:
+ - [JAWS](https://www.freedomscientific.com/products/software/jaws/) with Chrome, Windows ([JAWS keyboard shortcuts](//dequeuniversity.com/screenreaders/jaws-keyboard-shortcuts)).
+ - [VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac) with Safari, Mac ([VoiceOver keyboard shortcuts](//dequeuniversity.com/screenreaders/voiceover-keyboard-shortcuts)).
+ - [NVDA](https://www.nvaccess.org/download/) with Firefox, Windows ([NVDA keyboard shortcuts](//dequeuniversity.com/screenreaders/nvda-keyboard-shortcuts)).
-Generally, screen readers access the DOM (Document Object Model), and they use browser APIs (Application Programming Interfaces) to get the information they need. In this way, a screen reader knows what to say when a set of list items begins and ends, and it typically announces, in advance, how many items are in the list. A screen reader can also traverse a page using heading navigation to speak the heading level.
+### Check color contrast
+
+Your UI's colors should pass the following contrast checks to ensure that users across the vision spectrum can understand your product:
+ - Text color against background color ([Understanding WCAG 1.4.3](//www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html))
+ - Text color against link color ([Technique G183](//www.w3.org/TR/WCAG20-TECHS/G183.html))
+ - Visible boundaries of buttons and form elements against adjacent background color ([Understanding WCAG 1.4.11](//www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html))
-Here are a few aspects that can affect how screen readers communicate information:
+## Accessibility testing checklist
-- **Semantic HTML**: Semantics refers to the meaning of a piece of code. A semantic element clearly describes its meaning to both the browser and the developer. For example, `` and `
` are non-semantic elements because they don't describe their contents. Examples of semantic elements include `