diff --git a/2nd-gen/packages/swc/.storybook/about-swc/when-to-use-swc.mdx b/2nd-gen/packages/swc/.storybook/about-swc/when-to-use-swc.mdx deleted file mode 100644 index 43b5370f4e..0000000000 --- a/2nd-gen/packages/swc/.storybook/about-swc/when-to-use-swc.mdx +++ /dev/null @@ -1,57 +0,0 @@ -import { Meta } from '@storybook/addon-docs/blocks'; - - - -# 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: - -### 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. - -### 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. - -### 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. - -### 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. - -### 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. - -## SWC may not be enough on its own when: - -### 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. - -### 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. - -### 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. - -## 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. diff --git a/2nd-gen/packages/swc/.storybook/about-swc/first-gen-vs-second-gen.mdx b/2nd-gen/packages/swc/.storybook/learn-about-swc/first-gen-vs-second-gen.mdx similarity index 77% rename from 2nd-gen/packages/swc/.storybook/about-swc/first-gen-vs-second-gen.mdx rename to 2nd-gen/packages/swc/.storybook/learn-about-swc/first-gen-vs-second-gen.mdx index 093979d026..812bb8aac2 100644 --- a/2nd-gen/packages/swc/.storybook/about-swc/first-gen-vs-second-gen.mdx +++ b/2nd-gen/packages/swc/.storybook/learn-about-swc/first-gen-vs-second-gen.mdx @@ -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'; @@ -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 + + + Use 2nd-gen SWC. It matches the current Spectrum guidelines and offers + better performance and consistency. + + + 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. + + + 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 - It aligns with Spectrum 2, which is the standard for new Adobe work. - Components follow more consistent design and code patterns. diff --git a/2nd-gen/packages/swc/.storybook/about-swc/overview.mdx b/2nd-gen/packages/swc/.storybook/learn-about-swc/overview.mdx similarity index 98% rename from 2nd-gen/packages/swc/.storybook/about-swc/overview.mdx rename to 2nd-gen/packages/swc/.storybook/learn-about-swc/overview.mdx index 867b54e0ef..97108adf3e 100644 --- a/2nd-gen/packages/swc/.storybook/about-swc/overview.mdx +++ b/2nd-gen/packages/swc/.storybook/learn-about-swc/overview.mdx @@ -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 diff --git a/2nd-gen/packages/swc/.storybook/learn-about-swc/when-to-use-swc.mdx b/2nd-gen/packages/swc/.storybook/learn-about-swc/when-to-use-swc.mdx new file mode 100644 index 0000000000..e4c0e17a62 --- /dev/null +++ b/2nd-gen/packages/swc/.storybook/learn-about-swc/when-to-use-swc.mdx @@ -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'; + + + +# 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: + + + + 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. + + + 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. + + + 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. + + + 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. + + + Since SWC ships as individual packages, you can install only the + components you need. This keeps your project lighter and easier to + maintain. + + + +## SWC may not be enough on its own when: + + + + 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. + + + SWC is built to match Spectrum. If your product uses patterns that do + not follow Spectrum, you may need custom components or additional + styling. + + + SWC 2nd-gen changes some APIs and patterns. Large migrations may require + planning, refactoring, or testing before you switch fully. + + + +## 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. diff --git a/2nd-gen/packages/swc/.storybook/main.ts b/2nd-gen/packages/swc/.storybook/main.ts index 2d5ea2b8b4..0fdef77996 100644 --- a/2nd-gen/packages/swc/.storybook/main.ts +++ b/2nd-gen/packages/swc/.storybook/main.ts @@ -14,7 +14,7 @@ const config = { titlePrefix: 'Components', }, { - directory: 'about-swc', + directory: 'learn-about-swc', files: '*.mdx', titlePrefix: 'About SWC', },