Naming conventions

Purpose

This document establishes a consistent approach to naming components in the VA Design System. These guidelines apply to both the web component implementation (component-library) and the design system documentation site (vets-design-system-documentation).

Core Principles

1. Clarity and Purpose: Names should clearly describe the component’s purpose and functionality.
2. Consistency: Follow consistent patterns across the entire system.
3. Developer Experience: Names should be intuitive for technical implementation.
4. Scalability: The naming system should scale as new components are added.

Component naming rubric

Apply these rules in order when naming a new component or proposing a rename. When two rules conflict, the earlier rule wins.

1. Name the thing, not where it sits. Don’t encode page placement or orientation in a component name. Placement changes over time and the same treatment often appears in more than one place. Purpose doesn’t change.
2. Avoid contested or product-specific vocabulary. Don’t build a component name around a term that means different things in different VA products, or that’s under active review for user-facing content. A “step” is a single page in some VA forms and a chapter of many pages in others, so “step” isn’t a safe word to freeze into an API.
3. Use the established name. Among the names that satisfy the rules above, choose the one already in common use. If the component exists as a generic tool on the web, share that name. Prefer the U.S. Web Design System name first, then the name used across other major design systems.
4. Variants append to their base. New components use the ordinary term. A variant of an existing component appends its modifier to the base name: va-button-icon, documented as “Button - Icon”. A new component uses the ordinary name for the thing: va-process-list, documented as “Process List”.
5. Only append to a base that exists. Don’t invent a parent component so that related components group together in the index. va-nav-side and va-nav-progress would imply a va-nav base that doesn’t exist, and a side navigation and a form progress indicator share no API, accessibility semantics, or content model. Group components that merely share a topic in the components index and the collection folder, not in the name.
6. A component name is not a user-facing label. Component names are an API for designers and developers. The words a Veteran reads are a content decision, informed by research and the content principles. A component’s default labels, example content, and Storybook stories do influence what teams ship, so review those separately from the name.
7. Names are contracts. Renaming a published component breaks every team using it. Rename only with a documented alias, a deprecation period, and a design decision recording the rationale.

Grandfathered names

These components place the modifier before the base name and predate these rules. Don’t use them as models for new names, and don’t rename them without a deprecation path. Compare va-header-minimal, which follows the convention, with va-minimal-footer, which doesn’t. These names are tech-debt that the team will rectify over time.

• va-crisis-line-modal
• va-maintenance-banner
• va-minimal-footer
• va-official-gov-banner
• va-segmented-progress-bar
• va-sidenav

General naming guidelines for VADS

Names for components and templates

Pattern and template names should follow the VA content principles where possible, and should be consistent, clear, and user-focused. Component names are an API for designers and developers, not a user-facing label — see rule 6 of the Component naming rubric.

Read the complete VA content principles

Component names and template names should be short and succinct while still relaying necessary information to the user. While 1-2 words is ideal, there are exceptions, such as the On This Page component, where longer names are necessary for clarity.

If the component or template exists as a generic tool on the web (e.g., accordions), then the VADS component or template should share that name.

Names for patterns

Pattern names follow a two-step format, separated into two categories:

• Ask Users for…
• Help Users to…

The specific pattern name should then be a continuation of that first step. For example:

• Ask Users for Files
• Help Users to Sign In

Consistency in naming

Component, template, and pattern names should be consistent between documentation and code. For example, if a component is named “Memorable Date” in the guidance, the name in code should be memorable-date for consistency and ease of use.

Component Naming Guidelines

Web Component Implementation

Folder and File Structure

• Component folders should use kebab-case (e.g., action-bar, form-controls)
• Component files should follow consistent naming patterns (e.g., va-alert.tsx, va-modal.tsx)
• Helper files should use camelCase (e.g., alertUtils.js, modalHelpers.js)

Web Component Names

• Custom HTML elements should use kebab-case with va- prefix (e.g., <va-alert>, <va-modal>, <va-pagination>)
• The prefix va- should be used consistently for all components to indicate they are part of the VA Design System
• Make names concise and descriptive, avoiding acronyms where possible

Attributes

