This template provides a starting point for building digital solutions using the Department of Veterans Affairs (VA) design system. It implements VA web components and design patterns for creating accessible, user-friendly applications for Veterans.

This template serves as a clean foundation for VA digital applications. It includes:

• Essential VA Components: Header, footer, and layout components following VA Design System guidelines
• Responsive Design: Adaptable for mobile, tablet, and desktop devices
• Accessibility Compliance: Built with Section 508 and WCAG 2.1 AA guidelines in mind
• Modern Stack: Uses Vite, React, and the official VA component library

The template is designed to be a flexible starting point for building various types of VA applications, including:

• Landing pages
• Informational/content pages
• Single and multi-column layouts
• Form-based applications

• Node.js (v16+)
• npm or yarn

# Clone the repository
git clone https://github.com/YOUR-USERNAME/va-application-template.git

# Navigate to the project directory
cd va-application-template

# Install dependencies
npm install

# Start the development server
npm run dev

• VA Design System Integration: Pre-configured with VA Web Components library
• Example Pages: Home, Form Example, Components, and About pages for reference
• Accessibility-First: Skip links, semantic markup, and proper ARIA attributes
• Simple Form Validation: Basic form validation with clear error handling
• Responsive Layouts: Flexible layout templates for various content types
• Clean Architecture: Well-organized component structure with clear separation of concerns
• Modern Build Tooling: Fast development with Vite

This template initializes the VA Design System web components in main.jsx:

// Initialize VA web components
applyPolyfills().then(() => {
  defineCustomElements(window);
});

This makes all VA web components available throughout your application. You can use the React bindings for more complex components, though standard web components are preferred for better compatibility:

import { VaBreadcrumbs } from "@department-of-veterans-affairs/component-library/dist/react-bindings";

This template supports various layout patterns using VA Design System grid classes. Here are some examples you can use:

<div class="vads-u-padding-y--3">
  <main>
    <div class="vads-grid-container desktop-lg:vads-u-padding-x--0">
      <div class="vads-grid-row vads-u-margin-x--neg2p5">
        <div class="vads-grid-col-12 vads-u-padding-x--2p5 tablet:vads-grid-col-4 desktop-lg:vads-grid-col-3">
          <!-- Sidebar content -->
          <div class="vads-u-padding-x--2 vads-u-padding-y--7 vads-u-background-color--primary-alt-lightest">
            Sidebar navigation or supporting content
          </div>
        </div>
        <div class="vads-grid-col-12 vads-u-padding-x--2p5 tablet:vads-grid-col-8 desktop-lg:vads-grid-col-9">
          <!-- Main content -->
          <div class="vads-u-padding-x--2 vads-u-padding-y--7">
            Main content area
          </div>
        </div>
      </div>
    </div>
  </main>
</div>

<main>
  <div class="vads-grid-container desktop-lg:vads-u-padding-x--0">
    <div class="vads-grid-row vads-u-margin-x--neg2p5">
      <div class="vads-grid-col-12 vads-u-padding-x--2p5 tablet:vads-grid-col-8">
        <!-- Left column content -->
      </div>
      <div class="vads-grid-col-12 vads-u-padding-x--2p5 tablet:vads-grid-col-4">
        <!-- Right column content -->
      </div>
    </div>
  </div>
</main>

<main>
  <div class="vads-grid-container vads-grid-container--full">
    <!-- Hero or banner section -->
    <div class="vads-u-padding-y--5 vads-u-background-color--primary-alt-lightest">
      <div class="vads-grid-container">
        <h1>Landing Page Title</h1>
        <!-- Hero content -->
      </div>
    </div>
    
    <!-- Main content section with standard width -->
    <div class="vads-grid-container">
      <div class="vads-grid-row">
        <div class="vads-grid-col-12">
          <!-- Main content -->
        </div>
      </div>
    </div>
  </div>
</main>

├── public/               # Static assets
├── src/
│   ├── components/       # Reusable VA components
│   │   ├── footer.jsx    # Page footer component
│   │   ├── header.jsx    # Page header component
│   │   ├── help.jsx      # Help component with contact information
│   │   └── layout.jsx    # Main layout wrapper with flexible options
│   ├── pages/            # Example application pages
│   │   ├── About.jsx     # About page example
│   │   ├── Components.jsx # VA Design System components showcase
│   │   ├── ExampleForm.jsx # Form implementation example
│   │   └── Home.jsx      # Home page example
│   ├── constants/        # Application constants and configuration
│   ├── favicon.svg       # VA logo favicon
│   ├── styles.css        # Clean global styles for VA Design System
│   ├── App.jsx           # Main application component with routing
│   └── main.jsx          # Application entry point with VA components initialization
├── index.html            # HTML entry point
├── vite.config.js        # Vite configuration
├── package.json          # Dependencies and scripts
└── README.md             # Project documentation

This template provides a clean foundation for VA applications. Here's how to make the most of it:

1. Run the development server with npm run dev
2. Explore the example pages (Home, Components, ExampleForm, About)
3. Use the Components page as a reference for available VA components

The Layout component provides a consistent structure with VA header and footer:

import Layout from '../components/layout';

const MyPage = () => {
  return (
    <Layout title="My Page Title">
      {/* Your page content here */}
      <va-breadcrumbs uswds>
        <va-breadcrumb href="/">Home</va-breadcrumb>
        <va-breadcrumb current>My Page</va-breadcrumb>
      </va-breadcrumbs>
      
      {/* Main content with proper VA components */}
      <section className="vads-u-margin-bottom--4">
        <h2>Section Heading</h2>
        <p>Your content here...</p>
      </section>
    </Layout>
  );
};

1. Create a new page component in src/pages/
2. Add the route in App.jsx:

<Route path="/my-new-page" element={<MyNewPage />} />

• Reference the Components page to see properly formatted examples
• Use proper heading structure and semantic HTML
• Follow accessibility best practices for all components
• Use VA utility classes (vads-u-*) for spacing and layout

• Header: Modify src/components/header.jsx to change the application title or add navigation
• Footer: Update src/components/footer.jsx to add additional footer content or links
• Layout: The layout.jsx component can be customized for different page layouts (see comments in the file)

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build locally

• VA Design System
• VA Web Components Documentation
• VA Form Patterns
• VA.gov Accessibility Guidelines
• Vite Documentation
• React Router Documentation

This project contains code covered under federal government licenses and/or VA-specific terms of use.