[core] Improve the playground DX (mui#34739)

.eslintignore

@@ -3,7 +3,7 @@
 /benchmark/**/dist
 /coverage
 /docs/export
-/docs/pages/playground.tsx
+/docs/pages/playground/
 /examples/create-react-app*/src/serviceWorker.js
 /examples/gatsby/public/
 /examples/preact/config

.gitignore

@@ -14,7 +14,7 @@
 /coverage
 /docs/.env.local
 /docs/export
-/docs/pages/playground.tsx
+/docs/pages/playground/
 /examples/**/.cache
 /packages/mui-codemod/lib
 /packages/mui-envinfo/*.tgz

CONTRIBUTING.md

@@ -80,7 +80,7 @@ The core team is monitoring for Pull Requests. We will review your Pull Request
 ### Trying changes on the documentation site
 
 The documentation site is built with MUI and contains examples of all the components.
-This is a great place to experiment with your changes.
+This is the best place to experiment with your changes.
 It's the local development environment used by the maintainers.
 
 To get started:
@@ -89,9 +89,29 @@ To get started:
 yarn start
 ```
 
-You can now access the documentation site [locally](http://localhost:3000).
+You can now access the documentation site locally: http://localhost:3000.
 Changes to the docs will hot reload the site.
 
+### Trying changes on the playground
+
+While we recommend to try your changes on the documentation site—it's not always ideal.
+You might face following problems:
+
+- updating the existing demos prevent you to work in isolation on a single instance of the component
+- emptying an existing page to try your changes in isolation lead to a noisy `git diff`
+- static linters will report issues that you might not care about.
+
+To solve these problems—you can use the playground:
+
+```sh
+yarn docs:create-playground && yarn start
+```
+
+You can now access it locally: http://localhost:3000/playground/.
+
+You can create as many playgrounds as you want by going to the `/docs/pages/playground/` folder and duplicating the index.tsx file with a different name: `<file_name>.tsx`.
+The new playground will be accessible under: `http://localhost:3000/playground/<file_name>`.
+
 ### How to increase the chance of being accepted?
 
 Continuous Integration (CI) runs a series of checks automatically when a Pull Request is opened. If you're not

docs/package.json

@@ -13,6 +13,7 @@
     "export": "rimraf docs/export && next export --threads=3 -o export && yarn build-sw",
     "icons": "rimraf public/static/icons/* && node ./scripts/buildIcons.js",
     "start": "next start",
+    "create-playground": "cpy --cwd=./scripts/ playground.template.tsx ../pages/playground --rename=index.tsx",
     "typescript": "tsc -p tsconfig.json && tsc -p scripts/tsconfig.json",
     "typescript:transpile": "echo 'Use `yarn docs:typescript:formatted'` instead && exit 1",
     "typescript:transpile:dev": "echo 'Use `yarn docs:typescript'` instead && exit 1",

docs/scripts/playground.template.tsx

@@ -0,0 +1,7 @@
+import * as React from 'react';
+
+export default function Playground() {
+  return (
+    <div>A playground for a fast iteration development cycle in isolation outside of git.</div>
+  );
+}

package.json

@@ -24,6 +24,7 @@
     "docs:icons": "yarn workspace docs icons",
     "docs:size-why": "cross-env DOCS_STATS_ENABLED=true yarn docs:build",
     "docs:start": "yarn workspace docs start",
+    "docs:create-playground": "yarn workspace docs create-playground",
     "docs:i18n": "cross-env BABEL_ENV=development babel-node --extensions \".tsx,.ts,.js\" ./docs/scripts/i18n.js",
     "docs:link-check": "yarn workspace docs link-check",
     "docs:typescript": "yarn docs:typescript:formatted --watch",