---
version: alpha
name: Hugging Face
description: A bright, utilitarian white community canvas where a single dark-navy hero card carries the manifesto, Source Sans Pro keeps everything friendly and readable, the yellow mascot is the only logo color, and a full rainbow of category accents tags the models, datasets, and spaces below.

colors:
  # Surface / canvas
  background: "#ffffff"          # the page — bright white
  surface: "#f9fafb"             # gray section bands, trending strips
  surface-sunken: "#f3f4f6"      # input fills, muted chips
  hero: "#0b0f19"                # the one dark-navy hero card

  # Ink / text
  ink: "#111827"                 # primary headings, body on light
  ink-secondary: "#374151"       # supporting copy
  ink-muted: "#6b7280"           # captions, metadata, inactive
  on-hero: "#ffffff"             # text on the dark hero card
  on-hero-muted: "#cbd5e1"       # secondary text on the hero — was oklab .87 a/.8

  # Brand — the Hugging Face yellow mascot
  primary: "#ffd702"             # the logo / mascot yellow — the brand stamp
  primary-warm: "#ffa600"        # warmer yellow-orange companion
  on-primary: "#111827"          # near-black text on yellow

  # Link / interactive
  link: "#2563eb"                # standard link blue
  accent-blue: "#097eff"         # task-tag blue, focus

  # Category spectrum — the model/dataset/space tag palette
  accent-purple: "#861fff"       # transformers / NLP tags
  accent-pink: "#ff3270"         # diffusers / image tags
  accent-red: "#ff3939"          # hot / trending tags
  accent-green: "#16a34a"        # datasets / success
  accent-orange: "#ff9448"       # spaces / running

  # Borders
  border: "#e5e7eb"              # hairline card edges, dividers
  border-strong: "#d1d5db"       # input outlines

  # Shadow tints (opaque approximations for the elevation table)
  shadow-soft: "#000000"         # was rgba(0,0,0,0.05) — Google format requires hex
  shadow-card: "#0b0f19"         # was rgba(11,15,25,0.1) — Google format requires hex

typography:
  display-hero:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 48px
    fontWeight: 700
    lineHeight: 1.0
    letterSpacing: 0px
  display:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 36px
    fontWeight: 700
    lineHeight: 1.11
    letterSpacing: 0px
  heading:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 24px
    fontWeight: 700
    lineHeight: 1.25
    letterSpacing: 0px
  heading-sub:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 20px
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0px
  body-large:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 18px
    fontWeight: 400
    lineHeight: 1.56
    letterSpacing: 0px
  body:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0px
  body-strong:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 16px
    fontWeight: 600
    lineHeight: 1.5
    letterSpacing: 0px
  button:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 15px
    fontWeight: 600
    lineHeight: 1.2
    letterSpacing: 0px
  label:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 13px
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0px
  mono:
    fontFamily: "IBM Plex Mono, ui-monospace, SFMono-Regular, Menlo, monospace"
    fontSize: 13px
    fontWeight: 400
    lineHeight: 1.5
    letterSpacing: 0px
  caption:
    fontFamily: "Source Sans Pro, ui-sans-serif, system-ui, -apple-system, sans-serif"
    fontSize: 12px
    fontWeight: 400
    lineHeight: 1.4
    letterSpacing: 0px

spacing:
  xs: 4px
  sm: 8px
  md: 12px
  lg: 16px
  xl: 24px
  2xl: 32px
  3xl: 48px
  4xl: 64px
  5xl: 96px

rounded:
  sm: 4px
  md: 6px
  lg: 8px
  xl: 12px
  pill: 9999px

