Page History
...
- Labels must be succinct (1–2 words) and must not end with colons.
- Maintain consistent spacing: 24px around forms, 8px between fields.
- Separate input groups with sublines; an optional introduction may be added below.
- Use tooltips only for short, explanatory information; never for essential content.
- Provide help text below form titles to guide correct input.
- Apply inline error and validation messages directly within the form to inform users and offer corrective actions.
Accessibility
...
Usage
- Use for long, multi-line localized input where users must provide content per language, and label the field via
labelTranslations. - Pre-seed known copy with
defaultValueto reduce initial typing and clarify expected structure. - Limit verbosity with
maxLengthso each language stays within the allowed character budget. - Preserve in-progress work on long tasks by enabling
saveInLocalStorage. - Switch to review/read-only scenarios by setting
readonly: trueinstead of hiding the field.
Sizing & Layout
- Set the visible height using
rows; increase rows for drafting, reduce for compact forms. - Add breathing room around the field with
paddingClassto maintain consistent spacing. - Keep the field present but out of view when unnecessary by toggling
hidden.
States & Feedback
- Enforce mandatory content and per-language rules through
validation(e.g., required languages, length). - Reflect non-editable states explicitly with
readonlyto signal view-only content. - React to text edits in real time with
events.ON_VALUE_CHANGE(e.g., to trigger checks or previews).
Visibility & Authorization
- Gate visibility by policy with
visibilityPolicySetIdwhen users must not see the field. - Keep visible but disabled using
authorizationDisablewhen users should understand they lack edit rights.
Content & Localization
- Keep labels concise and localized with
labelTranslations(1–2 words, no trailing colon). - Align validation limits with
validationandmaxLengthso users see consistent, locale-appropriate rules.
Dos & Don’ts
| Do | Don’t | Article setting(s) |
|---|---|---|
Use labelTranslations for a short, localized label (e.g., “Description”). | Hard‑code an English label or add a trailing colon. | labelTranslations |
Pre-fill per‑language text with defaultValue to guide structure. | Start empty when templates are known. | defaultValue |
Cap length per language with maxLength. | Allow unbounded text that overflows downstream limits. | maxLength |
Use rows to make long‑form editing comfortable. | Force a tiny viewport that requires constant scrolling. | rows |
Turn on saveInLocalStorage for lengthy authoring. | Risk data loss on reloads for multi‑paragraph input. | saveInLocalStorage |
Drive real-time checks from ON_VALUE_CHANGE. | Validate only on submit when immediate feedback is needed. | events, ON_VALUE_CHANGE, validation |
Use readonly for review mode. | Hide the field (hidden) when users must read existing text. | readonly, hidden |
Gate access with visibilityPolicySetId/authorizationDisable. | Expose sensitive fields without policy controls. | visibilityPolicySetId, authorizationDisable |
Control presence with displayConditions. | Show the field in contexts where it isn’t applicable. | displayConditions |
Name payloads predictably with dataField and set controlsRequestType. | Rely on implicit server parsing or defaults. | dataField, controlsRequestType |
Accessibility
- Provide stable automation and a11y selectors with
dataTestIdandidfor targeting and verification. - Optionally support comprehension via guided tours using
enableAsHotspotwith localizedguidedTourHotSpotTitleandguidedTourHotSpotDescription(supplemental only; not for critical info). - Reduce accidental data loss during long authoring by enabling
saveInLocalStorage, which can benefit users who need more time to complete inputs. - Keep labels short and specific through
labelTranslations; avoid relying on placeholder-style guidance. - Increase
rowswhen long content is expected to minimize excessive scrolling.
