adobe · nikkimk · Dec 17, 2025 · Dec 15, 2025
@@ -1,5 +1,7 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 import '@spectrum-web-components/table/elements.js';
+import '@spectrum-web-components/accordion/sp-accordion.js';
+import '@spectrum-web-components/accordion/sp-accordion-item.js';
 
 <Meta title="First Gen vs Second Gen" />
 
@@ -68,19 +70,23 @@ SWC 2nd-gen is the next version of Spectrum Web Components. It updates the desig
 
 ## What this means for teams
 
-### If you are starting a new project
-
-Use 2nd-gen SWC. It matches the current Spectrum guidelines and offers better performance and consistency.
-
-### If your project already uses 1st-gen SWC
-
-You can continue using it, but you may want to plan a migration. Some components and APIs have changed in 2nd-gen, so updates may require code changes or testing.
-
-### If you maintain a large 1st-gen codebase
-
-Migration will take more time. Review your components, compare APIs, and update your patterns gradually. Not everything must move at once.
-
-### Why 2nd-gen is recommended
+<sp-accordion>
+    <sp-accordion-item label="If you are starting a new project">
+        Use 2nd-gen SWC. It matches the current Spectrum guidelines and offers
+        better performance and consistency.
+    </sp-accordion-item>
+    <sp-accordion-item label="If your project already uses 1st-gen SWC">
+        You can continue using it, but you may want to plan a migration. Some
+        components and APIs have changed in 2nd-gen, so updates may require code
+        changes or testing.
+    </sp-accordion-item>
+    <sp-accordion-item label="If you maintain a large 1st-gen codebase">
+        Migration will take more time. Review your components, compare APIs, and
+        update your patterns gradually. Not everything must move at once.
+    </sp-accordion-item>
+</sp-accordion>
+
+## Why 2nd-gen is recommended
 
 - It aligns with Spectrum 2, which is the standard for new Adobe work.
 - Components follow more consistent design and code patterns.

@@ -39,7 +39,8 @@ Key updates include:
 
 You can find a comparison on the 1st-gen vs 2nd-gen page.
 
-What you’ll find in this documentation (H2)
+## What you’ll find in this documentation
+
 This site includes:
 
 - information about how SWC works

@@ -0,0 +1,76 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+import '@spectrum-web-components/accordion/sp-accordion.js';
+import '@spectrum-web-components/accordion/sp-accordion-item.js';
+
+<Meta title="When to use SWC?" />
+
+# When to use SWC
+
+Spectrum Web Components (SWC) is a good choice when you want to build interfaces that match the Spectrum design system and can run in many different environments. This page explains when SWC is the right tool and when you may need extra support or a different approach.
+
+## Use SWC when:
+
+<sp-accordion>
+    <sp-accordion-item label="You need Spectrum-aligned UI in a web environment">
+        SWC gives you ready-made components that follow Spectrum design and
+        behavior. Use them when your project must look and feel like other Adobe
+        experiences.
+    </sp-accordion-item>
+    <sp-accordion-item label="You want components that work without a specific framework">
+        SWC works in plain HTML, JavaScript, or TypeScript. It also works with
+        frameworks like React through wrapper packages. This makes it a good
+        option for teams using mixed technologies. Use 2nd-gen SWC. It matches
+        the current Spectrum guidelines and offers better performance and
+        consistency.
+    </sp-accordion-item>
+    <sp-accordion-item label="You want consistent behavior across products">
+        Because SWC components share a common architecture and API, they behave
+        the same across all projects. This reduces the amount of one-off code
+        your team needs to maintain. Use 2nd-gen SWC. It matches the current
+        Spectrum guidelines and offers better performance and consistency.
+    </sp-accordion-item>
+    <sp-accordion-item label="You want built-in accessibility">
+        SWC includes accessibility features that follow Spectrum and web
+        standards. This helps teams meet accessibility requirements without
+        writing them from scratch. Use 2nd-gen SWC. It matches the current
+        Spectrum guidelines and offers better performance and consistency.
+    </sp-accordion-item>
+    <sp-accordion-item label="You only need a few components">
+        Since SWC ships as individual packages, you can install only the
+        components you need. This keeps your project lighter and easier to
+        maintain.
+    </sp-accordion-item>
+</sp-accordion>
+
+## SWC may not be enough on its own when:
+
+<sp-accordion>
+    <sp-accordion-item label="Your project depends on framework-specific features">
+        If your app uses advanced React, Vue, or Angular patterns, you might
+        need extra setup or wrapper components. SWC can still work, but you may
+        need additional engineering support.
+    </sp-accordion-item>
+    <sp-accordion-item label="You need a custom design system">
+        SWC is built to match Spectrum. If your product uses patterns that do
+        not follow Spectrum, you may need custom components or additional
+        styling.
+    </sp-accordion-item>
+    <sp-accordion-item label=" You are migrating large 1st-gen codebases">
+        SWC 2nd-gen changes some APIs and patterns. Large migrations may require
+        planning, refactoring, or testing before you switch fully.
+    </sp-accordion-item>
+</sp-accordion>
+
+## Questions to help you decide
+
+- Does your product need to follow Spectrum 2 design?
+- Do you want framework-agnostic components?
+- Will your team maintain custom UI, or should SWC handle that?
+- Does your project need built-in accessibility support?
+- Are you using only a small set of components or the full library?
+
+If you answered “yes” to most of these, SWC is likely a good fit.
+
+## Still not sure?
+
+Check the examples in the component documentation or explore how other Adobe teams use SWC. You can also reach out to the SWC team if you need help deciding whether SWC is the right fit for your project.
@@ -14,7 +14,7 @@ const config = {
             titlePrefix: 'Components',
         },
         {
-            directory: 'about-swc',
+            directory: 'learn-about-swc',
             files: '*.mdx',
             titlePrefix: 'About SWC',
         },