Category pages

About

A category page summarizes a single, complex VA service. It sits one level below My VA in the authenticated experience and one level above the feature pages that list a Veteran’s records in full.

VA.gov isn’t a system of record. A category page reads from the systems that are, and it shows a Veteran a recent slice of what those systems hold. That’s why a row can lag behind something the Veteran just did, and why some sections carry a processing state to say so.

This template documents the target state for a category page. Work is in progress toward it, so a page in production may not carry every section or behavior described here yet.

There are 4 category pages, each documented on its own page in this section:

• My HealtheVet
• Benefits
• Payments
• Forms — web only

This page holds the guidance that applies to all 4. Each sub-page covers only what its category does differently.

For the full set of page types in the authenticated experience, refer to the Authenticated home page template.

What a category page does

A category page does the same 3 jobs as My VA, scoped to one service:

1. Surface what needs a response in this category.
2. Summarize the Veteran’s records in this category, grouped by the feature they belong to.
3. Get the Veteran to the feature or task they came for.

How a category page differs from My VA

Both pages carry the same sections, but they behave differently because a category page is scoped to one service and My VA spans all of them.

Scope

My VA spans every category. A category page holds one.

What Updates shows

The same rows on both pages. My VA draws them from every category. A category page filters them to one area and groups them into record subsections, 2 at a time.

An empty section

Both keep Action required and show an empty state. Only a category page removes a section, and only a record subsection whose subject may not apply to the Veteran at all.

Alerts

My VA carries system-wide notices. A category page carries only notices scoped to that category.

Need help?

My VA lists routes that apply across VA.gov. A category page lists the desk that owns the category.

Usage

When to use this template

• For one of the 4 category pages. My HealtheVet, Benefits, Payments, or Forms.

When not to use this template

• For My VA. Use the Authenticated home page template.
• For a feature page. A feature page is the home of one tool or service, such as Appointments or Claims, and lists the Veteran’s complete set of records for it. A category page shows only the 2 most recent updates from each feature, and links to the feature page for the rest.
• For a detail page. A detail page holds a single record: one message thread, one claim, one copay bill. These are the pages that email, text, and push notifications point to.
• For an unauthenticated landing page. Use the Hub template.

Example

Each tab shows the same category page in a different state. Select a numbered marker to jump to the guidance for it. On the Default tab, every marker matches a numbered section in Structure. The Empty tab marks only the sections whose behavior changes. The Loading and Error tabs number the 2 scopes described in each, not the numbered sections. For an example filled in with real content, refer to the sub-page for each category.

Structure

Sections appear in the order shown. A category page uses only the sections it has content for, so most pages don’t carry all 9.

1. Page title — required
2. Page description — optional, discouraged
3. Category alert — conditional
4. Action required — required
5. Get started — optional
6. Updates — required
7. Record subsections — required
8. Quick access — optional
9. Need help? — required

Every category page sits inside the standard Header and Footer components, with the authenticated secondary navigation in the left column.

A category may add a section the other 3 don’t have, or shape a shared one differently. Benefits adds Enrollments. My HealtheVet carries a welcome bar in place of a page description. Check the sub-page for the category you’re working on.

Refer to Action List for how each variant behaves, what belongs in an item, and the component’s accessibility guidance. Give each list its heading through the component’s heading-text and heading-level rather than placing a separate heading element above it. The mockups on this page are built with the real component.

Choosing a section

What a piece of information is decides the section it belongs in, and the section decides the Action List variant. Work down this list and stop at the first match.

When to use Action required or Updates

• A date puts an item in Action required. A state puts it in Updates. An overpayment with a due date is an action. An open claim is a record, even though it carries dates.
• An item appears in one section, never both. An item in Action required doesn’t also appear in Updates.

When to use Get started or Quick access

Get started and Quick access are both lists of launchers, and they’re distinguished by what they hold and where they sit.

Get started

Sits between Action required and Updates. Holds top tasks with a clear entry point, so a Veteran who came to start something doesn't have to read their records first.

Quick access

Sits after Updates. Can also hold top tasks as well as links to related tools, services, and content, including pages in the unauthenticated experience.

