Standards documentation: URL standards additions and placement change

[mnorthuis]

IA standards request

Update the existing URL standards to provide more definition and move to a more visible place in VADS, and

Move URL standards out of the content styleguide

• Placement is TBD, but URLs should not be buried within the content styleguide, and need more visibility.
• Possibly move to component or pattern, I do not have a strong preference

Revise the parameters section

Revised content:

Guidelines for parameters in URLs

URL parameters - also known as query strings - are values added to the end of a URL that filter or organize the information on a page. Parameters are used for a number of reasons - most commonly for pagination, anchoring, filtering or sorting data, indicating language, or searching.

An example of a query string and parameter values in use on VA.gov is on our existing search functionality. The "?" indicates the beginning of the query string, followed by one or more parameters (i.e. page=1). Each parameter includes a key and a value, and multiple parameters are separated by an ampersand. https://www.va.gov/search/?page=1&query=disability+compensation&t=true

Like the core URL, parameters must also be readable and understandable to the user, so they know what information is being used to display the content of the page, and do not make the URL look untrustworthy. Parameters also impact SEO because they create unique URLs, so care must be taken to ensure they do not dilute the SEO value of the static, or, canonical version of the page.

When adding parameters to your URL, in addition to all the URL standards above, please follow the guidelines below.

• Do not use any PII in parameter values, or any other data that should not be logged or tracked. This includes everything from names and contact information to unique identifiers used that an be used to identify a specific person such as IP address, ICN, or EDIPI.
• Set the static, or main, URL as the canonical page using the rel=canonical attribute when the parameter-based URL is similar content to the canonical content. An example is when using parameters for sorting. The data returned is the same, but is in a different order, therefore include the rel=canonical attribute to tell search engines that the resorted page is the same as the original page.
• Parameter keys should be no more than 1 word for a label and must clearly define what the parameter is. Do not use generic terms such as “parm” or “key”.
• Do not expose empty or null value parameters in the URL
• For multi-select type values, combine the values into a single parameter rather than exposing the key multiple times in a URL multiple times (i.e. "color=blue,red,white" vs "color=blue&color=red&color=white")
• Avoid linking to URLs with parameters, link to the static, or, canonical URL when possible
• If multiple parameters are used in a query string, set a priority and list them in a consistent order

Acceptance criteria

• [x] A new home for the URL standards has been identified and cleared with the DST and OCTO IA Lead
• [x] URL standards have been moved out of the content style guide and into its new home in the design system
• [x] The parameters section of the URL standards has been updated and published

[erinrwhite]

Thanks @mnorthuis ! Will read carefully and circle back on Monday.

[shiragoodman]

thanks for tagging me @mnorthuis ! I have a few questions:

1. Is there an expected timeline as to when this work should be completed by?
2. Is there defined acceptance criteria? Assuming it's something like the URL standards guidance no longer exists within the content style guide and the parameters have been revised.
3. Is Erin expected to make and commit to these changes on their own or is Erin making a proposal for you to sign off/approve?
4. This ticket appears to not have a parent/epic or be part of a gh project. I know this is likely the first of many IA standards updates, and it would be helpful if all the work was bucketed for easy reference/reporting. Are you planning to make a parent ticket?

I'm very very excited to see this work kicking off, and I'm glad that @erinrwhite has a role in helping refine the standards. If there's anything you'd like to discuss, or if you need additional help with anything, please let me know. Governance is able to assist in moving this forward.

[mnorthuis]

Answers!

1. No expected timeline - I want to be conscious of the fact that collab cycle work comes first. That said if providing a date is helpful, I can definitely do that. My preference would be to see this work done in the next sprint, but look for your feedback on how full that sprint is.
2. I think you pretty much got the acceptance criteria - I added them to the description above and will include those in future tickets
3. For this work, its pretty straight forward, so PRs can go to myself for review before publishing, and it can also go to someone on DST if they want given its placement will be moving
4. I will work on an epic for standards work to group these - I think I already have one in the CAIA space, so will look to see if it makes sense to group with that or if these should be separate.

If there's anything else regarding ticket structure or process you want/need let me know. We can continue to evaluate as we get more into this work. Thank you!

[mnorthuis]

Epic added

[erinrwhite]

Thank you @mnorthuis @shiragoodman - in progress!

[shiragoodman]

Thanks, @mnorthuis ! I have added the governance-team label so it's easy for us to keep track of this. LMK if there's any concerns with the label.

[erinrwhite]

@mnorthuis After reviewing the difference between components, templates, and patterns here are some proposals for where this documentation would live. I also spent some time exploring the Foundations section, but it is very much focused on visual design. Let me know what you think, or if I'm off the mark or missing info on either of these approaches.

Option 1: Patterns > Help users to... > [Page]

In the Design System, patterns demonstrate how design, content strategy, reusable components, and accessibility can be put together to solve common problems that all Veterans may experience on VA.gov.

URLs could be added to Patterns > Help users to... as part of a new page or section, labeled something like "Understand their location within VA.gov"

Pros:

• Room to grow: this could be an entire section with sub-pages for URLs, as well as future IA-related content (including the current section on metadata, on the SEO page in the content style guide)
• Aligns with other types of topics in this section: Because most IA guidance is not component-specific but rather relates to experience design, it more closely hews to a mental model of the "patterns" section of the DS.

Cons: This would not elevate the URLs page in the IA. In fact, the page would be at least one level deeper than its current positioning in Content Style Guide.

