From 8135d4a76edb4481ef1fdc75a5fecc28a37112c0 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:06:16 +0000 Subject: [PATCH 01/10] docs: Add playground demo rule Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .claude/rules/playground-demos.md | 35 ++++++++++++++++++++++++++++++ .cursor/rules/playground-demos.mdc | 30 +++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 .claude/rules/playground-demos.md create mode 100644 .cursor/rules/playground-demos.mdc diff --git a/.claude/rules/playground-demos.md b/.claude/rules/playground-demos.md new file mode 100644 index 000000000000..9bb6286cf962 --- /dev/null +++ b/.claude/rules/playground-demos.md @@ -0,0 +1,35 @@ +--- +paths: + - "docs/**/*.md" + - "docs/**/*.mdx" + - "website/src/fixtures/**" + - "website/src/components/Demo/code/**" + - "website/src/components/Playground/DesignSystem/**" +--- + + + +# Playground demos + +For adding or changing a live playground demo (``, the homepage's `Demo/code`). How playgrounds work (props, layouts, fixtures, design-system classes) is in the [Playground README](../../website/src/components/Playground/README.md). + +## Goal + +A demo soft-sells Data Client first and teaches users and agents how to use it second. People copy what they see and agents copy the code, so both the preview and the code teach. + +- **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. +- **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). +- **Look**: very beautiful, built from the playground design system so it reads as a real app. +- **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. +- **New ideas**: coming up with a new demo idea needs at least high reasoning effort. Below that, ask to raise it (or hand the ideation to a subagent at high) before choosing. + +## Conventions from review + +- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. +- Loading states are skeletons (``, `skeleton`), never "Loading…" text. +- A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. +- Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. +- Styling lives in the design system, never inline styles or CSS in the example code. +- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask first. +- Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. +- Check it at phone width and in both light and dark themes. diff --git a/.cursor/rules/playground-demos.mdc b/.cursor/rules/playground-demos.mdc new file mode 100644 index 000000000000..60fe24655282 --- /dev/null +++ b/.cursor/rules/playground-demos.mdc @@ -0,0 +1,30 @@ +--- +description: How to choose and write live playground demos for the docs site (HooksPlayground examples, their fixtures and design-system markup) +globs: docs/**/*.md, docs/**/*.mdx, website/src/fixtures/**, website/src/components/Demo/code/**, website/src/components/Playground/DesignSystem/** +alwaysApply: false +--- + +# Playground demos + +For adding or changing a live playground demo (``, the homepage's `Demo/code`). How playgrounds work (props, layouts, fixtures, design-system classes) is in the [Playground README](../../website/src/components/Playground/README.md). + +## Goal + +A demo soft-sells Data Client first and teaches users and agents how to use it second. People copy what they see and agents copy the code, so both the preview and the code teach. + +- **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. +- **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). +- **Look**: very beautiful, built from the playground design system so it reads as a real app. +- **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. +- **New ideas**: coming up with a new demo idea needs at least high reasoning effort. Below that, ask to raise it (or hand the ideation to a subagent at high) before choosing. + +## Conventions from review + +- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. +- Loading states are skeletons (``, `skeleton`), never "Loading…" text. +- A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. +- Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. +- Styling lives in the design system, never inline styles or CSS in the example code. +- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask first. +- Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. +- Check it at phone width and in both light and dark themes. From 2612bdb267e28fddf8a16b7bc18b5222f0c47bcc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:08:24 +0000 Subject: [PATCH 02/10] docs: Tighten playground demo rule after audit Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .claude/rules/playground-demos.md | 13 ++++++------- .cursor/rules/playground-demos.mdc | 13 ++++++------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/.claude/rules/playground-demos.md b/.claude/rules/playground-demos.md index 9bb6286cf962..1887fb3e78d2 100644 --- a/.claude/rules/playground-demos.md +++ b/.claude/rules/playground-demos.md @@ -19,17 +19,16 @@ A demo soft-sells Data Client first and teaches users and agents how to use it s - **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. - **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). -- **Look**: very beautiful, built from the playground design system so it reads as a real app. +- **Look**: very beautiful, built from the playground design system so it reads as a real app. Styling goes in the design system, never inline styles or CSS in the example code, so a look changes in one place. - **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. -- **New ideas**: coming up with a new demo idea needs at least high reasoning effort. Below that, ask to raise it (or hand the ideation to a subagent at high) before choosing. +- **New ideas**: coming up with a new demo idea needs at least high reasoning effort, since the idea decides everything above. Below that, ask the user to raise it (or hand the ideation to a subagent at high) before choosing. ## Conventions from review -- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. -- Loading states are skeletons (``, `skeleton`), never "Loading…" text. +- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. Needing one means the use case doesn't show the advantage yet. +- Loading states are skeletons (``, `skeleton`), never "Loading…" text: the demo shows what a good app does. - A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. - Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. -- Styling lives in the design system, never inline styles or CSS in the example code. -- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask first. +- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask the user first. - Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. -- Check it at phone width and in both light and dark themes. +- Check it at phone width and in both light and dark themes: readers see all of them, and the site must work on every one. diff --git a/.cursor/rules/playground-demos.mdc b/.cursor/rules/playground-demos.mdc index 60fe24655282..9340a5735019 100644 --- a/.cursor/rules/playground-demos.mdc +++ b/.cursor/rules/playground-demos.mdc @@ -14,17 +14,16 @@ A demo soft-sells Data Client first and teaches users and agents how to use it s - **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. - **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). -- **Look**: very beautiful, built from the playground design system so it reads as a real app. +- **Look**: very beautiful, built from the playground design system so it reads as a real app. Styling goes in the design system, never inline styles or CSS in the example code, so a look changes in one place. - **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. -- **New ideas**: coming up with a new demo idea needs at least high reasoning effort. Below that, ask to raise it (or hand the ideation to a subagent at high) before choosing. +- **New ideas**: coming up with a new demo idea needs at least high reasoning effort, since the idea decides everything above. Below that, ask the user to raise it (or hand the ideation to a subagent at high) before choosing. ## Conventions from review -- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. -- Loading states are skeletons (``, `skeleton`), never "Loading…" text. +- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. Needing one means the use case doesn't show the advantage yet. +- Loading states are skeletons (``, `skeleton`), never "Loading…" text: the demo shows what a good app does. - A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. - Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. -- Styling lives in the design system, never inline styles or CSS in the example code. -- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask first. +- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask the user first. - Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. -- Check it at phone width and in both light and dark themes. +- Check it at phone width and in both light and dark themes: readers see all of them, and the site must work on every one. From e9dea428ccfacb1cfc77606ffc7af3bd7f104be7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:08:41 +0000 Subject: [PATCH 03/10] docs: Drop DesignSystem from playground demo rule globs Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .claude/rules/playground-demos.md | 1 - .cursor/rules/playground-demos.mdc | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/.claude/rules/playground-demos.md b/.claude/rules/playground-demos.md index 1887fb3e78d2..75a2841da277 100644 --- a/.claude/rules/playground-demos.md +++ b/.claude/rules/playground-demos.md @@ -4,7 +4,6 @@ paths: - "docs/**/*.mdx" - "website/src/fixtures/**" - "website/src/components/Demo/code/**" - - "website/src/components/Playground/DesignSystem/**" --- diff --git a/.cursor/rules/playground-demos.mdc b/.cursor/rules/playground-demos.mdc index 9340a5735019..5f4c79396f83 100644 --- a/.cursor/rules/playground-demos.mdc +++ b/.cursor/rules/playground-demos.mdc @@ -1,6 +1,6 @@ --- description: How to choose and write live playground demos for the docs site (HooksPlayground examples, their fixtures and design-system markup) -globs: docs/**/*.md, docs/**/*.mdx, website/src/fixtures/**, website/src/components/Demo/code/**, website/src/components/Playground/DesignSystem/** +globs: docs/**/*.md, docs/**/*.mdx, website/src/fixtures/**, website/src/components/Demo/code/** alwaysApply: false --- From 9eae38537ed5eed8d5e7a233edaec24c9d2e7abe Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:09:40 +0000 Subject: [PATCH 04/10] docs: Match playground demo rule description to its globs Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .cursor/rules/playground-demos.mdc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.cursor/rules/playground-demos.mdc b/.cursor/rules/playground-demos.mdc index 5f4c79396f83..dfeca20af511 100644 --- a/.cursor/rules/playground-demos.mdc +++ b/.cursor/rules/playground-demos.mdc @@ -1,5 +1,5 @@ --- -description: How to choose and write live playground demos for the docs site (HooksPlayground examples, their fixtures and design-system markup) +description: How to choose and write live playground demos for the docs site (HooksPlayground examples, the homepage demo, and their fixtures) globs: docs/**/*.md, docs/**/*.mdx, website/src/fixtures/**, website/src/components/Demo/code/** alwaysApply: false --- From db81ff2fb8b38e287cbf6847c78ad1ecf05453fe Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:10:42 +0000 Subject: [PATCH 05/10] docs: Move playground demo guidance from a rule to a skill A docs/** glob loaded it on every docs edit; a skill triggers only on demo work. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .../skills/playground-demos/SKILL.md | 13 ++++----- .cursor/rules/playground-demos.mdc | 29 ------------------- 2 files changed, 5 insertions(+), 37 deletions(-) rename .claude/rules/playground-demos.md => .agents/skills/playground-demos/SKILL.md (83%) delete mode 100644 .cursor/rules/playground-demos.mdc diff --git a/.claude/rules/playground-demos.md b/.agents/skills/playground-demos/SKILL.md similarity index 83% rename from .claude/rules/playground-demos.md rename to .agents/skills/playground-demos/SKILL.md index 75a2841da277..0c5d9d159a9d 100644 --- a/.claude/rules/playground-demos.md +++ b/.agents/skills/playground-demos/SKILL.md @@ -1,16 +1,13 @@ --- -paths: - - "docs/**/*.md" - - "docs/**/*.mdx" - - "website/src/fixtures/**" - - "website/src/components/Demo/code/**" +name: playground-demos +description: Choose and write live playground demos for the dataclient.io docs site and homepage (HooksPlayground examples, the homepage demo, their fixtures). Use when adding, redesigning or reviewing a docs demo, or coming up with a new demo idea for a feature. +metadata: + internal: true --- - - # Playground demos -For adding or changing a live playground demo (``, the homepage's `Demo/code`). How playgrounds work (props, layouts, fixtures, design-system classes) is in the [Playground README](../../website/src/components/Playground/README.md). +How playgrounds work (props, layouts, fixtures, design-system classes) is in the [Playground README](../../../website/src/components/Playground/README.md). ## Goal diff --git a/.cursor/rules/playground-demos.mdc b/.cursor/rules/playground-demos.mdc deleted file mode 100644 index dfeca20af511..000000000000 --- a/.cursor/rules/playground-demos.mdc +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: How to choose and write live playground demos for the docs site (HooksPlayground examples, the homepage demo, and their fixtures) -globs: docs/**/*.md, docs/**/*.mdx, website/src/fixtures/**, website/src/components/Demo/code/** -alwaysApply: false ---- - -# Playground demos - -For adding or changing a live playground demo (``, the homepage's `Demo/code`). How playgrounds work (props, layouts, fixtures, design-system classes) is in the [Playground README](../../website/src/components/Playground/README.md). - -## Goal - -A demo soft-sells Data Client first and teaches users and agents how to use it second. People copy what they see and agents copy the code, so both the preview and the code teach. - -- **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. -- **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). -- **Look**: very beautiful, built from the playground design system so it reads as a real app. Styling goes in the design system, never inline styles or CSS in the example code, so a look changes in one place. -- **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. -- **New ideas**: coming up with a new demo idea needs at least high reasoning effort, since the idea decides everything above. Below that, ask the user to raise it (or hand the ideation to a subagent at high) before choosing. - -## Conventions from review - -- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. Needing one means the use case doesn't show the advantage yet. -- Loading states are skeletons (``, `skeleton`), never "Loading…" text: the demo shows what a good app does. -- A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. -- Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. -- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask the user first. -- Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. -- Check it at phone width and in both light and dark themes: readers see all of them, and the site must work on every one. From 3346e6ae1da22cdebcd0d87ab30760ad7c467158 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:12:37 +0000 Subject: [PATCH 06/10] docs: Make playground demo skill's effort step actionable Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .agents/skills/playground-demos/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/skills/playground-demos/SKILL.md b/.agents/skills/playground-demos/SKILL.md index 0c5d9d159a9d..992919376c05 100644 --- a/.agents/skills/playground-demos/SKILL.md +++ b/.agents/skills/playground-demos/SKILL.md @@ -15,9 +15,9 @@ A demo soft-sells Data Client first and teaches users and agents how to use it s - **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. - **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). -- **Look**: very beautiful, built from the playground design system so it reads as a real app. Styling goes in the design system, never inline styles or CSS in the example code, so a look changes in one place. +- **Look**: very beautiful, built from the playground [design system](../../../website/src/components/Playground/README.md#design-system) so it reads as a real app. Styling goes in the design system, never inline styles or CSS in the example code, so a look changes in one place. - **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. -- **New ideas**: coming up with a new demo idea needs at least high reasoning effort, since the idea decides everything above. Below that, ask the user to raise it (or hand the ideation to a subagent at high) before choosing. +- **New ideas**: coming up with a new demo idea needs at least high reasoning effort, since the idea decides everything above. If your effort is lower or unknown, hand the ideation to a subagent at high effort, or ask the user to raise it, before choosing. ## Conventions from review From fe683c6b68d9d49c1461be4c0fe155cce189e7ee Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:16:38 +0000 Subject: [PATCH 07/10] docs: Simplify playground demos skill Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .agents/skills/playground-demos/SKILL.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/.agents/skills/playground-demos/SKILL.md b/.agents/skills/playground-demos/SKILL.md index 992919376c05..c2ee27a4f542 100644 --- a/.agents/skills/playground-demos/SKILL.md +++ b/.agents/skills/playground-demos/SKILL.md @@ -7,24 +7,24 @@ metadata: # Playground demos -How playgrounds work (props, layouts, fixtures, design-system classes) is in the [Playground README](../../../website/src/components/Playground/README.md). +How playgrounds work is in the [Playground README](../../../website/src/components/Playground/README.md); a demo author needs its [Layouts](../../../website/src/components/Playground/README.md#layouts) and [Design system](../../../website/src/components/Playground/README.md#design-system) sections. ## Goal -A demo soft-sells Data Client first and teaches users and agents how to use it second. People copy what they see and agents copy the code, so both the preview and the code teach. +A demo soft-sells Data Client first and teaches users and agents how to use it second. People copy what they see and agents copy the code, so both teach. -- **Use case**: pick one that clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). If the preview doesn't make the advantage visible, pick another use case. +- **Use case**: pick one whose preview clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). - **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). -- **Look**: very beautiful, built from the playground [design system](../../../website/src/components/Playground/README.md#design-system) so it reads as a real app. Styling goes in the design system, never inline styles or CSS in the example code, so a look changes in one place. +- **Look**: very beautiful, built from the playground design system (never inline styles or CSS in the example code) so it reads as a real app. - **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. -- **New ideas**: coming up with a new demo idea needs at least high reasoning effort, since the idea decides everything above. If your effort is lower or unknown, hand the ideation to a subagent at high effort, or ask the user to raise it, before choosing. +- **New ideas**: inventing a new demo idea needs at least high reasoning effort, since the idea decides everything above. At lower or unknown effort, hand the ideation to a high-effort subagent or ask the user to raise it. ## Conventions from review -- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. Needing one means the use case doesn't show the advantage yet. -- Loading states are skeletons (``, `skeleton`), never "Loading…" text: the demo shows what a good app does. +- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. +- Loading states are skeletons (``, `skeleton`), never "Loading…" text. - A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. - Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. - Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask the user first. - Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. -- Check it at phone width and in both light and dark themes: readers see all of them, and the site must work on every one. +- Check it at phone width and in both light and dark themes. From db982ff11b94023777f9a57459548538b1eae47a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:17:39 +0000 Subject: [PATCH 08/10] docs: Restore playground demo skill's caption fallback Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .agents/skills/playground-demos/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/playground-demos/SKILL.md b/.agents/skills/playground-demos/SKILL.md index c2ee27a4f542..d305458506ca 100644 --- a/.agents/skills/playground-demos/SKILL.md +++ b/.agents/skills/playground-demos/SKILL.md @@ -21,7 +21,7 @@ A demo soft-sells Data Client first and teaches users and agents how to use it s ## Conventions from review -- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. +- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. If it needs one, pick another use case. - Loading states are skeletons (``, `skeleton`), never "Loading…" text. - A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. - Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. From b4b56433e1fb2b9abd0153500cbfd0dec52708ca Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:20:03 +0000 Subject: [PATCH 09/10] docs: Trim playground demos skill to what agents don't already know Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .agents/skills/playground-demos/SKILL.md | 28 ++++++++++++------------ 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/.agents/skills/playground-demos/SKILL.md b/.agents/skills/playground-demos/SKILL.md index d305458506ca..61c0f0536450 100644 --- a/.agents/skills/playground-demos/SKILL.md +++ b/.agents/skills/playground-demos/SKILL.md @@ -7,24 +7,24 @@ metadata: # Playground demos -How playgrounds work is in the [Playground README](../../../website/src/components/Playground/README.md); a demo author needs its [Layouts](../../../website/src/components/Playground/README.md#layouts) and [Design system](../../../website/src/components/Playground/README.md#design-system) sections. +How playgrounds work is in the [Playground README](../../../website/src/components/Playground/README.md), mainly its Layouts and Design system sections. ## Goal A demo soft-sells Data Client first and teaches users and agents how to use it second. People copy what they see and agents copy the code, so both teach. -- **Use case**: pick one whose preview clearly shows the feature's advantage over the alternative (hand-rolled state, refetching, another library). -- **Mechanism**: make it easy to see how it works and why it's better: the reader can point at what the feature did (the row that updated in place, one request instead of three, the entry in the Store). -- **Look**: very beautiful, built from the playground design system (never inline styles or CSS in the example code) so it reads as a real app. -- **Scope**: as simple as possible while still showing maximum value, utility and related features. Cut whatever doesn't serve the point; add a related feature only when it shows more of the value. -- **New ideas**: inventing a new demo idea needs at least high reasoning effort, since the idea decides everything above. At lower or unknown effort, hand the ideation to a high-effort subagent or ask the user to raise it. +- **Use case**: one where the preview clearly shows the feature's advantage over the alternative. +- **Mechanism**: easy to see how it works and why it's better. +- **Look**: very beautiful, built from the playground design system, with no styling in the example code. +- **Scope**: as simple as possible while still showing maximum value, utility and related features. +- **New ideas**: inventing one needs at least high reasoning effort. At lower or unknown effort, hand the ideation to a high-effort subagent or ask the user. -## Conventions from review +## Conventions -- The demo makes its point by itself: no captions, narration or "watch this" text in the preview. If it needs one, pick another use case. -- Loading states are skeletons (``, `skeleton`), never "Loading…" text. -- A demo of a real public API keeps the real URL and response shape in its code and is intercepted by a fixture in `website/src/fixtures/`, so copied code returns real data. Live calls from the playground hit rate limits. -- Code models what a careful app would do (`React.memo` on a list whose parent re-renders per keystroke, stable keys) even when the perf win is tiny, because readers copy it. -- Use `row` (code beside the preview) when the code is the lesson, even for routed or `autoRun` demos. Use `demo` (code behind a toggle) only when the point is purely visual, and ask the user first. -- Anything extra a demo needs (a clock, toasts) goes in the demo code using a design-system component or class, never a new Playground prop: the Playground is shared by every demo. -- Check it at phone width and in both light and dark themes. +- The demo makes its point without captions or narration text. If it needs them, pick another use case. +- Loading states are skeletons (``, `skeleton`), not "Loading…" text. +- A demo of a real public API calls its real URL, intercepted by a fixture in `website/src/fixtures/`, so copied code works. +- The code follows the practices a careful app would, even where the demo could skip them, because readers copy it. +- Use the `row` layout when the code is the lesson. Ask the user before using `demo`, which hides the code. +- Anything extra a demo needs goes in the demo code with a design-system component, never a new Playground prop. +- Check phone width and both themes. From ba2bec773b4871ac341749a1930fc8106a583007 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 23:21:22 +0000 Subject: [PATCH 10/10] docs: Keep the demo layout's purely-visual criterion Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Y5C5ZD92iQGvdD3nbCEnXG --- .agents/skills/playground-demos/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.agents/skills/playground-demos/SKILL.md b/.agents/skills/playground-demos/SKILL.md index 61c0f0536450..cc2636c877b0 100644 --- a/.agents/skills/playground-demos/SKILL.md +++ b/.agents/skills/playground-demos/SKILL.md @@ -15,7 +15,7 @@ A demo soft-sells Data Client first and teaches users and agents how to use it s - **Use case**: one where the preview clearly shows the feature's advantage over the alternative. - **Mechanism**: easy to see how it works and why it's better. -- **Look**: very beautiful, built from the playground design system, with no styling in the example code. +- **Look**: very beautiful, built from the playground design system, with no inline styles or CSS in the example code. - **Scope**: as simple as possible while still showing maximum value, utility and related features. - **New ideas**: inventing one needs at least high reasoning effort. At lower or unknown effort, hand the ideation to a high-effort subagent or ask the user. @@ -25,6 +25,6 @@ A demo soft-sells Data Client first and teaches users and agents how to use it s - Loading states are skeletons (``, `skeleton`), not "Loading…" text. - A demo of a real public API calls its real URL, intercepted by a fixture in `website/src/fixtures/`, so copied code works. - The code follows the practices a careful app would, even where the demo could skip them, because readers copy it. -- Use the `row` layout when the code is the lesson. Ask the user before using `demo`, which hides the code. +- Use the `row` layout when the code is the lesson. Use `demo`, which hides the code, only when the point is purely visual, and ask the user first. - Anything extra a demo needs goes in the demo code with a design-system component, never a new Playground prop. - Check phone width and both themes.