Skip to content

docs(responsive): add a Responsive guideline and name what declares the container - #1191

Merged
bert-e merged 1 commit into
development/1.0from
improvement/CUI-icononly-container-discoverability
Aug 28, 2026
Merged

docs(responsive): add a Responsive guideline and name what declares the container#1191
bert-e merged 1 commit into
development/1.0from
improvement/CUI-icononly-container-discoverability

Conversation

@JeanMarcMilletScality

@JeanMarcMilletScality JeanMarcMilletScality commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

TL;DR — Documents core-ui's responsive capabilities in one guideline page: which three props declare the responsive CSS container, and which components query it — starting with Button's iconOnly.

Context / Why

Several components adapt to the width they are given by querying a container named responsive, and nothing declares that container by default. A component with no declaring ancestor is inert and silent: it renders at full size and nothing reports a problem.

That made it a documentation gap on both sides. The iconOnly prop said it "needs a responsive container ancestor" without naming a single way to get one, and none of the three components that declare the container mentioned that they do — so there was no way in from either end.

🧩 Approach

A Guidelines/Responsive page in two parts, shaped so it grows as more components become responsive:

Part 1 — declaring the container. The three props that do it, why it belongs on the box whose width should actually drive the reaction rather than as high up as possible (the query resolves against the nearest declaring ancestor, so a container on the page wrapper is the viewport again under another name), and why containment needs a width from the parent.

Component Prop
Form responsive
Box container
TwoPanelLayout container="left | right | both"

Part 2 — one section per responsive component, starting with Button's iconOnly and Form's responsive. Adding the next component means adding a section, not restructuring the page.

The prop docs now point both ways: iconOnly names the three establishers, and each establisher names what queries the container it declares.

📷 Screenshots

The new page:

responsive-containers-guideline-page

The iconOnly section's demo, which the default width cannot show — both frames narrowed to the same 300px. The top one declares the container, so its buttons collapse; the bottom one does not, so they never will:

container-vs-no-container-at-300px

🔍 Review focus

  • Minorstories/guideline/responsive.mdx — content accuracy, and whether the two-part split is the right shape to hang the next responsive component off. Everything else here is JSDoc.
  • Minorstories/form.guideline.mdx — the "Current limitation" paragraph still claimed only Input honors the fluid width. Select opted in with CUI-36 and the prop's own JSDoc already said so, so the two contradicted each other; corrected because the new page would inherit the contradiction.

🧪 How to test

  1. npm run storybook, open Guidelines → Responsive.
  2. Drag the right edge of each dashed frame in the iconOnly section below 360px. Only the top frame — the one wrapped in <Box container> — collapses its buttons to icons; the bottom frame keeps its labels at any width.
  3. Hover a collapsed button: the label is still the accessible name and still appears as a tooltip.
  4. Check the cross-links resolve — Form → Guideline points here, and this page points back.
What changed

No behavioural change: Buttonv2.component.tsx, Box.ts, Form.component.tsx and layout/v2/panels.tsx are JSDoc only.

stories/guideline/responsive.mdx is the new page, following the existing Guidelines/* pattern, backed by responsive.stories.tsx — tagged ['!dev', '!autodocs'] like selection-controls-overview.stories.tsx so its stories render inside the page rather than as separate sidebar entries.

@bert-e

bert-e commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

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.
/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

bert-e commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

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:

…he container

Several components adapt to the width they are given by querying a CSS container
named `responsive`, and nothing declares that container by default. A component
with no declaring ancestor is inert and silent — it renders at full size and
nothing reports a problem — so the gap was purely one of documentation: the
`iconOnly` prop said it "needs a `responsive` container ancestor" without naming
a single way to get one, and none of the three components that declare it said
that they do.

Adds a `Guidelines/Responsive` page in two parts, so it can grow as more
components become responsive: first how to declare the container — which three
props do it, why it belongs on the box whose width should drive the reaction
rather than as high up as possible, and why containment needs a width from the
parent — then a section per responsive component, starting with `Button`'s
`iconOnly` and `Form`'s `responsive`. The `iconOnly` section carries a live
side-by-side of the same two buttons with and without a declaring ancestor.

The prop docs now point both ways: `iconOnly` names the three establishers, and
each establisher names what queries the container it declares.

Also corrects the form guideline's fluid-field limitation, which still said only
`Input` honors it — `Select` has since opted in.
@JeanMarcMilletScality
JeanMarcMilletScality force-pushed the improvement/CUI-icononly-container-discoverability branch from e1576cc to 7171d3e Compare August 27, 2026 16:39
@JeanMarcMilletScality JeanMarcMilletScality changed the title improvement(button): warn when iconOnly={number} has no responsive container docs(responsive): add a Responsive guideline and name what declares the container Aug 27, 2026
Comment thread stories/guideline/responsive.mdx
@JeanMarcMilletScality
JeanMarcMilletScality marked this pull request as ready for review August 27, 2026 16:47
@JeanMarcMilletScality

Copy link
Copy Markdown
Contributor Author

/approve

@bert-e

bert-e commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

I have successfully merged the changeset of this pull request
into targetted development branches:

  • ✔️ development/1.0

Please check the status of the associated issue None.

Goodbye jeanmarcmilletscality.

The following options are set: approve

@bert-e
bert-e merged commit 7171d3e into development/1.0 Aug 28, 2026
7 of 8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants