Hugging Face Design System

Overview

Hugging Face's homepage is two-surface architecture: a near-black hero band ({colors.hero-canvas} — #0b0f19) running exactly one viewport tall, then a hard flip to pure white ({colors.workspace-canvas} — #ffffff) for the remaining ~3500px of scroll. There is no transitional gray, no shadow seam, no gradient mesh between them. The dark band carries the 48px Source Sans Pro wordmark headline and a wall of IBM Plex Mono code samples showing actual transformers and datasets API calls. The white band carries every interactive surface — model cards, dataset rows, Spaces tiles, the enterprise CTA.

Where most AI marketing pages anchor on a single saturated brand voltage and decorate the rest with neutrals, Hugging Face inverts the convention: the brand voltage IS the dark-to-white surface flip, and saturation is reserved for four signal-only repo category pills — blue #388bfd for Models, green #3fb950 for Datasets, amber #d29922 for changed-file labels, red #f85149 for warnings. The signature yellow emoji-face logo sits only at the top-left wordmark; it never colors a button or a band.

Signal-only saturation: the four pill hues are lifted straight from the GitHub Primer diff palette (the extracted CSS variables include --d2h-dark-ins-label-color: #3fb950, --d2h-dark-del-label-color: #f85149, --d2h-dark-change-label-color: #d29922). The system reads this way to every developer who has seen a unified-diff before — color carries semantic meaning about content type, not visual emphasis.

Key Characteristics:

• Two-surface architecture: hero-dark {colors.hero-canvas} (#0b0f19) flipping to workspace-white {colors.workspace-canvas} (#ffffff) with no transitional gray.
• Source Sans Pro carries the entire chrome — every heading, body, label, and button across the marketing surface uses the same family.
• IBM Plex Mono at 15.04px weight 400 with a 24px line-height handles inline repo IDs and code samples in the hero band.
• Four-hue repo category pill system: blue #388bfd, green #3fb950, amber #d29922, red #f85149 — signal-only, never decorative.
• 8px is the dominant card radius (41 hits in extraction) AND the dominant spacing increment (59 hits) — one number drives both rhythms.
• 48px Source Sans Pro weight-700 hero wordmark — the page's only display-tier headline, never repeated below the fold.

Colors

Surface

• Hero Canvas ({colors.hero-canvas} — #0b0f19) — frequency 2. Used as bg (1), gradient (1). The dark hero band that runs from the top of the page through the first content row. Carries the wordmark headline and code samples. Single-CSS-variable provenance (--d2h-dark-bg-color).
• Workspace Canvas ({colors.workspace-canvas} — #ffffff) — frequency 133. Used as text (71), bg (10), gradient (52). The white surface that carries every interactive element below the hero. Wired through 13 CSS variables including --color-white, --color-gray-50, --color-sky-50, --color-emerald-50 — every "50" Tailwind scale collapses to pure white.

Text

• Ink ({colors.ink} — #000000) — frequency 364. Used as text (300), bg (2), shadow (62). The dominant text color across the workspace tier. Headings, body paragraphs, and nav labels on white all sit at pure black.
• Ink Soft ({colors.ink-soft} — #161b22) — borderline-black tone wired through --color-slate-900 and --color-gray-900. Reserved for very dark surfaces and elevated dark cards.
• Ink Elevated ({colors.ink-elevated} — #21262d) — slightly lighter than ink-soft, wired through --color-gray-800. Used for dark-mode line borders and elevated dark surfaces in the diff renderer.
• Ink Border ({colors.ink-border} — #30363d) — the dark-tier border tone (--d2h-dark-border-color, --d2h-dark-empty-placeholder-border-color).
• Muted ({colors.muted} — #6e7681) — wired through --color-gray-500 and --color-neutral-500. The mid-gray for captions, secondary labels, code-sample comment text in the hero.

Hairlines

• Surface Light ({colors.surface-light} — #e6edf3) — wired through 13 CSS variables including --color-gray-100, --color-blue-100, --color-sky-100. The lightest cool-gray, used for surface-elevated badges on the white tier.
• Hairline Light ({colors.hairline-light} — #e1e1e1) — the 1px border tone used in card rows and table dividers (--d2h-empty-placeholder-border-color, --d2h-file-header-border-color).

Category signal

• Category Blue ({colors.category-blue} — #388bfd) — frequency 0 raw, but anchored through --d2h-dark-selected-color, --d2h-dark-info-border-color, --d2h-dark-info-bg-color. Reserved for Model repo pills and informational labels.
• Category Green ({colors.category-green} — #3fb950) — Datasets repo pill, "Insertion" label in the diff renderer (--d2h-dark-ins-label-color).
• Category Amber ({colors.category-amber} — #d29922) — Changed-file label in diffs, used for Spaces-tier badges (--d2h-dark-change-del-color, --d2h-dark-change-label-color).
• Category Red ({colors.category-red} — #f85149) — Deletion label and warning badges (--d2h-dark-del-border-color, --d2h-dark-del-label-color).

Diff palette (legacy GitHub Primer)

• Ins Label ({colors.ins-label} — #399839) — light-mode insertion label.
• Ins Soft ({colors.ins-soft} — #b4e2b4) — insertion border tone.
• Ins Highlight ({colors.ins-highlight} — #97f295) — insertion highlight background.
• Del Soft ({colors.del-soft} — #e9aeae) — deletion border tone.
• Del Highlight ({colors.del-highlight} — #ffb6ba) — deletion highlight background.
• Del Bg ({colors.del-bg} — #fee8e9) — wired through --color-red-50, --color-red-100. The error-tier surface fill.
• Change Soft ({colors.change-soft} — #d0b44c) — change-marker label.
• Change Bg ({colors.change-bg} — #fdf2d0) — change-marker surface fill.
• Selected Bg ({colors.selected-bg} — #c8e1ff) — wired through --color-blue-200. Light-mode selected-line background.
• Moved Label ({colors.moved-label} — #3572b0) — moved-file marker.

Typography

The system runs Source Sans Pro across every text role — display, headings, body, labels, captions, buttons, navigation. There is no display-family / body-family split. The variation comes from weight (400 / 600 / 700) and size (12px → 48px) rather than from a second typeface. Code switches to IBM Plex Mono at 15.04px with a 24px line-height for repo IDs and inline command samples. Both faces appear with letterSpacing: normal — no negative tracking on display, no widened tracking on uppercase caption.

The hero h1 is {typography.display-xl} (48px / 700 / line-height 1) — the only display-tier headline on the page. Below the fold, headings ladder from {typography.heading-lg} (30px / 700) for section heads down to {typography.heading-xs} (18px / 600) for card titles. Body paragraphs sit at {typography.body-md} (16px / 400) with a 24px line-height, and labels drop to {typography.label-md} (14px / 600). The 12px caption ({typography.caption}) is used for repo metadata — star counts, model size, last-modified timestamps.

Where most AI brands run a weight-300 display headline for restraint (Stripe, Mistral), Hugging Face runs weight 700 — the hero wordmark carries actual visual weight, no soft elegance.

Hierarchy

Layout

Spacing System

The system has an 8px base. {spacing.sm} (8px) is the dominant increment — 59 occurrences in the extraction, more than every other value combined. {spacing.base} (16px) and {spacing.md} (12px) follow at 17 hits each. The unusual {spacing.xs} (6px) appears in 2px 6px and 0px 6px pill padding pairs — small horizontal offset for inline badges.

{spacing.xxs} (2px) is the vertical padding inside category pills (padding: 2px 8px — 2px 6px — 2px 12px 0px). {spacing.lg} (24px) and {spacing.2xl} (32px) drive section padding and card internal padding respectively.

Grid & Container

The hero band is centered and bounded by Tailwind's standard container scale (--container-7xl: 80rem is wired in :root). The workspace tier uses an asymmetric 3-up grid for trending repos: Models column / Datasets column / Spaces column, each carrying ~5 repo rows. Below that, a 2-up grid pairs the "Open Source community" pitch with code samples, and a logo carousel at the footer runs at 6-up.

Whitespace

8px is both the radius and the spacing increment, so cards, gaps, and corners all snap to the same 8px lattice. Cards sit on the white tier with 8px rounded corners, separated by 8px and 16px gutters. Section padding is 32px.

Elevation & Depth

The system uses flat-on-flat elevation. Cards on the white workspace tier have no shadow; depth comes from the 1px {colors.hairline-light} border (#e1e1e1) and from contrast against the white canvas itself. The extracted shadow hits at the #000000 token (62 shadow occurrences) are mostly inline-shadow Tailwind defaults rather than authored card shadows.

The dominant depth move on the page is dark-card-on-white-tier: the enterprise CTA band in the lower third of the page inverts to {colors.hero-canvas} (#0b0f19) as a standalone rounded card inside the white workspace, which creates a much stronger elevation read than a shadow would.

Shapes

Border Radius Scale

The 25.6px pill radius is unusual — most systems use either 9999px or a small explicit value like 16px for pills. Hugging Face's 25.6px reads as a deliberate "fat pill" — large enough to wrap multi-word labels comfortably without going fully circular.

Components

top-nav

The pinned 56px nav bar sitting against the hero canvas {colors.hero-canvas}. Carries the yellow emoji-face mark + "Hugging Face" wordmark at left, then a horizontal menu (Models / Datasets / Spaces / Posts / Docs / Pricing) in {typography.nav-link} (16px / 400). Right cluster has a search input and the "Sign Up" {component.button-primary}.

hero-band

The dark hero band running one viewport tall. Background {colors.hero-canvas}, padding 32px, carrying the wordmark headline {component.hero-wordmark-heading} at left and a code-sample stack at right. No CTA inside — the hero relies on the wordmark headline alone.

hero-wordmark-heading

The 48px Source Sans Pro weight-700 headline on the dark canvas. {typography.display-xl} with letterSpacing: normal (no negative tracking). The page's only display-tier headline.

hero-code-sample

Inline IBM Plex Mono code window inside the hero band. Background {colors.hero-canvas} (same as the band — no contrasting fill), text {colors.muted} (#6e7681), padding 16px, rounded {rounded.md}. The code reads as part of the dark canvas, not as a separate card — pulled out only by its monospace face.

Buttons

button-primary — White button on the dark hero canvas. Background {colors.workspace-canvas} (#ffffff), text {colors.ink} (#000000), {typography.label-md} (14px / 600), padding 8px 16px, rounded {rounded.md} (8px), height 36px. The primary CTA inverts the page's surface contrast — white on dark.

button-secondary — Dark button used on the white workspace tier as the inverse. Background {colors.hero-canvas}, text {colors.on-hero} (#ffffff). Same dimensions and radius as primary.

Workspace cards

workspace-band — The white workspace tier itself. Background {colors.workspace-canvas}, padding 32px. Carries every interactive component below the hero.

repo-row — Single-line model/dataset/space row used in the trending grids. Background {colors.workspace-canvas}, hairline border, padding 12px, rounded {rounded.md}. Carries an avatar at left, repo name + author in {typography.body-md}, metadata in {typography.body-sm} (size, downloads, likes), and a {component.category-pill-models} indicating category.

Category pills

category-pill-models — Blue-text pill for Model repos. Background {colors.workspace-canvas}, text {colors.category-blue} (#388bfd), {typography.label-md}, padding 2px 8px, rounded {rounded.pill} (25.6px).

category-pill-datasets — Green-text pill for Dataset repos. Same geometry, text {colors.category-green} (#3fb950).

category-pill-spaces — Amber-text pill for Spaces. Same geometry, text {colors.category-amber} (#d29922).

category-pill-warning — Red-text pill for deprecated or warning labels. Background flips to {colors.del-bg} (#fee8e9), text {colors.category-red} (#f85149).

Badges

badge-uppercase — Small uppercase-tracked tag. Background {colors.surface-light}, text {colors.ink}, {typography.caption} (12px / 600), rounded {rounded.pill}, padding 2px 6px, letterSpacing 0.05em. Used for "NEW", "PRO", trending markers.

Enterprise CTA

enterprise-cta-band — Dark inverted card sitting inside the white workspace. Background {colors.hero-canvas}, text {colors.on-hero}, {typography.heading-md}, rounded {rounded.md}, padding 32px. The page's strongest visual elevation through surface inversion rather than shadow.

Inputs

text-input — Standard search/text input. Background {colors.workspace-canvas}, text {colors.ink}, {typography.body-md}, rounded {rounded.md}, padding 8px 12px 8px 32px (asymmetric left padding for the search icon), height 36px.

Footer

footer — Bottom footer on the white workspace tier. Background {colors.workspace-canvas}, text {colors.muted}, {typography.body-sm}, padding 32px. Carries a logo carousel at top and a multi-column link list below.

Do's and Don'ts

Do

• Anchor the hero on {colors.hero-canvas} (#0b0f19) for exactly one viewport, then flip to {colors.workspace-canvas} (#ffffff) for the rest of the page. The two-surface architecture is the brand.
• Run Source Sans Pro across every text role. Weight (400 / 600 / 700) and size carry the hierarchy — never reach for a second display family.
• Use IBM Plex Mono only for code, repo IDs, and command samples. Never use it for body or labels.
• Reserve the four category-pill hues for repo-type signal: blue Models, green Datasets, amber Spaces/changed, red warnings. Map them one-to-one to content category.
• Snap card radii to {rounded.md} (8px) and gutters to {spacing.sm} (8px) or {spacing.base} (16px) — the 8px lattice is the rhythm.
• Use surface inversion ({component.enterprise-cta-band}) rather than shadows for major card elevation on the white tier.

Don't

• Don't put a transitional gray band between the hero and the workspace. The flip from #0b0f19 to #ffffff is hard — adding a #161b22 or #21262d interstitial breaks the two-surface rule.
• Don't color CTA buttons with the category pill hues. #388bfd blue is a Models signal, not a primary-action color — using it on a button confuses the semantics.
• Don't add negative letter-spacing to display headlines. Source Sans Pro at 48px weight 700 is designed for letterSpacing: normal — the extracted value is exactly normal, and tracking it tighter reads as off-brand.
• Don't use the dark hero canvas as a card background on the white tier without a {rounded.md} corner — full-bleed dark on white reads as a layout error, not as the enterprise CTA.
• Don't reach for #000000 as a surface fill. The token has 364 occurrences but only 2 are bg uses — it's a text-and-shadow color, and filling a card with it breaks the workspace tier.
• Don't introduce a fifth category pill hue. The four-hue set (blue / green / amber / red) is closed — adding purple or teal pills dilutes the signal-only semantics.
• Don't use the 25.6px {rounded.pill} radius on rectangular buttons. It's reserved for pill-shaped category tags; on rectangular buttons it reads as bloated.

Known Gaps

• The actual product surface (model pages, the dataset viewer, Spaces, the Inference API console, discussion threads, Gradio embeds) adds many components beyond this marketing surface — repo file trees, commit graphs, model-card markdown renderers — that are out of scope here.
• The yellow emoji-face glyph at the top-left wordmark is treated as a logo asset rather than a system token. No yellow tone is surfaced as a color token because it never appears on a CTA or band.
• The GitHub Primer diff palette (--d2h-dark-* CSS variables) is fully present in the extracted CSS but only the category-signal subset is surfaced as a system token here. The full dark-mode workspace tier would need a second pass.
• Animation timings on the hero code-sample carousel and on the trending-repo refresh transitions are not extracted.
• Form validation states beyond the default text input are not extracted — error and success states would need a sign-up or feedback flow to confirm.
• The 3.35544e+07px radius value (17 hits in extraction) is the JavaScript-overflow representation of 9999px after a computed-style round-trip — it reduces to {rounded.full} at any rendered scale.