Messaging — arXiv Design System

Contents

Announcement band

The announcement band is minimal but gets a lot of attention. Use sparingly to maintain its impact. If it is frequently deployed then our users will get used to it and tune it out. It sits above the site header as part of the header unit (full demo on the header reference page). The dismissal action persists across all repositories, but only for that particular banner. A new banner with a new message should display again for all users even if they dismissed the previous one. To put one up, see Banner announcements: the shared announcements file, its fields, and how an entry is checked, previewed and published.

Alert vs announcement? An alert belongs to the page’s content and is specific to that user’s journey. The announcement belongs to the site and is for all users.

arXiv is now an independent nonprofit. Learn more

Relevant code

<div class="ds-announcement" role="region" aria-label="Announcement">
  <span class="ds-announcement-text"><svg class="ds-announcement-glyph" viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
    <path d="M3 11h3l9-7v16l-9-7H3z"/>
    <path d="M19 8a5 5 0 0 1 0 8"/>
  </svg>arXiv is now an independent nonprofit.</span>
  <span class="ds-announcement-links"><a class="ds-announcement-link" href="#">Learn more</a></span>
  <button type="button" class="ds-close">
    <svg viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="M18 6 6 18"/>
      <path d="m6 6 12 12"/>
    </svg>
    <span class="is-sr-only">Dismiss announcement</span>
  </button>
</div>

.ds-announcement: The band. Takes role="region" and an aria-label so a screen reader user can find it and skip it. Goes directly above .ds-site-header.
.ds-announcement-glyph: The icon: an inline SVG from the icon set with aria-hidden="true", or an <img> with an empty alt for one of the bones. Either way it is decoration; the sentence conveys the meaning. It goes first inside .ds-announcement-text, so on a narrow screen it stays on the sentence’s first line.
.ds-announcement-text: The one sentence, after the glyph.
.ds-announcement-link: The link. An <a> with a real href.
.ds-announcement-links: Holds the link, or two, so they wrap together, under the text when it does not fit.
.ds-announcement-sep: Between the two links: an empty  with a no-break space on each side, drawn as a line. The spaces keep it from starting or ending a line, which a typed "|" cannot do.
.ds-close: The dismiss control, last inside the band; the band positions it at the right edge. Remembering the dismissal is the host’s job.

Tone

Announcement band messages must be concise and actionable, with a short link label. "Donate today" works because it is short and to the point. These examples do not work: "Click here" is not informative, and "Learn more about donating to arXiv" is too long.

One sentence, and it states a fact. What is happening, and when if there is a when: "Submissions pause on 1 January for maintenance." The link is where the reader goes for the rest.
The link label is a verb and a noun. It says what the reader will get: "Support arXiv", "View roles", "See what is new". It never repeats the sentence.
arXiv’s voice. Plain and direct. No exclamation marks, no "we are excited", no countdowns.
Time-bound. Every announcement has an end date, set when it goes up. A band that is always there is furniture, and people stop reading it.
One at a time. Two announcements compete and both lose. If two things must be said, the more urgent one goes up first.

Notes

A box in the flow of a page that names its own register before the reader starts the paragraph: a requirement, a piece of guidance, the way a component differs on the internal surface. The tab is the whole design. It is also what keeps a note from reading as an alert — an alert reports a state as of right now and can be dismissed, a note is always true and stays. A note keeps its colours on every surface; .ds-internal does not change them.

Tone

Grey, the default. Guidance: how to write something, when to reach for one option over another. Nothing here is a rule you can fail.

Accessibility essentials

Blue. A requirement — something that has to be true for the pattern to be correct, usually with a WCAG success criterion behind it.

Easy to get wrong A note can include a ruled-off warning at its foot with .ds-note-gotcha. Use it for the mistake the rule keeps being broken by, not as a second paragraph.

Internal variant

Lime. How this component or rule differs in internal tools, shown in the section it belongs to rather than on a separate page. This is the one place a public page may show Access Lime, because here the internal surface is the subject rather than the accent.

Relevant code

<div class="ds-note ds-note--essential">
  <h3 class="ds-note-label">Accessibility essentials</h3>
  <p>…</p>
  <p class="ds-note-gotcha"><strong>Easy to get wrong</strong> …</p>
</div>

