Design guidelines: Form and form control by kaylachumley · Pull Request #5047 · patternfly/patternfly-org

kaylachumley · 2026-06-30T20:51:07Z

Changes

Added a Best practices section to the form design guidelines with a "Menu toggles and dropdowns in a form" subsection documenting the pf-m-form modifier
Added pf-m-form usage note to the form-control design guidelines
Updated spacing references in the form design guidelines to use design tokens (--pf-t--global--spacer--lg, --pf-t--global--spacer--md)
Replaced design guidelines images for the form, form-control, checkbox, radio, and text-input components

Adds a new "Best practices" section with a "Menu toggles and dropdowns in a form" subsection, documenting the use of the pf-m-form modifier and its effect on border radius across themes. Includes a do/don't example image.

patternfly-build · 2026-06-30T20:56:09Z

Preview: https://pf-org--pr-5047-site.surge.sh

cloudflare-workers-and-pages · 2026-07-09T23:06:38Z

Deploying patternfly-org with Cloudflare Pages

Latest commit:	`9c58498`
Status:	🚫 Build failed.

View logs

- Replace design guidelines images for form, form-control, checkbox, radio, and text-input - Update spacing references in form design guidelines to use token values (--pf-t--global--spacer--lg, --pf-t--global--spacer--md)

kaylachumley

updates all of the forms and form related design guidelines images

Swaps PNG placeholders for actual SVG files across form, form-control, checkbox, radio, and text-input design guidelines to fix blurry images. Updates markdown references to match new SVG filenames.

andrew-ronaldson · 2026-07-15T14:54:59Z

 ## Usage
 While form controls are useful in providing feedback on user input, they don't need to be implemented for every input instance. Only use form controls when it is essential to convey information to the user. For example, if any string is valid for a text input, or any selection in a list is acceptable, form controls are not necessary.

+Apply the `pf-m-form` modifier to all dropdowns and menu toggles used in a form. The `.pf-m-form` class modifies the menu toggle's border radius to match other form elements. Read more on form controls in the [Form guidelines](/components/forms/form/design-guidelines).


@nicolethoen @kmcfaul @mcoker this makes sense to me but do we need to mention props on the react components or is the CSS enough?

Personally I think it might be odd to only mention the class. "Apply the pf-m-form modifier, either by applying the class or using the isForm prop for React, to all menu toggles used in a form." Maybe? At the very least we should remove the "dropdown" from this as the modifier is only applicable to the menu toggle itself.

andrew-ronaldson · 2026-07-15T14:55:50Z

