fix(Storybook): update documentation links by paul-balchin-ibm · Pull Request #6989 · carbon-design-system/ibm-products

paul-balchin-ibm · 2025-02-26T17:07:48Z

Review and fix 404 links where possible.

What did you change?

38 various Storybook pages: .mdx, .docs-pages.js, and .stories.js.

Fixed once we figured out the difference between .mdx, .docs-page.js, and the various ways of using <StoryDocsPage /> ~~Note: some changes would not refresh or rebuild for no apparent reason: ActionBar, NotificationsPanel, Saving, TagSet.~~

How did you test and verify your work?

Storybook

netlify · 2025-02-26T17:08:08Z

✅ Deploy Preview for ibm-products-web-components ready!

Name	Link
🔨 Latest commit	`f732f30`
🔍 Latest deploy log	https://app.netlify.com/sites/ibm-products-web-components/deploys/67d058bdf26e9600086827e1
😎 Deploy Preview	https://deploy-preview-6989--ibm-products-web-components.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify · 2025-02-26T17:09:01Z

✅ Deploy Preview for carbon-for-ibm-products ready!

Name	Link
🔨 Latest commit	`f732f30`
🔍 Latest deploy log	https://app.netlify.com/sites/carbon-for-ibm-products/deploys/67d058bdfbf5d7000899ef5f
😎 Deploy Preview	https://deploy-preview-6989--carbon-for-ibm-products.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

codecov · 2025-02-26T17:12:35Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 81.73%. Comparing base (ccb1295) to head (f732f30).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6989      +/-   ##
==========================================
- Coverage   81.74%   81.73%   -0.01%     
==========================================
  Files         399      399              
  Lines       12970    12970              
  Branches     4269     4269              
==========================================
- Hits        10602    10601       -1     
- Misses       2368     2369       +1

Components	Coverage Δ
ibm-products	`∅ <ø> (∅)`
ibm-products-web-components	`∅ <ø> (∅)`

🚀 New features to boost your workflow:

❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

