# Mastercard — Design System
> Global payments technology company connecting people, businesses, and governments.
- **Canonical:** https://uiuxskills.com/library/mastercard
- **Source:** https://www.mastercard.com
- **Category:** Fintech & Crypto
- **Compatible tools:** claude, cursor, lovable, figma-make
- **Coverage:** 77%
- **License:** MIT
- **Last updated:** 2026-06-09T23:15:45.899Z

---

---
version: alpha
name: Mastercard
description: Global payments technology company connecting people, businesses, and governments.
tone: Professional, authoritative, global, and human-centric.
color-scheme: light
colors:
  primary: "#EB001B"
  secondary: "#F79E1B"
  surface: "#FFFFFF"
  surface-dim: "#F4F4F4"
  on-surface: "#1A1A1A"
  on-primary: "#FFFFFF"
  outline: "#D1D1D1"
  error: "#D32F2F"
  success: "#388E3C"
  focus-ring: "#005EB8"
typography:
  display-lg:
    fontFamily: sans-serif
    fontSize: 3rem
  display-md:
    fontFamily: sans-serif
    fontSize: 2.25rem
  headline-lg:
    fontFamily: sans-serif
    fontSize: 1.875rem
  headline-md:
    fontFamily: sans-serif
    fontSize: 1.5rem
  headline-sm:
    fontFamily: sans-serif
    fontSize: 1.25rem
  body-md:
    fontFamily: sans-serif
    fontSize: 1rem
  label-md:
    fontFamily: sans-serif
    fontSize: 0.875rem
rounded:
  sm: 2px
  md: 4px
  lg: 8px
  xl: 16px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
  2xl: 48px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    width: auto
  button-primary-hover:
    backgroundColor: "#C40016"
  button-secondary:
    backgroundColor: transparent
    textColor: "{colors.primary}"
    borderColor: "{colors.primary}"
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.md}"
    borderColor: "{colors.outline}"
  card-elevated:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.md}"
  input-field:
    rounded: "{rounded.sm}"
    borderColor: "{colors.outline}"
  input-field-focus:
    borderColor: "{colors.focus-ring}"
  link:
    textColor: "{colors.primary}"
  link-hover:
    textColor: "#A00012"
  badge:
    backgroundColor: "{colors.surface-dim}"
    textColor: "{colors.on-surface}"
  divider:
    backgroundColor: "{colors.outline}"
    height: 1px
  badge-error:
    backgroundColor: "{colors.error}"
    textColor: "{colors.on-primary}"
  badge-success:
    backgroundColor: "{colors.success}"
    typography: "{typography.label-md}"
    rounded: "{rounded.sm}"
    padding: 4px 8px
  swatch-secondary:
    backgroundColor: "{colors.secondary}"
    rounded: "{rounded.sm}"
    size: 32px
  swatch-focus-ring:
    backgroundColor: "{colors.focus-ring}"
    rounded: "{rounded.sm}"
    size: 32px
elevation:
  sm: 0 1px 2px rgba(0,0,0,0.06)
  md: 0 2px 4px rgba(0,0,0,0.08)
  lg: 0 4px 8px rgba(0,0,0,0.10)
---

## Overview

Mastercard's visual identity is defined by its iconic red and yellow circles, projecting a sense of global connectivity, trust, and innovation. The brand tone is professional, inclusive, and forward-thinking, emphasizing security and simplicity in the digital economy.

## Colors

The color strategy focuses on high-contrast, recognizable brand assets balanced by a clean, neutral interface palette to ensure accessibility and professional clarity.

