Clarify required vs optional field labeling patterns in PatternFly Forms documentation

[asuwebdesign]

Summary

PatternFly’s current Forms documentation provides limited guidance for indicating required versus optional fields in mixed forms. This proposal recommends documenting a minority-marking pattern—marking only the fields that differ from the majority requirement—supported by clear top-of-form instructions and accessible semantics.

This approach is already recommended by other mature design systems (IBM Carbon, GOV.UK, U.S. CMS) and aligns with W3C / WCAG guidance. Documenting this pattern would reduce visual noise, improve scanability, and promote consistent, accessible implementations across PatternFly products.

Current State

PatternFly documentation today primarily describes:

• Marking required fields using an asterisk
• Optionally stating “all fields are required” at the top of a form

What is not addressed:

1. How to handle mixed forms where only one or two fields differ
2. Whether text labels such as (optional) or (required) are preferred over symbols
3. When it is appropriate to mark only the minority of fields
4. How these decisions should be communicated to assistive technologies

As a result, teams frequently:

• Over-label every field, increasing visual clutter
• Invent local conventions that differ across products

Proposed Documentation Enhancement

1. Document a Minority-Marking Pattern

Guidance to add:

• When most fields are required, mark only optional fields using (optional) in the label
• When most fields are optional, mark only required fields using (required) in the label

This pattern should be presented as a recommended option, not an edge case.

Industry alignment:

• IBM Carbon Design System recommends marking the minority and providing a form-level instruction
• GOV.UK Design System defaults to required fields and marks optional fields only
• U.S. CMS Design System uses the same rule-based approach

2. Require a Clear Top-of-Form Instruction

When minority marking is used, documentation should recommend a short instruction immediately below the form title, such as:

• “Fields are required unless marked optional.”
• “Fields are optional unless marked required.”

This aligns with WCAG 2.1 Success Criterion 3.3.2 (Labels or Instructions) and W3C WAI guidance.

3. Labeling and Accessibility Guidance

Documentation should explicitly state:

• Required/optional status must be conveyed using visible text, not color or symbols alone
• Native HTML required should be used for programmatic accessibility
• Asterisks may be used visually but must not be the sole indicator

Example:

Name
[input]   ← required attribute applied

Description (optional)
[input]

4. Validation Expectations (Brief, Non-Prescriptive)

To ensure this pattern remains usable:

• Validation errors should appear at the field level
• Error messages should be programmatically associated with inputs (aria-describedby, aria-invalid)
• Focus should move to the first error on submission

Why This Matters

• Accessibility: Supports WCAG 3.3.2 and WAI guidance on form instructions
• Usability: Improves scanability by emphasizing exceptions rather than repeating the norm
• Consistency: Aligns PatternFly with established enterprise and government design systems

Anticipated Concerns & Clarifications

• This does not remove existing patterns; it adds guidance for a common scenario
• This is documentation, not enforcement
• Teams already use this pattern today without official guidance

Acceptance Criteria

• Update Forms documentation to include:
  • Minority-marking decision rules
  • Top-of-form instruction guidance
  • Accessible labeling examples
• Provide at least one modal example and one full-form example
• Reference WCAG 2.1 / 3.3.2 and W3C WAI form guidance

Closing

This enhancement formalizes a restraint-driven, accessibility-aligned pattern teams already rely on. Clear documentation would improve consistency, usability, and accessibility across PatternFly implementations.