docs(bundle): enhance README with detailed overview, usage instructions (#5836)

* docs(bundle): enhance README with detailed overview, usage instructions

* docs: update README.md for clarity and consistency

Author: blunteshwar

1st-gen/tools/bundle/README.md

@@ -1,37 +1,67 @@
-## Description
+## Overview
 
-`@spectrum-web-components/bundle` is a master dependency that allows a project to import any and all of the Spectrum Web Components. While it is a great approach to prototyping, the fact that is versions all of the Spectrum Web Components packages collectively means that depending on it can leave you with a lot of package updates to manage at any one version change. For a more predictable upgrade process we suggest that you depend upon individual packages directly, but hope you find this bundle productive when initially trying to get into the act of developing with Spectrum Web Components!
+`@spectrum-web-components/bundle` is a master dependency that allows a project to import any and all of the Spectrum Web Components. While it is a great approach to prototyping, the fact that it versions all of the Spectrum Web Components packages collectively means that depending on it can leave you with a lot of package updates to manage at any one version change. For a more predictable upgrade process we suggest that you depend upon individual packages directly, but hope you find this bundle productive when initially trying to get into the act of developing with Spectrum Web Components.
 
 ### Usage
 
 [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/bundle?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/bundle)
 [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/bundle?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/bundle)
 
-```
+```bash
 yarn add @spectrum-web-components/bundle
 ```
 
 Import the side effectful registrations of the bundled components:
 
-```
+```javascript
 import '@spectrum-web-components/bundle/elements.js';
 ```
 
 When looking to leverage their base classes as a type and/or for extension purposes, do so via something like the following for the `ActionButton` base class:
 
-```
+```javascript
 import { ActionButton } from '@spectrum-web-components/bundle';
 ```
 
-### Icons
+### Anatomy
+
+The bundle consists of several key parts:
+
+- All Spectrum Web Component elements registrations
+- Base classes for all components available for type checking and extension
+- Namespaced icon exports for UI and workflow icons (e.g., `UIIcons`, `WorkflowIcons`)
+
+### Options
 
-While this bundle directly re-exports the majority of functionality as they would be exported from their own packages, icon packages that export template literals are handled a little different. Due to the large number of exports that they feature, each of these packages are namespaced when included in the bundle.
+#### Component Registration
 
-#### UI
+Import all component registrations at once for rapid prototyping:
 
-`@spectrum-web-components/icons-ui` is renamed to `UIIcons` when leveraging the bundle. This means that you can use workflow icons in your demonstration code by importing them from `@spectrum-web-components/bundle/icons.js` like the following:
+```javascript
+import '@spectrum-web-components/bundle/elements.js';
+```
+
+This registers all available Spectrum Web Components for use in your application.
 
+#### Type Imports
+
+Import individual component classes for type checking and extension purposes:
+
+```javascript
+import { ActionButton, Button, Tooltip } from '@spectrum-web-components/bundle';
 ```
+
+### Behaviors
+
+#### Icon Handling
+
+While this bundle directly re-exports the majority of functionality as they would be exported from their own packages, icon packages that export template literals are handled differently. Due to the large number of exports that they feature, each of these packages is namespaced when included in the bundle.
+
+##### UI Icons
+
+`@spectrum-web-components/icons-ui` is renamed to `UIIcons` when leveraging the bundle. This means that you can use UI icons in your code by importing them from `@spectrum-web-components/bundle/icons.js`:
+
+```javascript
 import { UIIcons } from '@spectrum-web-components/bundle/icons.js';
 
 console.log(UIIcons.AsteriskIcon());
@@ -41,16 +71,28 @@ TemplateResult {strings: Array[1], values: Array[0], type: "html", processor: De
 ***/
 ```
 
-#### Workflow
+##### Workflow Icons
 
-`@spectrum-web-components/icons-workflow` is namespaced to `WorkflowIcons` when leveraging the bundle. This means that you can use workflow icons in your demonstration code by importing them from `@spectrum-web-components/bundle/icons.js` like the following:
+`@spectrum-web-components/icons-workflow` is namespaced to `WorkflowIcons` when leveraging the bundle. This means that you can use workflow icons in your code by importing them from `@spectrum-web-components/bundle/icons.js`:
 
-```
-import { IconsWorkflow } from '@spectrum-web-components/bundle/icons.js';
+```javascript
+import { WorkflowIcons } from '@spectrum-web-components/bundle/icons.js';
 
-console.log(IconsWorkflow.CircleIcon());
+console.log(WorkflowIcons.CircleIcon());
 
 /***
 TemplateResult {strings: Array[1], values: Array[0], type: "html", processor: DefaultTemplateProcessor, constructor: Object}
 ***/
 ```
+
+#### Version Management
+
+The bundle versions all Spectrum Web Components packages collectively. This means:
+
+- A single version bump updates all components simultaneously
+- You may receive updates for components you're not actively using
+- For production applications, consider depending on individual packages for more granular control
+
+### Accessibility
+
+All components included in the bundle follow WCAG accessibility guidelines. Each component maintains its own accessibility features as documented in their individual package documentation. Refer to the specific component documentation pages for detailed accessibility information.