*   Primary (#EB001B): The iconic Mastercard red, used for primary branding and key CTAs.
*   Secondary (#F79E1B): The iconic Mastercard yellow, used for secondary accents and brand recognition.
*   Surface (#FFFFFF): Clean white background for maximum readability.
*   Surface-dim (inferred) (#F4F4F4): Light grey for section backgrounds and subtle container separation.
*   On-surface (#1A1A1A): Dark charcoal for primary text to ensure high contrast.
*   On-primary (inferred) (#FFFFFF): White text for use on primary red backgrounds.
*   Outline (inferred) (#D1D1D1): Neutral grey for borders and dividers.
*   Error (inferred) (#D32F2F): Standard red for error states and validation messages.
*   Success (inferred) (#388E3C): Green for success states and positive feedback.
*   Focus-ring (inferred) (#005EB8): Blue focus ring for accessibility and keyboard navigation.

## Typography

The typography uses a clean, sans-serif family to maintain a modern, authoritative, and highly readable interface across all digital touchpoints.

*   Display-lg (inferred): Used for hero headlines to establish authority.
*   Headline-md (inferred): Used for card titles.
*   Body-md (inferred): Primary body text for readability.
*   Label-md (inferred): Used for navigation items and button labels.

## Layout

The site utilizes a responsive grid system with a max-width container to maintain readability, following an 8px base unit for consistent margins and padding. The page structure follows a logical flow: nav, hero, features, news, and footer. The hero pattern features a centered headline with a clear primary CTA and supporting imagery. The design is mobile-first, utilizing a hamburger menu for navigation on smaller viewports.

## Elevation & Depth

Elevation is used sparingly to differentiate interactive elements from the background, employing subtle single-layer shadows. The values are inferred based on the brand's clean, flat design language: `elevation.sm` for subtle card lift; `elevation.md` for standard component separation; and `elevation.lg` for modal or drawer overlays.

## Shapes

The brand uses a system of subtle rounding to maintain a modern, approachable feel while retaining professional sharpness. Radius values range from `rounded.sm` (2px) for small inputs and dividers, up to `rounded.xl` (16px) for larger containers, ensuring a consistent geometric language across the UI.

## Components

> **Note:** This spec was generated from a website scrape and contains visual approximations.
> For production use, add a deep reference to each component pointing to its authoritative
> source (Storybook story, metadata file, or component spec):
> `→ Deep reference: src/components/Button/metadata.ts`


### Buttons
Primary buttons use `{colors.primary}` with `{typography.label-md}` to drive clear, imperative actions. Secondary buttons use a transparent background with a `{colors.primary}` border to maintain hierarchy.

### Cards
Cards utilize `{colors.surface}` with `{rounded.md}` and an `{colors.outline}` border to group related information. Elevated cards use `elevation.md` to distinguish interactive content from the page background.

### Badges
Badges provide contextual status using `{colors.surface-dim}` for background and `{typography.label-md}`. Error and success variants use `{colors.error}` and `{colors.success}` respectively to provide immediate visual feedback.

## Do's and Don'ts

| Do | Don't |
| --- | --- |
| Use `{colors.primary}` for primary call-to-action buttons. | Do not use `{colors.secondary}` for primary buttons. |
| Apply `{typography.body-md}` for all standard paragraph content. | Avoid using `{typography.display-lg}` for body text. |
| Use `{rounded.md}` for card components to maintain consistency. | Do not mix sharp corners with `{rounded.full}` on the same component. |
| Ensure all interactive elements have a `{colors.focus-ring}` state. | Never use `{colors.error}` for non-destructive actions. |
| Use `{colors.surface-dim}` for secondary background sections. | Do not use low-contrast text on `{colors.surface-dim}` backgrounds. |
| Maintain `{spacing.md}` between grid items for breathing room. | Avoid excessive use of shadows; keep `{elevation.lg}` for modals only. |
| Use `{typography.label-md}` for button labels. | Do not use decorative fonts for UI labels. |
| Apply `{rounded.sm}` to `input-field` components. | Do not use large radii on dense form fields. |

## Content Style

CTA labels are written as imperative verbs, remaining concise and action-oriented to guide the user through the payment or information journey.

Headings are benefit-driven and professional, designed to establish authority while remaining human-centric and accessible.

Copy density is kept low, utilizing scannable, short paragraphs and bulleted lists to ensure the content rhythm remains fast and easy to digest.

## Imagery & Icons

The imagery style is mixed, combining high-quality lifestyle photography with clean, flat vector iconography. Photography should feel authentic and global, while icons must adhere to the brand's minimal and accessible design language, ensuring they remain legible at small sizes.

---

## Companion prompt

## Role
You are an AI assistant generating UI components and layouts for Mastercard, a minimal, accessible global payments brand with a professional and human-centric tone. Content, copy, and information architecture remain owned by the product team.

## How to use design.md
1. Reference every value by its YAML token name — `{colors.primary}`, `{typography.body-md}`, `{spacing.md}` — never hardcode hex values, sizes, or font stacks.
2. Use only the component variants defined under `components:`. Do not invent new button styles, card types, or badge variants beyond those specified.
3. Follow the Layout section for page structure (nav → hero → features → news → footer), mobile-first with a single breakpoint at 768px.
4. Apply elevation sparingly per the Elevation & Depth narrative: `elevation.sm` for cards, `elevation.md` for interactive separation, `elevation.lg` for modals only.
5. Treat the Do's and Don'ts table as authoritative. Surface any conflict with a user request before applying a change.

## Output contract

**Must:**
- Use all tokens by name on every generated component.
- Include hover, focus, and disabled states for interactive elements where the spec defines them (`button-primary-hover`, `input-field-focus`, `link-hover`, `{colors.focus-ring}` on all focusable elements).
- Use `{spacing.xs}` through `{spacing.2xl}` for all padding, margin, and gap values.
- Apply `{rounded.sm}` to inputs, `{rounded.md}` to cards, and follow the components block for all other radius assignments.
- Write CTA labels as imperative verbs per the Content Style section.

**Must NOT:**
- Invent colors, radii, or type scales not present in the spec.
- Use generic system defaults when a brand token exists.
- Add emoji, filler text, or marketing copy.
- Reference any specific framework or toolchain.
- Rewrite, replace, or restructure existing page copy, headings, or navigation items.
- Use `{colors.secondary}` for primary CTAs or `{colors.error}` for non-destructive actions.

## When in doubt
- If a value isn't in the spec, ask the product team before inventing one.
- Compose existing tokens and components before introducing anything new.
- For background roles, default to `{colors.surface}`; use `{colors.surface-dim}` for section separation.
- Tokens marked "(inferred)" are visual approximations. If an authoritative theme file or Storybook exists, those values override the spec.
- For text on `{colors.surface-dim}`, always verify contrast meets 4.5:1 using `{colors.on-surface}`.