Styleguide

Foundations

The "Foundations" section outlines the color tokens, typography styles, grid parameters, and spacing rules used throughout the AmnestyUSA theme.

Color

Background colors

Dynamic color palettes

Text colors change based on the bg color class

tokens/src/color.tokens.json

css/common/colors.css

In twig: .ts-text-high-contrast in CSS: var (--color-high-contrast)

ts-text-high-contrast

ts-text-md-contrast

ts-text-low-contrast

ts-text-highlight

ts-text-high-contrast

ts-text-md-contrast

ts-text-low-contrast

ts-text-highlight

ts-text-high-contrast

ts-text-md-contrast

ts-text-low-contrast

ts-text-highlight

ts-text-high-contrast

ts-text-md-contrast

ts-text-low-contrast

ts-text-highlight

Typography

Defined in css/common/typography.css. Use classes in twig templates to apply styles .

Use headings to improve scannability and provide context for users to better understand the page. Headings also help structure page content for screen readers and search engines. Headings should be logically structured on a page using proper hierarchy, headings are ranked "h1" through "h6". A page starts with the H1 heading, which describes a page's main topic— the title of the page. Subsections can be organized with "h2" level headings. Those subsections can themselves be divided with "h3" level headings, and so on.

Header styles

.h2-alt-lg

.h1

.h1-alt

.h2

.h3

.h4

.h5

.h6

Text styles

.body-2xl-bold

.body-xl (Intro text)

.body-base (Body text)

.body-base-bold

.body-sm (Small paragraph)

.body-xs

.utility-md uppercase

.utility-md

.utility-nav

.utility-sm

.utility-xs

.utility-2xs

.tag

.tag-lg

Spacing

tokens/src/spacer.tokens.json

.ts-py-block and .ts-py-block-sm classes define block-level spacing.

See assets/css/base/utilities.css for definitions.

All of the margin, padding and height classes use generated from these base values. The are also available as css and tailwind variables.

--spacer-[size]

5xl

13 rem

(208 px)

4xl

10 rem

(160 px)

3xl

7.5 rem

(120 px)

2xl

6 rem

(96 px)

xl

4.5 rem

(72 px)

lg

3 rem

(48 px)

md

2.5 rem

(40 px)

base

2.25 rem

(36 px)

sm

1.5 rem

(24 px)

xs

1 rem

(16 px)

2xs

.5 rem

(8 px)

3xs

.25 rem

(4 px)

px

.0625 rem

(1 px)

Grids

Defined in utilities.css. Use "xl:container p-site" for site container and padding.

Wrapped in ts-grid-col-2

Wrapped in ts-grid-col-3

Wrapped in ts-grid-col-3-outline

Wrapped in ts-grid-col-4

Wrapped in ts-grid-col-5

Wrapped in ts-grid-7-5

Wrapped in ts-grid-centered

Components

The “Components” section outlines larger UI elements throughout the theme including buttons, inputs, dropdowns, and cards that display a variety of different snippets of content. These elements are present within the larger blocks or sections of your page builder.

Buttons and links

css/common/_buttons-links.css

views/btns

Buttons and links with icons are reusable components found in twig "views/btns"

All button and links use an included template.
See views/btns/[btn name] for templates and docs

btn-solid
btn-outline
btn-underline
btn-underline, color: 'yellow'
btn-solid, color: 'black'
btn-solid, color: 'gray-200'
btn-solid, color:'gray-200', size:'md'
btn-solid, size: 'md'
btn-solid, size:'sm'
btn-outline--sm
btn-outline--sm Arrow pointing downwards.

Variation details: color: 'white', link_svg_name:'download'

btn-outline--sm

Variation details: color: 'white', link_svg_name:'arrow-45degrees'

btn-arrow

btn-tag, events

btn-tag, press releases

btn-tag, campaigns

Form Inputs

Searchable Select

views/components/input--select.twig

Select

views/components/input--select.twig

Cards

Coming soon: card previews

Heroes

Heroes are located at the top of each page, and contain the page heading. Some pages have the hero set automatically, and others allow you to select between styles. Hero style and text values can be edited on the edit screen, at the bottom of the blocks section.

Hero (solid color)

The default option for Basic Pages. Best used for secondary level pages when the breadcrumb will be present. When an image is loaded, it will be automatically cropped to a 16:7 aspect ratio. Template name: hero--solid-color

eyebrow

Ways to Give

Optional subtitle. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Hero (solid color, no image)

Available on Basic Pages. Template name: hero--solid-color.

eyebrow

Ways to Give