components:
  button-primary:
    backgroundColor: "{colors.hero}"
    textColor: "{colors.on-hero}"
    typography: "{typography.button}"
    rounded: "{rounded.pill}"
    padding: 10px 18px
  button-primary-hover:
    backgroundColor: "{colors.ink-secondary}"
    textColor: "{colors.on-hero}"

  button-ghost:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.button}"
    rounded: "{rounded.pill}"
    padding: 10px 18px
  button-ghost-hover:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"

  button-accent:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button}"
    rounded: "{rounded.lg}"
    padding: 10px 18px
  button-accent-hover:
    backgroundColor: "{colors.primary-warm}"
    textColor: "{colors.on-primary}"

  card:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    rounded: "{rounded.lg}"
    padding: 16px
  card-sunken:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"
    rounded: "{rounded.lg}"
    padding: 16px

  hero-card:
    backgroundColor: "{colors.hero}"
    textColor: "{colors.on-hero}"
    rounded: "{rounded.xl}"
    padding: 48px

  input:
    backgroundColor: "{colors.surface-sunken}"
    textColor: "{colors.ink}"
    typography: "{typography.body}"
    rounded: "{rounded.lg}"
    padding: 10px 14px
  input-focus:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"

  nav-bar:
    backgroundColor: "{colors.background}"
    textColor: "{colors.ink}"
    typography: "{typography.label}"
    padding: 12px 24px

  link:
    textColor: "{colors.link}"
    typography: "{typography.body}"
    padding: 0px

  tag:
    backgroundColor: "{colors.surface-sunken}"
    textColor: "{colors.ink-secondary}"
    typography: "{typography.label}"
    rounded: "{rounded.pill}"
    padding: 4px 10px

  tag-purple:
    backgroundColor: "{colors.surface-sunken}"
    textColor: "{colors.accent-purple}"
    typography: "{typography.label}"
    rounded: "{rounded.pill}"
    padding: 4px 10px

  badge:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.caption}"
    rounded: "{rounded.sm}"
    padding: 2px 8px

  code-block:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.ink}"
    typography: "{typography.mono}"
    rounded: "{rounded.lg}"
    padding: 16px
---

# Hugging Face Design System

## Overview

Hugging Face's site is built like the homepage of an open-source community, and it reads that way on purpose. The canvas is bright white (`{colors.background}`) with light gray section bands (`{colors.surface}`), set in Source Sans Pro — a friendly, highly-readable humanist sans that signals "approachable and technical" rather than "luxury product." Nothing is precious. The layout is dense and utilitarian: rows of models, datasets, and Spaces, each a small card with a name, a count, and a colored category tag. This is a library catalog for machine learning, and the design gets out of the content's way.

The signature move is the single dark hero card. On an otherwise white page, the top of the homepage is one big near-black navy panel (`{colors.hero}`) carrying the manifesto — "The AI community building the future." — in bold white Source Sans Pro, with the yellow Hugging Face mascot peeking in. That one dark block is the entire brand statement; everything below returns to light. The two hero CTAs are a white outlined pill ("Explore AI Apps") and a quieter ghost link ("Browse models") — restrained, because the dark card is already doing the shouting.

Then there's the color. The brand's only true brand color is the mascot **yellow** (`{colors.primary}`) — it lives in the logo and a few highlight moments, never as a button fill across the chrome. The real chromatic energy comes from the category-tag spectrum: purple for transformers, pink for diffusers, blue for inference, green for datasets, orange for Spaces (`{colors.accent-purple}`, `{colors.accent-pink}`, `{colors.accent-blue}`, `{colors.accent-green}`, `{colors.accent-orange}`). Those colored tags turn a wall of grayscale cards into something legible and a little joyful — a rainbow index over a neutral catalog. The result feels open, technical, and welcoming, the visual equivalent of a well-organized public repo.

**Key Characteristics:**
- Bright white canvas (`{colors.background}`) with light gray bands (`{colors.surface}`) — a light, community-first theme
- Source Sans Pro everywhere — friendly humanist sans, bold (700) for headings, neutral tracking
- A single dark-navy hero card (`{colors.hero}`) carries the manifesto; the rest of the page is light
- The mascot **yellow** (`{colors.primary}`) is the only brand color — a stamp, not a workhorse fill
- A category-tag spectrum (`{colors.accent-purple}`, `{colors.accent-pink}`, `{colors.accent-blue}`, `{colors.accent-green}`, `{colors.accent-orange}`) colors the catalog
- Hero CTAs are restrained: a white outlined pill plus a ghost link — the dark card does the shouting
- Dense, utilitarian layout — rows of model / dataset / Space cards, each with a name, count, and tag
- Pill buttons (`{rounded.pill}`) for primary actions; small `{rounded.sm}`–`{rounded.lg}` radii on cards and tags
- Soft, barely-there shadows (`{colors.shadow-soft}`) — separation is mostly hairline borders (`{colors.border}`)
- A monospace voice (`{typography.mono}`) appears in code blocks and model IDs — the site is built for developers

