Docs cleanup needed

[sgilberg]

Hi Bootstrap team, I've taken a spin through the v6 docs in progress, and I'm excited about a number of the updates and new features (though admittedly a bit daunted by the migration ahead). I discovered a number of UI issues in the docs, many of which are probably just a matter of needing to update the example code to match the new functionality, but it's possible some indicate underlying issues in components. I had started to try to fix a couple via a PR but quickly realized I wasn't familiar enough with the system and some things (like breakpoints) will need a broader refactor.

Content

• Prose
  • Minor copy edit under "How it works": "designed for long form content that originates from source Markdown files" - (fixed by Docs: fix 'originals' → 'originates' typo in Prose page #42338)

Forms

• Chip Input
  • Overview states these are statically sized, but there is a Sizing section below that one (where, despite labeling, all sizes appear the same). Should this section be removed? (fixed by v6: Form cleanup & new --radius-* tokens/classes #42356)
  • Chip used in disabled input can't be dismissed, but it still highlights and changes the cursor to pointer on hover, which seems a little misleading.
• OTP input
  • Styling on connected inputs looks a little odd. Is this intended to only have rounded corners on the left and right ends of the group (similar to a button group)?

Components

• Feedback
  • Alert
    • In Live Example section, nothing happens when "Show live alert" is pressed (see [v6] "Show live" buttons don't work for Alert and Toast #42340)
  • Progress
    • Spacing is needed between progress bars in all examples where they are stacked (especially important when showing difference between 1px and 20px height). I see that the v5 docs achieve this via sass adding a 1rem top margin to .bd-example > .progress + .progress and I think the same could be done here. (fixed by Docs: add gap to Progress examples #42344)
• Overlays
  • Dialog
    • Overlays inside Dialogs example has a Popover that sticks when you open it, and "Show toast" doesn't appear to do anything (see [v6] "Show live" buttons don't work for Alert and Toast #42340). These might be connected to broader issues with these overlays (see below).
    • Slide down and slide up examples seem to be switched? At least they appear to me to be doing the opposite direction
    • Overflow scroll example doesn't scroll as described
    • Swapping dialogs says "Notice the backdrop stays visible - no flash!" but I'm seeing a flash when navigating from one to the next
  • Drawer
    • Buttons in Footer appear to overlap the bottom edge of the drawer Fixed in v6-dev
  • Popover
    • Example popovers can't be dismissed - tried clicking in, around, on the toggle button (see [v6] Popover can't be dismissed #42339)
  • Toast
    • Example not working - "show live toast" does nothing (see [v6] "Show live" buttons don't work for Alert and Toast #42340)
    • Also the preview boxes of most of the examples on this page appear to be blank. Unsure if this was an issue before? Seems fixed.
• Navigation
  • Tabs
    • Vertical pills styling feels a little off. Would expect the active pill to be neatly nested within the grey of the larger nav as it is in the horizontal version. Here the full list seems to have a larger border radius
  • Nav overflow
    • Overflow functionality isn't working on first example, or on "Keep items visible" or "With disabled items" examples. Seems like the common denominator might be nav-pills (vs nav-tabs or nav-underline which are working).
    • For "In a navbar" example, it works when resizing down, but not resizing back up.
• Layout
  • Card Fixed issues in v6: Card updates, use var(--spacer) over $spacer more #42354.
    • Examples of cards with centered text still have button aligning left ("header and footer" example, and "Navigation" examples)
    • Cards in "Theme variants" section appear very narrow, hard to read the text in them
    • Card layout -> Masonry section references v4 vs v5, can this section be removed in v6 docs? Or do we want to keep it but update the reference?
  • List group
    • Horizontal responsive variant classes need to be updated to prefix-style e.g. sm:list-group-horizontal etc. (This was the one I tried to fix but quickly discovered that the breakpoints in the docs likely need a larger refactor to adopt the new prefix style. There are a number of similarly affected spots when I search the docs code, e.g. responsive tables) (tackled in Docs: use correctly breakpoints as prefixes for utility classes, and docs content #42347)
• Interactions
  • Accordion
    • First example, Accordion Item #1 content says "It is shown by default because the open attribute is present", but it's closed by default. I notice the code below it is missing the open attribute. (fixed by Docs: add missing open attribute to first Accordion example #42345)

Helpers

• Focus Ring
  • Clicking focus ring buttons does nothing. Only shows when tabbing via keyboard. (see [v6] Focus ring doesn't appear when clicked #42342)
  • All focus rings look the same (blue), despite different color descriptions. (see [v6] Focus ring always has the primary color #42343)

[julien-deramond]

Thanks a lot for your review, @sgilberg. A few months ago, @mdo and I started a private document to track issues ahead of the v6 rollout. I can recognize several of them in your notes, and a few seem new, so this is really helpful.

Thanks again for taking the time to share this. I’ll sync with @mdo to decide whether we should start opening individual issues or discussions so we can track everything more precisely and transparently.

[sgilberg]

@julien-deramond I appreciate your response! It's quite a complex project, so I understand that the question of how best to track such issues may not be super straightforward. I do think, to the extent possible, if the docs examples could be kept up to date with current v6 functionality, that would facilitate better quality feedback from folks like myself who are interested in its release, and limit the number of false positive issue reports. Let me know if I can be of further help in this endeavor.

[sgilberg]

Hi @julien-deramond I'm amazed at how much of this has been cleaned up so fast! I'm seeing that even the items not-yet-crossed-out above are mostly already fixed. Amazing.

FYI, a couple things I still see in play:

• For OTP connected inputs, it looks like some of the input groups are still squared off on the right end, while others are appropriately rounded (not immediately clear to me where the discrepancy lies).
• For the Focus Ring, I see the different color rings now but I'm still not seeing it show on click, even though that issue has been closed. I see that the instructions now say "Tab into..." rather than "Click directly on..." so this might be intentional, but this is a change from how focus rings worked in Bootstrap 5 and I'm a little curious why.

[mdo]

• For the Focus Ring, I see the different color rings now but I'm still not seeing it show on click, even though that issue has been closed. I see that the instructions now say "Tab into..." rather than "Click directly on..." so this might be intentional, but this is a change from how focus rings worked in Bootstrap 5 and I'm a little curious why.

This is because we use :focus-visible vs :focus, where :focus-visible is only showing for keyboard users basically.

[sgilberg]

FYI @julien-deramond @mdo for the OTP connected inputs, I figured out why I was still seeing some of the inputs squared off on the right end. It's not inherent to the docs or the styling, but I have a password manager extension which adds a hidden <span> element after the last input in the group, making the input that would be the :last-child no longer the last child. I'm not sure how often this use case is encountered, or how to mitigate it exactly, but I'm mentioning it in case it helps.