Visage has a new documentation site that combines all the documentation in one place,
so this legacy site will be retired soon.
Please update your bookmarks to:
https://visage.prod.merch.vpsvc.com/
Accessibility is not a component in and of itself; accessibility support is tied to each individual component, and documented in each component's entry.
This section demonstrates additional UI Library features that are specifically to support accessibility.
Putting the class ".visually-hidden" on an element hides it on screens, but leaves it visible to screen readers and assistive technologies. This paragraph is visible to all browsers and devices, unlike the next one, which is hidden on screens:
This paragraph is visually hidden, so it will not show on a screen, but will be read by screen readers and other assistive technologies.
aria-label
doesn't work for providing a cue to an element's function. For instance,
a paginator might have "previous" and "next" buttons with icons provided
via the background-image property, meaning it can't use
alt text. In this case, you could put a span
inside that button with visually-hidden on it and the word "Previous"
or "Next" as its contents.
The class ".accessibility-keyboard-clickable" makes it so that if the element is in focus, and the user hits either the Enter or Space keys, the keypress will act as a click upon the element.
The native tags for interactive elements (such as radio buttons, checkboxes, and <button> tags) are
inherently clickable with the keyboard. This feature is for elements that semantically serve
as buttons or interactive elements, but for whatever reason cannot use the semantically-appropriate tag.
<button> or <input>. These elements
are natively clickable with the keyboard, and don't need this feature. This feature
is only for those rare instances when, for whatever reason, you can't use the semantically
correct tag.
tabindex="0" to put it into the tab order.
Without this, the user can't put the element into focus using the keyboard or a screen reader.
role="button" for a clickable element that acts
(but doesn't necessary look like!) a button.
An accordion is comprised of collapsible list items that open and close when their summary is clicked, hiding or revealing content.
On Medium and Large screens, Accordion is intended to be used inside a 10-column grid element with one column of offset, so that is how it is shown here.
The "peek" skin shows a small amount of the content while the accordion is closed. It is intended for SEO copy and similar blocks of text where we want to entice the user into opening the accordion. This skin should only be used for accordions with a single collapsible.
I'm the collapsible content for the "peek" skin, where you can see part of the content peeking out when the collapsible is closed. Clicking on the summary then lets you see the rest of the content.
This feature is intended for things like SEO copy on product pages.
If you want the summary text to be horizontally centered, you can use the text-center
class from our typography:
I'm the collapsible content for the "peek" skin, where you can see part of the content peeking out when the collapsible is closed. Clicking on the summary then lets you see the rest of the content.
This feature is intended for things like SEO copy on product pages.
Using the "rich" option on the summary element allows you to customize the summary typography by putting typographic styles onto sub-elements inside the summary. Those sub-elements will be arranged in a single horizontal line, aligned to the left.
Adding the "align right" option to the last sub-element will make that sub-element align to the right edge.
aria-expanded="true" onto the collapsible-summary-button
element and the class
collapsible-content-open on the associated collapsible-content element.
If using the old API, the aria-expanded="true" should go onto the collapsible-header
instead.
"accordion-multiple" to the element that has class "accordion" on it.
"collapsible-ignore-click" will not toggle the collapsible open/closed.
collapsible-summary-button
(or, for the old API, every collapsible-header)
must have:
aria-expanded attribute set to true or false, depending on whether
the accordion is open or closed.
aria-controls attribute whose value is the id of the collapsible-content section it controls.
role="button" and tabindex="0" attributes, so that the
collapsible-header
will be recognized by assistive devices as something that the user can click on.
Since the Step Indicator does not provide a good user experience on Extra-Small screens, pages should use adaptive design and provide an Accordion (with the "steps" skin) instead of a Step Indicator on those screens.
In this case, the "collapsibles" for previous steps might not have content in them; they might actually be links or buttons that take the user back to a previous page in the flow. Similarly, "collapsibles" for future steps might be disabled, because the user has not yet reached that step in the flow.
To support this, Accordions can have fake collapsibles that are actually links/buttons, or collapsibles that are disabled and cannot be opened.
<ol>
and <li> tags, as it represents a list of steps.
aria-current="step" on it.
Form input errors indicate where a user's input for a specific input field was invalid or incorrect.
Last name required.
Please select a shipping method.
aria-invalid="true" to
indicate that its current value is invalid.
It should also have both an aria-describedby attribute and an aria-errormessage attribute,
both of whose values are the id of the error message.
role="status" aria-live="polite" on it.
These attributes inform assistive technologies that they need to notify the user
when any content inside that area changes, and thus the browser will announce the error message
when it appears.
Alert boxes are for alert messages that apply to an entire page, or to a section of a page. For instance, if a user has incorrectly filled out some form fields, each form field might get its own individual error message (see above), but the whole form would also get an alert box at the top, right below its heading, calling attention to the entire form.
Page alerts are for page-level alerts, and are displayed at the top of the page, right below the site navigation.
visually-hidden to hide some of the text from screens.
For instance, a positive alert indicating that an operation has succeeded might have
<span class="visually-hidden">Success:</span> at the start of the message.
role="status" aria-live="polite" on it.
These attributes inform assistive technologies that they need to notify the user
when any content inside that area changes, and thus the browser will announce the alert
when it appears.
The background color containers are simple wrappers which just set the background color of a section.
This is a section with "background-light-grey".
This is a section with "background-light-blue".
This is a section with both "background-dark-blue" and "text-color-white".
This is a section with "background-white", shown inside a section with a different-colored background.
This is a section with "background-loading-shimmer".
This is a Card Container with "background-light-grey", overriding the Card Container's innate white background.
This is a section with "background-mist".
This is a section with "background-translucent-blue". (Note that it is no longer actually translucent after the 2020 Refresh, where we only use opaque light-blue backgrounds instead.)
This is a section with "background-black", plus "knockout" on the text.
The "short" option makes the background color only 80% of the height of the container, with gaps at the top and bottom.
A badge is an inline piece of text that draws attention to a particular characteristic, such as a product being recommended or having a different price.
This sentence has a Sample badge in the middle of it. Here's a badge on a line by itself:
50% off — using the "discount" skin for discount prices
New! — using the "announcement" skin for announcements
Through Dec 25 — using the "holiday" skin
Visage doesn't have a single banner component, but here are some of the types of banners that it offers:
Standard Hero can be used outside of the page's hero zone to create a narrow banner in the middle of a page. To do so, add the "narrow" option to the Standard Hero, which will adjust the hero's layout and typography to better fit a narrow width. Then place the Standard Hero inside a layout grid element.
Banner title
This banner uses the "narrow" options, plus the "text-center" and "text-align-bottom" options.
Banner title
This banner is showing the "transparent-background" option.
A Bounded Content box is used around a page's central content. It puts a maximum width on that content, keeping the content from touching the edges of the browser window.
Most pages will want to place any content between header and footer inside of a Bounded Content box. Any content that should span the full browser window, such as hero zones, should go outside the Bounded Content.
Breadcrumbs are typically located at the top of the page, and contain navigational links. They indicate the user's location within the site hierarchy.
Putting class .breadcrumbs and a role onto the ul element instead:
<nav> tag signifies that the breadcrumbs are a navigation landmark.
aria-label attribute helps guide users on assistive technologies as to what this particular
navigation is. Its value will be displayed to assistive technologies, so the value must be localized.
breadcrumbs class onto the <ul>
tag, along with role="navigation", leaving out the <nav> tag. This API was incorrect;
since it redefined the <ul> as a navigation element, it would then cease to act as a proper container
for the <li> list items.
"Textbutton" is our name for our standard site button.
These skins are deprecated, and predate our current site look. No new instances of these should be added to the site. They will be removed in a future version of Visage, so if your page is using any of them, please update them to use a skin that isn't deprecated.
Here's how they appear using our current site visuals:
The "wide" option puts extra padding on the left and right sides of the button:
With the "full-width" option, the textbutton expands to fill the width of its container. Here's an example inside a col-6 element, where the col-6's edges are shown with a dashed line:
<button> tags<a> tag instead of a <button> tag
if it acts as a link, where clicking on it just takes the user to a new page without any submission of form information.
<label> tag only when acting as a label for a (presumably hidden)
input element.
<span> tag when an unusual technical limitation prevents the use of
a better tag.
Buttons that are not <button> tags can't use the disabled property,
so they should set aria-disabled="true" instead.
<a> tag) if clicking it takes you
to another page. In cases where you have to place a textbutton inside a link,
the link may apply an underline to the text inside the button.
In this case, use class link-skin-unstyled on the link to remove the underline from the link.
<a> or <span> tags should not put any
additional tags inside the button other than a <br> tag or an icon.
Super buttons with these tags use flex layout, and any internal tags
will be treated as flexbox children, which can affect the button's layout.
<a> for buttons that are hyperlinks to a new page, the <button> tag for textbuttons
that interact with the page, and <span> tags only when the previous two tags can't be used for some reason.
<span> tags also need the class accessibility-keyboard-clickable and
the attribute tabindex="0" to make them usable with a keyboard and/or screen reader. They also need
the attribute role="button" to mark them functionally as buttons.
disabled attribute (e.g. it is a span tag),
add the attribute aria-disabled="true" to aid in accessibility.
<button> tags<img> tags).
Images should be square, and at least 36px by 36px.
The icon will stretch to fill the available space inside the button, so if you want the icon to appear smaller,
you will want to include whitespace in the image itself, around the visible part of the icon.
<button> tag, it can't
be used on an <input> tag.
If you want a button that has the Textbutton look but (ironically) has no text, you can use a "round Textbutton" and put a Control Icon inside it:
As with any Textbutton, these also come in mini size:
using (unnecessary) "textbutton-icon" class:
Old API using a "textbutton-icon" element instead of Control Icon:
These buttons are not Textbuttons, but are instead skins for the <button> tag.
These skins are for elements that semantically function like buttons, even if they don't look like it.
If you need a <button> tag for proper semantics, but it needs to look like a link,
you can use a .
You can also add the to a button
(although this skin is not intended for inline links, and should only be used in specific locations
such as Standard Heroes and Standard Tiles!)
"Link" buttons can also and can have a Control Icon inside them, or just like a real link.
This paragraph has an in the middle of it.
This paragraph shows what a looks like, or one with .
<button> and not a link.
The "link" class can be used on a <button> to give it the appearance of a link.
These buttons are used to launch "panel" modal dialogs.
aria-labelledby
attribute whose value is the id of the element that labels the button.
visually-hidden text inside the button, such as
"(Click to change selection)".
A buttonbar is a set of choices that are visually grouped together. A buttonbar can be either multi-select (using checkboxes) or mutually exclusive (using radio buttons).
<fieldset> tag for the buttonbar,
because Chrome doesn't support enough styling of that tag.
aria-label whose value is a localized description of
what the buttonbar is or does, e.g. "Change view".
aria-controls
attribute whose value is the id of the section it controls.
A Callout is a merchandising element that calls attention. It may be overlaid on top of another element, or used inline.
When overlaid on top of an image, a Callout should use the "overlay" option.
The "inverse" option provides an alternate presentation, inverting the normal text and background colors.
Cards provide a strong visual cue of content relationships. They are simple containers into which you can put any content.
The "full bleed" option removes the internal padding around the card's contents, so that the contents will touch the border of the card.
This Card Container above has the "full bleed" option. With this option, the Container has no internal padding,
so the image runs right up to the edges of the Card Container.
By default, a card container will only be as tall as its contents. If you want all the card containers on the same grid row to have the same visible height, add the "even height" option to the cards. This will also put some vertical spacing below each card, so that there is a gap between rows of cards.
Adding a set of dividers inside a Card will create vertical dividing lines.
Note: the dividers don't add any internal spacing. Use the spacing system if
you need to add spacing between the dividing lines and the content.
A Card Set is a row in the layout grid that gives all of its column elements the appearance of a card. All cards in the same visual row will have the same height.
Adding a set of dividers inside a Card will create vertical dividing lines.
Note: the dividers don't add any internal spacing. Use the spacing system if
you need to add spacing between the dividing lines and the content.
card-set element)
around the cards element must have a role="radiogroup"
attribute.
card-set element)
element must have an aria-labelledby attribute whose value is the id of the element
that acts as a title for the set of cards (typically, a heading right above that set.)
If the
set of cards
does not have a visible title,
then instead it needs an aria-label attribute whose value is a descriptive title of the set;
this text must be localized, as some browsers will read it to the user.
A carousel allows multiple pieces of content to be browsed in a cyclical view. An infinite carousel will cycle the numbered frames continuously and a finite carousel will have a beginning and end.
Do not use a carousel in the hero spot!
A Vistaprint study in 2015 found that the first frame got over 200 times as many clicks as frame two (199,824 vs 1,029)! Revenue discrepancy was even greater. The overhead of designing and implementing a hero carousel is not worth the small increase in revenue.
The study did indicate a better response rate for a product carousel located further down the page as a "see also".
col-* element with a Standard Product Tile inside it.
.carousel.carousel-dots-fraction
{
--visage-my-property: my-fraction-specific-value;
}
initializeCarousel()
function, e.g. $(".my-carousel").initializeCarousel().
reinitializeCarousel()
function, e.g. $(".my-carousel").reinitializeCarousel().
carousel() function with the string "add" as the first argument.
The second argument should be an HTML string or DOM node for the new slide. The third argument (which is optional) is the zero-indexed location
of where the slide should be added, defaulting to the end of the list,
e.g. $(".my-carousel").carousel("add", "<div class='carousel-slide'>new slide</div>", 3)
carousel() function with the string "remove" as the first argument.
The second argument should be the zero-indexed location of the slide to remove,
e.g. $(".my-carousel").carousel("remove", 0)
carousel() function with the string "goto" as the first argument.
The second argument should be the zero-indexed location of the slide to advance to,
e.g. $(".my-carousel").carousel("goto", 0)
Checkboxes are almost never intended to be used on their own. Instead, they should be used within a Selection Set, so that they have a standard label and standard layout.
input tag, and not any label or related visual element.
role="group". This wrapper element must have an aria-labelledby attribute
whose value is the id of the element that acts as a title for the group — or, if the group does not have a visible title,
an aria-label attribute whose value is a descriptive title of the group. The value of aria-label must be localized,
as some browsers will read it to the user.
aria-required="true" to the input.
"favorite" checkbox
input tag, and not any label or related visual element.
span inside the label will be read to the user by assistive technologies, so it must be localized.
Use text that reflects the function of the checkbox.
We use a minimal color palette on our site to help communicate simple information hierarchy, while reinforcing our brand presence in an aesthetically-pleasing way.
$global-font-color (for fonts)$link-color (for links)$selected-color (for input elements that are selected)
$border-color (for borders)
$error-color (for error messaging)
$holiday-color
$discount-color (for discounts)You can set the background color of a page zone using the Background Color component.
You can set the text color using our typography classes.
Default text is charcoal.
.text-color-dark-grey
.text-color-holiday
.text-color-pink
.text-color-brand-blue
.text-color-white
.knockout
.error
.alert
$discount-color across the site.
$ in the color variable names, which is the syntax for SCSS. If your project is still using LESS,
you should use a @ symbol for the variables instead.
$border-color for borders instead of $medium-grey,
because in future visual refreshes, our borders might no longer be medium grey.
Color swatches are used to show and/or select color options for products.
Older, deprecated API that puts class color-swatches onto the Selection Set itself:
Older, deprecated API that puts class color-swatches onto the Selection Set itself:
background-color CSS property, either with
an inline style attribute, or via an external stylesheet.
background-color attribute to the shade
on the bottom/right, and the color attribute to the color on the top/left.
disabled property on the
associated input tag will give the swatch the disabled look. For color swatches that are
not radio buttons or checkboxes, you can add the color-swatch-disabled class to the swatch itself.
title attribute (for color-blind users)
and an aria-label attribute (for assistive technologies),
whose values are a localized description of the color choice, e.g.
title="light blue" aria-label="light blue"
The Control Icon is a utility component that lets you create an arbitrary icon from our stock icon set. The typical use case is inside a button or link, so that a click on the icon performs a related action.
If you want a Control Icon to be a button all by itself, place it inside an "unstyled" button.
A Control Icon changes its color when it is directly hovered over. However, if you want the icon to also change
color when an ancestor is hovered over, place the class control-icon-hover-container
on that ancestor.
span tag.
span tag inside a button tag.
span tag inside an a tag.
aria-hidden="true" to hide it from assistive technologies.
aria-labelledby attribute whose value is the id of the element that describes it.
span with class visually-hidden. Inside this span,
add localized text explaining what the button does (e.g. "Close", "Next").
Counts are numeric messages that indicate amount.
4
span
with the class visually-hidden that provides additional context; this element will be hidden from screens, but
read out by assistive devices. For instance, if a Count of 4 represents 4 items in the cart,
add <span class="visually-hidden"> Items</span> inside the Count, after the number.
The datepicker allows users to pick a single date to fill-in a text field. A calendar displays months and days of the week in a localized format. Datepicker is used in Studio for highlighting dates in a calendar.
When a calendar icon or text field is selected, an overlay appears that displays the current and next month, from which the user may select a date for input.
We don't support a direct entry of dates into a text field, to guarantee the date is in a valid format.
A Details Banner shows an image, and alongside it some details about the content shown in the image.
Dividers are used to divide content into visible sections.
This is a paragraph of text with a | divider in the middle of it, using class .pipe around a | character.
Dropdown is a pull-down list of items that appear when the dropdown is selected; this list remains open until a user selects an item or dismisses the list.
Deprecated: wrapping the dropdown in a container with class stylized-select-container
Our dropdown uses (and extends) the native <select> element, rather than try to reproduce its functionality with HTML. This does impose some limits on the styling we can perform on the options inside the dropdown. There are many reasons for using a native dropdown:
<select> means that
phone users get their device's own select experience, which is mobile-optimized.
(For instance, iPhone users get the fullscreen "scroll wheel" display.)
The browser manufacturers have invested a lot of UX research into determining that this is a good user experience for touch-screen users.
For usability, the dropdown uses generous padding and a large font. This means that the control does have a certain minimum width (this number depends on the widest option within the dropdown). For this reason, you should be sure to place it in a part of the page that gives it sufficient room to render, including the possibility that translated text might be longer than English text. If it is placed in an area that is too narrow, it may not display properly.
We have limited styling choices for the content of the dropdown's menu items, because we use the browser's native dropdown menu (see "Implementation Notes") to provide an optimal experience on mobile devices and assistive technologies. The browsers don't give you as much styling control as you might want; for instance, we can set the font color, size, and weight, but only for the entire dropdown, not for just one part of it. We cannot use strikethrough text or set any layout inside those dropdown choices.
initializeControl event on it.
display: table-cell on it, as this can cause the dropdown to be rendered
more narrowly than its true minimum width.
<label> tag, with a for
attribute whose value is the id of the dropdown. (If a <label> tag is not possible,
the <select> tag either needs a aria-labelledby attribute, or an aria-label attribute with a
localized value.)
<select> tag should have aria-describedby and aria-errormessage
attributes whose value is the id of the error message. In addition,
while the dropdown's value is invalid, the <select> should have aria-invalid="true" on it.
aria-required="true" to
the <select> tag.
The Embedded Text Hero is a hero where all the visible text embedded in the hero image itself.
h1 tag.
If it is not the page title, use whatever tag is appropriate for the page structure.
alt text about what's shown in the image.
The fieldset is a container that groups a set of related form fields.
<fieldset> tags must have a <legend> tag that labels them, for accessibility.
If the information in the legend is superfluous to sighted users, the legend can be hidden on screens by putting the CSS class
visually-hidden on the legend.
<legend> cannot be (or contain) a heading (H1-H6) tag. If the page structure requires a heading to label
the form fields, don't use a <fieldset> tag.
Instead, group them using a wrapper tag that has the
role="radiogroup" attribute (for radio buttons) or role="group" attribute (for everything else),
plus an aria-labelledby attribute whose value is the id of the heading.
The flipswitch is a toggle used to turn a feature or app on or off. The flipswitch stretches its width to fit its contents.
Show Prices:
OffShow Prices:
Offlabel tags, which creates accessibility issues.
label tag does not sufficiently describe the function of the switch,
you will need to give the input tag an aria-labelledby attribute whose id
is the element that describes the function of the switch (as shown above).
Used in the UK site's header to set VAT tax.
The floating container pins its contents to the left- or right-hand side of a grid element, with the rest of the content flowing around it.
A col-12 with additional text that should start to the right of the container, and wrap around the container so that it ends up below the container. (Except on Extra-Small screens, where all the text should sit below the container.) Here's some additional text to make this paragraph a little longer.
A col-12 with additional text that should start to the left of the container, and wrap around the container so that it ends up below the container. (Except on Extra-Small screens, where all the text should sit below the container.) Here's some additional text to make this paragraph a little longer.
A col-12 with additional text that should start to the right of the container, and wrap around the container so that it ends up below the container. Here's some additional text to make this paragraph a little longer. Here's some additional text to make this paragraph a little longer.
A col-12 with additional text that should start to the left of the container, and wrap around the container so that it ends up below the container. Here's some additional text to make this paragraph a little longer. Here's some additional text to make this paragraph a little longer.
Floating can position assets and cause other assets such as text to wrap around them. A clear property can be used to eliminate wrapping.
The floating container should be used only inside another col-N element, as a direct child of that
col-N element. (If you place it elsewhere, such as making it a child of a grid container or a row element,
you may get layout errors.)
If the content of the floating container is secondary to the main
text (as is usually the case), consider using a semantically-accurate <aside>
tag instead of a generic <div> for the floating container.
Our "standard form" wraps a series of Input Group elements and their labels, providing a standardized layout for forms.
Helper text
Error message.
Please select a shipping method.
Last name is required.
The "tight" skin puts less vertical space between each input group.
Helper text
A horizontal form uses rows in the layout grid to arrange the labels and form inputs side-by-side.
Horizontal forms assume a vertical arrangement on Extra-Small screens.
Helper text
Error message.
<label> tag, with a for
attribute whose value is the id of the input. (If a <label> tag is not possible,
the input either needs a aria-labelledby attribute, or an aria-label attribute with a
localized value.)
aria-required="true" to the input, to signal to assistive technologies that the field is required.
role="group". This wrapper element must have an aria-labelledby attribute
whose value is the id of the element that acts as a title for the group — or, if the group does not have a visible title,
an aria-label attribute whose value is a descriptive title of the group. The value of aria-label must be localized,
as some browsers will read it to the user.
autocomplete property.
aria-describedby attribute whose value is a space-separated list of the
ids of the message(s).
aria-describedby and aria-errormessage
attributes whose value is the id of the error message. In addition,
while the input's value is invalid, the input should have aria-invalid="true" on it.
aria-labelledby attribute whose value is the id of the element that describes it.
span with class visually-hidden
whose contents are localized text explaining what the button does (e.g. "Search").
Full-Width Containers are for laying out parts of the page (such as hero zones) that should try to span the full available width, rather than using the layout grid.
Graphic button is deprecated as of Visage v3, and will be removed in the future.
If you just need a simple icon, instead please use a Control Icon.
If your page currently contains a Graphic Button with a visible border around it (using a textbutton skin), the new site look no longer uses this visual style, so your page will need some redesign work to figure out what should go there instead — whether that's a button without a visible border, a textbutton with both text and an icon, etc. Please reach out to us for assistance, or to your designer if your team has one.
Graphic buttons are graphics that show an icon, such as "X" close icons or arrows. They may perform an action when pressed. They may have a buttonlike look, or have a transparent background.
These skins are only meant to be used on a <button> tag, on
elements that are clickable and interactive.
Using the "primary" skin:
Using the "secondary" skin:
An older API used actual textbuttons to create the Graphic Button look.
Note: this feature cannot be used on an <input> tag.
button tag.
If that is not possible for some reason, you need to add the attributes role="button", tabindex="0", and
class="accessibility-keyboard-clickable" to provide accessibility.
span tag inside an
a tag. It should not have the attributes role="button" or tabindex="0", so that it does not provide
inaccurate accessibility.
span tag.
It should not have the attributes role="button" or tabindex="0", so that it does not provide inaccurate accessibility.
aria-labelledby attribute whose value is the id of the element that describes it.
span with class visually-hidden
whose contents are localized text explaining what the button does (e.g. "Close").
aria-hidden="true" to hide it from screen readers.
Graphic buttons are used in Studio controls, info icons, and video play buttons.
The grid is an invisible framework responsible for the order and rhythm of a page. By imposing constraints on layout, the grid makes it easy to achieve consistent and proportionate designs across devices.
The grid starts with an element with class grid-container. Inside it, place a row element with class row.
Within the row, place one or more
col-N elements, where N is a number between 1 and 12.
You can safely place more than 12 columns' worth inside a single row; the grid elements will show the first 12 columns' worth, and then will line-wrap the rest.
You can nest one grid element inside another one. The nested (inner) grid will be divided into 12 new columns, proportional to the width of the nested (inner) grid.
You'll need to place another row element inside the outer element, around the inner column elements.
You can also place an entire new grid container inside a column element:
col-12 with a grid container inside it:
Offsets let you indent a grid element, or widen the gap between elements.
Offsets shift a block over to the right by a certain number of columns.
They are ignored on Extra-Small screens.
The grid's layout is adjustable for our different screen sizes:
When you put a col-N class on a grid block, by default all screen sizes (except Extra-Small) will
make that grid block fill that number of columns. You can override that number for specific screen sizes:
col-lg-N.
This class will tell the grid blocks how many columns to occupy
on Large screens, overriding the default col-N value.
col-md-N.
col-sm-N.
On Extra-Small screens, by default, all the column elements will be full-width and
will fill the whole display. This is true
regardless of their col-N element.
You can override this behavior by appending a class of col-xs-N.
If columns in a row need to be re-ordered on a certain screen size, they can be "pushed" rightward or "pulled" leftward. Pushes and pulls are ignored on Extra-Small screens.
In each of the examples below, the green "col-9" element occurs first in the HTML. Pushes and pulls are used to move the elements around.
You can hide an element entirely on a certain screen size by using a hidden-XX class.
By contrast, you can make an element visible only on a certain screen size with
a visible-XX class.
You can apply more than one visible-XX
class to a given element, but don't put both a visible-XX and a hidden-XX
onto the same element.
These classes can be used on non-grid elements as well!
Sometimes a row should semantically be a list, since the columns are list items (e.g. rows of product tiles).
Other times, a grid container should be a list, since the rows are list items (e.g. Cart).
To support this, grid elements can be ul and li tags.
Adding the class col-flex-column to a col- element
will cause all of its direct children to be arranged as a column, spread out evenly between the top and bottom of the
row (rather than all being aligned to the top).
This is useful for keeping some elements aligned to the top and bottom of a
taller neighboring element.
Adding the class col-vertically-center to a col- element
will cause its contents to be vertically centered within the row.
Making a column element "sticky" means it will stay on screen so long as some other element in the same row is also visible. You can see it in action below by scrolling slowly downward. (However, things get a little tricky here on the UI Library Viewer because its navbar overlaps the content.)
To make the stickiness function properly, the row will not vertically stretch all its columns to be the same height, as it normally does. This can affect the display of the columns in that row. For instance, if you are using a Card Container with the "even height" option, (or a Card Set), the cards in that row may not be all the same height.
Adding the class "col-unsticky-xs" will make a sticky column act normally (that is, not sticky) on Extra-Small screens.
This option narrows the gutters between column elements. It is to be used with Standard Tiles using the "gallery" skin.
col-N element inside another, put a row element
around the inner element, or a layout error may occur.
col-3 and standard-section on the same element.)
Those other components may add spacing that will conflict with the grid component's spacing, and
might alter the grid's display. Notable exception: you can put Background Color onto a grid element.
ul and li tags as appropriate
instead of div tags. For instance, if a row contains a sequence of product tiles, the row
should be an ul tag, and the column elements should be li tags — because
semantically, those tiles are a list.
Hotspot zones allow clickable hotspots to be placed over a background image. The user can click a hotspot to view more information about what is displayed in that part of the image.
data-hotspot-top and data-hotspot-left
attribute, whose value is a number indicating how far across the hotspot should be from the background's
top left corner (considered as a percentage). For instance, a hotspot that should be 40% of the way down from the top
should have data-hotspot-top="40" as an attribute.
An Icon Tile Set consists of a number of Icon Tiles, which give prominence to important standalone links or elements. An Icon Tile Set can be used to create a "brand banner".
Icon Tile description
Icon Tile description with a link inside it
Icon Tile description
Icon Tile description with a link inside it
responsive-image stylesheet in the current platform.
It is part of a now-outdated API for the old platform only, and it will screw up the appearance of images.
Responsive Image is for when the image's aspect ratio is known. A Responsive Image will expand to fill its container.
padding-bottom,
with a value equal to the image's aspect ratio, expressed as a percentage.
img tags can, and often should, use the srcset attribute to
provide both hi-res and lo-res versions of the image.
You can read
more info on srcset at MDN.
alt attribute.
Typically, the alt attribute should have a small description of the image itself.
However, sometimes that
attribute might be a blank value (alt=""):
alt attribute if there is nearby HTML text that presents the same content as the image description.
For instance, a product tile offers both a product image and the product name.
The image does not also need the product name in its alt attribute, since this would mean that screen readers
would say the same thing twice in a row:
"Business Cards... Business Cards." In this case, the product image should use an empty alt attribute.
alt attribute if the image is purely decorative, such as a page divider, or a >
glyph at the end of a link.
alt attribute, the WC3 provides a handy
flowchart, "An alt Decision Tree".
alt attribute for accessibility reasons, but we cannot use an empty string
for some reason (e.g. we need the image to have a descriptive string to help boost SEO for image searches),
then as long as the image and its accompanying text are both inside the same link, you can put
role="presentation" aria-hidden="true" onto the image. This signals to assistive technologies that the image is
decorative and should be hidden from assistive technologies.
Fluid Image is for when the page does not know the image's aspect ratio. A Fluid Image will expand to fill its container, but will also force a reflow once it loads, so it is less preferable than a Responsive Image.
img tags can, and often should, use the srcset attribute to
provide both hi-res and lo-res versions of the image.
You can read
more info on srcset at MDN.
An Input Group groups together a Text Input with any helper text or error message. It is only meant to be used inside a Standard Form.
Helper text
Error text
Left-hand navigation is a vertical list of links used to navigate a site section. Left-hand navigation is a pattern made up of multiple link-list components.
nav tag. If for some reason
you cannot use the nav tag, you must instead place role="navigation" on the wrapper
element.
Links are hyperlinked text used for navigation.
Here is a paragraph of regular body text with a link in the middle of it.
Here is a link with class "strong" on it.
Here is a dark page section with a link with class "text-color-white" in the middle of it.
Here is a link with class "unstyled" on it. It won't show up with normal link styling, although it still gets the "pointer" cursor if you hover over it. (This link is intended only for use directly around product tiles and other elements that provide their own affordance!)
Note: these links are only to be used in particular locations such as tiles and heroes!
A link with the "CTA" skin on it.
Inside a block of text-color-white, the CTA link
automatically changes its icon to white:
A link with the "CTA" skin on it
The "link-with-icon" component is a link that has both text and an image or icon, and vertically centers both sub-elements.
Some link with a graphic button
Using option "link-with-icon-separated" to put spacing between the image and text
rel="nofollow" attribute to internal links that are pointing to a page that should not be crawled by
search engine bots.
Lists contain related items that are organized vertically.
li, which is incorrect semantic HTML
that causes accessibility issues.
(An icon bullet list allows you to set a custom icon as the "bullet" for each item.)
And here's a paragraph of text below it
Lists are useful, efficient, and easily digestible by users. Use lists when describing steps, instructions, or rules. When using lists, make sure items are:
aria-labelledby attribute whose value is the id of the heading.
A lazyload zone will delay the loading of its contents until after the main content of the page finishes loading.
This paragraph contains content that is not lazyloaded, so it will be shown as soon as the page loads.
This is content inside the lazyload zone that is not commented out, so it will not be lazyloaded.
div, so choose a semantically-appropriate tag.
The zone has display: contents set on it, for those browsers that
support that value.
aria-live="polite" on it, to cue
screen readers and other assistive technologies.
Media query variables are a feature used in LESS/SCSS to make some CSS only apply to certain screen sizes.
(The layout grid also features some pre-defined hidden-XX and visible-XX CSS classes that replicate some of this functionality.
Those classes can be used to make elements appear or not appear on certain screen sizes.)
This text should only be red on Large screen sizes.
This text should only be red on Small screen sizes.
This text should only be red on Extra-Small screen sizes.
This text should only be red on Small screens or smaller.
This text should only be red on Small screens or larger.
For meta-level information that is not shown to customers. For instance, this might be used for metadata sections shown during debugging, or for information shown only in Sitecore's Experience Editor but not in the actual customer-facing page.
This is regular content.
This is regular content.
A Modal Dialog is a secondary window that appears in a layer above the application, to display content that demands user action.
(Our modern modal dialog is also known as "Stylized Dialog", since in the vanilla API, it adds Vistaprint styling to the native <dialog> element.)
without a nav or body
Some other dialog use cases:
Setting the "takeover" option will cause the dialog to fill the full screen.
The "no close button" will suppress the "X" close button in the dialog.
The "full bleed" skin removes the padding around the dialog content, so that the dialog's content touches the dialog's edges.
The "data-dialog-enable-browser-history" attribute allows modal dialogs to be closed with the browser's back button.
The "panel" option turns the dialog into a panel that slides out from the edge of the screen. If sliding from the left or the right, the panel will be as tall as the screen.
"Panel" dialogs can also add a "pinned" option that will make the dialog footer pinned to the bottom of the dialog (for those browsers that can support this feature).
An updated API in version 4.15 adds a "body" element around the dialog's main content, as well as a "nav" element (optional, but recommended) around the close button. Most of the dialogs in the "current API" column below also use the "panel-capped" option to limit the width of the panel.
Instead of a dialog footer, an older API used two optional sub-elements:
The "panel menu" is for left-hand flyout menus, such as the site navigation on mobile devices.
body tag, and not
in the head tag. This will ensure that it smoothly loads its polyfill as needed.
data-dialog-show attribute whose value is the ID of the dialog.
You can also show it by calling the method showStylizedDialog()
with the dialog's DOM node as the argument.
Once the dialog has been shown, it will trigger a showStylizedDialog event.
Do not use the native showModal() or show() methods,
as these will cause display and functionality errors.
stylized-dialog-close
on it.
You can also close it by calling the method closeStylizedDialog()
with the dialog's DOM node as the argument.
Do not use the native close() method.
Once the dialog has been closed, it will trigger a close event.
data-dialog-max-width attribute on the dialog, e.g. data-dialog-max-width="1000"
data-dialog-iframe-url (the URL of the iframe), data-dialog-iframe-id
(the id of the iframe), and data-dialog-iframe-title (the title of the iframe).
dialog node within the DOM tree,
in order to position it properly on the screen and to provide accessibility support.
Therefore, you shouldn't rely upon the dialog being able
to inherit any CSS from any given ancestor, and you shouldn't use an ancestor selector in your CSS that
expects the dialog to have a certain ancestor. Any CSS selectors for the dialog content should
only refer to elements within the dialog itself.
id attribute on them.
dialog tag should have an attribute
aria-labelledby whose value is the id of the title. If it does not have a heading,
then the dialog tag needs an aria-label attribute whose value acts as a title
for the dialog; the text for this value must be localized, since some browsers will read it to the user.
dialog tag should have an attribute
aria-describedby whose value is the id of that descriptor element.
The old jQuery Modal Dialog component is now deprecated. It is based on the SkinnyJS modal dialog component.
Open the dialog (using <a> tags for the buttons, instead of <button> tags)
Option Set is deprecated as of Visage 3.0. Its functionality has been largely supplanted by the much simpler Selection Set.
Option sets allow users to make selections from a set of choices, arranging visual labels for those choices. Option sets can be either multi-select (using radio buttons) or single-select (using checkboxes).
(The "detailed" option lets you provide additional details, which will sit to the far right of each option.)
(You can add inner controls besides the left-hand radio button.)
(The "wide" option gives the buttons a minimum width, typically wider than the button's content.)
(The "half" option makes the buttons be half as wide as their container, so that they line up neatly into two vertical stacks.)
Shown with simple content:
Shown with horizontal Secondary Tiles inside the labels:
initializeControl event on it.
<label> tag. Any other
option-set-contents elements (such as price or quantity) should use another appropriate tag such as <div>.
option-set-inner-control on those inner controls.
This will ensure that the Option Set behaves correctly when an inner control is clicked on.
label tag for the option-set-contents element, since a label
cannot have another form element inside it. Instead, put the visible text of the label inside a span
with an id, and give the radio/checkbox an aria-labelledby attribute whose value is that id.
"checked" to indicate a checked state.
This class is often used as part of a polyfill for older versions of IE, and will be removed when we drop support for those IE versions.
Therefore, you should not use it to verify the checked state of the control. Instead, use the checked property of the underlying
input tag.
option-set must also have a role
attribute. If the Option Set is a set
of radio buttons, it should have role="radiogroup". If it is an Option Set of checkboxes, it should have role="group".
fieldset tag for the outer element. However, due to a bug in Chrome,
this caused problems when using display: flex with the control. We now recommend that you do not
use the fieldset tag.
option-set must have an aria-labelledby attribute whose value is the id of the element
that acts as a title for the Option Set (typically, a heading right above the Option Set.) If the Option Set does not have a visible title,
then instead it needs an aria-label attribute whose value is a descriptive title of the Option Set; this text must be localized,
as some browsers will read it to the user.
option-set-option-wrapper should also have a role attribute. For Option Sets of radio
buttons, this should be role="radio". For Option Sets of checkboxes, use role="checkbox".
aria-required="true" to the input.
Option Set is used to pick a size on product pages such as the Yard signs page.
A Paginator allows for navigation across a range of pages of related content, and also indicates a user's position within that range.
<a> tags, change the Prev/Next button to a
<span> tag and add class paginator-button-disabled.
<button> tags, disable the button as you
normally would for a button, by adding the attribute disabled="disabled".
<a> or <button> tags.
Use <a> tags if a click takes the user to a new page; use <button>
tags if a click loads new content into the same page.
aria-label values will need to be localized, since they will be presented to the user
by screen readers and assistive devices.
<a> tags<button> tags<a> or <button> tags.
Use <a> tags if a click takes the user to a new page; use <button>
tags if a click loads new content into the same page.
<a> tags, change the Prev/Next button to a
<span> tag and add class pagination-button-disabled. If your
Pagination Buttons uses <button> tags, disable the button as you normally would,
by adding the attribute disabled="disabled".
aria-label values will need to be localized, since they will be read out loud
by screen readers and assistive devices.
aria-current="true" to the button.
If you are using <a> tags, this button should be a <span>
tag (since the user does not need a clickable link to the current page).
The Price Bar displays price information and related content during product flow.
using a dropdown:
using a textbutton that launches a modal dialog:
using neither:
Older, deprecated API:
By default, the banner segments will be hidden on Small and Extra-Small screens. However, an adaptive design might require that for these screens, the banner be shown elsewhere on the page, separate from the regular Price Bar.
In this case, you can create a second Price Bar in a second location on the page, and add the "show-banner" option, which will force that Price Bar to show its banner (and only its banner) on all screens.
body tag
or the .site-main element, and give the Price Bar
position: fixed or position: sticky in your CSS,
along with an appropriate CSS value such as bottom: 0.
If you use position: fixed, you will likely want to
place some empty space at the bottom of that parent
element so that the Price Bar does not overlap other page content
when the page is scrolled down all the way.
.site-main element, and give the Price Bar
position: sticky in your CSS,
along with an appropriate CSS value such as top: 0.
<label>
tag, plus the visually-hidden class to hide it from screens.
Price Block is deprecated as of Visage 3.0, as it no longer represents our desired presentation for pricing across the site.
Pricing presentation now varies from component to component and from page to page, but most pricing information uses the standard API provided on the Type page.
The price block provides a standard display for the purchase price, plus optional additional information.
A popover is a small container of secondary content that appears when a user clicks on a trigger element. The popover appears next to the trigger, pointing to the trigger to show that the popover’s contents are contextual.
Popovers are less disruptive than a modal dialog, and allow the user to continue browsing the page, closing as soon as the user clicks on anything else on the page.
The popover will automatically position itself, trying to avoid having its contents go off-screen, and it will typically have its arrowhead pointing to the center of the element that triggered it. You can specify its preferred orientation (above, below, to the left of, or to the right of the trigger).
The default version of a popover acts like a tooltip, except that it shows up on click rather than on hover. A "tooltip" popover provides additional information, but cannot contain any interactive elements.
If the popover has any interactive elements, it's acting not as a tooltip, but rather as a (modeless) dialog, so the
triggering element needs to specify the data-popover-role="dialog" attribute.
This allows the popover to provide the proper accessibility support.
Any element inside the tooltip with class popover-close will close the popover when clicked.
This is a "dialog" popover.
Setting data-popover-skin="full-bleed" on the triggering element will add the "full-bleed" skin to the popover.
This skin removes the padding around the popover's contents.
This is a popover with the "full-bleed" skin
data-popover-role="dialog" attribute.
<template> tag does not exist as an element in the DOM tree
(as with any <template> tag), so will not be available to JavaScript until the
popover has been triggered.
If you need the content to be available before the popover has been triggered,
use an <aside> tag instead of a <template> tag.
<template> tag has an id, that id will not
be passed on to the popover once created; the id stays associated with the <template>.
Instead, if you need to give the popover a particular id, give the triggering element
a data-popover-id attribute; its value will be added to the popover as its id.
popover-content tag should have an attribute
aria-labelledby whose value is the id of the heading. If the popover does not have a heading,
then the popover-content tag needs an aria-label attribute whose value acts as a title
for the dialog; the text for this value must be localized, since some browsers will read it to the user.
A visual element that shows an operation is in progress.
Shipping Cost: Loading... for two-day delivery
You can put a Preloader inside a Textbutton to show that the page is readying a response to the button being clicked; the preloader will take on a special appearance inside a Textbutton. You should disable the button while the Preloader is showing, to prevent the user from trying to click the button again.
span with class
visually-hidden, whose contents are localized text that describe what is happening
(e.g. "Loading...")
A determinate indicator that informs the user the percentage to completion of a system operation.
Use when uploading or downloading large files or a longer system operation.
When customizing the Progress component via themes, you can add a border or drop shadow around the bar, but be aware that some browsers (including Chrome and Safari) can be inconsistent about the width, making it appear thicker on some sides.
If you need to change the value of the progress bar, you will need to use the function setProgressValue() on the
<progress> DOM node, e.g. setProgressValue(myProgressBarNode, 23);
This function will update both the progress bar and the numeric label.
A Progressive Image improves the user's perceived page load time by deferring the loading of large images. Each Progressive Image contains both a low-res placeholder image that is part of the initial HTML, plus a second, full-resolution image that loads at a later time.
The "immediate" option makes the page load the full image as soon as possible, typically at the DOMready event. This is useful for images "above the fold" at the top of the page.
The "eager" option makes the page load the full image as soon as the page reaches the "load" event. This is useful for images that are near the top of the page.
A default Progressive Image loads only when it scrolls into the viewport.
A promo bar contains a promotional message, typically a promo code plus other promotional information. It is used directly above a hero.
<p> tag that is a direct child of the
promo bar. The promo bar automatically puts a small amount of spacing between each segment.
A promo code is a code that the user can enter to receive a discount at checkout.
default
using "text-color-white"
"white" skin
Radio buttons are almost never intended to be used on their own. Instead, they should be used within an Selection Set, so that they have a standard label and standard layout.
role="radiogroup". This wrapper element must have an aria-labelledby attribute
whose value is the id of the element that acts as a title for the radio group — or, if the group does not have a visible title,
an aria-label attribute whose value is a descriptive title of the radio group.
The value of aria-label must be localized, as some browsers will read it to the user.
aria-required="true" to the input.
A range input lets users pick a numeric value along a track using a handle.
min,
max, and step.
--visage-range-height, and if you
make this number taller than the height of the thumb, you will get extra whitespace around the thumb
and track.
A range slider is a control that uses a handle to let users adjust value or pick a range of values along a track. The lesser value is placed on the left or bottom and the greater value to the right or the top.
Use value labels and tick marks when users need to know exact numeric settings.
initializeRangeSlider()
function, e.g. $(".my-range-slider").initializeRangeSlider().
Ratings and Reviews provide customer-submitted reviews of our products, to inspire consumer confidence.
which has a 1-star rating.
which has a 5-star rating.
which has a 3.5-star rating.
ratings-and-reviews-hide-ask-a-question to the outer wrapper (the one with class ratings-and-reviews)
will hide the "Ask a Question" button.
Secondary tiles are used for presenting secondary pieces of information on a page, such as accessories or product options.
Tile name
Tile name
Tile with badge above
Tile with price
Tile with promo message badge
If the tile is an <a> tag, then all such tiles in the same grid row
will be equalized, so that they have the same visible height.
The tile name should use the underlined "CTA" link only if the tile name has no other accompanying information (no price, badge, etc).
If the tile doesn't have a CTA link on it,
we recommend adding class secondary-tile-shadow-hover to give
the tile a drop shadow when hovered over,
to provide some affordance that the tile is clickable.
Tile name
Tile description goes here
Tile name
Tile description goes here
Tile description goes here
Tile description goes here
Tile description goes here
Tile name with no description
Tile name with price
Tile that launches a panel dialog
<label> tagsul and li
tags, so that the tiles are grouped semantically into a list. Use <ul class="row">
and <li class="N"> for the grid elements around the tiles.
role="radiogroup",
plus an aria-labelledby
property whose value is the id of the element that labels the set of radio buttons (e.g.
the heading for that page section).
secondary-tile-labeled-input with a button that
shows the currently selected value and, when clicked, opens a dialog. These buttons
must have:
aria-labelledby attribute whose value is the id of the associated label
visually-hidden inside the button, whose contents
provide instruction to the user about what clicking the button does. For instance, this span
might say "(Click to change selection)".
We use heroes to show our most important content and grab the user's attention in a visual way. Heroes are positioned at the top of the page to lead the additional POV and content for the rest of the page. The Standard Hero represents the usual visual treatment for heroes on our site.
The default Standard Hero puts text and image alongside each other. The image will always have a fixed height, though its width will vary based on the user's screen width. The image may be scaled and/or cropped to fit.
A Standard Hero heading on multiple lines Abcdefghijklmno
This standard hero description also wraps onto two lines, or maybe even onto three lines.
The "full width image" option makes the image fill the entire hero, with the text overlaid on top. The height of the hero will be determined by the height of the text; the image will be stretched and/or cropped to match.
Hero title here
The standard look. You still need to explicitly specify the "full width image" option, for backwards-compatibility reasons.
(Optional) A footnote can go below the button.
Using "text-right" option
Adding the "text-right" option aligns the text box to the right.
Using "text-center" option
Adding the "text-center" option aligns the text box to the center, and also makes the contents of that box centered.
using "staggered" option
This option makes the image and text box staggered.
using "staggered" option and "text-right" option
This option makes the image and text box staggered.
using "text-transparent-background" option
Keep the description short!
(Optional) text with class "strong" plus "mt-0 mb-2"
using "short" option
plus the "text-transparent-background" option.
(Optional) A footnote can go below the button.
Hero title
This option is deprecated, as we no longer want to use top-aligned text.
Some hero with text on right
This standard hero has its text on the right-hand side.
Some hero heading that wraps
aria-hidden="true" to the highlights element.
This will hide the highlights from assistive technologies.
h1 tag.
If it is not the page title, use whatever tag is appropriate for the page structure.
alt text about what's shown in the image.
Standard Hero can be used outside of the page's hero zone to create a narrow banner in the middle of a page. To do so, add the "narrow" option, which will adjust the hero's layout and typography to better fit a narrow width. Then place the Standard Hero inside a layout grid element.
Banner title
This banner uses the "narrow" options, plus the "text-center" and "text-align-bottom" options.
Banner title
This banner also adds the "staggered" option to the previous list.
Banner title
This banner is showing the "transparent-background" option.
This combination places a Left-Hand Navigation component over part of a full-width-image hero, with the navigation spilling over into the area below the hero. The content below the hero is shifted over to accommodate it.
Hero heading Abcdefghijklmno
The hero should use the "text-transparent-background" option.
Here is the content that goes below the hero.
A Selection Set is a series of radio buttons or checkboxes (aka "selections"), though they may have the look of other elements. For instance, a mutually exclusive set of Standard Tiles would be a Selection Set.
The "show-inputs" option will cause the underlying <input> element (the actual radio button or checkbox) to be displayed
rather than hidden.
Combining this with the "simple-column" skin will create a columnar layout of the inputs and their labels.
Shown using checkboxes instead of radios:
Please select an option.
Shown using nested Selection Sets and multi-level checkboxes:
selection-set class onto a grid row element, if the
selections that the user is choosing from are spread out among the columns inside that row.
For instance, if you are presenting a row of Standard Tiles to choose from, the row can also
act as the selection-set element.
type="checkbox" instead of type="radio" on the input tag.
<input> tag)
inside the <label> tag.
selection-set
must also have a role attribute.
If the Selection Set is a set of radio buttons, it should have role="radiogroup".
If it is an Selection Set of checkboxes, it should have role="group".
selection-set must have an aria-labelledby attribute whose value is the id of the element
that acts as a title for the Selection Set (typically, a heading right above the Selection Set.) If the Selection Set does not have a visible title,
then instead it needs an aria-label attribute whose value is a descriptive title of the Selection Set; this text must be localized,
as some browsers will read it to the user.
aria-required="true" to the input.
While Visage components may have their own internal spacing, the spacing classes allow you to add specific spacing between page elements.
The spacing classes follow the format {property}{sides}-{size}, where:
m for margin (external spacing), p for padding (internal spacing).
b for bottom, t for top, y for y-axis (both top and bottom),
l for left, r for right, and x for x-axis (both left and right).
1 and 12; see table below.
0, which will cancel out that margin and set it to zero. This can be useful if a component already has margin that you don't want.
8 through 12 are only available for top and bottom. (If you need more horizontal spacing than size 7, use the layout grid instead.)
For instance, to put margin size 5 on the top and bottom of an element, use class my-5.
There are some additional choices for margins:
mx-auto sets the x-axis (left and right margins) to auto.
This can be used to horizontally center a block element.
ml-auto and mr-auto set the left- and right-hand margins
to auto. These can be useful with flex-based layouts.
my-3 mt-5 is a bad idea, because they are both trying to set the top margin.
But mt-3 p-5 is fine, as is my-3 mx-5.
A Square Image Container creates a square element that centers a Fluid Image inside it, and stretches the image to fill the width or height of the square as appropriate for its aspect ratio.
Square Image Container should only use Fluid Images and not Responsive Images.
Use the Standard Section to wrap major sections of the page, to provide margin at the bottom of that major section, so that its contents do not run up against the section that follows it. For instance, it might be used to wrap a page's hero so that the hero doesn't touch the content that follows it.
Do not use Standard Section just to add some spacing somewhere! Use it only to wrap major sections of a page, as part of the page's document structure. Using it improperly can cause accessibility issues for some assistive devices.
If you just need to add some space, use our Spacing system instead.
Standard Section adds 32 pixels of margin at the bottom. You can also pick the "mini" option, which will give you 16 pixels instead.
Standard Section is intended to wrap major sections of the page, and should not be used to adjust spacing for smaller page elements. (Using it improperly can cause a accessibility issues for some assistive devices.)
Some components may have their own bottom margin or spacing, which may interact with the Standard Section's bottom margin.
Standard Section is intended to wrap major sections of the page. If you just need to add some spacing around an element, use the Spacing system instead.
Assistive technologies such as screen readers construct a document outline based on the HTML for the page. Therefore, only use Standard Section for major sections of the page, or the page may be presented incorrectly to assistive technologies.
The Standard Tile may be used for promoting products, or for other instances where an image should be followed by descriptive text.
Standard Tiles should use the "product" skin when clicking on them takes you to a product/category page.
Adding the "full-bleed" option to a "product" tile makes the image stretch all the way out to the edge of the tile:
The "gallery" skin looks much like the "product" skin, but has a slightly different layout. Standard Tiles should use the "gallery" skin when displaying a design choice, where clicking on the tile selects or drills down on that choice, rather than going to a product page for the product.
Tiles with the "gallery" skin should only be used inside a grid using the "tight" option.
The "gallery" skin can also take a background image for the tile. It then puts a background color under the tile contents so that they can be seen against that background image.
Without using either of the above skins, the tile takes on the default look. This can be used for informational tiles, or other tiles that aren't about products or designs.
Pages that were built before the product and gallery skins were available may still be using this look for products and designs, if they haven't updated yet.
This is a tile that's not a link, such as informational tiles in Resource Center pages. It has no CTA at the bottom.
This whole tile is not a link.
These Card Containers are using the "even height" option so that every tile on the same row has the same height, and the "bordered" option to give them a visible border.
This whole tile is not a link, but the tile name is a clickable link.
standard-tile-name sub-element.
<button> tag.
This prevents nested <a> tags, which are prohibited by HTML.
ul and li
tags, so that the tiles are grouped semantically into a list. Use <ul class="row">
and <li class="col-N"> for the grid elements around the tiles.
alt attributes:
alt attribute if there is nearby HTML text that presents the same
content as the description of the image — which is usually the case for Standard Tiles, since the tile name
immediately follows the image, and typically describes the image.
(Using an empty alt attribute prevents screen readers from saying the same thing twice in a row:
"Business Cards... Business Cards.")
alt attribute not be empty (per the above),
so that the image shows up better in image searches. In this case, if the image and the tile name
are both inside the same hyperlink, you can put role="presentation" aria-hidden="true"
onto the image. This will hide the image entirely from assistive technologies, but not from screens or
search engines.
A Step Indicator is a navigational element that shows the user's progress in a series of steps or pages within a design or order flow.
Use a step indicator to break up tasks into manageable steps, which helps the user avoid information overload and assists in decision-making.
On mobile devices, implement adaptive design and use an Accordion instead of Step Indicator to indicate progress. (The Step Indicator will not automatically adjust to an Accordion!)
with a clickable <a> tag to go to a previous step:
with a clickable <button> tag to go to a previous step:
on the first step:
on the last step:
using step values:
showing what happens when the Step Indicator content is wider than the available area:
step-past on them. The immediate previous step
should also get class step-previous.
step-future on them. The immediate next step
should also get class step-next.
<button> tag inside one of the steps, you'll need to apply the class
link to the button to make it look like a link.
<button> tag inside one of the steps, you'll need to apply the class
link to the button to make it look like a link.
aria-current="step" attribute on it.
a tag if you just need a link to another URL,
or a <button> tag with class link if you need to
perform an in-page action such as a JavaScript event.
Tables organize data into columns and rows to make information easier to scan.
| Qty | Greyscale grid | Color grid |
|---|---|---|
| 1 | $X.XX | $X.XX |
| 5 | $XX.XX | $XX.XX |
| 10 | $XX.XX | $XX.XX |
| 50 | $XXX.XX | $XXX.XX |
| Quantity | Small Unit cost | Medium Unit cost | Large Unit cost |
|---|---|---|---|
| 1 | $X.XX $X.XX | $X.XX $X.XX | $X.XX $X.XX |
| 5 | $XX.XX $XX.XX | $XX.XX $XX.XX | $XX.XX $XX.XX |
| 50 | $XXXX.XX $XX.XX | $XXXX.XX $XX.XX | $XXXX.XX $XX.XX |
| Style |
Tri-fold Ideal for larger menus and displaying additional information like images. |
Long Ideal for smaller menus, food trucks, and restaurants with a more limited selection. |
|---|---|---|
| Size | A standard 8.5" x 11" sheet folded three times, offering six separate panels. | A flat sheet of 3.6" x 8.5" paper. Double-sided, full-color printing available. |
| Paper Stock | Standard glossy, Premium glossy | Standard glossy, Premium matte, Premium recycled |
<table> tag should only be used for tabular display of data, such as a pricing table.
It should not be used to lay out page content into rows and columns; use the
layout grid for that.
<caption> tag
that sits as the first child of the <table> tag.
By default, caption contents horizontally centered; you can use the class
text-left on the contents to make them left-aligned.
table-scroll-container will allow it to horizontally scroll,
if the table's content is wider than the available width.
<table> tag should only be used for tabular display of data, such as a pricing table.
It should not be used for page layout!
<th> tag is a row header rather than a column header, be sure to include scope="row".
If your table has both row and column headers, the column headers will need scope="col".
Use tabs to organize and navigate between different types of related content at the same level of hierarchy, in the same viewing area on a page.
Tab headers will not line-wrap if there is not enough space to display them all. Instead, the user will be able scroll them horizontally. A slight gradient will appear at the right edge to indicate there is hidden content.
Use this to toggle between high priority content. Placements include the returning customer homepage and product pages on desktop.
With this option, the tab headers all have a fixed width of 240px. Use this to toggle between high priority content. Placements include product pages on mobile.
This option makes the headers sticky to the top of the screen if the tabs content is tall.
Tab 1 content, which should be the default for this set of Tabs.
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
Some really tall content
This option makes the headers wrap to the next line if there isn't enough room.
Note: the API for this skin is different from normal; it places the contents before the headers.
This skin is intended for tab sets that show a large image in each tab panel, with thumbnails of the images as the tab headers. For instance, on a product page, the tab panels might show product images, with thumbnails of those images as the tab headers.
Tab 1 content, which is not the default tab for this container.
Tab 2 content, which should be the default tab for this tab container,
because it's been specified as selected in the HTML.
Tab 3 content, which you should not be able to see because this tab is disabled.
Tab 4 content, which is not the default tab for this container.
checked="checked".
disabled property onto the radio button associated with that tab.
tabs-headers element must have role="tablist".
input inside tabs-headers must have role="tab" and an
aria-controls property whose value is the id of the tab panel that it goes with.
tabs-contents, each tab panel must have role="tabpanel" and an
aria-labelledby attributes whose value is the id of the label in tabs-headers
that the tab panel goes with.
A text field enables users to input or edit alpha-numerical information.
With the "input with floating label" component, the input appears as an underline. The label appears to sit inside the input, floating upwards once the user enters text.
A text input and a button can be grouped together. The input should then use the "input with floating label" functionality.
The "resize-vertical" option limits resizing to vertical, prohibiting horizontal resizing.
<input> tag, always use a value for type that is
appropriate for the input's function. For instance, if the input represents a search
field, use type="search" rather than type="text".
Title Block is deprecated as of Visage 3.7. Page titles vary visually from page to page, so this generic component was insufficient for many pages. Instead, use our Type and Spacing to display your page's title as appropriate for your specific page.
The title block is a wrapper for the page title which properly distances the title (and optional subtitle) from the content below. It does not set the font size of the title, which is up to the individual page; it only sets spacing between elements.
h1 tag, and should appear on the DOM before any h2 or other heading tag.
h1 tag per page.
(You can have multiple h2 and other heading tags, as long as the structure is relevant for both users and search engines.)
The Thumbnail Hero lets the user see large images by clicking on one of a series of inset thumbnail images. A content box is overlaid on top of the hero to provide additional text or controls.
Toggle switches are digital on/off switches. They prompt users to choose between two mutually exclusive options, and always have a default value. Toggles should provide immediate results, giving users the freedom to control their preferences as needed.
aria-checked attribute
of the button. A value of true means that the switch is on.
aria-labelledby attribute
whose value is the id of the element that labels the switch. If the page design
does not call for a visible label for the switch, you will need to create a labelling
element anyway, and then use the visibility-hidden class to make the labelling element
hidden on screens.
.visually-hidden) to the
switch's labelling element to make the purpose of the switch more clear.
Our font is Graphik, in three weights:
| Font file name | Visage font weight | Used by |
|---|---|---|
| Graphik Regular | 400 | default text |
| Graphik Medium | 700 |
CSS font-weight: bold, <strong> tags
|
| Graphik Bold | 900 |
heading tags <h1> through <h6>, .text-size-1 through .text-size-3
|
This is standard body text for the site: Etenim, siste, me iuva, auscultaque. Gelu redivit cum inventione novissima. Nescioquid me constringit. Fluo ceu hasta baleanarum necandarum noctu et quotidie. Umquam hoc desistetne? Ego dubito. Lucernis restinctis luceam. Ad ultimum flecto microphonem ut vandal. Scenam illumino et ineptum incero etsi candelam faciam.
This is body text adding class "strong".
This is body text adding classes "small" and "strong".
This is body text adding class "body-large".
Structural headings should use h1-h6 tags as appropriate for the document,
rather than choosing a heading based on its font size. (You can then adjust the font size of a heading;
see "Text Sizes" below.)
For comparison, here is a paragraph of regular body text. Etenim, siste, me iuva, auscultaque. Gelu redivit cum inventione novissima. Nescioquid me constringit. Fluo ceu hasta baleanarum necandarum noctu et quotidie. Umquam hoc desistetne? Ego dubito. Lucernis restinctis luceam. Ad ultimum flecto microphonem ut vandal. Scenam illumino et ineptum incero etsi candelam faciam.
A heading or paragraph can override its default font size by specifying one of these classes:
text-size-0
text-size-1 (font 56px/line height 1) (font 38px/line height 1)
text-size-2 (font 46px/line height 1.2)
text-size-3 (font 30px/line height 1)
text-size-4
text-size-5
text-size-6 (font 14px/line height 1.5)
text-size-7 (font 12px/line height 1.5)
These text sizes are only for marketing use inside hero zones:
text-size-A
text-size-B
You can change the default font size of a heading (or any other tag) by adding one of these text size classes:
Default text
.text-center
.text-right
List prices use the class .list-price, which normally looks the same as normal text.
Inside a .comparative-pricing block, its appearance changes:
.list-price
.discount-price
A full .pricing block may also include offer information and/or a tax message:
100 Starting at
€10.99
€8.99
Inc. VAT
(This block may get context-specific styling in certain contexts, e.g. inside a Standard Tile.)
The .discount-price class can also be used by itself
(outside of a comparative pricing block) to indicate price savings, e.g.:
You saved $12.34!
This is the default text color. (If something else has changed the text color and you want to set it specifically to black instead, you can use .text-color-black to do so.)
.text-color-dark-grey
.text-color-holiday
.text-color-pink
.text-color-brand-blue
.text-color-white
.knockout
.error
.alert
An "overline" is text that goes right above a heading, providing broader-level context for the heading, often to indicate the product category of the product described by the heading.
Overline
.all-caps
h1 through h6)
based on the semantic structure of the page's content.
Then apply the text size class that matches the intended visual look.
Any text size class can be used on any heading tag!
h1, and it should be the page title.
h1. The next level of heading for the page should be an h2,
and so on.
p or div) and apply a text size class to it.
$dark-grey fall below the minimum contrast ratio when used on white.
Likewise, white can be used for text used on dark backgrounds.
The "Uncustomizable Markup" component is a wrapper to put around any content where we don't have the ability to customize the HTML markup, and thus can't add UI Library classes to the HTML tags. This component gives some UI Library standard look-and-feel to the HTML tags in that content.
The following content is inside an Uncustomizable Markup component:
stylized-list class
stylized-list class
stylized-list class
stylized-list class
| Table header | Table header | Table header |
|---|---|---|
| This table has thead and tbody tags. | Table data | Table data |
| Table data | Table data | Table data |
Video refers to moving images with or without sound, not motion graphics such as animated gifs. Video can be an effective way to add value when content is complicated or detailed, and is a good conveyor for experiential merchandising.
This content has moved to the new site.
This content has moved to the new site.
To use a specific version of the visage-core library, visit the link below for that version of the viewer, and then use the reference URLs provided there.
Note: this list shows only the versions older than the one you're currently viewing. To ensure you are getting the most up-to-date list of possible versions, visit the viewer at the "Latest vN" URL at the top of the list.
If you think you could make this content even better, please reach out to the Visage team!