## Colors

### Surface & Canvas
- **White** (`{colors.background}`): The dominant canvas — the whole page outside the hero.
- **Gray Band** (`{colors.surface}`): Section bands, trending strips, and code-block fills.
- **Sunken Gray** (`{colors.surface-sunken}`): Input fills and muted chip backgrounds.
- **Hero Navy** (`{colors.hero}`): The one dark panel — the homepage manifesto card. Also the primary-button fill.

### Ink / Text
- **Ink** (`{colors.ink}`): Headings and body on light.
- **Secondary / Muted** (`{colors.ink-secondary}`, `{colors.ink-muted}`): Supporting copy, captions, metadata.
- **On-Hero** (`{colors.on-hero}`, `{colors.on-hero-muted}`): White and muted-slate text on the dark hero card (the muted variant was flattened from an rgba).

### Brand
- **HF Yellow** (`{colors.primary}`): The mascot color — the logo and a few highlight moments. A stamp, used sparingly. **Warm Yellow** (`{colors.primary-warm}`) is its warmer companion.

### Links & Category Spectrum
- **Link Blue / Accent Blue** (`{colors.link}`, `{colors.accent-blue}`): Standard links and focus.
- **Spectrum** (`{colors.accent-purple}`, `{colors.accent-pink}`, `{colors.accent-red}`, `{colors.accent-green}`, `{colors.accent-orange}`): The category-tag palette that colors models, datasets, and Spaces.

### Borders & Shadow Tints
- **Border / Strong** (`{colors.border}`, `{colors.border-strong}`): Hairline card edges and stronger input outlines — the primary structural device.
- **Soft / Card** (`{colors.shadow-soft}`, `{colors.shadow-card}`): Opaque stand-ins for the very soft card shadows (originals were rgba — flattened for the Google spec).

## Typography

### Font Family
- **Primary**: `Source Sans Pro` — a friendly, open humanist sans, with fallbacks `ui-sans-serif, system-ui, -apple-system, sans-serif`. Carries all display and body text.
- **Monospace**: `IBM Plex Mono`, with fallbacks `ui-monospace, SFMono-Regular, Menlo, monospace`. Used for code blocks, model IDs, and CLI snippets.
- **Tracking**: neutral throughout — Source Sans Pro is left at its natural spacing; hierarchy comes from weight and size.

### Hierarchy

The full type scale lives in the `typography:` token block. Reference tokens directly.

| Token | Use |
|---|---|
| `display-hero` | 48px / 700 — the dark-card manifesto headline |
| `display` | 36px / 700 — large section titles |
| `heading` | 24px / 700 — feature headings |
| `heading-sub` | 20px / 600 — sub-section headings, card titles |
| `body-large` | 18px / 400 — lead paragraphs |
| `body` | 16px / 400 — standard body |
| `body-strong` | 16px / 600 — emphasized body, card names |
| `button` | 15px / 600 — button text |
| `label` | 13px / 600 — tags, UI labels |
| `mono` | 13px / 400 — code, model IDs |
| `caption` | 12px / 400 — counts, metadata |

### Principles
- **Readable over refined**: Source Sans Pro is chosen for legibility and friendliness, not luxury — it suits a community of developers.
- **Weight does hierarchy**: bold 700 for headings, 600 for sub-heads and labels, 400 for body. Tracking stays neutral.
- **Mono for the machine**: code blocks and model IDs switch to IBM Plex Mono — the site never hides that it's a developer tool.

## Layout

### Spacing System
The full scale is in the `spacing:` token block. Base unit: 8px, with a 4px sub-step. Cards and rows pack tightly (`{spacing.md}`–`{spacing.lg}`); the hero and major sections get generous padding (`{spacing.3xl}`–`{spacing.5xl}`).

### Grid & Container
- Max content width: ~1280px, centered
- Hero is a single dark card spanning the content width, with the catalog grids below
- Catalog uses dense multi-column grids of model / dataset / Space cards, plus three "Trending" columns

### Whitespace Philosophy
- **Dense and useful**: the catalog is meant to show a lot at once — tight rows, compact cards, scannable
- **One big breath at the top**: the dark hero card gets generous internal padding; below, density returns
- **Borders over air**: hairline borders (`{colors.border}`) separate cards more than whitespace does

## Elevation & Depth

