From a0efc7d981144d855e4d03856673ba18e1558f2a Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:04:41 -0400 Subject: [PATCH 01/11] add release lifecycle doc --- README.md | 7 +++ RELEASE-LIFECYCLE.md | 95 +++++++++++++++++++++++++++++++++ storybook/release-lifecycle.mdx | 5 ++ 3 files changed, 107 insertions(+) create mode 100644 RELEASE-LIFECYCLE.md create mode 100644 storybook/release-lifecycle.mdx diff --git a/README.md b/README.md index 10ea04cf..ae1bc18f 100644 --- a/README.md +++ b/README.md @@ -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) (documentation) | Alpha 🔴 | +| Banner (source) (documentation) | Alpha 🔴 | +| Identifier (source) (documentation) | Alpha 🔴 | diff --git a/RELEASE-LIFECYCLE.md b/RELEASE-LIFECYCLE.md new file mode 100644 index 00000000..2e6faf37 --- /dev/null +++ b/RELEASE-LIFECYCLE.md @@ -0,0 +1,95 @@ +# 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) + * **Light DOM** + * Proposed light DOM follows declared uswds convention + * **Component matches USWDS 3** + * Visuals match USWDS 3 + * Interaction matches USWDS 3 + * Accessibility 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) \ No newline at end of file diff --git a/storybook/release-lifecycle.mdx b/storybook/release-lifecycle.mdx new file mode 100644 index 00000000..4abfe467 --- /dev/null +++ b/storybook/release-lifecycle.mdx @@ -0,0 +1,5 @@ +import { Meta, Markdown, Typeset } from "@storybook/blocks"; +import content from "../RELEASE-LIFECYCLE.md?raw" + + +{content} From 709e5f8094ed08f18c5a545c41250eb329748295 Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:18:38 -0400 Subject: [PATCH 02/11] add simple READMEs for components --- src/components/usa-banner/README.md | 2 ++ src/components/usa-link/README.md | 3 +++ 2 files changed, 5 insertions(+) create mode 100644 src/components/usa-banner/README.md create mode 100644 src/components/usa-link/README.md diff --git a/src/components/usa-banner/README.md b/src/components/usa-banner/README.md new file mode 100644 index 00000000..0e947e34 --- /dev/null +++ b/src/components/usa-banner/README.md @@ -0,0 +1,2 @@ +# Banner +This component is currently in alpha status. It is under active development, and not intended for production use. diff --git a/src/components/usa-link/README.md b/src/components/usa-link/README.md new file mode 100644 index 00000000..05391331 --- /dev/null +++ b/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. + From 349a2c8cee64eca407b3068dd537bfd3f24529ef Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:28:19 -0400 Subject: [PATCH 03/11] Add component list --- README.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ae1bc18f..c53c41ee 100644 --- a/README.md +++ b/README.md @@ -30,8 +30,7 @@ While this new version is meant to facilitate incremental adoption, the new comp 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) (documentation) | Alpha 🔴 | -| Banner (source) (documentation) | Alpha 🔴 | -| Identifier (source) (documentation) | Alpha 🔴 | +| 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | From 9a539ef8481e32e89573658473b97624b03802cf Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:30:41 -0400 Subject: [PATCH 04/11] lint fix --- README.md | 5 +- RELEASE-LIFECYCLE.md | 162 ++++++++++++++-------------- src/components/usa-banner/README.md | 1 + src/components/usa-link/README.md | 2 +- storybook/release-lifecycle.mdx | 2 +- 5 files changed, 87 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index c53c41ee..fdb7c3ef 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,8 @@ While this new version is meant to facilitate incremental adoption, the new comp 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | +| 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | diff --git a/RELEASE-LIFECYCLE.md b/RELEASE-LIFECYCLE.md index 2e6faf37..93365beb 100644 --- a/RELEASE-LIFECYCLE.md +++ b/RELEASE-LIFECYCLE.md @@ -1,95 +1,95 @@ # Component Release Lifecycle -This document describes the criteria we will use to determine each component's production readiness. +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) - * **Light DOM** - * Proposed light DOM follows declared uswds convention - * **Component matches USWDS 3** - * Visuals match USWDS 3 - * Interaction matches USWDS 3 - * Accessibility 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 +- **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) + - **Light DOM** + - Proposed light DOM follows declared uswds convention + - **Component matches USWDS 3** + - Visuals match USWDS 3 + - Interaction matches USWDS 3 + - Accessibility 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 +- **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. +- **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) \ No newline at end of file +- **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) diff --git a/src/components/usa-banner/README.md b/src/components/usa-banner/README.md index 0e947e34..aada5695 100644 --- a/src/components/usa-banner/README.md +++ b/src/components/usa-banner/README.md @@ -1,2 +1,3 @@ # Banner + This component is currently in alpha status. It is under active development, and not intended for production use. diff --git a/src/components/usa-link/README.md b/src/components/usa-link/README.md index 05391331..217b62cc 100644 --- a/src/components/usa-link/README.md +++ b/src/components/usa-link/README.md @@ -1,3 +1,3 @@ # Link -This component is currently in alpha status. It is under active development, and not intended for production use. +This component is currently in alpha status. It is under active development, and not intended for production use. diff --git a/storybook/release-lifecycle.mdx b/storybook/release-lifecycle.mdx index 4abfe467..da60caef 100644 --- a/storybook/release-lifecycle.mdx +++ b/storybook/release-lifecycle.mdx @@ -1,5 +1,5 @@ import { Meta, Markdown, Typeset } from "@storybook/blocks"; -import content from "../RELEASE-LIFECYCLE.md?raw" +import content from "../RELEASE-LIFECYCLE.md?raw"; {content} From a8039a5ad83e8c519aff5314156d494fd686a3ec Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:41:42 -0400 Subject: [PATCH 05/11] grammar fix --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index fdb7c3ef..5b198679 100644 --- a/README.md +++ b/README.md @@ -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 @@ -33,5 +33,5 @@ This is not an exhaustive list, and we expect many more big and small questions | 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | +| 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | From df914f195d8f4a616ecba558b02677bd0362d5c0 Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:46:36 -0400 Subject: [PATCH 06/11] Link to lifecycle docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5b198679..6feb31f7 100644 --- a/README.md +++ b/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/uswds-next/?path=/docs/release-lifecycle--docs) for more information on how we will determine when components are production-ready. # USWDS Web Components From c2a61f53f45831983864eac921f9f78275229f6c Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:47:22 -0400 Subject: [PATCH 07/11] lint fix --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6feb31f7..80d52ab3 100644 --- a/README.md +++ b/README.md @@ -33,5 +33,5 @@ This is not an exhaustive list, and we expect many more big and small questions | 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | +| 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | From 5af83a84e5b1e96a10ceca707d937dbaf00b5eab Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:55:22 -0400 Subject: [PATCH 08/11] Links to new Pages site --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 80d52ab3..650134df 100644 --- a/README.md +++ b/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. See our [release lifecycle documentation](https://federalist-c7964e49-2db7-4585-85f1-49d23b9329cb.sites.pages.cloud.gov/site/uswds/uswds-next/?path=/docs/release-lifecycle--docs) for more information on how we will determine when components are production-ready. +> 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 @@ -31,7 +31,7 @@ This is not an exhaustive list, and we expect many more big and small questions ## 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/uswds-next/?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/uswds-next/?path=/docs/components-link--docs)) | Alpha 🔴 | +| 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 🔴 | From 4f632fc5983f232ab244280680f58cb18725ba21 Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Tue, 13 Aug 2024 18:59:31 -0400 Subject: [PATCH 09/11] lint fix --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 650134df..00df5ae5 100644 --- a/README.md +++ b/README.md @@ -33,5 +33,5 @@ This is not an exhaustive list, and we expect many more big and small questions | 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 🔴 | +| 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 🔴 | From db149eb164f6b0cbc31000b236e489d20de1efa2 Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Wed, 14 Aug 2024 12:43:56 -0400 Subject: [PATCH 10/11] small text changes --- RELEASE-LIFECYCLE.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/RELEASE-LIFECYCLE.md b/RELEASE-LIFECYCLE.md index 93365beb..1b215f88 100644 --- a/RELEASE-LIFECYCLE.md +++ b/RELEASE-LIFECYCLE.md @@ -9,12 +9,9 @@ This document describes the criteria we will use to determine each component's p - **Requirements:** - **Accessibility** - Component passes automated accessibility tests (currently in Storybook) - - **Light DOM** - - Proposed light DOM follows declared uswds convention - **Component matches USWDS 3** - Visuals match USWDS 3 - Interaction matches USWDS 3 - - Accessibility matches USWDS 3 - Theme settings match USWDS 3 - **Storybook** - Component is integrated into Storybook From d442b7f61992759e52c9e3c378ce3fb24199c209 Mon Sep 17 00:00:00 2001 From: Matt Henry Date: Wed, 14 Aug 2024 13:19:52 -0400 Subject: [PATCH 11/11] add super basic installation docs --- storybook/getting-started.md | 28 ++++++++++++++++++++++++++++ storybook/getting-started.mdx | 6 ++++++ 2 files changed, 34 insertions(+) create mode 100644 storybook/getting-started.md create mode 100644 storybook/getting-started.mdx diff --git a/storybook/getting-started.md b/storybook/getting-started.md new file mode 100644 index 00000000..0add8a0e --- /dev/null +++ b/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 + + + +It's dangerous to go alone. Here, take this. +``` + +However, if you import components individually, your build tool may be able to help you ship less code over the wire: + +```html + + +It's dangerous to go alone. Here, take this. +``` diff --git a/storybook/getting-started.mdx b/storybook/getting-started.mdx new file mode 100644 index 00000000..f4978b6b --- /dev/null +++ b/storybook/getting-started.mdx @@ -0,0 +1,6 @@ +import { Meta, Markdown, Typeset } from "@storybook/blocks"; +import content from "./getting-started.md?raw"; + + + +{content}