diff --git a/docs/contribute/doc-style-guide.md b/docs/contribute/doc-style-guide.md
index 901df0c55c..3aa56b336f 100644
--- a/docs/contribute/doc-style-guide.md
+++ b/docs/contribute/doc-style-guide.md
@@ -157,6 +157,37 @@ dilute their impact and make the content harder to read. If a section has
 more than two admonitions, restructure the content so that most of the
 information is in regular paragraphs.
 
+## Accordions
+
+Use HTML `<details>` and `<summary>` elements to create collapsible sections.
+These are useful for "Common issues" sections, lengthy reference tables, or
+supplementary content that would otherwise break the reading flow.
+
+```markdown
+<details>
+  <summary>Summary text visible when collapsed</summary>
+
+Content inside the accordion. You can use **Markdown** here, including code
+blocks, lists, and other formatting.
+
+</details>
+```
+
+<details>
+  <summary>Summary text visible when collapsed</summary>
+
+Content inside the accordion. You can use **Markdown** here, including code
+blocks, lists, and other formatting.
+
+</details>
+
+Leave a blank line after the `<summary>` tag and before the closing
+`</details>` tag so that Markdown content inside renders correctly.
+
+Use backticks for inline code inside `<summary>` elements instead of HTML
+`<code>` tags. Backticks render correctly inside summary elements and keep
+the source consistent with the rest of the Markdown content.
+
 ## Markdown elements
 
 ### Line breaks
diff --git a/docs/golden-path/plugins/frontend/001-first-steps.md b/docs/golden-path/plugins/frontend/001-first-steps.md
index 5ece316d9f..d229933cf0 100644
--- a/docs/golden-path/plugins/frontend/001-first-steps.md
+++ b/docs/golden-path/plugins/frontend/001-first-steps.md
@@ -88,12 +88,26 @@ yarn workspace @internal/plugin-todo start
 
 ## Common issues
 
-- **Plugin page not showing up.** Verify that `app.packages` is set to `all`
-  in your `app-config.yaml`. If you use include/exclude filters, make sure your
-  plugin package is not excluded.
-- **`yarn new --select frontend-plugin --option pluginId=todo --option owner=` fails during installation.** Make sure
-  you have run `yarn install` in the repository root first and that your
-  Node.js version matches the one required by the project.
-- **TypeScript errors after scaffolding.** Run `yarn tsc` from the repository
-  root to check for type errors. A fresh scaffold should compile cleanly — if
-  not, try running `yarn install` again.
+<details>
+  <summary>Plugin page not showing up</summary>
+
+Verify that `app.packages` is set to `all` in your `app-config.yaml`. If you
+use include/exclude filters, make sure your plugin package is not excluded.
+
+</details>
+
+<details>
+  <summary>`yarn new` fails during installation</summary>
+
+Make sure you have run `yarn install` in the repository root first and that
+your Node.js version matches the one required by the project.
+
+</details>
+
+<details>
+  <summary>TypeScript errors after scaffolding</summary>
+
+Run `yarn tsc` from the repository root to check for type errors. A fresh
+scaffold should compile cleanly — if not, try running `yarn install` again.
+
+</details>