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:	`c22ca21`
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?

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?

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:41:14Z

+![Example of a group of checkboxes.](./img/checkbox-alignment.svg)
 </div>

 You also have the option to use progressive disclosure by nesting other controls underneath a checkbox. The nested options would be enabled or disabled when the user selects or deselects a checkbox.


In the form docs for progressive disclosure, we use the language "hide and show", which I think is more clear than enabled/disabled since enable/disable has special meaning when it comes to form fields.

Suggested change

You also have the option to use progressive disclosure by nesting other controls underneath a checkbox. The nested options would be enabled or disabled when the user selects or deselects a checkbox.

You also have the option to use progressive disclosure by nesting other controls underneath a checkbox. The nested options would be shown or hidden when the user selects or deselects a checkbox.

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.

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.

mcoker · 2026-07-16T20:29:41Z

+![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.


Nit, but above you used the period conditionally to refer to the "pf-m-form modifier" and ".pf-m-form class", but here you're referring to the class so I would use the period.

Suggested change

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.

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 toggles always match the border radius of the surrounding form fields, regardless of theme.

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

	You also have the option to use progressive disclosure by nesting other controls underneath a checkbox. The nested options would be enabled or disabled when the user selects or deselects a checkbox.
	You also have the option to use progressive disclosure by nesting other controls underneath a checkbox. The nested options would be shown or hidden when the user selects or deselects a checkbox.


		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

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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