Optional subtitle. No image. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Hero (background image or video)

Can display an image or video, and up to two buttons. Best used for top level landing pages that need an immediate CTA. An image is required, and displays on mobile. Template name: hero--background-image-or-video.

Aya in her family home in Toronto. When Debbie Rix saw the tragic, iconic image of three-year-old Alan Kurdi lying lifeless on a beach in Turkey, she decided it was time to take action. “In my store, the front page of our national newspaper had that picture above the fold. People kept coming in and turning the newspaper over, saying ‘I don't want to see that’. “I kept turning it back over and saying: ‘We have to look at this - we can't look away’.” The next day Debbie put a call out through Facebook that resonated with many friends, and friends of friends. A month later, their sponsorship group was 50 people strong. By August 2016, they had raised thousands of Canadian dollars and navigated a bureaucratic maze in order to welcome a family from southern Syria: Ahmed, his wife Razan, their children Aya, seven, and Raed, five, along with Ahmed’s sister Hoda, her boys Louai, 17, and Wael, 13, and grandma Khadija. Ahmed (not his real name, to protect relatives back home) used to own a huge restaurant for hungry tourists. Then his house and his restaurant were bombed and completely destroyed. The family were in Jordan for a number of years before finally being sponsored to come to Canada. Ahmed now attends a 6-week hospitality training scheme along with nephew Louai (17) at the Ritz-Carlton Toronto, specifically designed to equip refugees with crucial work skills. He hopes to open a Syrian restaurant in Toronto one day. The adults are learning English and the children are thriving, including seven-month-old baby Adam, who was born in Canada.

Ways to Give

Optional subtitle.

Take Action Give Now

Hero (texture)

Best used for tertiary level pages when the breadcrumb will be present. Gives you the options to select "yellow" or "gray" with the textured background, or "gradient" with a yellow gradient background.

Yellow Gradient

  • — Get Involved 2nd Level (when no image is desired - otherwise solid color with image)
  • — About 2nd Level (when no image is desired - otherwise solid color with image)
  • — Learn 2nd Level (when no image is desired - otherwise solid color with image)

Yellow Texture