A category page can carry both. Today Forms is the only one that carries Get started. The other 3 put their tasks in Quick access, below Updates.

Section guidance

1. Page title

Required. Names the page.

• The title is an H1. It matches the secondary navigation label and the breadcrumb exactly.
• The title may carry one primary button beside it for the task that starts new work in this category, such as filing a claim or starting a form.
• Add that button only when one task clearly outranks the others. When several tasks are peers, leave the title bare and carry them in Get started instead.

Never:

• Use a name that differs from the navigation label or the breadcrumb.

2. Page description

Optional, and discouraged. A single line under the title that describes what the page covers. None of the 4 category pages carries one today.

• Leave it out unless the page title alone doesn’t make the purpose of the page clear.
• Where it’s used, keep it to a short description of what the page is for.

Never:

• Include Veteran data, records, statuses, dates, or amounts.

3. Category alert

Conditional. A notice about the state of this category.

An alert on a category page is always scoped to that category. It tells a Veteran something about the service before they try to use it: a system that’s down, records that can’t be reached, a connection they need to set up.

Use an alert for:

• A category system that’s temporarily unavailable.
• Records this category can’t reach right now.
• A connection or enrollment the Veteran needs to complete before the page can show their records.

Never use an alert for:

• A system-wide notice. Site maintenance and VA.gov-wide outages are system-level and belong on My VA.
• A task specific to one Veteran. That’s what Action required is for.
• A receipt confirming something the Veteran just did.
• The state of a single record. An alert reports something that affects the whole category. The state of one record belongs in that record’s row.

An alert persists until the issue is resolved.

Use the Alert component with the informational, warning, or error status, matched to the impact.

4. Action required

Required. Time-sensitive items for this category only.

An item appears here because of a date. Anything with a date or deadline coming up or just passed belongs in Action required. Anything surfaced by its state instead — a refillable prescription, an active claim — belongs in a record subsection under Updates.

Those two examples are worth noting, because both look actionable and neither is. A pharmacy system marks a prescription refillable whether or not the Veteran still needs the medication, so a refill is an option, not a task. A claim is a record the Veteran waits on; the evidence request attached to it is the part they can act on, and that’s what goes in Action required.

Properties:

• Time-sensitive. The item has a deadline approaching or just passed, or an event coming up.
• Scoped to this category. An item from another category never appears here.
• Shown the same way on My VA. An item reads the same way here as it does on My VA, which gathers the same items from every category. Travel pay is the one exception, and it’s deliberate. Refer to Travel pay reads per appointment.
• Sorted by deadline, soonest first. When two items share a date, group them by feature so items from the same feature read together.
• No overlap with Updates. An item that appears in Action required doesn’t also appear in a record subsection.
• Paginated at 5. Show 5 items, then a “Show more” control for the rest.
• Unread until the Veteran opens it. Mark an item unread when the Veteran hasn’t seen it yet.
• Kept when empty. When there’s nothing to act on, the section keeps its heading and shows an empty state.

Required content for each item:

• Title. What the item is. Lead with the record’s identity, including the dollar amount where there is one: “$120.40 overpayment for Post-9/11 GI Bill,” “3 evidence requests,” “Travel pay ready to file.”
• Metadata. What the Veteran has to do, the date they have to do it by, or both: “Respond by March 4, 2026,” “Call us to update your address on file.” Keep it to 3 lines at most.
• Tag. Optional, and most items carry none. Add one only for an error, a past-due deadline, or an item that’s processing.

Never:

• Invent a deadline so an item has a date to show.
• Give the parent feature a line of its own. The title already says what the item is.
• Remove the section when there’s nothing to act on. Show the empty state instead.
• Show a processing tag on an item that isn’t in flight. The tag means the Veteran acted and the source system hasn’t caught up. It means nothing else.

How long an item stays in Action required

By default, an item appears in Action required for 30 days. This keeps the section short enough to scan and reserves it for what’s genuinely time-sensitive.

Exceptions are granted case by case. Request one when a task stays consequential well past 30 days. These exceptions are already approved, each shown with how long it appears:

Evidence requests on a claim or appeal

Indefinitely

