Improve UX guidance in Patterns > Templates > Hub

[rtwell]

Hub pages A hub page page does the following:

Provides an executive summary of this hub Provides links to lead users to specific sections about that benefit Crosslink to related benefits Allows users to connect via social media Provides contact information for this benefit An example hub page: Image of va.gov housing assistance hub page

The hub page pattern can be broken down into an ordered set of components: Image of va.gov housing assistance hub page

Hierarchy We surface information that is important to Veterans first. The hierarchy of a hub page is as follows:

Page title (h1) Tells the user what’s on this page, is also important semantically for html, defined in Foundation here

Intro text Similar to the title, Intro text is an executive summary of page content, define in stype in Foundation here. Intro text is also important for SEO.

Jump link navigation (On this page) Jump link nav serves two purposes: 1) It informs users what sections are on this particular page, and 2) it allows the user to jump to the section they wish to read.

Section breaks In order to be clear when a section begins, we use a “—★★★★★—” visual treatment documented here

Section 1 (h2) The first section on a Hub page template contains information about how a Veteran might go about getting this benefit. Our h2s are defined in Foundation

Section 2 (h2) The second section on a Hub page template contains information about how a Veteran might go about managing this benefit.

Section 3 — optional (h2) The third section on a Hub page template contains information about how a Veteran might go about finding more information about this benefit.

Link and teaser component Each section contains a set of “link + teaser” components which takes the user to a particular subsection of the benefit (e.g. a page to see if they are eligible for health care, a page to apply for health care, etc). This component doesn’t have a home in our design system yet.

Cross-reference / footnote component At the bottom of every Hub page, we list benefits that are related to, but not part of, the current benefit the user is viewing. All of these links drive users to other hub pages, so we treat this section visually different than the Link and teaser component. This content also deserves to be component-ized.

Right rail The right rail contains [this kind] of content. More stuff about the right rail.

Promo spot The top of the right rail contains our Promo spot. I don’t know anything about this content, but it seems like it should be a component in our design system

Accordion In the second postion within the right rail, we list accordions containing specific groups of content. These accordions are the lowest priority pieces of content on a hub page, and they are positioned as such—at the bottom of the page. Some examples of accordions are:

“Ask questions” a short list of contact emails and phone numbers “Not a Veteran” helpful links for folks that aren’t Veterans “Connect with us” social media links What’s New? Vets.gov Playbook Accessibility Privacy VA | U.S. Department of Veterans Affairs

[rtwell]

[mnorthuis]

@rtwell I have a number of questions and thoughts on this, I'll reach out.

[jenniferlee-dsva]

This may seem random. Could we number our components? It's so hard referring to them and know what ppl are really talking about because everyone calls it different things.

I've seen components labeled as #s in other design systems and it was enormously helpful.

[jaredcunha-usds]

@jenniferlee-dsva Can you point to a design system where that system is in use? I might be little wary of maintenance implications of creating a numbering system. My hope is that when developing well-defined components, that vocabulary will develop as folks get familiar with the design system.

[jenniferlee-dsva]

@jaredcunha-usds - I must confess, it was at my last company, and they don't keep their pattern library publicly available. We started using numbers when we went to a page level templates where there was some flexibility for mixing and matching different components.

It also became easier to know we were all talking about the SAME thing by referring to it by the #. EX - we had 3 different kinds of 'buy' components, but which one do we use?

Same thing here - we have several things we call alerts and we try to differentiate what we're talking about - 'global' alert, 'global' banner (neither of which are actually 'global' btw); info alert; in-body alert; the alert with the exclamation point icon.

Ditto the 'blue box' - which I've also heard called the eligibility box, but doesn't always contain eligibility info.

Just a thought.

[rtwell]

Updated screen grab to include the Veteran image and Right Rail content:

[jenniferlee-dsva]

@jaredcunha-usds & @rtwell - RE above https://github.com/department-of-veterans-affairs/va.gov-team/issues/55#issuecomment-475320506

Sharing something that came up in the Drupal (CMS) training the content team attended this afternoon - another reason to maybe use numbers for our components.

In Drupal workflow, the content editor/reviewer has to select which component to add to a page and then add the content into the component. Right now the labels that the CMS uses for our components sometimes matches our design system informal names, but not always, especially when our informal names are not totally reflective of how it's actually used.

Ex: the blue box - which we all refer to casually as the blue box or blue callout; but sometimes also the blue eligibility component. (Even though there are times that it is used for just "important" info, and not strictly "eligibility" info... hence the difficulty with naming these.)

