Names - Design decisions

What is an ADR?

We use the ADR (Architecture Decision Record) to structure design decision documentation. Each ADR covers three things: the context that prompted the decision, the decision itself, and its consequences — including trade-offs and any open questions.

ADR 001 - Allow users to always enter their full first and last name

• Date raised: June 12, 2026
• Deciders: DS+F Team, Forms Library, VA.gov Frontend

Context

Several form teams have requested that the Full Name pattern enforce character limits on the first name and last name fields to match the fixed-width constraints of the underlying PDF forms. PDF-based VA forms are produced from fixed-field templates that can only accommodate a certain number of characters in name fields before the content is clipped or overflows the form layout.

This request surfaces a tension between two valid concerns:

• PDF fidelity: The generated PDF must render legibly and within its defined field boundaries.
• Veteran data integrity: Veterans must be able to enter their full, legal name without truncation or rejection on the digital form. Names are highly variable in length across cultures, and arbitrary UI-level character limits would create an inequitable, inaccessible experience.

The Full Name pattern currently uses va-text-input for first and last name fields. No platform-level character limit guidance exists for these fields. Individual form teams have been making ad hoc decisions — some enforcing maxlength in the frontend, others leaving it unconstrained.

Decision

The frontend UI must not restrict character count on name fields.

Veterans must be able to enter their full legal name in the first name, middle name, and last name fields without encountering a character limit on the digital form. The va-text-input component used in name fields must not have maxlength set on behalf of PDF constraints.

PDF constraint handling is a backend/data-mapping concern and must be addressed downstream using one of the two approved strategies below.

Why not restrict at the UI layer?

Imposing a character limit to match a PDF field boundary violates the principle of equitable access. Names vary significantly in length across cultures, languages, and legal naming conventions — a limit sized to fit a PDF field will disproportionately affect Veterans with longer names. It also creates a confusing and frustrating user experience: a Veteran should never be blocked from entering their own name on a government form.

Additionally, the character limits on PDF fields vary by form. If each form team sets its own maxlength based on the PDF template, the experience becomes inconsistent across VA.gov forms with no clear rationale surfaced to the user.

The digital form layer should represent the Veteran’s true input. Constraint handling belongs to the layer closest to the constraint — the PDF generation and data-mapping layer.

Why is this the right boundary?

The VA.gov digital form is not the PDF. The digital form collects data; the PDF renders a specific output format. These are separate concerns. The backend is already responsible for mapping form data to PDF fields — truncation or overflow handling is a natural extension of that responsibility, not a new one.

Approved strategies for PDF constraint handling

Form teams encountering PDF field length constraints must implement one of the following backend strategies. Choosing a strategy is the responsibility of the form team in coordination with their backend engineers. DS+F does not own PDF generation.

Strategy A: Backend truncation

When mapping the digital form submission to the PDF template, the backend truncates the name value to the maximum number of characters the PDF field supports.

Use when: The form does not support an overflow page, and the PDF field character limit is well-defined and stable.

Considerations:

• The truncated value is written to the PDF only; the full value should remain stored in the backend system of record (e.g., vets-api) and not be truncated at the data storage layer.
• Form teams should document the truncation limit and which fields are affected.
• No user-facing indication of truncation is required on the digital form (since the digital form faithfully captures what the Veteran entered), but form teams should evaluate whether confirmation language in the review/submit flow is appropriate.

Strategy B: Overflow page

Some PDF forms support an additional overflow page that can be appended when field values exceed the primary template’s capacity. When a name value exceeds the PDF field limit, the backend writes the full name to the overflow page rather than truncating it.

Use when: The form’s PDF template supports an overflow page mechanism, and the form team has confirmed this capability with their PDF generation pipeline.

Considerations:

• Overflow page support must be verified with the form’s PDF generation team before selecting this strategy.
• This is the preferred strategy when available, as it preserves the full name in the rendered output.

Rejected alternative: Frontend maxlength enforcement

Setting maxlength on va-text-input to match PDF field limits was considered and rejected for the following reasons:

• Creates an inequitable experience for Veterans with longer names.
• PDF character limits vary per form and are not a stable frontend concern.
• Violates the separation of concerns between data capture (frontend) and data rendering (PDF generation).

Guidance for form teams

If your form’s PDF has a character limit on a name field, you must:

1. Identify the character limit for the affected field(s) in your PDF template.
2. Determine whether your form supports an overflow page (Strategy B) or requires backend truncation (Strategy A).
3. Implement the chosen strategy in your vets-api data-mapping layer.
4. Do not add maxlength to va-text-input in the digital form for this purpose.

Consequences

Positive:

• Veterans can always enter their full legal name without UI-level rejection.
• The Full Name pattern remains consistent across all forms using it.
• PDF constraint handling is encapsulated in the layer that owns PDF output.

Negative / watch items:

• Form teams must implement one of the two backend strategies; this ADR does not eliminate the work, it redirects it.
• Teams that have already implemented frontend maxlength on name fields will need to remove those constraints and implement a backend strategy instead.