Web components: Add more documentation ahead of launch

README.md

@@ -1,5 +1,5 @@
 > [!CAUTION]
-> Work on the next version of the Design System is happening in this repo. The code in this repository is not yet ready for production use.
+> Work on the next version of the Design System is happening in this repo. The code in this repository is not yet ready for production use. See our [release lifecycle documentation](https://federalist-c7964e49-2db7-4585-85f1-49d23b9329cb.sites.pages.cloud.gov/site/uswds/web-components/?path=/docs/release-lifecycle--docs) for more information on how we will determine when components are production-ready.
 
 # USWDS Web Components
 
@@ -13,7 +13,7 @@ Over the course of the next several months (and beyond), we will incrementally b
 
 ## Upgrading to Web Components
 
-We are releasing these Web Components incrementally with the intent that they can also be added incrementally to existing sites that are currently using USWDS. If you are not currently using USWDS or are using a version older USWDS 3, we recommend adopting version 3 in the near term rather than waiting until the full suite of Web Components is production-ready.
+We are releasing these Web Components incrementally with the intent that they can also be added incrementally to existing sites that are currently using USWDS. If you are not currently using USWDS or are using a version older than USWDS 3, we recommend adopting version 3 in the near term rather than waiting until the full suite of Web Components is production-ready.
 
 ## Guiding Principles
 
@@ -28,3 +28,10 @@ While this new version is meant to facilitate incremental adoption, the new comp
 - **How can we be sure the new components are as accessible as possible?** Existing USWDS components [use JavaScript to progressively enhance semantic HTML](https://designsystem.digital.gov/documentation/developers/) to make them useable to as much of the public as possible. Because web components require JavaScript by default, developing the next version of design system components will require special attention to continuing the progressive enhancement approach.
 
 This is not an exhaustive list, and we expect many more big and small questions to arise over the course of developing these components.
+
+## Components Available
+
+| Component                                                                                                                                                                                                                                                      | Release Status |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| Link ([source](https://github.com/uswds/web-components/tree/develop/src/components/usa-link)) ([documentation](https://federalist-c7964e49-2db7-4585-85f1-49d23b9329cb.sites.pages.cloud.gov/site/uswds/web-components/?path=/docs/components-banner--docs))   | Alpha 🔴       |
+| Banner ([source](https://github.com/uswds/web-components/tree/develop/src/components/usa-banner)) ([documentation](https://federalist-c7964e49-2db7-4585-85f1-49d23b9329cb.sites.pages.cloud.gov/site/uswds/web-components/?path=/docs/components-link--docs)) | Alpha 🔴       |

RELEASE-LIFECYCLE.md

@@ -0,0 +1,92 @@
+# Component Release Lifecycle
+
+This document describes the criteria we will use to determine each component's production readiness.
+
+## Alpha 🔴
+
+- **Summary:** Experimental code - likely to undergo frequent revisions. Not intended for use in projects.
+- **Intended audience:** Internal use only
+- **Requirements:**
+  - **Accessibility**
+    - Component passes automated accessibility tests (currently in Storybook)
+  - **Component matches USWDS 3**
+    - Visuals match USWDS 3
+    - Interaction matches USWDS 3
+    - Theme settings match USWDS 3
+  - **Storybook**
+    - Component is integrated into Storybook
+    - Component has basic controls that allow you customize content and variants
+  - **Documentation**
+    - Storybook autodocs available for each component
+  - **Default component text**
+    - Provide default component text in both English and Spanish
+    - Provide ability for users to add custom translation
+  - **Theming**
+    - Styles may use existing Sass/SCSS styles
+    - Component has CSS parts added to each element in the shadow DOM
+    - Component has CSS custom properties that match current uswds settings
+  - **Unit tests**
+    - Basic unit tests available (core functionality, smoke tests).
+  - **Code style**
+    - Meets all defined linting and code style standards
+
+## Beta I (Early beta) 🟠
+
+- **Summary:** Early release. Component code is moderately stable. Not intended for use in projects.
+- **Intended audience:** Testers working directly with the design system team
+- **Requirements:**
+  - **Accessibility**
+    - Passes all items in the component’s accessibility checklist.
+  - **Usability**
+    - Available for user testing?
+  - **Storybook**
+    - Full controls available for variants, content, and theming
+    - Controls follow a consistent standard across components
+    - Controls are standardized and intuitive
+    - Args match defined standard
+  - **Documentation**
+    - Enhanced documentation available in Storybook. This should document whichever of the following are available in the component:
+      - Component-specific CSS custom properties
+      - Parts
+      - Props and attributes
+      - Slots and/or expected child elements
+      - JS methods/functions
+    - The main implementation file for the component includes a JSDoc comment conforming to custom-element-manifest syntax
+  - **Default component text**
+    - Provide default component text in both English and Spanish
+    - Provide ability for users to add custom translation
+  - **Theming**
+    - Integrates user-added classes
+    - Component has the expected CSS custom properties
+    - If there is remaining Sass/SCSS, all theming is done with vanilla CSS (CSS variables and/or parts)
+  - **Unit tests**
+    - Full suite of unit tests
+  - **Internationalization/Localization**
+    - If component contains strings, they are translated to supported languages using Lit’s msg functionality
+
+## Beta II (Mature beta) 🟡
+
+- **Summary:** Can be used in projects, but might experience some breaking changes
+- **Intended audience:** Early adopters
+- **Requirements**:
+  - **Usability**
+    - No reported issues during usability testing
+  - **Framework Interoperability**.
+    - The component should have undergone some testing to ensure it can be used as expected in applications built with other frameworks. If the component uses custom events, those events should be able to pass upward to the framework. Additionally, framework components should be able to pass data to web components as props/attributes.
+  - **Internationalization/Localization**
+    - Component supports user-supplied language strings
+  - **Performance/Resilience**
+    - The component needs to have some way of mitigating or preventing Flash of Undefined Custom Element. This should take into account layout shift as well as any accessibility implications.
+
+## Production 🟢
+
+- **Summary:** Stable - Safe for production use in projects
+- **Intended audience:** General public use
+- **Requirements**:
+  - **Accessibility**:
+    - Passes all items in the component’s accessibility checklist
+    - Components have been fully tested, including with assistive technology users
+- **Usability**:
+  - Components have undergone real end-user testing
+  - Components have been tested for developer usability
+- **Documentation**: Documentation available on [designsystem.digital.gov](https://designsystem.digital.gov)

src/components/usa-banner/README.md

@@ -0,0 +1,3 @@
+# Banner
+
+This component is currently in alpha status. It is under active development, and not intended for production use.

src/components/usa-link/README.md

@@ -0,0 +1,3 @@
+# Link
+
+This component is currently in alpha status. It is under active development, and not intended for production use.

storybook/getting-started.md

@@ -0,0 +1,28 @@
+# Getting Started
+
+First, install the package from NPM (note for monthly call viewers: the package isn't published yet.)
+
+```sh
+npm install @uswds/web-components
+```
+
+Once you have the package installed, you can use the components in your project. If you import the entire package, all of the components will be available as exports.
+
+```html
+<script type="module">
+    import '@uswds/web-components';
+</script>
+
+<usa-banner></usa-banner>
+<usa-link href="https://designsystem.digital.gov">It's dangerous to go alone. Here, take this.</usa-link>
+```
+
+However, if you import components individually, your build tool may be able to help you ship less code over the wire:
+
+```html
+<script type="module">
+    import { UsaLink } from '@uswds/web-components';
+</script>
+
+<usa-link href="https://designsystem.digital.gov">It's dangerous to go alone. Here, take this.</usa-link>
+```

storybook/getting-started.mdx

@@ -0,0 +1,6 @@
+import { Meta, Markdown, Typeset } from "@storybook/blocks";
+import content from "./getting-started.md?raw";
+
+<Meta title="Getting Started" />
+
+<Markdown>{content}</Markdown>

storybook/release-lifecycle.mdx

@@ -0,0 +1,5 @@
+import { Meta, Markdown, Typeset } from "@storybook/blocks";
+import content from "../RELEASE-LIFECYCLE.md?raw";
+
+<Meta title="Release Lifecycle" />
+<Markdown>{content}</Markdown>