Skip to content

UI: Add Form best practices Storybook page - #82197

Merged
mirka merged 5 commits into
trunkfrom
add-form-best-practices
Aug 31, 2026
Merged

UI: Add Form best practices Storybook page#82197
mirka merged 5 commits into
trunkfrom
add-form-best-practices

Conversation

@mirka

@mirka mirka commented Aug 28, 2026

Copy link
Copy Markdown
Member

What?

Adds a Form Best Practices page under Design System ▸ Components ▸ Form in Storybook.

Why?

People composing several controls under one visible group label need a documented accessible pattern. The Form primitives overview already tells authors to prefer a *Control. This page shows that composition inside a fieldset.

How?

Adds packages/ui/src/form/stories/best-practices.mdx and packages/ui/src/form/stories/best-practices.story.tsx. The example uses Fieldset for the group label and InputControl with hideLabelFromVision for each field, so each input keeps a native label without a second visible one. Hidden labels include the visible unit (lb, pounds) so voice-control users can target the text they see.

Testing Instructions

  1. Open Storybook.
  2. Go to Design System ▸ Components ▸ Form ▸ Best Practices.
  3. Confirm the Shipping weight example shows two number inputs with lb and oz suffixes, and no visible Pounds or Ounces labels.
  4. Confirm each input still has an accessible name (lb, pounds, oz, ounces) via its hidden label.

Screenshots

Best practices page in Storybook

@mirka mirka self-assigned this Aug 28, 2026
@github-actions github-actions Bot added the [Package] UI /packages/ui label Aug 28, 2026
@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

Size Change: 0 B

Total Size: 7.92 MB

compressed-size-action

@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

Flaky tests detected in 09f89ca.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/33415301078
📝 Reported tests:

two users concurrently move list items (RTC WebSocket) in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts, passed after 1 failed attempt.
Error: expect(received).toBeLessThan(expected)

Expected: < 3
Received:   4

Call Log:
- Timeout 10000ms exceeded while waiting on the predicate
    at assertMovedOrder (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:646:8)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:650:10

@mirka mirka added the [Type] Developer Documentation Documentation for developers label Aug 31, 2026
@mirka
mirka marked this pull request as ready for review August 31, 2026 15:50
@mirka
mirka requested a review from a team as a code owner August 31, 2026 15:50
@github-actions

github-actions Bot commented Aug 31, 2026

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🚀

Left one non-blocking comment.

* legend for the group. Give each `InputControl` its own `label` and set
* `hideLabelFromVision` so only the group label stays visible.
*/
export const LabelingComposedComponents: StoryObj = {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: The fields show lb and oz, but their accessible names are Pounds and Ounces, so voice-control users cannot reliably target them using the visible text.

Should we include the unit in each label, such as label="lb, pounds", and clarify that labels should only be visually hidden when other visible text still identifies each control?

(related, related)

@mirka
mirka enabled auto-merge (squash) August 31, 2026 16:56
@mirka
mirka merged commit 0c92122 into trunk Aug 31, 2026
51 checks passed
@mirka
mirka deleted the add-form-best-practices branch August 31, 2026 17:05
@github-actions github-actions Bot added this to the Gutenberg 24.0 milestone Aug 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Package] UI /packages/ui [Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants