fix(IconHelp): stable sizing and alignment, add stories and guideline by JeanMarcMilletScality · Pull Request #1115 · scality/core-ui

JeanMarcMilletScality · 2026-05-22T09:52:01Z

Summary

Fix IconHelp size and vertical-alignment drift introduced when the icon was reworked into a focusable <button> (was inheriting parent font, line-height and using vertical-align: text-bottom, making the glyph float and rescale per consumer).
Pin the help button to a fixed 1rem × 1rem hit area centered with inline-flex, so the icon stays the same recognizable "info" affordance everywhere and sits center inside the focus outline. Use FontAwesome's -0.125em baseline offset for stable inline alignment with surrounding text.
Add focused usage stories under Components/IconHelp (Simple, Tooltip placement, Explaining values) and a Guideline mdx attached to the same group (same pattern as InfoMessage).

Test plan

Open Storybook → Components/IconHelp → check Simple, Tooltip placement, Explaining values render correctly.
Check the Guideline tab on the same component renders the embedded canvases.
Verify existing consumers (Templates/Form, Components/TextBadge, modal stories) still show the help icon aligned with adjacent text and not oversized in headings.
Focus the icon with Tab — focus outline wraps the icon tightly with the icon centered.

🤖 Generated with Claude Code

Pin the help button to a fixed 1rem hit area centered with inline-flex, keep the icon size constant across consumers, and use FontAwesome's -0.125em baseline offset for consistent inline alignment. Add focused usage stories (Simple, Tooltip placement, Explaining values) and a component-level Guideline mdx. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bert-e · 2026-05-22T09:52:04Z

Hello jeanmarcmilletscality,

My role is to assist you with the merge of this
pull request. Please type @bert-e help to get information
on this process, or consult the user documentation.

Available options

name	description	privileged	authored
`/after_pull_request`	Wait for the given pull request id to be merged before continuing with the current one.
`/bypass_author_approval`	Bypass the pull request author's approval	⭐
`/bypass_build_status`	Bypass the build and test status	⭐
`/bypass_commit_size`	Bypass the check on the size of the changeset `TBA`	⭐
`/bypass_incompatible_branch`	Bypass the check on the source branch prefix	⭐
`/bypass_jira_check`	Bypass the Jira issue check	⭐
`/bypass_peer_approval`	Bypass the pull request peers' approval	⭐
`/bypass_leader_approval`	Bypass the pull request leaders' approval	⭐
`/approve`	Instruct Bert-E that the author has approved the pull request.		✍️
`/create_pull_requests`	Allow the creation of integration pull requests.
`/create_integration_branches`	Allow the creation of integration branches.
`/no_octopus`	Prevent Wall-E from doing any octopus merge and use multiple consecutive merge instead
`/unanimity`	Change review acceptance criteria from `one reviewer at least` to `all reviewers`
`/wait`	Instruct Bert-E not to run until further notice.

Available commands

name	description	privileged
`/help`	Print Bert-E's manual in the pull request.
`/status`	Print Bert-E's current status in the pull request `TBA`
`/clear`	Remove all comments from Bert-E from the history `TBA`
`/retry`	Re-start a fresh build `TBA`
`/build`	Re-start a fresh build `TBA`
`/force_reset`	Delete integration branches & pull requests, and restart merge process from the beginning.
`/reset`	Try to remove integration branches unless there are commits on them which do not appear on the source branch.

Status report is not available.

bert-e · 2026-05-22T09:52:10Z

Waiting for approval

The following approvals are needed before I can proceed with the merge:

the author
one peer

Peer approvals must include at least 1 approval from the following list:

Cuervino · 2026-05-22T16:15:49Z

IconHelp is a small info icon that reveals a tooltip on hover or focus. Use it to provide secondary information without overloading the interface.

The second phrase is more in the "when to use" part.

Cuervino

Design review of the guideline and stories. The component fix itself is correct.

Seven points below: two are blocking (intro structure, validation rule in tooltip), five are improvements to the guideline coverage.

Cuervino · 2026-05-22T16:30:10Z

+
+# IconHelp
+
+`IconHelp` is a small info icon that reveals a tooltip on hover or focus. Use it to provide secondary information without overloading the interface.


The intro should be a single descriptive sentence, per the guideline writing convention in CLAUDE.md. The second sentence ("Use it to provide secondary information without overloading the interface") is a usage recommendation and belongs in "When to use it".

Suggested intro: `IconHelp` is an inline icon button that reveals a tooltip on hover or focus.

Applied as suggested in e009220. Intro is now IconHelp` is an inline icon button that reveals a tooltip on hover or focus. and the usage recommendation moved into the opening line of "When to use it".

Cuervino · 2026-05-22T16:30:10Z

+## When not to use it
+
+- **Don't use it as the only way to convey critical information.** A tooltip is hidden by default — anything required to complete a task must remain visible (helper text, error message, inline description).
+- **Don't stack multiple `IconHelp` next to each other.** If a section needs that much explanation, write a short paragraph or link to documentation instead.


Two parts of this bullet need clarification.

"Write a short paragraph" — where? Name the concrete pattern: a description paragraph below the section heading, an InfoMessage above the content area, etc. Without a target location, this advice is not actionable.

"Link to documentation" has the same gap: how is the link surfaced? Inline in the layout? As an InfoMessage footer? This needs a concrete pattern or should be removed.

Rewrote the bullet in e009220 to name concrete patterns: a description paragraph under the section heading, or an InfoMessage above the content area (with a link to the dedicated doc page when a longer explanation is needed). "Never long text in a tooltip" is now explicit.

Cuervino · 2026-05-22T16:30:10Z

+
+## Explaining values in a key/value list
+
+In summary or detail pages, attach an `IconHelp` only to the values whose meaning is not obvious. Leave plain values (a name, an email, an ID) without one.


IconHelp can also go on the key side when the label itself is the opaque term: "Object lock", "RPO", "Standard" (as a storage class). The current phrasing ("attach... only to the values") is too restrictive and will mislead consumers.

Suggest updating this sentence and adding a labelHelp prop to KeyValueRow in the story to show key-side placement alongside value-side placement.

Done in e009220. The section now spells out both sides — key-side when the label itself is opaque (Object lock, RPO, Replication policy) and value-side when the value is the unclear term. The story's KeyValueRow got a new labelHelp prop and Object lock + RPO are demonstrated key-side.

Cuervino · 2026-05-22T16:30:10Z

+
+## In a form
+
+In forms, `FormGroup` already exposes a `labelHelpTooltip` prop that renders an `IconHelp` next to the field label — you don't need to add one manually. Use it to clarify:


The section is missing the key decision rule: use helper text when the information is needed to complete the task, because it is always visible. IconHelp in a form is appropriate only for conceptual context — what a field represents, why it matters — not for constraints the user must act on to fill the form correctly.

Without this distinction, consumers have no clear signal for when to reach for IconHelp versus FormGroup.helperText.

Added in e009220. "In a form" now opens with the decision rule: helper text (via FormGroup's help prop, always visible) for task-completion info; IconHelp (labelHelpTooltip) only for conceptual context (what the field represents, why it matters).

Cuervino · 2026-05-22T16:30:10Z

+In forms, `FormGroup` already exposes a `labelHelpTooltip` prop that renders an `IconHelp` next to the field label — you don't need to add one manually. Use it to clarify:
+
+- **What the field represents** — e.g. _"The name other users will see on your profile."_
+- **The accepted format or validation rule** — e.g. _"Must be 3–32 characters, letters and digits only."_


Remove this bullet. Format and validation rules ("Must be 3–32 characters, letters and digits only") are needed to complete the task, so they belong in always-visible helper text, not a tooltip. This contradicts the rule two bullets above: "don't use IconHelp as the only way to convey critical information".

Even if we are not super strict in the UI, it should be strict in the design system.

Cuervino · 2026-05-22T16:30:10Z

+  name: 'Simple',
+  render: () => (
+    <Text>
+      Replication policy{' '}


The {' '} before <IconHelp> is the correct spacing convention — but it is not documented anywhere. Add a note in the guideline: one space between the adjacent text and the icon, managed by the parent, not built into the component.

This is debatable, I don't know if it's a spacing component or if it's managed with a space.

- Rewrite intro as one descriptive sentence; move usage line into "When to use it" (Toggle/Checkbox/Radio convention). - Spell out concrete alternatives to stacked IconHelps (description paragraph or InfoMessage, never long text in a tooltip). - Clarify that IconHelp can sit on either the key or the value side of a key/value pair; add Object lock + RPO key-side examples. - Open "In a form" with the helper-text vs IconHelp decision rule (helper text via FormGroup.help for task-completion info, IconHelp only for conceptual context). Drop the validation-rule bullet. - Replace literal {' '} spacing with Stack horizontal/gap r4 in all stories to match the codebase convention (see ChartHeader and FormSection title usages). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

bert-e · 2026-05-26T16:16:35Z

Waiting for approval

The following approvals are needed before I can proceed with the merge:

the author
one peer

Peer approvals must include at least 1 approval from the following list:

Cuervino

LGTM

ChengYanJin approved these changes May 22, 2026

View reviewed changes

Cuervino reviewed May 22, 2026

View reviewed changes

Cuervino approved these changes May 27, 2026

View reviewed changes


		# IconHelp

		`IconHelp` is a small info icon that reveals a tooltip on hover or focus. Use it to provide secondary information without overloading the interface.


		## Explaining values in a key/value list

		In summary or detail pages, attach an `IconHelp` only to the values whose meaning is not obvious. Leave plain values (a name, an email, an ID) without one.


		## In a form

		In forms, `FormGroup` already exposes a `labelHelpTooltip` prop that renders an `IconHelp` next to the field label — you don't need to add one manually. Use it to clarify:

Conversation

JeanMarcMilletScality commented May 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

bert-e commented May 22, 2026

Hello jeanmarcmilletscality,

Uh oh!

bert-e commented May 22, 2026

Waiting for approval

Uh oh!

Cuervino commented May 22, 2026

Uh oh!

Cuervino left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bert-e commented May 26, 2026

Waiting for approval

Uh oh!

Cuervino left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JeanMarcMilletScality commented May 22, 2026 •

edited

Loading