Skip to content

Storybook: Reorganize design system introduction for first touch-point usefulness#79360

Merged
aduth merged 3 commits into
trunkfrom
add/ds-intro-mcp
Jun 22, 2026
Merged

Storybook: Reorganize design system introduction for first touch-point usefulness#79360
aduth merged 3 commits into
trunkfrom
add/ds-intro-mcp

Conversation

@aduth

@aduth aduth commented Jun 19, 2026

Copy link
Copy Markdown
Member

What?

Updates the Storybook Design System > introduction page:

  • Makes it about the WordPress Design System, not design systems as an abstract concept
  • Changes headings from Q&A style to typical documentation flow: High-level overview ➡️ setup / how to use ➡️ guiding principles
  • Mention and recommend the MCP server as a resource when working with AI (the MCP server is not currently mentioned anywhere in Storybook)
  • Deemphasize "Principles of the Design System": Shift the focus to what someone would care about in using the design system.

Why?

Reorient the documentation toward helping someone who's interested in using the design system. Since this page could be many people's first touch point with the design system, it's more important to put those people on the right track in using the design system successfully.

Testing Instructions

Review updated content for relevance and accuracy.

Use of AI Tools

No AI was used. Content under "Principles of the Design System" is reusing preexisting content, which was AI-generated at the time. For what it's worth, I'd like to rewrite this whole section at some point, but it's not the focus here.

@aduth aduth requested a review from a team June 19, 2026 17:40
@aduth aduth added [Type] Developer Documentation Documentation for developers Storybook Storybook and its stories for components Design System Issues related to the system of combining components according to best practices. [Package] Design System MCP /packages/design-system-mcp labels Jun 19, 2026
@aduth aduth requested a review from Copilot June 19, 2026 17:41

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR reorganizes the Storybook “Design System > Introduction” page to better serve as an initial, practical entry point for the WordPress Design System (vs. an abstract discussion of design systems).

Changes:

  • Rewrites the opening and section structure to focus on using the WordPress Design System (usage, theming, and key resources).
  • Adds a recommendation to use the WordPress Design System MCP Server when working with AI agents.
  • Moves the prior “differences vs @wordpress/components” content into a concluding section.

Comment thread storybook/stories/design-system/introduction.mdx Outdated
Comment thread storybook/stories/design-system/introduction.mdx Outdated
Co-authored-by: Copilot Autofix powered by AI <[email protected]>
@github-actions

github-actions Bot commented Jun 19, 2026

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <[email protected]>
Co-authored-by: mirka <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions

Copy link
Copy Markdown

Flaky tests detected in 26c4ce8.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/27840833499
📝 Reported issues:

@mirka mirka left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me 👍

Comment thread storybook/stories/design-system/introduction.mdx Outdated
@aduth aduth merged commit 1c9a672 into trunk Jun 22, 2026
47 of 49 checks passed
@aduth aduth deleted the add/ds-intro-mcp branch June 22, 2026 16:35
@github-actions github-actions Bot added this to the Gutenberg 23.5 milestone Jun 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Design System Issues related to the system of combining components according to best practices. [Package] Design System MCP /packages/design-system-mcp Storybook Storybook and its stories for components [Type] Developer Documentation Documentation for developers

Projects

Status: 💫 Done

Development

Successfully merging this pull request may close these issues.

3 participants