Skip to content

Commit 21d6b9d

Browse files
Merge pull request #3840 from department-of-veterans-affairs/298/manage-benefits-tools-docs
Add page for pattern: Manage benefits and tools, and component: Service List Item
2 parents 3a9bb57 + 9ef4346 commit 21d6b9d

File tree

10 files changed

+267
-0
lines changed

10 files changed

+267
-0
lines changed

src/_components/service-list-item.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
layout: component
3+
title: Service list item
4+
intro-text: The Service list item summarizes a benefit or tool. For example, a Service list item could show the most important details about an appointment, prescription, or benefit. It shows high-level details, offers a link to view more information, and can alert the user to any actions that need to be taken. It is always displayed in a list, as described in the “Help users to… Manage benefits and tools” pattern.
5+
status: use-with-caution-candidate
6+
research-title: Service list item
7+
figma-link: https://www.figma.com/design/ZIGDfSb8D5YLBdJavzDdqi/AE-Design-Patterns---Service-list?node-id=1-129&t=52qYQM9JQBOPO71q-1
8+
contributors: Lynn Stahl (Agile Six), Adam Whitlock (Ad Hoc), Belle Poopongpanit (Agile Six), Christine Rose Steiffer (Agile Six), Kristen Faiferlick (Ad Hoc)
9+
draft: true
10+
web-component: va-service-list-item
11+
anchors:
12+
- anchor: Examples
13+
- anchor: Usage
14+
- anchor: Code usage
15+
- anchor: Content considerations
16+
- anchor: Accessibility considerations
17+
- anchor: Related
18+
- anchor: Component checklist
19+
---
20+
21+
## Examples
22+
Storybook previews are coming shortly
23+
24+
### With only the required elements (header, status, details)
25+
26+
{% include component-example.html alt="A set of information—designed to be shown within a list—that contains a header, a status tag, and one set of data formatted as a “Label: Value” pair." file="/images/components/service-list-item/service-list-item-minimal.png" class="x2" %}
27+
28+
### With the Critical information component
29+
30+
{% include component-example.html alt="A set of information—designed to be shown within a list—that contains a header, a bright call to action, a status tag, and four sets of data formatted as “Label: Value” pairs." file="/images/components/service-list-item/service-list-item-critical-action.png" class="x2" %}
31+
32+
### With the optional link
33+
34+
{% include component-example.html alt="A set of information—designed to be shown within a list—that contains a header, a status tag, four sets of data formatted as “Label: Value” pairs, and a link." file="/images/components/service-list-item/service-list-item-link.png" class="x2" %}
35+
36+
37+
38+
### With all possible elements
39+
40+
{% include component-example.html alt="A set of information—designed to be shown within a list—that contains a header, a bright call to action, a status tag, four sets of data formatted as “Label: Value” pairs, and a link." file="/images/components/service-list-item/service-list-item-all-info.png" class="x2" %}
41+
42+
## Usage
43+
44+
### Terms
45+
46+
* **Benefit**: Aid or assistance provided by VA to Veterans, family members, or caretakers. Examples include health care, education and training, disability compensation, life insurance, and pension.
47+
* **Tool**: A digital product that Veterans, family members, or caretakers use to manage benefits. Examples include appointments, prescriptions, payments, secure messages, and claims.
48+
* **Service**: A term used to describe both benefits and tools.
49+
* **Service list**: A list of services. The [“Help users to… Manage benefits and tools” pattern]({{ site.baseurl }}/patterns/help-users-to/manage-benefits-and-tools) describes how to build a Service list.
50+
* **Service list item**: An item in a service list. Each item contains a summary of the benefit or tool, with a link to for the user to get more information. This component explains how to use and build a Service list item.
51+
52+
### When to use Service list item
53+
54+
* **When you want to show benefits or tools the user is currently enrolled in or has access to.**
55+
56+
### When not to use Service list item
57+
58+
* **When you are representing items that are neither a benefit nor a tool.** Do not use the same visual appearance or structured data to represent items that are not a benefit nor a tool. If you want to group short, related pieces of information that are not benefits or tools, consider using the [Card component]({{ site.baseurl }}/components/card).
59+
* **When you want to put links, radio buttons, or checkboxes in a container.** There are some components that have variations with containers around them. These might look like Service list items, but they are distinct. Service list items are exclusively for benefits and tools, offer a brief snapshot of information, and link to another page with more details. The guidance within the [Not a card]({{ site.baseurl }}/components/card#not-a-card) section of the Card component also applies to the Service list item.
60+
* **When you want to show benefits within a form.** Do not use this component to show benefits or services in an interactive list with checkboxes or other selection methods.
61+
* **When you want to display content in an unordered list.** Content that can be shared with bullet points should use an unordered list. Find more information in the [List component]({{ site.baseurl }}/components/list) and the [Bulleted list style guide]({{ site.baseurl }}/content-style-guide/bulleted-lists).
62+
63+
### Anatomy or layout details
64+
65+
{% include component-example.html alt="An annotated Service list item, calling out the header, critical information, status, details, and link." file="/images/components/service-list-item/annotated-service-list-item-component.png" %}
66+
67+
A Service list item can have:
68+
69+
* Header (required)
70+
* The header consists of an icon (optional), header text, and chevron. These elements combine to create a link to a page with more details about the benefit or tool. All Service list items must link to a details page from the header.
71+
* Headers should be visually consistent in each list item within the list. For example, if some list item headers have icons, all list items in the list should have icons.
72+
* The header has a default, hover, active, focus, and visited state. See details in the [Header states section](#header-states) below.
73+
* Status (required)
74+
* Status must be represented by a gray Tag component.
75+
* Every benefit or tool in a list has a set of internal states, which are used to track the progress of enrolling in that benefit or using that tool. A status is the way to communicate the item's state to the user (such as Active, Pending, etc).
76+
* Statuses do not have to mirror internal states in a one-to-one manner. (They can, but they are not required to.) Every state change does not necessarily warrant a status change.
77+
* Critical information
78+
* This component is still under development. It navigates the user to the most direct path to take action on the critical information. Future updates will include adjustments to color contrast, focus states, and more.
79+
* Details (required)
80+
* The details provide users with helpful information, formatted in a “Label: Value” structure (for example, “Approved on: May 5, 2011”).
81+
There can be anywhere from one to five lines of “Label: Value” pairs.
82+
* Link (optional)
83+
* Some service list items might require an additional link, in addition to the details page linked to from the header and the actionable link offered in the Critical information component. In these cases, one additional link may be displayed at the bottom of the Service list item.
84+
The link should use the standard default, hover, focus, active, and visited link states.
85+
86+
### Header states
87+
* Default: The link and chevron are the standard vads-color-link.
88+
* Hover: The link becomes underlined and both the link and chevron turn to vads-color-link-active. There is no background shading.
89+
* Focus: Similar to the default state, but with a yellow outline. The outline is similar to the focus state of action links.
90+
* Active: Similar to the default state, but underlined and with a yellow outline. The outline is similar to the focus state of action links.
91+
* Visited: Similar to the default state, but the color of the link and chevron turn to vads-color-link-visited once the link has been visited.
92+
93+
{% include component-example.html alt="A table of headers for the Service list item. There are two columns, one for mobile and one for desktop. The five rows show each of the states described above: default, hover, focus, active and visited." file="/images/components/service-list-item/annotated-service-list-item-header-states.png" %}
94+
95+
## Code usage
96+
97+
(Coming soon)
98+
99+
## Content considerations
100+
Teams used the Card component before this component existed. When evaluating if your team needs to use Service list items instead of cards, consider if your content is either a “benefit” or “tool,” as defined in the [Usage](#usage) section.
101+
102+
Statuses should be normalized with CAIA so that the same terms are used when the same meanings are intended (for example, “pending” versus “in-progress”). CAIA will define which of those is correct across benefits and tools.
103+
104+
## Accessibility considerations
105+
106+
Review the accessibility concerns section of the following components:
107+
* [Card]({{ site.baseurl }}/components/card#accessibility-considerations)
108+
* [List]({{ site.baseurl }}/components/list#accessibility-considerations)
109+
* [Link]({{ site.baseurl }}/components/link/#accessibility-considerations)
110+
* [Link - Action]({{ site.baseurl }}/components/link/action#accessibility-considerations)
111+
* [Tag]({{ site.baseurl }}/components/tag#accessibility-considerations)
112+
* Critical information (link coming soon)
113+
114+
## Related
115+
116+
Service list item may be confused with several other components:
117+
* [List]({{ site.baseurl }}/components/list): See [When not to use Service list item]({{ site.baseurl }}/components/service-list-item#when-not-to-use-service-list-item) for information on when to use a list instead of a Service list item.
118+
* [Card]({{ site.baseurl }}/components/card): See [When not to use Service list item]({{ site.baseurl }}/components/service-list-item#when-not-to-use-service-list-item) and [Content considerations]({{ site.baseurl }}/components/service-list-item#content-considerations) for information on when to use a card instead of a Service list item.
119+
120+
The below components are nested within the Service list item component:
121+
* Critical information (NEW; link coming soon)
122+
* [Tag]({{ site.baseurl }}/components/tag)
123+
* [Link]({{ site.baseurl }}/components/link/)
124+
125+
{% include _component-checklist.html component_name="va-service-list-item" %}
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
maturity:
2+
- name: guidance
3+
score: false
4+
- name: research
5+
score: false
6+
- name: stability
7+
score: false
8+
- name: adoption
9+
score: false
10+
code-assets:
11+
- name: variations
12+
score: false
13+
- name: responsive
14+
score: false
15+
- name: interactive-states
16+
score: false
17+
- name: tokens
18+
score: false
19+
- name: internationalization
20+
score: false
21+
visual-assets:
22+
- name: variations
23+
score: false
24+
- name: responsive
25+
score: false
26+
- name: interactive-states
27+
score: false
28+
- name: tokens
29+
score: false
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
layout: pattern
3+
title: Manage benefits and tools
4+
draft: true
5+
permalink: /patterns/help-users-to/manage-benefits-and-tools
6+
aka: Service list
7+
contributors: Lynn Stahl (Agile Six), Adam Whitlock (Ad Hoc), Belle Poopongpanit (Agile Six), Christine Rose Steiffer (Agile Six), Kristen Faiferlick (Ad Hoc)
8+
sub-section: help-users-to
9+
intro-text: Follow this pattern to help users manage their benefits and tools.
10+
figma-link: https://www.figma.com/design/ZIGDfSb8D5YLBdJavzDdqi/AE-Design-Patterns---Service-list?node-id=1-129&t=ndStAutrvUcgt5Um-1
11+
github-title: manage-benefits-and-tools
12+
research-title: Help users to manage benefits and tools
13+
status: use-with-caution-available
14+
anchors:
15+
- anchor: Usage
16+
- anchor: How to design and build
17+
- anchor: Examples
18+
- anchor: Code usage
19+
- anchor: Content considerations
20+
- anchor: Accessibility considerations
21+
- anchor: Research findings
22+
---
23+
24+
## Usage
25+
26+
### Terms
27+
28+
* **Benefit**: Aid or assistance provided by VA to Veterans, family members, or caretakers. Examples include health care, education and training, disability compensation, life insurance, and pension.
29+
* **Tool**: A digital product that Veterans, family members, or caretakers use to manage benefits. Examples include appointments, prescriptions, payments, secure messages, and claims.
30+
* **Service**: A term used to describe both benefits and tools.
31+
* **Service list**: A list of services. This pattern articulates how to design a Service list.
32+
* **Service list item**: An item in a service list. Each item contains a summary of the benefit or tool, with a link to for the user to get more information. See more details in the [Service list item component]({{ site.baseurl }}/components/service-list-item).
33+
34+
### When to use this pattern
35+
36+
* **When you are using the [Service list item]({{ site.baseurl }}/components/service-list-item) component.**
37+
* **When you want to show benefits or tools the user is currently enrolled in or has access to.**
38+
39+
### When not to use this pattern
40+
41+
* **When you are representing items that are neither a benefit nor a tool.** Do not use the same visual appearance or structured data to represent items that are not a benefit nor a tool.
42+
* **When you want to show benefits within a form.** Do not use this pattern to show benefits or services in an interactive list with checkboxes or other selection methods.
43+
* **When you want to display content in an unordered list.** Content that can be shared with bullet points should use an unordered list. Find more information in the [List component](https://design.va.gov/components/list) and the [Bulleted list style guide](https://design.va.gov/content-style-guide/bulleted-lists).
44+
45+
## Design Principles
46+
47+
* **Scannable—limited amount of information per list object**: The job of the list view is to display a summary of the object, not the entire object.
48+
* **Consistency of content and hierarchy**: The content should be consistent from item to item in the list and show the same types of information in each list item. For example, in a list of appointments, every appointment should have the same details (time, date, status, appointment type, etc.).
49+
* **Consistent implementation of supporting functionality**: If used, sort or filter functionality should interact the same despite different needs. For example, one list might sort items by date while another sorts items alphabetically, but the interaction should work the same.
50+
51+
## How to design and build
52+
53+
### How this pattern works
54+
55+
This pattern vertically stacks Service list items to form a list, called a “Service list.” As noted in the [Service list item component]({{ site.baseurl }}/components/service-list-item), the user can access a page with more details about each list item by clicking or tapping on the header. Various other elements of the list item–such as a Critical information component, and status–all convey additional information to the user. View more information about these elements and their interactivity in the Service list item component.
56+
57+
### Display order
58+
59+
* List items should be displayed in an order that best suits the content. Common options include ordering alphabetically or by date. Check with subject matter experts and consider running usability studies to confirm the most appropriate display order for your content.
60+
61+
* Note that when list items include a Critical information component (coming soon), these items should be displayed at the top of the list, regardless of the chosen display order. This avoids burying items that need review or action at the bottom of a list or on a subsequent page.
62+
63+
### Components used in this pattern
64+
65+
* [Service list item (NEW)]({{ site.baseurl }}/components/service-list-item)
66+
* Critical information (NEW; link coming soon)
67+
* [Tag component](https://design.va.gov/components/tag])
68+
69+
## Examples
70+
71+
### Benefits
72+
73+
Below are some potential benefits a Veteran or family member may enroll in, which might use this pattern:
74+
75+
* Burials
76+
* Careers and employment
77+
* Disability compensation
78+
* Education
79+
* Housing assistance
80+
* Life Insurance
81+
* Pension
82+
* Vocational rehabilitation (VRE)
83+
84+
{% include component-example.html alt="A list of benefits a Veteran is currently enrolled in. Two of the benefits have critical information components shown, linking the user to a page where they can take important actions." file="/images/patterns/help-users-to/manage-benefits-and-tools/service-list-example.png" caption="An example of how this pattern can be applied to help users navigate and learn about their benefits." %}
85+
86+
### Tools
87+
88+
Below are some tools that a Veteran, family member, or caretaker may use to manage a Veteran’s benefits, which might use this pattern:
89+
90+
* Appointments
91+
* Claims
92+
* Forms
93+
* Letters
94+
* Medical records
95+
* Payments
96+
* Prescriptions
97+
* Secure messages
98+
99+
## Code usage
100+
101+
(Link coming soon)
102+
103+
## Content considerations
104+
105+
Statuses should be normalized with CAIA so that the same terms are used when the same meanings are intended (for example, "pending" versus "in-progress"). CAIA will define which of those is correct across across benefits and tools.
106+
107+
## Accessibility considerations
108+
109+
Review the accessibility considerations for the [Service list item component]({{ site.baseurl }}/components/service-list-item#accessibility-considerations).
110+
111+
## Research findings
112+
113+
[Secondary research](https://github.com/department-of-veterans-affairs/va.gov-research-repository/issues/810) suggests that users view lists positively and should be able to navigate through them with relative ease. This particular pattern has not yet been tested directly with users.
Loading
Loading
Loading
Loading
Loading
Loading
Loading

0 commit comments

Comments
 (0)