elycheea · 2025-02-26T19:15:27Z

        },
        {
-          href: 'https://react.carbondesignsystem.com/?path=/docs/modal--default',
+          href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',


Suggested change

href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',

href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal',

While this updates correctly, I think removing --overview is actually safer in case there are future changes to their story organization.

Ah. I didn't know that was a thing.

elycheea · 2025-02-26T19:15:54Z

+        label: 'Carbon Modal usage guidelines',
+      },
+      {
+        href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',


Suggested change

href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',

href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal',

elycheea · 2025-02-26T19:20:06Z

-          href: 'https://www.carbondesignsystem.com/guidelines/motion/overview/',
-          label: 'Carbon motion guidelines',
+          href: 'https://pages.github.ibm.com/carbon/ibm-products/patterns/cascade/',
+          label: 'Cascade overview',


Interesting that we’re calling it “overview” instead of usage guidelines. Is it because the Cascade doesn’t go to a Usage tab? But
I would keep with the same naming for now but open this as a discussion in #6959.

Suggested change

label: 'Cascade overview',

label: 'Cascade usage guidelines',

That's the problem with specificity.

/ibm-products/components/about-modal/usage/ → "AboutModal usage guidelines"

Is part of the "Component" navigation.

"/usage/" in the URL.

"Usage" tab name.

"guidelines" is a word used in the doc, but not specifically about AboutModal.

ibm-products/patterns/cascade/

Is part of the "Patterns" navigation.

No mention of "/usage/" in the URL.

No "Usage" tab. (No tabs at all)

No mention of "guidelines" anywhere.

"Overview" is the first section. (But is one of three with the same heading level)

ibm-products/guidelines/accessibility/overview/

"Guidelines" is a specific section in the navigation. (But it's not directly linkable)

While I understand your point, for this current issue, I’d avoid introducing new naming until we have a larger discussion on the IA via #6959.

For most of our patterns, you’ll notice that the majority of our “patterns” do still have a Usage and Code tab, whether or not that’s correct. (You’ll see occasional ”Overviews” too.) While I’m not sure why Cascade and Notifications panel don’t currently have one, I would treat them the same until the larger docs issue.

elycheea · 2025-02-26T19:28:07Z

            },
            {
-              href: 'https://react.carbondesignsystem.com/?path=/docs/modal--default',
+              href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',


Suggested change

href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',

href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal',

elycheea · 2025-02-26T19:34:11Z


 # InterstitialScreenViewModule

+[InterstitialScreen overview](https://pages.github.ibm.com/carbon/ibm-products/components/onboarding/interstitial-screen/)


Suggested change

[InterstitialScreen overview](https://pages.github.ibm.com/carbon/ibm-products/components/onboarding/interstitial-screen/)

[InterstitialScreen usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/onboarding/interstitial-screen/)

elycheea · 2025-02-26T19:36:49Z

 # NotificationsPanel

-[CD&AI Notifications panel usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/patterns/notifications/usage/)
+[CD&AI Notifications panel usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/notification-panel/usage/)


Suggested change

[CD&AI Notifications panel usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/notification-panel/usage/)

[Notifications panel usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/notification-panel/usage/)

This one is actually coming up as a broken link in Storybook — although we updated the MDX, it looks like notifications panel URL actually comes from the Stories file where we have the <StoryDocsPage>.

I mentioned that in the description above. There are some .mdx files (not all) where changes can be saved, but are not being "built".

Ahh, I figured out the issue in NotificationsPanel —

export default { title: 'IBM Products/Components/Notifications panel/NotificationsPanel', component: NotificationsPanel, tags: ['autodocs'], parameters: { styles, layout: 'fullscreen', docs: { page: mdx, }, }, // ... }

Currently, docs are under argTypes. Might be the same issue for those other pages. 👀

Since the .mdx page was old, I replaced it with a docs-page.js in #6904.

elycheea · 2025-02-26T19:40:46Z

 # Saving

-[Usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/patterns/saving/usage/)
+[Saving usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/save/usage/)


This one doesn’t seem to have updated the URL in Storybook which already uses “Saving usage guidelines” — probably need to overwrite it.

Looks like the mdx is commented out in Saving.stories.jsx. Adding them back in should fix it. 👍

Replaced .mdx file with inline <StoryDocsPage ... />, same as .../CreateTearsheetNarrow.stories.jsx.

elycheea · 2025-02-26T19:41:34Z


 # ScrollGradient

+[Scrolling overview](https://pages.github.ibm.com/carbon/ibm-products/components/datagrid/scrolling/usage/)


Suggested change

[Scrolling overview](https://pages.github.ibm.com/carbon/ibm-products/components/datagrid/scrolling/usage/)

The scroll gradient doesn’t actually have any supporting guidelines.

elycheea · 2025-02-26T19:44:43Z

+|
+[Carbon Tag usage guidelines](https://carbondesignsystem.com/components/tag/usage/)
+|
+[Carbon Tag documentation](https://react.carbondesignsystem.com/?path=/docs/components-tag--overview)


Doesn’t look like these updates are applied since TagSet doesn’t use the MDX file at the moment. (I see it but it’s commented out.)

The import of the .mdx file was commented out in the .stories.js file.

If you and I were part of the "in crowd", we would have known that because the page property wasn't defined, then by default the Storybook setup was automatically injecting the following...

export default { page: () => ( <StoryDocsPage /> ), }

...which is why we didn't understand why our .mdx updates weren't being applied.

Whoever did the last update didn't clean up behind themselves, leaving us to deal with the mess.

…docs-links

Co-authored-by: elysia <elysia.hwang@gmail.com>

elycheea

I made one small fix since I realize that my last suggested change broke since StoryDocsPage was never imported in the TagSet stories before. 😲 TagSet docs should be back up now. 😅

…docs-links

fix: storybook documentation links

142994d

paul-balchin-ibm requested a review from a team as a code owner February 26, 2025 17:07

paul-balchin-ibm requested review from elycheea and makafsal and removed request for a team February 26, 2025 17:07

Merge branch 'main' into 6659_fix-storybook-docs-links

63aa5ba

paul-balchin-ibm marked this pull request as draft February 26, 2025 17:30

elycheea reviewed Feb 26, 2025

View reviewed changes

paul-balchin-ibm added 4 commits March 3, 2025 13:40

Merge remote-tracking branch 'upstream/main' into 6659_fix-storybook-…

2282f63

…docs-links

fix: update as per comments

a2cbca5

fix: updates as per comments

ee8f773

fix: update broken stories

6f0656c

elycheea reviewed Mar 4, 2025

View reviewed changes

Comment thread packages/ibm-products/src/components/TagSet/TagSet.stories.jsx Outdated

paul-balchin-ibm and others added 2 commits March 6, 2025 11:31

Update packages/ibm-products/src/components/TagSet/TagSet.stories.jsx

0d38082

Co-authored-by: elysia <elysia.hwang@gmail.com>

fix: import and TagSet guidelines URL

db37c27

elycheea previously approved these changes Mar 6, 2025

View reviewed changes

paul-balchin-ibm marked this pull request as ready for review March 7, 2025 18:06

elycheea added the status: one more review 👀 label Mar 7, 2025

paul-balchin-ibm mentioned this pull request Mar 10, 2025

Audit storybook docs for any 404 guideline links #6659

Closed

2 tasks

elycheea added the status: merge conflict ✋ label Mar 10, 2025

davidmenendez previously approved these changes Mar 10, 2025

View reviewed changes

Merge remote-tracking branch 'upstream/main' into 6659_fix-storybook-…

ecd3714

…docs-links

paul-balchin-ibm dismissed stale reviews from davidmenendez and elycheea via ecd3714 March 11, 2025 11:53

paul-balchin-ibm requested review from davidmenendez and elycheea March 11, 2025 12:19

devadula-nandan previously approved these changes Mar 11, 2025

View reviewed changes

devadula-nandan removed the status: merge conflict ✋ label Mar 11, 2025

fix: requested update

f732f30

paul-balchin-ibm dismissed devadula-nandan’s stale review via f732f30 March 11, 2025 15:37

elycheea approved these changes Mar 11, 2025

View reviewed changes

devadula-nandan approved these changes Mar 12, 2025

View reviewed changes

carbon-automation Bot removed the status: one more review 👀 label Mar 12, 2025

paul-balchin-ibm added this pull request to the merge queue Mar 12, 2025

Merged via the queue into carbon-design-system:main with commit 50f65d9 Mar 12, 2025

paul-balchin-ibm deleted the 6659_fix-storybook-docs-links branch March 12, 2025 12:20

	href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal--overview',
	href: 'https://react.carbondesignsystem.com/?path=/docs/components-modal',

	label: 'Cascade overview',
	label: 'Cascade usage guidelines',


		# InterstitialScreenViewModule

		[InterstitialScreen overview](https://pages.github.ibm.com/carbon/ibm-products/components/onboarding/interstitial-screen/)

	[InterstitialScreen overview](https://pages.github.ibm.com/carbon/ibm-products/components/onboarding/interstitial-screen/)
	[InterstitialScreen usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/onboarding/interstitial-screen/)

	[CD&AI Notifications panel usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/notification-panel/usage/)
	[Notifications panel usage guidelines](https://pages.github.ibm.com/carbon/ibm-products/components/notification-panel/usage/)


		# ScrollGradient

		[Scrolling overview](https://pages.github.ibm.com/carbon/ibm-products/components/datagrid/scrolling/usage/)

Conversation

paul-balchin-ibm commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What did you change?

How did you test and verify your work?

Uh oh!

netlify Bot commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for ibm-products-web-components ready!

Uh oh!

netlify Bot commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for carbon-for-ibm-products ready!

Uh oh!

codecov Bot commented Feb 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

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!

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!

paul-balchin-ibm Mar 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Uh oh!

elycheea left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

paul-balchin-ibm commented Feb 26, 2025 •

edited

Loading

netlify Bot commented Feb 26, 2025 •

edited

Loading

netlify Bot commented Feb 26, 2025 •

edited

Loading

codecov Bot commented Feb 26, 2025 •

edited

Loading

paul-balchin-ibm Mar 3, 2025 •

edited

Loading