diff --git a/showcase/app/templates/components/application-state.hbs b/showcase/app/templates/components/application-state.hbs index 4727e347457..4f9696e1749 100644 --- a/showcase/app/templates/components/application-state.hbs +++ b/showcase/app/templates/components/application-state.hbs @@ -298,7 +298,7 @@ /> - + @@ -318,7 +318,7 @@ /> - + diff --git a/website/docs/components/application-state/index.md b/website/docs/components/application-state/index.md index 093af1feb1b..b04e1eab191 100644 --- a/website/docs/components/application-state/index.md +++ b/website/docs/components/application-state/index.md @@ -11,6 +11,7 @@ navigation: ---
+ @include "partials/guidelines/overview.md" @include "partials/guidelines/guidelines.md"
diff --git a/website/docs/components/application-state/partials/code/component-api.md b/website/docs/components/application-state/partials/code/component-api.md index f968d4af3c4..223c2193d04 100644 --- a/website/docs/components/application-state/partials/code/component-api.md +++ b/website/docs/components/application-state/partials/code/component-api.md @@ -3,6 +3,9 @@ ### ApplicationState + + `ApplicationState::Media` yielded as contextual component (see below). + `ApplicationState::Header` yielded as contextual component (see below). @@ -19,6 +22,19 @@ ### Contextual components +#### [A].Media + +The `ApplicationState::Media` component, yielded as contextual component. + + + + Elements passed as children are yielded as inner content of the "media" block. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + + + #### [A].Header The `ApplicationState::Header` component, yielded as contextual component. @@ -30,7 +46,12 @@ The `ApplicationState::Header` component, yielded as contextual component. Adds a leading icon to the title. Accepts any [icon](/icons/library) name. - + + The text of the title + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + #### [A].Body @@ -39,10 +60,13 @@ The `ApplicationState::Body` component, yielded as contextual component. - Supports block invocation for custom content (see [Block Content](https://guides.emberjs.com/release/components/block-content/) in Ember docs). + Elements passed as children are yielded as inner content of the "body" block. - Note: use `@text` for an inline invocation only. This component does not support `@text` on the component invocation if it is used as a block. + Note: use `@text` to pass directly text to the "body", with a predefined style. This component does not support `@text` on the component invocation if it is used with yielded content. + + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). @@ -51,10 +75,16 @@ The `ApplicationState::Body` component, yielded as contextual component. The `ApplicationState::Footer` component, yielded as contextual component. - - Indicates if there should be a visible divider above the footer. + + The `Button` component, yielded as contextual component inside the `"footer"` block of the ApplicationState. It exposes the same API as the [`Button` component](/components/button). + + + The `Dropdown` component, yielded as contextual component inside the `"footer"` block of the ApplicationState. It exposes the same API as the [`Dropdown` component](/components/dropdown). The `Link::Standalone` component, yielded as contextual component inside the `"footer"` block of the ApplicationState. It exposes the same API as the [`Link::Standalone` component](/components/link/standalone). + + This component supports use of [`...attributes`](https://guides.emberjs.com/release/in-depth-topics/patterns-for-components/#toc_attribute-ordering). + diff --git a/website/docs/components/application-state/partials/code/how-to-use.md b/website/docs/components/application-state/partials/code/how-to-use.md index 7699ffbcc81..266a968a6e7 100644 --- a/website/docs/components/application-state/partials/code/how-to-use.md +++ b/website/docs/components/application-state/partials/code/how-to-use.md @@ -33,37 +33,49 @@ This component intends to replace a few different simple error and empty/zero st ``` -#### Empty state with a footer link and divider +#### Empty state with yielded body block ```handlebars - - - + + + + + ``` -#### Empty state with yielded body block +#### Empty state with body text ```handlebars - - - + ``` -#### Empty state with body text +#### Empty state with center alignment + +```handlebars + + + + + + + +``` + +#### Empty state with media ```handlebars + portrait of a cat wearing coat and tie @@ -124,19 +136,37 @@ To indicate that the message is an error state, add `@errorCode` to the `[A].Hea ``` -#### Error state with a footer divider +#### Error state with center alignment + +```handlebars + + + + + + + + +``` + +#### Error state with media ```handlebars + portrait of a cat wearing coat and tie - + - + -``` \ No newline at end of file +``` diff --git a/website/docs/components/application-state/partials/guidelines/guidelines.md b/website/docs/components/application-state/partials/guidelines/guidelines.md index 9616f856119..f565b06ce5b 100644 --- a/website/docs/components/application-state/partials/guidelines/guidelines.md +++ b/website/docs/components/application-state/partials/guidelines/guidelines.md @@ -2,28 +2,117 @@ ### When to use -- When a user’s action does not yield any results due to incorrect or incomplete input. - When an application encounters an issue or error during its operation. +- When emphasis is needed on the creation of a new object within a null state. ### When not to use - When the absence of content is expected and does not require an explanation to the user. - When there is a clear and intuitive way to add or populate content. -## Icon +## Alignment -- The icon should align with the purpose of the content and effectively communicate the same message. +The Application State supports two alignment options: `left` (default) and `center`. The alignment affects text alignment, action placement/alignment in the footer, and media placement; however, it does not change the default page alignment. -## Actions +!!! Info -- In the footer, you can include up to two stand-alone links. -- We don’t recommend using buttons, as most actions will navigate the user away from this page. Learn more about [when to use a link vs. a button](https://helios.hashicorp.design/components/link/standalone#usage). -- For the standalone link, we recommend using the medium size. -- Use footer actions to redirect or guide users in solving errors/access issues with actionable steps. +By default, the Application State has horizontal auto margins applied to it, always centering it on the page or containing element. This can be overridden with CSS properties. -## Content +!!! -- The title should be short and provide a clear and concise message. -- Focus on relevant information and avoid unnecessary details. -- Provide a straightforward explanation of the problem or error. -- Include suggestions or guidance for how the user can resolve the issue, if possible. +### Left alignment + +![Left aligned application state](/assets/components/application-state/application-state-alignment-left.png) + +### Center alignment + +![Center aligned application state](/assets/components/application-state/application-state-alignment-center.png) + +## Media + +The media slot is used to add illustrations to increase the visual impact of the Application State. + +This provides additional visual prominence while also elevating the brand experience. If the illustration has a circular container, we recommend setting the `alignment` to `center`. + +![Empty state for Vault Secrets, guiding user to create new secrets or importing them](/assets/components/application-state/application-state-media-slot-spot-illustration-center-alignment.png) + + +## Header + +### Icon + +When set, the icon is displayed side by side with the title. + +![Showing an icon left of the title, with some body text below it.](/assets/components/application-state/application-state-icon-usage.png) + +This is commonly used when displaying an error state for application failures. The icon must always be accompanied by a title. + +### Title + +The title should be short and provide a clear and concise message. + +### Error code + +If enabled and available, an error code will be shown, providing additional information associated with the title. + +## Body + +Focus on relevant information and avoid unnecessary details. If there is an error, include suggestions or guidance for how the user can resolve the issue, if possible. If no objects are found (zero/empty state), provide a brief explanation on how creating this new object will benefit the user. + +The body allows for two types of content: `text` and `generic`. + +![Showing two different kind of body content types, one as text and another as generic yielded content](/assets/components/application-state/application-state-body-content-types.png) + + +## Footer +The Application State supports up to three actions, including [Dropdown](/components/dropdown), [Standalone Link](/components/link/standalone), and [Button](/components/button) components. Use footer actions to help users resolve errors or access issues with actionable steps. + +![A button set showing a dropdown, secondary button, and stand alone link](/assets/components/application-state/application-state-footer-action-types.png) + +### Using buttons or links + +Buttons, along with links, are the most common actions used in the footer. Buttons are more often used in empty state contexts because they provide high visibility for the primary action on the page. Links are more common in error state contexts as a means to provide a solution to the error they encountered. + +Read more about when to use [Buttons](/components/button) and [Links](/components/link/standalone). + +!!! Dont + +When there is an empty state that occupies the majority of the page, do not display two similar actions in different areas of the UI. In this example, there is a primary button in the Page Header and in the Application State. + +![Showing an empty state with a primary button and a page header with a primary button](/assets/components/application-state/application-state-empty-state-dont-duplicate-buttons.png) + +!!! + +!!! Do + +Instead, use the Application State as the only means of drawing attention to the primary action. + +![Showing an empty state with a primary button with a page header with out a primay button](/assets/components/application-state/application-state-empty-state-do-keep-one-primary-cta.png) + +!!! + +### Using dropdowns + +Dropdowns can be used as actions in the footer in rare cases. Limit dropdowns to one per Application State. + +![Showing an empty state with a primary button with a page header with out one](/assets/components/application-state/application-state-dropdown-actions.png) + +## Width constraints + +The Application State’s content has a max width of 480 pixels. This is done for better readability, ensuring that the max character count is close to 70 characters per line. + +## Examples + +Here are some common use cases for the Application State, however, it is not limited to just these two examples. + +### Error state + +Error states are used when the application encounters an issue or error during its operation. It shows the associated error code, icon, messages, and actions to help users find a solution. + +![Showing an example of an error state with a 404 error code and two links](/assets/components/application-state/application-state-error-state.png) + +### Empty state + +An empty state occurs when a user has yet to create an object. Illustrations are placed using the `media` slot to further elevate the experience and express the purpose of the object. + +![Showing an empty state with a primary and secondary button along with a stand alone link](/assets/components/application-state/application-state-empty-state.png) \ No newline at end of file diff --git a/website/docs/components/application-state/partials/guidelines/overview.md b/website/docs/components/application-state/partials/guidelines/overview.md new file mode 100644 index 00000000000..7b626210f62 --- /dev/null +++ b/website/docs/components/application-state/partials/guidelines/overview.md @@ -0,0 +1 @@ +The Application State is used to communicate status, errors, and zero/empty states. \ No newline at end of file diff --git a/website/docs/components/application-state/partials/specifications/anatomy.md b/website/docs/components/application-state/partials/specifications/anatomy.md index c3ade3e3021..7d5f95a38e6 100644 --- a/website/docs/components/application-state/partials/specifications/anatomy.md +++ b/website/docs/components/application-state/partials/specifications/anatomy.md @@ -4,10 +4,10 @@ | Element | Usage | |------------------|-------------------------------------------------| +| Media | Optional. | | Title | Required. | | Icon | Optional, but recommended with errorCode. | | errorCode | Optional, but recommended when in errorState. | | Body | Required. | -| Separator | Optional, but recommended when separating actions from content. | | Footer | Optional. | -| Action | Required, if no footer; optional. | \ No newline at end of file +| Actions | Required, if no footer; optional. | \ No newline at end of file diff --git a/website/public/assets/components/application-state/application-state-alignment-center.png b/website/public/assets/components/application-state/application-state-alignment-center.png new file mode 100644 index 00000000000..4f554990b79 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-alignment-center.png differ diff --git a/website/public/assets/components/application-state/application-state-alignment-left.png b/website/public/assets/components/application-state/application-state-alignment-left.png new file mode 100644 index 00000000000..a371fdae81b Binary files /dev/null and b/website/public/assets/components/application-state/application-state-alignment-left.png differ diff --git a/website/public/assets/components/application-state/application-state-anatomy-page.png b/website/public/assets/components/application-state/application-state-anatomy-page.png index 71951df5c91..91a3db5d717 100644 Binary files a/website/public/assets/components/application-state/application-state-anatomy-page.png and b/website/public/assets/components/application-state/application-state-anatomy-page.png differ diff --git a/website/public/assets/components/application-state/application-state-body-content-types.png b/website/public/assets/components/application-state/application-state-body-content-types.png new file mode 100644 index 00000000000..4387e7db402 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-body-content-types.png differ diff --git a/website/public/assets/components/application-state/application-state-dropdown-actions.png b/website/public/assets/components/application-state/application-state-dropdown-actions.png new file mode 100644 index 00000000000..c8462b0fe7b Binary files /dev/null and b/website/public/assets/components/application-state/application-state-dropdown-actions.png differ diff --git a/website/public/assets/components/application-state/application-state-empty-state-do-keep-one-primary-cta.png b/website/public/assets/components/application-state/application-state-empty-state-do-keep-one-primary-cta.png new file mode 100644 index 00000000000..4ed668962b7 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-empty-state-do-keep-one-primary-cta.png differ diff --git a/website/public/assets/components/application-state/application-state-empty-state-dont-duplicate-buttons.png b/website/public/assets/components/application-state/application-state-empty-state-dont-duplicate-buttons.png new file mode 100644 index 00000000000..a74d45d172b Binary files /dev/null and b/website/public/assets/components/application-state/application-state-empty-state-dont-duplicate-buttons.png differ diff --git a/website/public/assets/components/application-state/application-state-empty-state.png b/website/public/assets/components/application-state/application-state-empty-state.png new file mode 100644 index 00000000000..6ef8028c2b8 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-empty-state.png differ diff --git a/website/public/assets/components/application-state/application-state-error-state.png b/website/public/assets/components/application-state/application-state-error-state.png new file mode 100644 index 00000000000..41126280e7c Binary files /dev/null and b/website/public/assets/components/application-state/application-state-error-state.png differ diff --git a/website/public/assets/components/application-state/application-state-footer-action-types.png b/website/public/assets/components/application-state/application-state-footer-action-types.png new file mode 100644 index 00000000000..aded3e74f31 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-footer-action-types.png differ diff --git a/website/public/assets/components/application-state/application-state-icon-usage.png b/website/public/assets/components/application-state/application-state-icon-usage.png new file mode 100644 index 00000000000..0a241f606e2 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-icon-usage.png differ diff --git a/website/public/assets/components/application-state/application-state-media-slot-icon-tile-center-alignment.png b/website/public/assets/components/application-state/application-state-media-slot-icon-tile-center-alignment.png new file mode 100644 index 00000000000..868aef1ad8c Binary files /dev/null and b/website/public/assets/components/application-state/application-state-media-slot-icon-tile-center-alignment.png differ diff --git a/website/public/assets/components/application-state/application-state-media-slot-spot-illustration-center-alignment.png b/website/public/assets/components/application-state/application-state-media-slot-spot-illustration-center-alignment.png new file mode 100644 index 00000000000..496bd2e9020 Binary files /dev/null and b/website/public/assets/components/application-state/application-state-media-slot-spot-illustration-center-alignment.png differ diff --git a/website/public/assets/components/application-state/application-state-media-slot.png b/website/public/assets/components/application-state/application-state-media-slot.png new file mode 100644 index 00000000000..9bba981be5f Binary files /dev/null and b/website/public/assets/components/application-state/application-state-media-slot.png differ