cgalo5758
36e58cd821
Move sub-surfaces into their sections: billing views get a pill row, org types a header button. Replace inline IdP handoff copy with an SVG icon and tooltip, add help icons to dense form rows, and delete the registry-driven sidebar nav plumbing. Update specs and tests.
4.6 KiB
form-conventions Specification
Purpose
Cross-cutting presentation contract for forms, badges, and table cells across operator and member surfaces (UX-15): one convention per question, everywhere.
Requirements
Requirement: Required is the default and only optional is marked
Forms SHALL treat required as the default: only optional fields carry an "(optional)" suffix on their label, required fields carry no marker, and a form containing any optional field SHALL state once, near its top, "All fields are required unless marked optional." No surface SHALL use a required-asterisk convention or leave its requiredness convention unstated while mixing required and optional fields.
Scenario: A mixed form marks only the optional fields
- WHEN a user views a form with both required and optional fields
- THEN optional field labels end in "(optional)"
- AND required field labels carry no requiredness marker
- AND the form states the default once
Requirement: Badge colors carry stated, consistent semantics
Status badge colors SHALL carry one meaning each across the application: the success (green) treatment only for live/delivering/healthy states, the warning (amber) treatment only for states needing operator attention, and the neutral treatment for informational states. Color SHALL never be the only carrier of meaning: every badge's text states the state. A badge SHALL NOT reuse the success or warning treatment for a state outside its meaning (e.g. an amber "Yes" beside amber warnings, or a green state that is not live).
Scenario: Green means live everywhere
- WHEN a user sees a green badge anywhere in the application
- THEN the badged state is a live/delivering/healthy state
- AND the badge text names the state
Requirement: Placeholders are format examples only
Input placeholders SHALL be used only to show a format example of the expected value. State text (such as "no value") and instructions SHALL NOT be carried in placeholders; state renders as help text or the empty-value marker, instructions as labels or help text.
Scenario: No state text in placeholders
- WHEN a user views a form input showing that no value is set
- THEN that fact is conveyed outside the placeholder
- AND any placeholder present shows only a format example
Requirement: Create and edit forms agree or disclose their difference
The create and edit forms for one object SHALL expose the same field set, or every difference SHALL be disclosed at the field where it occurs — as one short visible line in a stacked form, or in the field's help-icon tooltip in a dense row (see "Dense form rows keep explanations behind a help icon") — stating why the field exists only here. A field SHALL NOT exist on one form and be silently absent, undefined, from the other.
Scenario: A create-only field explains itself
- WHEN a user views a form field that exists on create but not on edit (or the reverse)
- THEN the form states, at the field (visibly or in its help-icon tooltip), why it is only settable here
Requirement: Dense form rows keep explanations behind a help icon
A compact multi-column form row SHALL NOT hold visible explanatory copy beyond field labels: a field in such a row whose meaning needs explaining carries a small monochrome question-mark help icon after its label, with the full explanation in the icon's hover tooltip (maintainer decision 2026-08-23: don't overwhelm people; the help-icon tooltip is the established pattern for this). The icon follows the same rules as the external-destination marker (chrome-conventions): an inline SVG inheriting the text color, never an emoji or emoji-presentable character, and never separable from its label by line wrapping. A short single-line hint under a field in a stacked (vertical) form remains allowed; multi-sentence explanations prefer the help icon there too.
Scenario: A dense row explains through the icon, not visible copy
- WHEN a user views a compact multi-column form row containing a field that needs explanation
- THEN the explanation is available from a question-mark help icon's tooltip at that field
- AND no multi-line explanatory copy renders inside the row
Requirement: One empty-cell marker
Tables SHALL render an absent value as the single em-dash marker "—" (the exempt unavailable-value marker), identically across surfaces; per-table variants ("n/a", blank, "none") SHALL NOT be used for absent values.
Scenario: Absent values render identically
- WHEN a user views tables on different surfaces with absent values
- THEN every absent value renders as "—"