Get Involved 3+ Level (we know you'd going a few levels deep in this area, so anything 3rd level and beyond should be the yellow texture)

Black Texture

  • — About 3rd Level
  • — News 2nd Level / Learn 3rd Level (reports and press releases have their own hero that pairs well with this)

Template name:hero--texture

Sint ex

Consequat do cillum

Labore in laborum reprehenderit nisi veniam ex dolore.
Sint ex

Consequat do cillum

Labore in laborum reprehenderit nisi veniam ex dolore.
Sint ex

Consequat do cillum

Labore in laborum reprehenderit nisi veniam ex dolore.

Hero (values animation)*

This hero is only available on the homepage and ties to our strategic goal of highlighting Amnesty values front and center. It should be used for the homepage when there is not an urgent action or issue to highlight. An image is required, and displays on mobile. Template name: hero--values-animation

*Available on limited pages.

We work to protect people wherever justice is denied.

Hero (urgent action)*

Available on the Homepage. Can display an image or video, and up to two buttons. Best used for featuring urgent crises/updates with immediate CTAs. An image is required, and displays on mobile. Template name: hero--urgent-action.

*Available on limited pages.

Aya in her family home in Toronto. When Debbie Rix saw the tragic, iconic image of three-year-old Alan Kurdi lying lifeless on a beach in Turkey, she decided it was time to take action. “In my store, the front page of our national newspaper had that picture above the fold. People kept coming in and turning the newspaper over, saying ‘I don't want to see that’. “I kept turning it back over and saying: ‘We have to look at this - we can't look away’.” The next day Debbie put a call out through Facebook that resonated with many friends, and friends of friends. A month later, their sponsorship group was 50 people strong. By August 2016, they had raised thousands of Canadian dollars and navigated a bureaucratic maze in order to welcome a family from southern Syria: Ahmed, his wife Razan, their children Aya, seven, and Raed, five, along with Ahmed’s sister Hoda, her boys Louai, 17, and Wael, 13, and grandma Khadija. Ahmed (not his real name, to protect relatives back home) used to own a huge restaurant for hungry tourists. Then his house and his restaurant were bombed and completely destroyed. The family were in Jordan for a number of years before finally being sponsored to come to Canada. Ahmed now attends a 6-week hospitality training scheme along with nephew Louai (17) at the Ritz-Carlton Toronto, specifically designed to equip refugees with crucial work skills. He hopes to open a Syrian restaurant in Toronto one day. The adults are learning English and the children are thriving, including seven-month-old baby Adam, who was born in Canada.

Hero (urgent action)

Optional subtitle.

Take Action Give Now

Hero (download)*

This hero style is only available on any news or report related content. It includes the ability to download a file. Template name: hero--download

*Available on limited pages.

Download Hero Style

June 8, 2023

Hero (Issue Detail)*

This hero style is only available on the issue detail pages. Includes page title, image, description, share links and last updated text. Template name: hero--inline-image

*Available on limited pages.

Gender and Sexuality Justice

Women, survivors, queer, trans, and femme people experience gender-based violence all over the world.

Share

Last updated on June 8, 2023

Hero (country)*

This hero is only available on country detail pages. Template name: hero--country

*Available on limited pages.

Eu enim exercitation sit

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin consectetur lorem mi, quis mattis ante luctus sed.

Hero (Event)*

This hero is only available on event pages and includes automatically populated event data such as date, time, location, and cost. Template name: hero--event

*Available on limited pages.

event

Rally to Free Leonard Peltier

Date & Time
November 13, 2022 @ 2:00 pm - 5:00 pm EST
Location
Lincoln Memorial
2 Lincoln Memorial Cir NW
Washington, DC 20002 United States
Event Website

Hero (Search)*

This hero is only available on the Search pages and includes a search form. Template name: search-form.twig

*Available on limited pages.

Search

Hero (Person)*

This hero is only available on the Person pages and includes social media and email contact information. Template name: hero--person.twig

*Available on limited pages.

Person Name

Executive Operations Specialist

LinkedIn Twitter Email

Blocks (page-specific)

Blocks are full width elements that can be added to the page, and combined to create a variety of layouts and designs.

Wayfinding cards*

The 3-up card is available on the homepage as a wayfinding tool to drive users into your core areas of work.

*Available on limited pages.

Our fight for human rights relies on a three-tiered strategy

Research

Our crisis response teams and researchers travel to affected areas around the world to uncover and document human rights abuses

Explore Resources

Advocate

Our staff and volunteers meet with policymakers and rally activists to put pressure on state and federal governments to protect human rights

Join Our Movement

Mobilize

Our campaign teams educate the public and give our members and grassroots activists information and tools to demand that human rights be protected

Get Involved

Issue scroller*

Available only on the homepage to provide pathways for users to explore main issues pages.

*Available on limited pages.

We are more powerful together than apart

Keep hope alive for refugees & asylum-seekers

Anyone fleeing danger or conflict should be given protection without discrimination. Help us support people seeking safety everywhere.

Explore our work

End gun violence

Join the movement for gun control across the United States so that everyone can live free from fear of gun violence.

Explore our work

Protect individuals at risk

Use your voice to help us campaign for the freedom of wrongfully detained human rights activists around the world.

Explore our work

Campaign List*

Wayfinding grid available only on the Campaigns Landing page to encourage users to explore more campaign detail pages.

*Available on limited pages.

Explore Campaigns

Photo by David McNew/Getty Images

Free People from ICE Detention

No one should be locked up for seeking safety. The US must respect the human right to seek asylum.

Explore

Photo by David McNew/Getty Images

Free People from ICE Detention

No one should be locked up for seeking safety. The US must respect the human right to seek asylum.

Explore

Photo by David McNew/Getty Images

Free People from ICE Detention

No one should be locked up for seeking safety. The US must respect the human right to seek asylum.

Explore

Photo by David McNew/Getty Images

Free People from ICE Detention

No one should be locked up for seeking safety. The US must respect the human right to seek asylum.

Explore

Issue Grid*

Wayfinding grid with animation to be used on the Issues Landing page only. Encourages users to click into relevant issues detail pages.

*Available on limited pages.

Issues

Individuals At Risk

CHILDREN SHOULD NOT BE LOCKED UP FOR SEEKING SAFETY.

Fight to End Gun Violence
Attendees hold signs during a protest against the death penalty at Speakers' Corner in Singapore on April 3, 2022. (Photo by ROSLAN RAHMAN/AFP via Getty Images)

Death Penalty

Event List*

Displays events in list mode - reserved for Events Landing Page only.

Preview of this block is not available.

*Available on limited pages.

Blocks (global)

Blocks available on all pages.

Image + text

Used to promote or feature a piece of content, specific pathway, call-to-action, or supplemental content. Works well for landing pages to showcase priority content or at the end of pages to give users relevant related pathways. Since this block offers a button, it is ideal to encourage users to click-through (as opposed to the Flexible Image + Text with no button).

The latest around the world

Content teaser text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin consectetur lorem mi, quis mattis ante luctus sed.
See all issues

Image

Used to display in-content media. One or two images can be added and background colors can be chosen between white, black, and yellow.

Flexible Image + text

Used as a supplemental content block to display media, it allows for flexibility to add images within longer form content (such as reports) to break up long text sections. Images can be displayed on the left or right with paragraph text fields.

Esse ullamco elit nisi

Content teaser text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin consectetur

ATTILA KISBENEDEK/AFP via Getty Images

Callout + Text

Visually dramatic way to call out a piece of text. Block splits into two columns with highlighted large text and paragraph text. When a subtitle isn't used, the title is larger and highlighted. Available with white or black background color.

No one should be punished for seeking safety

But every day, people are unjustly detained by ICE in abusive, deadly conditions and deported back to danger. Others at the border are blocked from exercising their right to seek asylum and sent back in harm’s way.

ICE is currently holding over 23,000 immigrants and asylum seekers. We've documented long-standing problems in the immigration detention system. These abuses were exacerbated by a rapid expansion of detention under former President Donald Trump.

No one should be punished for seeking safety
Optional subtitle

But every day, people are unjustly detained by ICE in abusive, deadly conditions and deported back to danger. Others at the border are blocked from exercising their right to seek asylum and sent back in harm’s way.

ICE is currently holding over 23,000 immigrants and asylum seekers. We've documented long-standing problems in the immigration detention system. These abuses were exacerbated by a rapid expansion of detention under former President Donald Trump.

Two Column Text

Block splits into two columns with paragraph text.

Lorem Ipsum

Left, dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lorem Ipsum

Right, dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Card Grid

Cards can be 2 or 3 columns wide. Used as a wayfinding tool to encourage movement to another part of the site or piece of content. Block cards can contain an image, title, teaser text, and button. Good for highlighting nested content within sections or related content. Recommended teaser text below 50 words.

ATTILA KISBENEDEK/AFP via Getty Images

End Gun Violence

We’re demanding Congress fund community-based gun violence prevention now.
Explore Campaign
ATTILA KISBENEDEK/AFP via Getty Images

Release Individuals At Risk

Our fight to secure freedom for people imprisoned simply for exercising their human rights.
Explore Campaign

Lorem Ipsum

ATTILA KISBENEDEK/AFP via Getty Images

End Gun Violence

We’re demanding Congress fund community-based gun violence prevention now.
Explore Campaign
ATTILA KISBENEDEK/AFP via Getty Images

Release Individuals At Risk

Our fight to secure freedom for people imprisoned simply for exercising their human rights.
Explore Campaign
ATTILA KISBENEDEK/AFP via Getty Images

End Gun Violence

We’re demanding Congress fund community-based gun violence prevention now.
Explore Campaign

Research Cards

Encourages users to dive deeper into Amnesty’s research by pulling in top relevant reports, fact sheets, and toolkits. Capable of referencing report posts. Title styling reminiscent of branded report covers.

Learn more

Report

In the Line of Fire: Human Rights and the U.S. Gun Violence Crisis

The U.S. government has allowed gun violence to become a human rights crisis, according to “In the Line of Fire: Human Rights and the U.S. Gun Violence Crisis,” a new report from Amnesty International. The report examines how all aspects of American life have been compromised in some way by the unfettered access to guns, with no attempts at meaningful national regulation.

Report

In the Line of Fire: Human Rights and the U.S. Gun Violence Crisis

The U.S. government has allowed gun violence to become a human rights crisis, according to “In the Line of Fire: Human Rights and the U.S. Gun Violence Crisis,” a new report from Amnesty International. The report examines how all aspects of American life have been compromised in some way by the unfettered access to guns, with no attempts at meaningful national regulation.

Report

In the Line of Fire: Human Rights and the U.S. Gun Violence Crisis

The U.S. government has allowed gun violence to become a human rights crisis, according to “In the Line of Fire: Human Rights and the U.S. Gun Violence Crisis,” a new report from Amnesty International. The report examines how all aspects of American life have been compromised in some way by the unfettered access to guns, with no attempts at meaningful national regulation.

Latest Scroller

A catch all block that features content from a variety of site areas, pulling in automatically the absolute latest post types such as Press Releases, Victories, Updates, etc. Overflows into a slider for shortened scroll and user-driven discoverability. Issue-specific detail pages will automatically filter promoted content that relates to that issue.

The Latest

View more

Event Scroller

Used to promote events across the site, such as the Get Involved section. Carousel will display upcoming events with a button to view more that will take users to the Events landing page.

Subscribe Form

Subscribe forms can be added to all post types to encourage users to sign up for your email subscription.

Quick Actions

Automatically displays Actions (same as those that appear in the expandable drawer). Issue-specific pages will be automatically filtered to display actions that are tagged with that specific issue. Edit actions through the Action post type on the admin screen.

Take Action

Tab + Text

Tabs can be used to break up content into digestible sections and reduce the length of the page. Tabs should be natural sections of the page copy, and clear to the user what the content within the tab holds. Recommended use on longer form content such as issues detail pages.

These policies continue to harm and oppress millions of people today. The U.S. is needlessly and brutally detaining people like Maura Martinez, a transgender woman from Nicaragua seeking protection in the U.S. She's being held at the Otay Mesa Detention Center in California, where trans people have reportedly been denied medical treatment, subjected to physical and sexual violence, and placed in housing that does not accord to their gender identity. Maura and countless others are stuck inside a system built on cruelty and needless detention.

There is a long pattern of abuse against migrants, and this cruelty and racism has shaped immigration policies for years. Black, Indigenous, and Brown people bear the brunt of harsh, punitive immigration policies and practices.

Immigrants and asylum-seekers should be allowed to navigate their immigration cases in freedom and in community, where they have family, faith, and the support of sponsors and community-based nonprofits. Test Link

  • Test List Item
  • Immigrants and asylum-seekers should be allowed to navigate their immigration cases in freedom and in community, where they have family, faith, and the support of sponsors and community-based nonprofits.
  • Test List Item
  1. Test List Item
  2. Test List Item
  3. Test List Item

Numbers Cards

Numbers cards provide a visual representation of key stats and numbers related to content. Block will automatically adjust depending on the number added (3 is not required).

By the numbers
23,753
People detained by ICE
Source: Title of Source
As of 7/11/2022
By the numbers
284,813
Families and immigrants monitored by ICE under their “alternative to detention” surveillance program
Source: Title of Source
As of 7/11/2022
By the numbers
134
ICE detention facilities with confirmed COVID-19 cases
Source: Title of Source
As of 7/11/2022

Testimonial

Used to display individuals’ stories and experiences. Quotes can be added and highlighted within any post type.

Moroccan journalist Hajar Raissouni, who works for the independent daily newspaper Akhbar al-Yaoum, was arrested on 31 August along with her fiancé Amin Rifaat, as they left a doctor’s office in Rabat. The doctor and two others working at the clinic were also arrested on suspicion of carrying out an abortion. “The arrest of Hajar Raissouni and four others is completely unjust and these allegations are an outrageous invasion of her privacy,” said Heba Morayef, Amnesty International Regional Director for the Middle East and North Africa. Under Moroccan law sex outside of marriage is a criminal offence. Abortion is also criminalized in all circumstances unless the health of the pregnant woman is at risk and her spouse agrees. However, under international law women have a right to bodily and personal autonomy which includes being free to make their own sexual and reproductive decisions. Criminalization of health services needed only by women, such as an abortion, amounts to gender discrimination.

If you want to improve your quality of life and the quality of life for all women, never stop questioning society or calling for change.

— Renee Wells Amnesty Argentinian student activist

Accordion

Accordions organize content into "hidden" sections. Good for content with questions-and-answers or longer sections where you want to have only headings visible on page load and encourage users to expand content to see more details.

In May, parliament adopted changes to the Criminal and Criminal Procedure Codes to align them with international criminal law, extending the definition of aggression, crimes against humanity and other specific war crimes, lifting their statute of limitation and providing for universal jurisdiction. The President did not sign these changes into law by year's end, however, and the Rome Statute of the International Criminal Court remained unratified.

In May, parliament adopted changes to the Criminal and Criminal Procedure Codes to align them with international criminal law, extending the definition of aggression, crimes against humanity and other specific war crimes, lifting their statute of limitation and providing for universal jurisdiction. The President did not sign these changes into law by year's end, however, and the Rome Statute of the International Criminal Court remained unratified.

In May, parliament adopted changes to the Criminal and Criminal Procedure Codes to align them with international criminal law, extending the definition of aggression, crimes against humanity and other specific war crimes, lifting their statute of limitation and providing for universal jurisdiction. The President did not sign these changes into law by year's end, however, and the Rome Statute of the International Criminal Court remained unratified.

Downloads

Link list to display a group of relevant downloads in a simple bullet-list format. Good for useful downloadable resources (such as PDFs) that are supplemental to the page content.

Downloads