| Level | Treatment | Use |
|---|---|---|
| Flat (Level 0) | No shadow; `{colors.border}` hairline | Most cards, catalog rows |
| Subtle (Level 1) | `0 1px 2px` at ~5% (`{colors.shadow-soft}`) | Resting cards, inputs |
| Card (Level 2) | `0 1px 3px` + `0 1px 2px -1px` at ~10% (`{colors.shadow-card}`) | Hover cards, dropdowns |
| Hero (Block) | No shadow — separation by the dark `{colors.hero}` fill | The manifesto card |
| Focus Ring | 2–3px `{colors.accent-blue}` ring | Inputs and interactive focus |

**Shadow Philosophy**: Hugging Face is almost flat. Cards sit on the white canvas separated by hairline borders, with only the faintest soft shadow on resting and hover states. The biggest "elevation" is conceptual, not physical — the dark hero card reads as a distinct layer because of its near-black fill, not a drop shadow. The system trusts borders and color blocks to do the structural work.

## Shapes

The full radius scale is in the `rounded:` token block.

| Token | Value | Use |
|---|---|---|
| `sm` | 4px | Small badges, inline tags |
| `md` | 6px | Compact chips, small buttons |
| `lg` | 8px | Cards, inputs, yellow accent buttons |
| `xl` | 12px | The hero card, large panels |
| `pill` | 9999px | Category tags, primary pill buttons, avatars |

The system mixes tidy small radii on the catalog (4–8px) with full pills on tags and primary buttons. The contrast keeps the dense card grids crisp while the round tags add the playful, indexed feel.

## Components

The complete component spec lives in the `components:` token block.

### Buttons
- **`button-primary`** — Dark navy (`{colors.hero}`) pill, white text. The main filled CTA. Hover lifts toward `{colors.ink-secondary}`.
- **`button-ghost`** — White / outlined pill, ink text. The "Browse models" secondary pattern. Hover fills `{colors.surface}`.
- **`button-accent`** — Yellow (`{colors.primary}`) fill, near-black text, `{rounded.lg}`. Reserved for highlight moments where the brand color carries an action.

### Cards
- **`card`** / **`card-sunken`** — White or gray-band surfaces, 8px radius, hairline border. The catalog unit: name, count, and a category tag. **`hero-card`** is the one dark manifesto panel.

### Inputs
- **`input`** — Sunken gray fill, 8px radius. **`input-focus`** brightens to white with a blue (`{colors.accent-blue}`) ring.

### Tags & Badges
- **`tag`** / **`tag-purple`** — Pill tags on a sunken fill; the text color carries the category (`{colors.accent-purple}` for transformers, etc.). **`badge`** is the yellow stamp for highlight labels.

### Code
- **`code-block`** — Gray-band fill, IBM Plex Mono, 8px radius — model snippets and CLI commands.

### Navigation
- **`nav-bar`** — White, hairline bottom border, ink labels, a search field, sits flush at the top.

## Do's and Don'ts

### Do
- Keep the canvas bright white (`{colors.background}`) with light gray bands (`{colors.surface}`) — a community-first light theme
- Use the one dark-navy hero card (`{colors.hero}`) for the manifesto, then return to light below
- Treat yellow (`{colors.primary}`) as a stamp — the logo and rare highlight moments, not a chrome-wide fill
- Color the catalog with the category-tag spectrum (`{colors.accent-purple}`, `{colors.accent-pink}`, etc.)
- Set everything in Source Sans Pro; lean on weight (700 / 600 / 400) for hierarchy, not tracking
- Keep the layout dense and scannable — tight rows of name + count + tag cards
- Use pill buttons (`{rounded.pill}`) for primary and secondary CTAs; small radii on cards and tags
- Switch to IBM Plex Mono (`{typography.mono}`) for code blocks and model IDs

### Don't
- Don't fill buttons with yellow across the chrome — yellow is the mascot stamp, the primary CTA is dark navy
- Don't add a second dark section — the design is light, with exactly one dark hero card
- Don't cast heavy shadows — separation is hairline borders (`{colors.border}`) and the dark fill, not elevation
- Don't tighten Source Sans Pro tracking — it's left at natural spacing
- Don't swap the friendly humanist sans for a luxury serif or a clinical grotesque — readability is the point
- Don't make the layout sparse and airy — the catalog wants density
- Don't drop the colored category tags — they're what turns a grayscale catalog into a legible index