Overpayments

Indefinitely

Form submissions that failed and need to be resubmitted

60 days

Copays don’t need an exception. A past-due copay bill rides the most recent monthly statement, so it re-surfaces inside the default window on its own.

When an item has no date

Every item needs a date to sort on, and some source systems don’t supply one. Debts over 120 days old are the case we’ve hit so far: the system reports how old the debt is but not when it started, so the date is approximated as today minus 120 days. That puts the oldest debts at the top, which is where they belong.

When you find another item with no date, work down this list and stop at the first one you can do:

1. Approximate a date from whatever the source system does report, the way the 120-day debt does.
2. Sort the item after every dated item when there’s nothing to approximate from.

An approximated date is a sort key, not a deadline. Display only a date the source system supports.

Payments and Forms shape this section differently. On Payments, an unresolved overpayment never ages out of the section. On Forms, every item is a submission that didn’t go through.

Use the Action List component’s attention variant with max-visible-count set to 5, and its empty variant when there’s nothing to act on.

5. Get started

Optional. Launchers for the top tasks a Veteran comes to this category to do.

Get started sits between Action required and Updates, so a Veteran who came to start something doesn’t have to read their records first.

• Each row names a task and leads to a clear entry point: apply for a benefit, dispute a debt, start a form, manage direct deposit.
• Include only tasks a Veteran can begin right away.
• Keep the list short. Curate it based on popularity, Veteran feedback, or both.

Never:

• Include records, status badges, or dates. These are doorways, not records. Anything with a status or a date belongs in a record subsection.
• List a full catalog. Get started holds the few tasks that matter most, not every form or tool in the category.
• Use an internal product name that a Veteran wouldn’t recognize.

Use the Action List component’s launcher variant.

6. Updates

Required. A heading over the record subsections.

Updates does one job: it separates what changed from what the Veteran can do. Actions go above it, records below. The heading carries no rows of its own.

Never:

• Put rows directly under this heading. Every record belongs to a subsection.
• Put launchers here. Tasks belong in Get started or Quick access.

7. Record subsections

Required. One subsection for each set of records the category covers.

Each subsection is an H3 under Updates, named for the records it holds. The order matches the secondary navigation, so the page and the navigation read the same way.

Properties:

• Named, never generic. “Claims and appeals status,” not “Subsection.”
• State-based, not date-based. A subsection surfaces a record because of its state — refillable, open, in progress. Any date in a row is metadata about the record, not the reason it’s there.
• A default window of 90 days, adjustable to the category. Claims may need a longer window because cases take longer to resolve. Medications change often enough that 90 days captures everything recent.
• Cut to the 2 most recent items, newest first.
• One “Show all” link per subsection, naming what it opens. The subpage and the navigation entry both have to exist.

Required content for each row:

• Title. What the row leads to, written as an action or a unique description: “Manage upcoming appointments,” “Claim for disability compensation.”
• Metadata. What’s waiting behind the row. That’s a count, such as “6 ready for refill,” or enough detail to act on, such as “Step 3 of 8” with the date the claim moved there.
• Status. Only where a row leads to one record and that record has a state. Not every row needs one.

When a subsection is empty:

• A subject that applies to every Veteran keeps its heading and shows an empty state. Intent to file is one example: any Veteran can file one.
• A subject that may not apply at all comes off the page entirely, along with its navigation entry and its subpage. Education benefits are one example. Removing it is the point, because an empty state there reports the absence of something that was never theirs.

No other section on a category page comes off the page for being empty.

Never:

• Show the full record set. That’s what the subpage is for.
• Drop a subsection whose subject applies just because it’s empty right now. The set of subsections needs to stay stable from visit to visit.
• Point a “Show all” link at a feature page that doesn’t exist. Every subsection needs a feature page behind it, and that page needs an entry in the secondary navigation. Drafts on the Forms page is a known, temporary exception: its “Show all” link opens a full list that isn’t a navigation child yet.

Use the Action List component’s summary variant, and its empty variant for a subsection that keeps its heading but has nothing to list.

8. Quick access

Optional. Launchers to related tools, services, and content, placed after Updates.