+![Do and don't example showing a menu toggle with the pf-m-form modifier applied (square corners) versus without it (pill shape) in a form context.](./img/form-toggle-modifier.svg)
+</div>
+
+In the default PatternFly theme, form elements use `--pf-t--global--border--radius--control--form-element` (6px) border radius token. In the [Felt theme](/foundations-and-styles/theming#project-felt-theme), form elements, including input fields, menu toggles, and dropdowns, continue to use the same `--pf-t--global--border--radius--control--form-element` (6px) token, while other non-control components use `--pf-t--global--border--radius--control--default`. Using the `pf-m-form` class ensures that your form elements and menu toggle always match the border radius of the surrounding form fields, regardless of theme.


Thanks for this update @kaylachumley

andrew-ronaldson

Looks good to me but waiting on feedback about the react props.

mcoker

Left some comments, some are pretty nitpicky so feel free to pick and choose what you think is worth updating. Nothing here is blocking.

One thing though - it looks like this PR is adding a .png file for most/all of the SVGs - was that intended to be checked in? The images on the site are all still using the .svg - none of the markdown docs pages were updated to reference the new .png files.

mcoker · 2026-07-16T18:35:17Z


    <div class="ws-docs-content-img">
-    ![Example 1 of do's and don'ts for using a checkbox or a switch.](./img/CB-vs-switch-1.svg)
+    ![Example 1 of do's and don'ts for using a checkbox or a switch.](./img/checkbox-vs-switch-1.svg)


Should you remove the "Save changes" button from the one with switches?

Misread the image a bit. I think the "save changes" button on the switch side is intended since it's a "Don't" example. Still, could we expand the alt text?

Example 1 of do's and don'ts for using a checkbox versus a switch. On the left is the "do" example, a group of checkboxes that require a "Save changes" button. On the right is the "don't" example, a group of switches that automatically update upon clicking them, but still have a "Save changes" button.

mcoker · 2026-07-16T18:42:52Z

The alignment is a little off. There is a 4.5px top padding in the component

mcoker · 2026-07-16T19:25:23Z

no big deal but the form on the right has "Button" text for both buttons, and has more space than the form on the left. I would expect the link button text to be "Cancel" since that's what all of our examples use.

mcoker · 2026-07-16T19:48:45Z

FWIW the exclamation-circle in the right one is kinda floating in the middle of the input

mcoker · 2026-07-16T20:00:35Z

The field group toggle/text is off-center compared to the examples

mcoker · 2026-07-16T20:10:00Z


 ### General spacing
-Always add 24px of spacing underneath each form input. If a form input includes helper text, this 24px spacing should start below the helper text. Spacing between data inputs like checkboxes and radio buttons should also be 24px when on the same line or stacked on one another. For more spacing information, consult the [PatternFly spacer guidelines](/foundations-and-styles/spacers#considering-line-height-and-padding).
+Add `--pf-t--global--spacer--lg` (24px) of spacing below each form input. If a form input includes helper text, this spacing should start below the helper text. Spacing between data inputs like checkboxes and radio buttons should also be `--pf-t--global--spacer--lg` (24px) when on the same line or stacked on one another. For more spacing information, see the [PatternFly spacer guidelines](/foundations-and-styles/spacers#considering-line-height-and-padding).


FWIW we use --pf-t--global--spacer--gap--group-to-group--vertical--default between form groups.

IMO the image is a little weird, too

It shows padding around the form, which probably shouldn't be there (it isn't part of our form)

It calls out the xl/32px spacer between the last form group and the submit button row but that isn't in this paragraph

Also the image refers to that spacer as "2xl" when the code uses "xl"

If we do use the more semantic spacer (gap--group-to-group...) in the docs, I wonder if we should update the image, too.

Good call outs - I left the original structure(padding in pink) of the image that erin included but it could stand for some updates. I agree that it would be good to update the semantic spacer callouts in the image and the text description. Il'l remove the padding on the perimeter of the form image.
thank you 🫡 @mcoker

mcoker · 2026-07-16T20:14:13Z

 ### Button spacing

-Place submit or cancel buttons on the bottom left of a form, left-aligned with all form fields. Buttons should be placed 16px apart in all contexts. Buttons for actions other than submitting or canceling the form may be placed elsewhere within a form depending on your use case. 
+Place submit or cancel buttons on the bottom left of a form, left-aligned with all form fields. Buttons should be spaced using `--pf-t--global--spacer--md` (16px) in all contexts. Buttons for actions other than submitting or canceling the form may be placed elsewhere within a form depending on your use case. 


FWIW we use --pf-t--global--spacer--gap--action-to-action--default in the code (in our action list component).

mcoker · 2026-07-16T20:26:02Z

+
+To ensure your forms are consistent, maintainable, and adaptable across different themes, we recommend following these best practices.
+
+### Menu toggles and dropdowns in a form


If this is clear for designers, I'm sure it's good, but to me the word "dropdowns" reads like it's something separate from a menu toggle. I would probably just say menu toggles.

Agreed with this, especially because for me a Select could be used in a form as well. The verbiage for this section looks to be more just about the MenuToggle itself, I don't beleive anything is specific to a Dropdown.

thatblindgeye · 2026-07-17T12:47:06Z


    <div class="ws-docs-content-img">
-    ![Example 1 of do's and don'ts for using a checkbox or a switch.](./img/CB-vs-switch-1.svg)
+    ![Example 1 of do's and don'ts for using a checkbox or a switch.](./img/checkbox-vs-switch-1.svg)


Misread the image a bit. I think the "save changes" button on the switch side is intended since it's a "Don't" example. Still, could we expand the alt text?

Example 1 of do's and don'ts for using a checkbox versus a switch. On the left is the "do" example, a group of checkboxes that require a "Save changes" button. On the right is the "don't" example, a group of switches that automatically update upon clicking them, but still have a "Save changes" button.

thatblindgeye · 2026-07-17T12:56:32Z

 ## Usage
 While form controls are useful in providing feedback on user input, they don't need to be implemented for every input instance. Only use form controls when it is essential to convey information to the user. For example, if any string is valid for a text input, or any selection in a list is acceptable, form controls are not necessary.

+Apply the `pf-m-form` modifier to all dropdowns and menu toggles used in a form. The `.pf-m-form` class modifies the menu toggle's border radius to match other form elements. Read more on form controls in the [Form guidelines](/components/forms/form/design-guidelines).


Personally I think it might be odd to only mention the class. "Apply the pf-m-form modifier, either by applying the class or using the isForm prop for React, to all menu toggles used in a form." Maybe? At the very least we should remove the "dropdown" from this as the modifier is only applicable to the menu toggle itself.

thatblindgeye · 2026-07-17T13:06:56Z

+
+### Menu toggles and dropdowns in a form
+
+Apply the `pf-m-form` modifier to all dropdowns and [menu toggles](/components/menus/menu-toggle/html/#usage) used in a form. The `.pf-m-form` class modifies the menu toggle's border radius to match other form elements.


Same comment would apply here as to the one I responded to from Andrew above.

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

…/checkbox/checkbox.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com>

…/form/forms.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com>

…/form-control/form-control.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

kaylachumley added 2 commits June 30, 2026 14:25

Add best practices section to form design guidelines

12db9ce

Adds a new "Best practices" section with a "Menu toggles and dropdowns in a form" subsection, documenting the use of the pf-m-form modifier and its effect on border radius across themes. Includes a do/don't example image.

Update form-control design guidelines with pf-m-form usage note

9b7e458

kaylachumley changed the title ~~Updat to Form and form control guidelines~~ Updat to Form and form control design guidelines Jun 30, 2026

kaylachumley requested review from andrew-ronaldson, bekah-stephens and lboehling June 30, 2026 20:59

kaylachumley changed the title ~~Updat to Form and form control design guidelines~~ Update to Form and form control design guidelines Jul 9, 2026

kaylachumley changed the title ~~Update to Form and form control design guidelines~~ Design guidelines: Form and form control Jul 9, 2026

andrew-ronaldson requested changes Jul 9, 2026

View reviewed changes

Comment thread packages/documentation-site/patternfly-docs/content/components/form/forms.md Outdated

Merge branch 'main' into form-guidelines

9a6ce88

kaylachumley added 2 commits July 10, 2026 13:26

Update design guidelines images and spacing token references

74a04ae

- Replace design guidelines images for form, form-control, checkbox, radio, and text-input - Update spacing references in form design guidelines to use token values (--pf-t--global--spacer--lg, --pf-t--global--spacer--md)

Refine border radius token references in form best practices section

bb34d00

kaylachumley commented Jul 10, 2026

View reviewed changes

kaylachumley added 4 commits July 10, 2026 13:45

Fix blurry images by correcting file extensions from .svg to .png

998c931

Replace raster images with true SVGs for form design guidelines

5aa4338

Swaps PNG placeholders for actual SVG files across form, form-control, checkbox, radio, and text-input design guidelines to fix blurry images. Updates markdown references to match new SVG filenames.

Update checkbox-nested.svg

1550763

Update SVG images for checkbox and form design guidelines

c22ca21

kaylachumley requested a review from andrew-ronaldson July 10, 2026 21:19

andrew-ronaldson reviewed Jul 15, 2026

View reviewed changes

mcoker requested a review from thatblindgeye July 16, 2026 18:15

mcoker reviewed Jul 16, 2026

View reviewed changes

thatblindgeye requested changes Jul 17, 2026

View reviewed changes

kaylachumley and others added 4 commits July 17, 2026 13:04

Update packages/documentation-site/patternfly-docs/content/components…

32a76a3

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

22d0307

…/checkbox/checkbox.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

ce1028b

…/form/forms.md Co-authored-by: Michael Coker <35148959+mcoker@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

52cdab3

…/form-control/form-control.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

kaylachumley and others added 6 commits July 17, 2026 13:28

Update packages/documentation-site/patternfly-docs/content/components…

3611751

…/form-control/form-control.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

27d4219

…/form-control/form-control.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

1d08c95

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

02229c4

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

6dcbcd0

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>

Update packages/documentation-site/patternfly-docs/content/components…

9c58498

…/checkbox/checkbox.md Co-authored-by: Eric Olkowski <70952936+thatblindgeye@users.noreply.github.com>


		To ensure your forms are consistent, maintainable, and adaptable across different themes, we recommend following these best practices.

		### Menu toggles and dropdowns in a form


		### Menu toggles and dropdowns in a form

		Apply the `pf-m-form` modifier to all dropdowns and [menu toggles](/components/menus/menu-toggle/html/#usage) used in a form. The `.pf-m-form` class modifies the menu toggle's border radius to match other form elements.

Uh oh!

Conversation

kaylachumley commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Uh oh!

patternfly-build commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

cloudflare-workers-and-pages Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying patternfly-org with Cloudflare Pages

Uh oh!

kaylachumley left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andrew-ronaldson left a comment

Choose a reason for hiding this comment

Uh oh!

mcoker left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

kaylachumley commented Jun 30, 2026 •

edited

Loading

patternfly-build commented Jun 30, 2026 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jul 9, 2026 •

edited

Loading

kaylachumley left a comment •

edited

Loading