Option 2: Components > URLs

Components are design elements that define a visual style and/or micro-interaction. A component is the smallest unit of measure within a design system. They can be considered concrete, a finite list: Button, accordion, table, etc.

URLs could be added as a discrete item in Components just as Breadcrumbs, On this page, and other IA-related elements appear.

Pros:

• Discrete, single page rather than being part of a parent section keeps the content modular and narrowly focused.
• URLs wouldn't be buried in the IA (would be housed at he same hierarchy level as in Content Style Guide)
• Likely to get more attention from designers and developers, who are more likely to reference the content.

Cons:

• Doesn't quite match the model of components being items that are visible within the DOM (every other item in the components section is rendered as HTML on the page). On the other hand, this opens the door for other IA items that aren't necessarily encapsulated HTML components to appear in the list.

[mnorthuis]

This is great @erinrwhite!

I'm leaning towards components for a couple of reasons:

• Its not really any combination of design/content/a11y per se, it is more of a single element
• Putting it in components makes it a bit more visible to developers, who are ultimately the ones that need to know

I would see this having a section for URLs, which sub-sections for form flows, parameters, and vanity URLs

Would love to Matt's thoughts on this to make sure it doesn't go against anything he envisions for that section.

[erinrwhite]

Thanks @mnorthuis! I agree. Bringing in @humancompanion-usds to this thread.

Matt, we'd love to get your take on this approach - moving the URLs guidance from the Content Style Guide to the Components section, while improving/expanding the page content. We weighed a couple of options for where this content would be best suited, and think this is the best approach.

Sound good? And, do you recommend we socialize this with the Design System Team as well? This'll be one of a series of IA standards changes coming through in the coming months so I want to make sure we're developing a workflow that'll work for everyone. Thanks!

[humancompanion-usds]

Hmm. URLs are by definition not components. By our own definition components are:

Components are interactive and non-interactive UI elements that can be grouped together or presented individually. They are independent, reusable chunks of a user interface.

But I do agree that would give it more visibility than being in the Content style guide for developers at least. I'm not opposed to putting URLs in Components if it's temporary and gets us started on adding more IA guidance to the Design System. Because what I'd really like to start on is option 3:

Option 3: Foundations > Information Architecture > URLs

Perhaps it could cover the following (I'm cribbing from an older doc):

• IA Principles
• Structure - What is the current structure of the site
• URLs
• Primary entry points - How to define them for your application
• User flows - Standards around what a user flow should show (could use some or all of Jenny's doc?)
• Navigational components - Pointers to the navigation components (breadcrumbs, header, footer, sidenav, et. al.)
• Crosslinking opportunities - Our philosophy or strategy on secondary placements
• Redirects- Our approach to redirects

FWIW, Shopify's Polaris puts their IA section in Foundations. I would be for revising the IA of the Foundation section on design.va.gov to look more like this:

• Foundations
  • Accessibility
  • Overview
  • Accessibility annotations
  • Information Architecture
  • Overview
  • URLs
  • Visual Design
  • Overview
  • Breakpoints
  • Color palette
  • Design tokens
  • Icons
  • Image aspect ratios
  • Layout
  • Logos
  • Spacing units
  • Typography
  • Utilities

I've been wanting to move Accessibility out of the About anyway and I agree that what is in Foundation today speaks more to the Foundation of the base visual styling of the Design System itself rather than the foundations of VA.gov.

Anyway, not opposed to starting in Components for URLs but I think we should plan for a bigger IA section in future.

[mnorthuis]

I totally agree that it doesn't fit the description of today's "components", and option 3 of creating a broader IA space is already on our list of things to evaluate, but we are not ready to act on that quite yet.

In the mean time, I'd like to get some of these core things into a space that makes more sense. URLs are not content and do not belong there. URL guidance is more for developers than anyone else and often they just create their own structures without knowing there's guidance. So I'd love to start with these in components.

We will be looking at the broader plan for where IA fits into the design system and what would go in that section. The challenge we will have, is teams do not understand what IA is, so looking there for detailed engineering guidance on things like URLs may be tough.

[erinrwhite]

Thanks both! @humancompanion-usds @mnorthuis

Matt, I really like going with an update to the Foundations section like you laid out. I hadn't seen the Shopify design system. I think this could also be something we pass back to USWDS for their own documentation.

Sounds like we are set on this plan:

• Immediate term: Add URLs to components section (I can start on this right away)
• Longer term: reshuffle Foundations section to include IA and Accessibility per @humancompanion-usds's diagram

If this sounds good I'll get started on the updated URLs page. Thanks!

[mnorthuis]

I'm not 100% sold on the the foundations section as of yet. Visibility of IA standards and IA practice in general is currently an issue, so I'd really like to think about that a bit more before we call it the plan. We also need to figure out what else from IA belongs in the design system before we can chart out a section.

[erinrwhite]

Team, quick update here - I'm planning on proceeding with adding URLs to components while we think longer-term about where a section of IA pages might land in the Design System.

Done:

• set up local development environment for vets-design-system-documentation

Todo:

• move and update URLs page
• post for review

This work will proceed into our next sprint.

[erinrwhite]

Pull request submitted for review and assigned @mnorthuis !

[erinrwhite]

Pull request reviewed and merged. For when you're back @mnorthuis: do we want to communicate this change with VFS teams at all? No rush, keeping this ticket open til we're signed and sealed.

[mnorthuis]

Work complete and communicated out!