Skip to content

[docs] Add agent skills for styling, theming, Next.js, and Tailwind CSS integrations#48187

Open
mapache-salvaje wants to merge 17 commits intomui:masterfrom
mapache-salvaje:agent-skills
Open

[docs] Add agent skills for styling, theming, Next.js, and Tailwind CSS integrations#48187
mapache-salvaje wants to merge 17 commits intomui:masterfrom
mapache-salvaje:agent-skills

Conversation

@mapache-salvaje
Copy link
Copy Markdown
Contributor

@mapache-salvaje mapache-salvaje commented Apr 2, 2026

This PR adds a batch of 4 agent skills to the repo based on some of the most common issues that users face:

  • styling: when to choose sx prop vs global styles vs theme
  • theming and design tokens
  • Next.js integration
  • Tailwind CSS integration

The style and structure mirrors that of Vercel's collection of agent skills, but I'm not married to those particulars.

I tested these by creating a spec for a full-fledged internal dashboard with requirements that would lead an LLM to face issues if they don't have context about the list items above. I gave the spec to multiple agents, with and without access to the skill files, and had them build out MVPs. Those without the skill files frequently got stuck on common expected issues and took significantly longer to get an app running than those with the skill files, which were able to avoid those pitfalls entirely. When the skill-less LLMs were given the skills after the fact, they confirmed that the additional context would have been useful.

In one instance, an LLM tripped over the Next.js integration as it relates to Suspense, so I had it suggest improvements we could make to the Next.js integration page so others might avoid that issue. I've included that in this PR as well.

@mapache-salvaje mapache-salvaje added docs Improvements or additions to the documentation. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. labels Apr 2, 2026
@mui-bot
Copy link
Copy Markdown

mui-bot commented Apr 2, 2026

Netlify deploy preview

Bundle size report

Bundle Parsed size Gzip size
@mui/material 0B(0.00%) 0B(0.00%)
@mui/lab 0B(0.00%) 0B(0.00%)
@mui/system 0B(0.00%) 0B(0.00%)
@mui/utils 0B(0.00%) 0B(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 932c032


export default function Page() {
return (
<Suspense fallback={null}>
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.

imo fallback={null} is a particularly bad pattern as it can cause layout shift. e.g. Here where we just hide the Toolbar during hydration and then show it on first render. If we recommend this pattern, we should probably give full examples of the components in a way that prevents layout shift.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@Janpot updated with dimension-stable suspense fallback instead of null, as well as a note explaining why.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to the documentation. type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants