Help ladder, callouts, disclosure and switches #620

New issue

Closed

opened 2026-10-25 18:51:06 +01:00 by simon · 0 comments

simon commented

2026-10-25 18:51:06 +01:00

Owner

Split from #618

Motivation

Help appears in about nine visual styles, from solid alerts below AA contrast to palette boxes and explanations below tables. Some settings save immediately through checkboxes next to fields that wait for “Save”. DESIGN_GUIDELINES §17 (help ladder), §18 (form controls) and §5.7 (labels) define the target. #618 delivered <.section>, <.danger_zone>, the detail layout, the Save rule and the width rule; this issue builds on them.

Visible improvement

Hints are readable and look the same everywhere; it is obvious when a change takes effect.

Scope (ordered steps, `just ci-dev` green after each)

<.callout>, <.collapsible>, help on <.input>; migrate hints by the help ladder:
- fee settings: explanations into section descriptions and field help, examples into a collapsible;
- user form: password hint and member-linking hints as callouts / field help;
- import: instructions into a collapsed “How the import works”, two sections (“Prepare file”, “Upload and check”); keep minimal, the dialog-guided import will replace the page;
- fees tab empty state: no longer an alert;
- the ENV status callout #540 added to the global settings groups becomes a <.callout> kind; remove the interim component;
- example values move out of placeholders into field help below the field, with example.com hosts (SMTP, Vereinfacht API/app URL).
- UI guard: add a zero-tolerance pattern for solid alert-* used as hints (toasts keep alert inside the flash component).
<.input type="toggle"> with a hook that resets checked when the handler pushes the stored value after an error (push_event, DESIGN_GUIDELINES §8.1); handlers take the target state from the event instead of flipping the stored value. Global settings checkboxes that save immediately become switches (toast + rollback; the flash #540 adds to "Allow direct registration" becomes this toast). The switch keeps #540's two states: set via environment variable (OIDC_ONLY: shown, not toggleable, lock line) and not switchable until OIDC is fully configured. The “Change password” checkbox becomes a disclosure through <.collapsible>.
Checkbox size and color fixed by the component (fee settings uses a raw checkbox today).
Labels on touched forms per §5.7 (“Save”, “New ‹entity›”).
Showcase sections: callout (all kinds), collapsible, input with help, switch.

Acceptance criteria

DESIGN_GUIDELINES §17, §18.1, §18.2 met on every migrated page; no solid alert-* for hints (guard at zero).
Before/after screenshots: fee settings, import, user form, global settings; light and dark; global settings also in ENV mode (one group complete, one incomplete, ASSOCIATION_NAME set), German locale.
The ENV callout's warning text reaches 4.5:1 in the dark theme too.
Help texts linked via aria-describedby; callouts reach 4.5:1 (text) and 3:1 (icon); switches have role="switch" and a toast on change; a ui-tagged browser test shows the stored value again after a failed save (Firefox and Chromium).
UX non-regression matrix for the switch flows (as in #615/#618).
Showcase sections added.

Dependencies

#618 merged (<.section>, Save rule, detail layout).
U9 builds on the switch input.

Found in the #618 showcase check (2026-10-25, `main` @ `baa69474`)

A disabled checkbox renders at opacity: 0.2 (daisyUI default): border and mark are nearly invisible in both themes, so the user cannot tell that the control exists or which state it holds. WCAG exempts disabled controls from contrast, but step 3 (checkbox fixed by the component) should give disabled checkboxes and switches a legible disabled look (e.g. the ENV-locked look #540 built), measured in both themes. Screenshot: .pipeline/clarify/mitgliederverwaltung-618-showcase/sc-form-*.png.
Raw checkbox/switch labels in the showcase (text-sm) are larger than <.input type="checkbox"> labels; the switch input of step 2 should settle one label size.

Split from #618 ## Motivation Help appears in about nine visual styles, from solid alerts below AA contrast to palette boxes and explanations below tables. Some settings save immediately through checkboxes next to fields that wait for “Save”. DESIGN_GUIDELINES §17 (help ladder), §18 (form controls) and §5.7 (labels) define the target. #618 delivered `<.section>`, `<.danger_zone>`, the detail layout, the Save rule and the width rule; this issue builds on them. ## Visible improvement Hints are readable and look the same everywhere; it is obvious when a change takes effect. ## Scope (ordered steps, `just ci-dev` green after each) 1. `<.callout>`, `<.collapsible>`, `help` on `<.input>`; migrate hints by the help ladder: - fee settings: explanations into section descriptions and field help, examples into a collapsible; - user form: password hint and member-linking hints as callouts / field help; - import: instructions into a collapsed “How the import works”, two sections (“Prepare file”, “Upload and check”); keep minimal, the dialog-guided import will replace the page; - fees tab empty state: no longer an alert; - the ENV status callout #540 added to the global settings groups becomes a `<.callout>` kind; remove the interim component; - example values move out of placeholders into field help below the field, with `example.com` hosts (SMTP, Vereinfacht API/app URL). - UI guard: add a zero-tolerance pattern for solid `alert-*` used as hints (toasts keep `alert` inside the flash component). 2. `<.input type="toggle">` with a hook that resets `checked` when the handler pushes the stored value after an error (`push_event`, DESIGN_GUIDELINES §8.1); handlers take the target state from the event instead of flipping the stored value. Global settings checkboxes that save immediately become switches (toast + rollback; the flash #540 adds to "Allow direct registration" becomes this toast). The switch keeps #540's two states: set via environment variable (`OIDC_ONLY`: shown, not toggleable, lock line) and not switchable until OIDC is fully configured. The “Change password” checkbox becomes a disclosure through `<.collapsible>`. 3. Checkbox size and color fixed by the component (fee settings uses a raw checkbox today). 4. Labels on touched forms per §5.7 (“Save”, “New ‹entity›”). 5. Showcase sections: callout (all kinds), collapsible, input with help, switch. ## Acceptance criteria - DESIGN_GUIDELINES §17, §18.1, §18.2 met on every migrated page; no solid `alert-*` for hints (guard at zero). - Before/after screenshots: fee settings, import, user form, global settings; light and dark; global settings also in ENV mode (one group complete, one incomplete, `ASSOCIATION_NAME` set), German locale. - The ENV callout's warning text reaches 4.5:1 in the dark theme too. - Help texts linked via `aria-describedby`; callouts reach 4.5:1 (text) and 3:1 (icon); switches have `role="switch"` and a toast on change; a `ui`-tagged browser test shows the stored value again after a failed save (Firefox and Chromium). - UX non-regression matrix for the switch flows (as in #615/#618). - Showcase sections added. ## Dependencies - #618 merged (`<.section>`, Save rule, detail layout). - U9 builds on the switch input. ## Found in the #618 showcase check (2026-10-25, `main` @ baa69474) - A disabled checkbox renders at `opacity: 0.2` (daisyUI default): border and mark are nearly invisible in both themes, so the user cannot tell that the control exists or which state it holds. WCAG exempts disabled controls from contrast, but step 3 (checkbox fixed by the component) should give disabled checkboxes and switches a legible disabled look (e.g. the ENV-locked look #540 built), measured in both themes. Screenshot: `.pipeline/clarify/mitgliederverwaltung-618-showcase/sc-form-*.png`. - Raw checkbox/switch labels in the showcase (`text-sm`) are larger than `<.input type="checkbox">` labels; the switch input of step 2 should settle one label size.

simon added this to the Minor UI and Feature Polishing | TI I milestone

2026-10-25 18:51:06 +01:00

simon added this to the Sprint 18: Oktober 2026 project

2026-10-25 18:51:06 +01:00

simon referenced this issue from a pull request that will close it,

2026-10-26 20:02:12 +01:00

Give forms field help, callouts, collapsible instructions and switches that save immediately closes #620 #623

simon closed this issue

2026-10-26 20:13:42 +01:00

simon referenced this issue from a commit

2026-10-26 20:13:43 +01:00

Merge pull request 'Give forms field help, callouts, collapsible instructions and switches that save immediately closes #620' (#623) from issue/mitgliederverwaltung-620 into main