The challenge is that the Drupal labels are trying not to name things in such a way that it misleadingly defines the content, but also doesn't want to just refer to it by the visual ("blue box") because it is trying to map components to content purpose, rather than just as a way to visually differentiate any text.

I don't actually think inside the CMS is where that ^ defining should happen -- I think it belongs in the design system, like we are doing now.

But for the interim period today, where we are still working towards defining the content purpose of each component, it would be very helpful to have a clear way of referring to them without tying ourselves in a knot while figuring out what we're talking about and what the CMS is talking about.

• What happens now: 'okay, "Featured Content" component inside the CMS maps to the "blue box" component in our design system which maps to eligibility content type, ideally but not always for now.'

• Another example: 'okay, the thing that's called "Additional Info" inside the CMS is actually mapping to our dotted-line-expandable-helper-text-link-like-the-one-used-for-Spanish-language-summary -- and not to the gray-more-information callout box in our design system.'

Sorry to harp on this, but it is getting seriously cumbersome and confusing for the ppl who are actually using these components to create content, especially with the added layer of CMS. It's. In. Sane.

[mnorthuis]

@rtwell This is a very early draft and just some random thoughts, but hopefully gives you something to work with for now in regards to usage guidelines (how each content chunk/component should be used).

[jaredcunha-usds]

@jenniferlee-dsva I don't believe that a numeric system will solve those problems. I feel strongly about this.

The problem you described the CMS team having, to me, sounds like there's a lot of confusion around what to call the thing. So it might be named in the CMS one way, designers might call it something else, and the design system might call it something different. I think the reason we are doing this is that we never had a design system, or centralized place even, for officially named things. Over time, I think the design system will address this, but the CMS will need to reflect the naming conventions in the design and designers will need to be proactive in correction how we refer to things until that shared vocabulary becomes muscle memory. It's easier if that's where you start, but because we never codified how we name things, it'll take a bit of time to erase those habits.

I don't think that the numbers would help solve those problems. If someone told me to use Component 34, I have no idea what that means. I'd have to have the design system AND numbering system memorized to make sense of that request. Not only that, naming frames how we think about a components usage, whereas using numbers removes that because it's just a number.

Naming components must be based on semantics and NEVER refer to its visual presentation. I can't recall the number of times I've seen that happen and then at some point, that visual presentation changes. We really should not be saying "blue box." In the design system, it a "Featured content" because @emilywaggoner and I discussed calling it that. However, it's still called an "Information callout," so we need to update the Sketch file along with the CMS and our own personal vocabulary.

The component you are as the Additional Info is actually correct (https://department-of-veterans-affairs.github.io/vets-design-system-documentation/components/additional-info). I don't have anything named "Additional Info" that appears in a gray box.

In a more practical sense, a numeric naming system will create an additional burden in managing the overall system. Would there be any sequence to the numbers? Would there be a hierarchy? How would we handle variants of components? How are those enforced as new components are introduced? Those are decisions one would have to make that did not need to be made previously.

On top of that, there would have to be more coordination in keeping numbers in sync. Formation, the documentation site, the React components, va.gov, and the CMS are all separate codebases. There's nothing I can to add a number to a component to one place and have it updated in all areas. Each codebase would have to be updated individually.

[caw310]

Closing as this is over 3 yrs old.

[mnorthuis]

@caw310 @humancompanion-usds I think there are some things in here that would be helpful to add to the template in the design system. The template documentation currently focuses on the design specs, but there is also general ux guidance that would be helpful to publish to support teams when responding to stakeholder requests. Could we revisit this?

[humancompanion-usds]

there is also general ux guidance that would be helpful to publish to support teams when responding to stakeholder requests.

@mnorthuis -Sure. Are you referring to what you wrote here?: https://github.com/department-of-veterans-affairs/va.gov-team/issues/55#issuecomment-476597024

[jcklpe]

Was in a design system workshop and was asked to review this and prioritize it. My take away from reading this thread and looking at the existing docs: I think this can be closed.

[mnorthuis]

@humancompanion-usds Sorry for the delayed response, I was out for a couple of weeks when you left your comment. Yes, I think that's primarily what I'm referring to. Basically, with some of the templates, and even like the top nav, there are general ux "rules" and guidance that we use when evaluating how to use or place something in it. I think that information would be helpful, especially when working with VA stakeholders.