---

## Responsive Behavior

### Breakpoints
*(No explicit breakpoints surfaced in extraction; the values below are the standard Tailwind-style stops the site behaves to.)*

| Name | Width | Key Changes |
|---|---|---|
| Mobile | <640px | Single column; hero card stacks copy above the mascot art; catalog grids collapse to one column |
| Tablet | 640–1023px | Hero copy / art side-by-side; catalog at 2 columns; nav condenses to a menu |
| Desktop | 1024–1279px | Full layout; dark hero card spans the width; catalog at 3 columns |
| Large | ≥1280px | Max ~1280px container; trending shown as three parallel columns |

### Touch Targets
- Pill buttons run ~40px tall with `10px 18px` padding — comfortable for thumbs
- Category tags and counts stay legible at 12–13px; card rows carry generous vertical padding

### Collapsing Strategy
- **Navigation**: full horizontal nav + search → menu toggle on mobile
- **Hero**: the dark card's copy and mascot art go from side-by-side to stacked
- **Catalog**: multi-column model / dataset / Space grids collapse toward a single column
- **Spacing**: section padding compresses from `{spacing.5xl}` toward `{spacing.2xl}`

### Image Behavior
- Model / dataset thumbnails and the mascot art scale as responsive grid children; avatars stay circular (`{rounded.pill}`)

---

## Agent Prompt Guide

### Quick Color Reference
- Background: White (`{colors.background}`)
- Text: Ink (`{colors.ink}`)
- Brand stamp: HF Yellow (`{colors.primary}`)
- Hero / primary CTA fill: Navy (`{colors.hero}`)
- Secondary text: `{colors.ink-muted}`
- Border: `{colors.border}`
- Link: Blue (`{colors.link}`)

### Example Component Prompts

- "Create the hero card: a dark-navy (`{colors.hero}`) `{rounded.xl}` panel on a white page, with a 48px bold white (`{colors.on-hero}`) Source Sans Pro headline 'The AI community building the future.', the yellow (`{colors.primary}`) mascot in the corner, a white outlined pill CTA and a ghost link below"
- "Build the primary button: dark navy (`{colors.hero}`) fill, white (`{colors.on-hero}`) text, `{rounded.pill}` radius, `10px 18px` padding, `{typography.button}`; hover lifts toward `{colors.ink-secondary}`"
- "Render a model card: white (`{colors.background}`) surface, hairline (`{colors.border}`) edge, `{rounded.lg}` radius, a bold name (`{typography.body-strong}`), a muted download count (`{colors.ink-muted}`), and a purple category tag (`{components.tag-purple}`)"
- "Design an input: sunken gray (`{colors.surface-sunken}`) fill, ink text, `{rounded.lg}` radius, `10px 14px` padding; on focus brighten to white (`{colors.background}`) and add a blue (`{colors.accent-blue}`) ring"
- "Create a category tag: pill (`{rounded.pill}`) on a sunken fill (`{colors.surface-sunken}`) with the text colored by category — `{colors.accent-purple}`, `{colors.accent-pink}`, `{colors.accent-blue}`, `{colors.accent-green}`, or `{colors.accent-orange}`"

### Iteration Guide

1. Start on bright white (`{colors.background}`). The page is light; only the hero card is dark.
2. Build exactly one dark hero card (`{colors.hero}`) for the manifesto, then return everything else to white / gray bands.
3. Yellow (`{colors.primary}`) is a stamp — logo and rare highlights. The primary CTA is dark navy, not yellow.
4. Set everything in Source Sans Pro; hierarchy is weight (700 / 600 / 400), tracking stays neutral.
5. Separate cards with hairline borders (`{colors.border}`) and only the faintest shadow — the system is nearly flat.
6. Color the catalog with the tag spectrum; keep card radii small (`{rounded.lg}`) and tags / primary buttons pill.
7. Switch to IBM Plex Mono (`{typography.mono}`) for any code, model ID, or CLI snippet.

---

## Attribution

Independent design analysis from [Design Swatches](https://designmd.santiagoalonso.com) by [Santiago Alonso](https://santiagoalonso.com). Based on publicly observable interface patterns. Not affiliated with or endorsed by Hugging Face. Brand names and trademarks belong to their respective owners.