• Attributes in web components should use kebab-case (e.g., close-handler, is-visible, button-text)
• Boolean attributes should follow HTML convention where presence indicates true (e.g., disabled, required, closeable)
• Boolean attributes that need explicit values should use “is-“, “has-“, or “should-“ prefixes (e.g., is-disabled, has-error, should-validate)

Slots and Shadow DOM

• Named slots should use kebab-case (e.g., <slot name="header-content">)
• Internal shadow DOM class names should use Block Element Modifier (BEM) notation with kebab-case:
  • Block: .va-component-name
  • Element: .va-component-name__element
  • Modifier: .va-component-name--modifier or .va-component-name__element--modifier
• NOTE: The shadow DOM of web components encapsulates CSS so that BEM is unnecessary to scope styles, however it is useful for semantic and hierarchical clarity.

Documentation Site

Front Matter Component Names

• In the front matter YAML, specify the actual web component name with the va- prefix in kebab-case

• Example:

  title: Alert - Expandable
  web-component-name: va-alert-expandable
  

Page Titles and Display Names

• Convert kebab-case web component names to Title Case with spaces for page titles
• Use plain language titles that are more human-readable
• Examples:
  • <va-alert-expandable> becomes “Alert - Expandable”
  • <va-text-input> becomes “Text Input”
  • <va-checkbox> becomes “Checkbox”

URL Structure

• Use the primary component pattern for URLs in kebab-case (without the va- prefix):
  • Example: <va-alert> → /components/alert
• For component variations, use hierarchical URLs:
  • First level: base component (e.g., /components/link)
  • Second level: variation category (e.g., /components/link/action)
  • Anchor links for specific variants (e.g., /components/link/action#primary-entry)

Hierarchical Component Naming

For components with multiple levels of variation:

1. Page Title Hierarchy

   • Primary Component: “Link”
   • Variation Category: “Link - Action”
   • Specific Variant: “Link - Action - Primary entry”

2. Documentation Structure

   • Use dash separators (“ - “) to indicate hierarchy levels in titles
   • Each level becomes more specific about the variant or option
   • For deeply nested variants, maintain consistency across all levels

3. Examples of Multi-level Component Naming:

   Web Component Documentation Title URL Path va-link variant="action" type="primary-entry" Link - Action - Primary entry /components/link/action#primary-entry va-button-group continue Button Group - Continue /components/button-group#continue va-radio-button tile=true Radio Button - Tile /components/form/radio-button#tile

Naming Pattern Examples

Component Examples

Variant Naming

When a component has variants, name them using these patterns:

1. Documentation Strategy:

   • Main component page with variants as sections
   • Separate pages for significant variants
   • Use clear titles to indicate relationship (e.g., “Button - Secondary”)

2. URL Strategy:

   • For minor variants: Use anchor links (e.g., /components/button#secondary)
   • For major variants: Use subpaths (e.g., /components/button/button-group)

Implementation Guidelines

Adding New Documentation Pages

Follow guidance for contributing to documentation.

1. Create front matter that includes:

   • The actual web component name with va- prefix in kebab-case
   • A human-readable title in Title Case with appropriate hierarchy
   • Any additional metadata needed for the component

2. For titling the new component in documentation:

   • Transform kebab-case to Title Case
   • Use dashes with spaces (“ - “) to separate hierarchical elements
   • Be consistent with existing similar components
   • Links to components or patterns should just include the title. Don’t include the words “component” or “pattern” in the link text.

3. For URL structure:

   • Use appropriate depth based on the component’s complexity
   • Consider the user’s mental model for finding the component
   • Maintain URL patterns consistent with similar components

Handling Complex Component Variations

For components with multiple variations or states:

1. Simple Variations:
   • Document on the main component page
   • Use anchor links for navigation
   • Example: “Button - Primary” as a section on the Button page
2. Complex Variations:
   • Create separate pages for significant variants
   • Maintain hierarchical relationship in titles
   • Example: “Link - Action” as a separate page from “Link”
3. State Variations:
   • Document states on the relevant component/variation page
   • Use clear state indicators in section titles
   • Example: “Radio Button - Error” as a section on the Radio Button page