[CDX-348] Apply the OS UI docs guideline for Storybook

[Alexey-Pavlov]

This pull request makes significant updates to the Storybook configuration, primarily to improve documentation handling, enhance the organization and navigation of stories, and clean up unused or redundant story files.

OS UI Libraries Documentation Guideline

[esezen]

This is looking great. I left some comments. Can we also update the main link in README.md?

[esezen]

Are we removing the tests completely?

[Alexey-Pavlov]

Nope! I did that by mistake 👀

[esezen]

Same

[constructor-claude-bedrock]

Code Review Results

✅ Strengths

Well-organized documentation restructure following OS UI guidelines with clear navigation hierarchy and comprehensive MDX documentation for all components and hooks.

🚨 Critical Issues

None identified.

⚠️ Important Issues

[File: .storybook/main.js Line: L1]

• Issue: Using ES6 import syntax with export default in .storybook/main.js, but the file extension is .js not .mjs. This requires the package to have "type": "module" in package.json or the file to be renamed to .mjs.
• Why: Without proper module configuration, Node.js will fail to parse ES6 module syntax in .js files.
• Recommendation: Either rename .storybook/main.js to .storybook/main.mjs, or verify that Storybook's build system handles this transformation correctly. If Storybook 8.6+ handles this automatically, this is acceptable, but should be tested.

[File: .eslintrc.json Line: L106]

• Issue: Adding "**/*.mdx" to eslintignore patterns is good, but the PR removes old story files without confirming they're no longer needed in production builds.
• Why: The .storybook/main.js previously had production/development branching logic that filtered stories, which has been removed.
• Recommendation: Confirm that removing the isProduction conditional and all old story paths won't break production Storybook builds.

[File: package.json Line: L110]

• Issue: Added remark-gfm as a devDependency for GitHub Flavored Markdown support, and package-lock.json was properly updated.
• Why: This is correct - the dependency addition matches the package-lock.json changes.
• Recommendation: No action needed - this is properly implemented.

💡 Suggestions

[File: .storybook/preview.jsx Line: L35-L38]

• Suggestion: The new table of contents (TOC) configuration is a nice addition. Consider documenting this feature in the Storybook setup documentation if it's a new pattern for the team.

[File: src/stories/components/CioAutocomplete/CioAutocomplete.mdx]

• Suggestion: The documentation is comprehensive and well-structured. Consider adding a troubleshooting section for common issues users might encounter (e.g., API key errors, CORS issues, etc.).

[General]

• Suggestion: The PR removes 10 old story files and adds many new MDX documentation files. Consider adding a migration guide or changelog entry to help team members understand the new structure.

[File: .storybook/main.js Line: L4-L11]

• Suggestion: The explicit story ordering is excellent for documentation discoverability. The order follows a logical learning path: Getting Started → Basic Concepts → Components → Hooks → Utils.

[File: README.md Line: L12, L48]

• Suggestion: Updated Storybook URLs to point to the new "Getting Started/Introduction" path. Verify these links work after deployment.

Overall Assessment: ✅ Pass

---

Summary

This is a well-executed documentation restructuring that follows the OS UI Libraries Documentation Guideline. The changes improve organization and discoverability. The main concern is ensuring the ES6 module syntax in .storybook/main.js is compatible with the build system, and verifying that removing the production/development story filtering doesn't break production builds. No test coverage is required for documentation changes, which is appropriate for this type of refactoring.

[esezen]

LGTM!