.ds-note: The box, on a <div> in the flow of the page. On its own it is the grey register: guidance.
.ds-note-label: The tab, and the note's first child. The label is a heading, at whatever level the page is up to: .ds-note-label resets the type completely, so h2 through h4 all render the same tab. Keeping it a heading keeps the note in the document outline, which is how a screen-reader user finds it.
.ds-note--essential: The blue register: a requirement. It uses the info status colours.
.ds-note--internal: The lime register: how the component differs in internal tools.
.ds-note-gotcha: A ruled-off warning at the foot of the note, on a  whose first child is a  lead.

Three registers, and the set is closed on purpose. Adding one is three custom properties — --ds-note-tint, --ds-note-line, --ds-note-mark — but a colour only earns a register when it has a job. There is no background-colour utility class, because a tint that a page picks freely teaches the reader nothing.
No left edge and no icon. Both belong to the alert, and the tab already does the work of saying what kind of box this is — in words, so nothing has to be read out of a colour.

Accessibility essentials

Give the band a name. Keep role="region" and aria-label="Announcement" on it. That is how a screen reader user finds the band in the page’s landmarks, and how they skip it once they have read it.
Do not make it a live region. The band is part of the page as it loads, not a change that happens later. role="alert" or aria-live would make every page announce it aloud, on every visit, before anything else.
The sentence conveys the meaning. The icon is hidden from assistive technology (aria-hidden="true", or an empty alt), and the band’s colour says nothing on its own. Read the sentence without the icon and the colour; it must still make sense.
The link is a real link. An <a> with an href, so it works with JavaScript off and opens in a new tab if the reader wants. Never a button that navigates.
Name the dismiss control. The .ds-close button needs its Dismiss announcement. Do not use title or aria-label for this; page translation tools skip attributes.
After a dismiss, focus has somewhere to go. Removing the band removes the focused button. Move focus to the site header’s first item, so a keyboard user is not dropped back to the top of the document.
Nothing the page needs lives in the band. A dismissed band never comes back for that reader, so a link they must be able to find belongs in the page too.

Modifiers

Icon options

Icons are important for conveying meaning quickly and effectively. The small smileybones are drawn for this small use case. Each has its own colours, so it goes in as an image, not as a true svg icon. No alt text needed, the icon is purely decorative and the text conveys the meaning.

Celebrations

Open access

Maintenance

Relevant code

Smileybones

<img class="ds-announcement-glyph" src="assets/images/bones/icon_small-smileybones.svg" alt="">

Infinitybones

<img class="ds-announcement-glyph" src="assets/images/bones/icon_small-infinitybones.svg" alt="">

Errorbones

<img class="ds-announcement-glyph" src="assets/images/bones/icon_small-errorbones.svg" alt="">

Color variations

Open Blue is our default banner color, and should be overridden sparingly. For messages that call for a different treatment, two color variations are available: Black for maintenance and service notices, 'Smileybones yellow' for events.

arXiv will be closed for maintenance on January 1st Learn more

Relevant code

<div class="ds-announcement ds-announcement--maintenance" role="region" aria-label="Announcement">
  <span class="ds-announcement-text"><img class="ds-announcement-glyph" src="assets/images/bones/icon_small-errorbones.svg" alt="">arXiv will be closed for maintenance on January 1st</span>
  <span class="ds-announcement-links"><a class="ds-announcement-link" href="#">Learn more</a></span>
  <button type="button" class="ds-close">
    <svg viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="M18 6 6 18"/>
      <path d="m6 6 12 12"/>
    </svg>
    <span class="is-sr-only">Dismiss announcement</span>
  </button>
</div>

.ds-announcement--maintenance: For service notices: maintenance windows, outages, deadlines. The band takes the header’s dark ground in both themes, with light text and the light link blue.

We are celebrating 35 years of open science! Join the party

Relevant code

<div class="ds-announcement ds-announcement--event" role="region" aria-label="Announcement">
  <span class="ds-announcement-text"><img class="ds-announcement-glyph" src="assets/images/bones/icon_small-smileybones.svg" alt="">We are celebrating 35 years of open science!</span>
  <span class="ds-announcement-links"><a class="ds-announcement-link" href="#">Join the party</a></span>
  <button type="button" class="ds-close">
    <svg viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="M18 6 6 18"/>
      <path d="m6 6 12 12"/>
    </svg>
    <span class="is-sr-only">Dismiss announcement</span>
  </button>
</div>

.ds-announcement--event: For milestones and celebrations. The band takes the smileybones yellow in both themes, with fixed brown text; the link is the darker link blue, because the lighter one does not reach 4.5:1 on yellow.