Quick access holds what a Veteran might want next, once they’ve seen what’s waiting for them. It can carry top tasks the way Get started does, and it can also carry what Get started can’t: a related tool or service, a partner site, or a page in the unauthenticated experience.

• Each row names its destination.
• Curate the list based on popularity, Veteran feedback, or both. It isn’t the same from category to category.
• Keep the list to 5 links or fewer.
• A launcher that leaves VA.gov names where it goes.

Never:

• Include records, status badges, or dates. These are doorways, not records. Anything with a status or a date belongs in a record subsection.
• Use an internal product name that a Veteran wouldn’t recognize.

Use the Action List component’s launcher variant.

9. Need help?

Required. Contact routes and hours for this category. Always the last section on the page.

• Include phone numbers with their hours and a route to Ask VA.
• Include only routes that apply to this category. Anything that applies across VA.gov belongs on My VA.
• Every category page carries this section, so a Veteran who can’t finish the task on the page always has a way to reach the desk that owns it.

Never:

• Place it among the content sections. It sits below all of them.

General guidance

Where amounts and action labels go

A dollar amount is data about a record, not a label or an action. In Action required it leads the title, as in “$65 copay bill for Medical Center Green.” In a record subsection it reads in the metadata line beneath the title.

Action labels such as “Download,” “Continue,” and “Refill” read in the row title or the metadata line too.

Refer to Action List for what’s clickable in a row, where a status tag sits and what doesn’t belong in one, and how rows wrap and reflow.

Breaking the rules

The guidance above helps teams decide how to surface information. There will be times when something is timely and important enough to break it, even though it doesn’t meet the criteria. For example, a new decision letter may be considered significant enough to put into Action required, the action being to read the decision, as it may have a significant impact on the Veteran if missed.

Content considerations

• Write an Action required item in two parts. The title names the record, and the metadata line carries the action, the date, or both. For example, “$65 copay bill for Medical Center Green” with “Due by August 5, 2026” beneath it.
• Name each record subsection the same way the secondary navigation does.
• Write “Show all” links so they name what they open. “Show all claims and appeals,” not “Show all.” A link can drop a trailing qualifier from the subsection name when that reads better, so “Claims and appeals status” opens with “Show all claims and appeals.”
• Spell out dates. Write “August 24, 2026” with no leading zero on the day. Refer to Dates and numbers for the full rules.
• Use the Veteran-facing name of a tool, not the internal product name.

Accessibility considerations

• Sections are headings, not decoration. Each section title is an H2 under the page’s H1, and each record subsection is an H3 under Updates.
• Announce content that loads after the page. When a section finishes loading or fails to load, make sure assistive technology users learn about the change. Refer to the Loading indicator and Alert components for how each handles focus and announcements.
• Don’t rely on color or position alone to communicate that an item is time-sensitive or that a record has a status.
• Keep the page and the secondary navigation in sync. When a subsection comes off the page, its navigation entry comes off too, so a Veteran is never offered a link to a page about something they don’t have.
• The page reflows. Every section stacks to a single column at 200% and 400% zoom and down to a 320px viewport, with no horizontal scrolling and no loss of content or function.

Research

The category page isn’t new thinking. It comes out of the blue sky vision for the authenticated experience presented in 2024, which was itself built on years of cumulative feedback from Veterans across VA.gov.

Two bets sit at the center of that vision:

1. Veterans want a personalized experience.
2. Veterans want to be told when something changes.

A 2025 meta-analysis tested both bets against evidence. It combined metrics on how Veterans actually use VA.gov with insights drawn from 34 earlier studies. The analysis set out to answer other questions, but it confirmed both bets along the way: Veterans ask for personalization and for notification of changes consistently, across studies and across benefits.

That’s the basis for the two sections that carry the most weight on every category page. Action required answers the first bet. Updates answers the second.

Individual categories have their own findings on top of that. Refer to the research on My HealtheVet for the usability testing behind that page.

Related

• Authenticated home page — My VA, the page above every category page
• Hub — the unauthenticated landing page for a benefit or topic area
• Help users to stay informed of their application status
• Action List
• Alert
• Loading indicator