VTEX

---
name: "VTEX"
description: "Enterprise digital commerce platform design system — Shoreline for admin back-office experiences"
colors:
  primary: "#0366DD"
  secondary: "#F50963"
  accent: "#0366DD"
  surface: "#FFFFFF"
  surface-soft: "#F5F5F5"
  on-surface: "#1F1F1F"
  on-surface-soft: "#707070"
  success: "#019213"
  warning: "#9C7901"
  critical: "#D31A15"
  informational: "#157BF4"
typography:
  headline:
    fontFamily: "Inter"
    fontSize: "1.5rem"
    fontWeight: 600
    lineHeight: "2rem"
    letterSpacing: "-0.04rem"
  body:
    fontFamily: "Inter"
    fontSize: "0.875rem"
    fontWeight: 400
    lineHeight: "1.25rem"
    letterSpacing: "-0.00875rem"
  caption:
    fontFamily: "Inter"
    fontSize: "0.75rem"
    fontWeight: 500
    lineHeight: "1rem"
    letterSpacing: "0rem"
  action:
    fontFamily: "Inter"
    fontSize: "0.875rem"
    fontWeight: 600
    lineHeight: "1.25rem"
    letterSpacing: "-0.00875rem"
rounded:
  none: "0rem"
  sm: "0.25rem"
  md: "0.5rem"
  lg: "0.75rem"
  full: "9999rem"
spacing:
  "0": "0rem"
  "05": "0.125rem"
  "1": "0.25rem"
  "2": "0.5rem"
  "3": "0.75rem"
  "4": "1rem"
  "5": "1.25rem"
  "6": "1.5rem"
  "7": "1.75rem"
  "8": "2rem"
  "10": "2.5rem"
  "12": "3rem"
  "16": "4rem"
  "20": "5rem"
  "24": "6rem"
  "28": "7rem"
  "32": "8rem"
---

## Overview

VTEX is a Brazilian enterprise digital commerce platform powering over 3,400 online stores globally. Their design system, **Shoreline**, is tailored for back-office admin experiences, providing merchants and operators with clean, functional, and information-dense interfaces.

The design philosophy is rooted in:
- **Clarity** — Neutral gray palette with blue accent ensures content hierarchy without distraction
- **Density** — Compact spacing scale (starting at 0.125rem) supports data-heavy admin interfaces
- **Consistency** — Token-first approach with semantic naming (bg, fg, border prefixes) ensures predictable theming
- **Accessibility** — Focus rings, proper contrast ratios, and ARIA-first component architecture

The legacy Styleguide (`@vtex/styleguide`) served the VTEX IO platform with React components. Shoreline represents the modern evolution with CSS custom properties, semantic tokens, and a composition-based component architecture.

## Colors

VTEX uses a 14-step gray scale (0–13) as foundation, with semantic color scales for blue (accent), red (critical), green (success), yellow (warning), orange, teal, purple, pink, and cyan.

### Primitive Gray Scale
| Token | Hex | Role |
|---|---|---|
| gray-0 | `#FFFFFF` | Base background |
| gray-1 | `#F5F5F5` | Soft background |
| gray-3 | `#E0E0E0` | Strong background, borders |
| gray-5 | `#C2C2C2` | Focus ring outline |
| gray-7 | `#999999` | Disabled foreground |
| gray-9 | `#707070` | Soft foreground |
| gray-11 | `#3D3D3D` | Muted foreground |
| gray-12 | `#1F1F1F` | Base foreground (text) |
| gray-13 | `#000000` | Maximum contrast |

### Semantic Accent (Blue)
| Token | Hex | Role |
|---|---|---|
| blue-2 | `#E1F3FF` | Accent background |
| blue-6 | `#79BCFB` | Focus ring accent |
| blue-9 | `#157BF4` | Informational foreground |
| blue-10 | `#0366DD` | **Primary accent** — buttons, links, active states |
| blue-11 | `#0155B7` | Accent hover |
| blue-12 | `#014592` | Accent pressed |

### Semantic Critical (Red)
| Token | Hex | Role |
|---|---|---|
| red-1 | `#FDF6F5` | Critical background |
| red-8 | `#F95D47` | Critical border strong |
| red-10 | `#D31A15` | Critical foreground |
| red-11 | `#B40202` | Critical hover |
| red-12 | `#940303` | Critical pressed |

### Semantic Success (Green)
| Token | Hex | Role |
|---|---|---|
| green-1 | `#E9FCE3` | Success background |
| green-9 | `#019213` | Success foreground |
| green-10 | `#017D10` | Success strong |

### Semantic Warning (Yellow)
| Token | Hex | Role |
|---|---|---|
| yellow-1 | `#FBF7D4` | Warning background |
| yellow-9 | `#9C7901` | Warning foreground |

### Background Tokens (Semantic)
| Token | Value | Use Case |
|---|---|---|
| `--sl-bg-base` | white | Page background |
| `--sl-bg-base-soft` | gray-1 | Subtle sections |
| `--sl-bg-base-strong` | gray-3 | Elevated containers |
| `--sl-bg-inverted` | gray-12 | Dark surfaces |
| `--sl-bg-muted` | 5% gray-12 | Hover/pressed states |
| `--sl-bg-accent-strong` | blue-10 | Primary buttons |

### Foreground Tokens (Semantic)
| Token | Value | Use Case |
|---|---|---|
| `--sl-fg-base` | gray-12 | Primary text |
| `--sl-fg-base-soft` | gray-9 | Secondary text |
| `--sl-fg-base-disabled` | gray-7 | Disabled text |
| `--sl-fg-inverted` | white | Text on dark surfaces |
| `--sl-fg-accent` | blue-10 | Links, interactive elements |
| `--sl-fg-critical` | red-10 | Error messages |

## Typography

Shoreline uses **Inter** as its primary (and only) typeface, with a system font fallback stack. All typography is controlled through composite text tokens.

### Font Stack
```
"Inter", -apple-system, system-ui, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, sans-serif
```

### Weight Scale
| Token | Value | Usage |
|---|---|---|
| `--sl-font-weight-regular` | 400 | Body text, display-4 |
| `--sl-font-weight-medium` | 500 | Emphasis, captions |
| `--sl-font-weight-semibold` | 600 | Actions, headings (display 1–3) |

### Size Scale
| Token | Value | Pixel Equiv. |
|---|---|---|
| `--sl-font-size-1` | 0.75rem | 12px |
| `--sl-font-size-2` | 0.875rem | 14px |
| `--sl-font-size-3` | 1rem | 16px |
| `--sl-font-size-4` | 1.25rem | 20px |
| `--sl-font-size-5` | 1.5rem | 24px |

### Text Presets
| Preset | Weight | Size | Line Height | Use |
|---|---|---|---|---|
| `display-1` | 600 | 1.5rem | 2rem | Page titles |
| `display-2` | 600 | 1.25rem | 1.75rem | Section headings |
| `display-3` | 600 | 1rem | 1.5rem | Subsection headings |
| `display-4` | 400 | 1rem | 1.5rem | Large body text |
| `action` | 600 | 0.875rem | 1.25rem | Buttons, CTAs |
| `emphasis` | 500 | 0.875rem | 1.25rem | Bold labels |
| `body` | 400 | 0.875rem | 1.25rem | Default body copy |
| `caption-1` | 500 | 0.75rem | 1rem | Active captions |
| `caption-2` | 400 | 0.75rem | 1rem | Supporting captions |

### Letter Spacing
| Token | Value | Applied To |
|---|---|---|
| `--sl-letter-spacing-1` | 0rem | Body, captions, action |
| `--sl-letter-spacing-2` | -0.00875rem | Emphasis, body |
| `--sl-letter-spacing-3` | -0.02rem | Display 3–4 |
| `--sl-letter-spacing-4` | -0.04rem | Display 1–2 |

## Layout

### Spacing System

Shoreline uses a 4px base unit (0.25rem) with a comprehensive scale from 0 to 32 (128px). The default gap between elements (`--sl-space-gap`) is `1rem` (16px).

| Token | Value | Common Use |
|---|---|---|
| `--sl-space-05` | 2px | Micro gaps (icon-to-text) |
| `--sl-space-1` | 4px | Inline padding, tight groups |
| `--sl-space-2` | 8px | Element spacing within groups |
| `--sl-space-3` | 12px | Small component padding |
| `--sl-space-4` | 16px | Default gap, standard padding |
| `--sl-space-6` | 24px | Section internal padding |
| `--sl-space-8` | 32px | Card padding, group spacing |
| `--sl-space-12` | 48px | Section spacing |
| `--sl-space-16` | 64px | Page section gaps |
| `--sl-space-24` | 96px | Major layout spacing |
| `--sl-space-32` | 128px | Full page vertical rhythm |

### Layout Components
- **Page** — Full-page structure with PageHeader + PageContent
- **Content / Container** — Content width constraints
- **Flex** — Flexbox utility layout
- **Grid / GridCell** — CSS Grid layout
- **Stack** — Vertical stacking with consistent spacing
- **Bleed** — Allows content to escape container padding
- **Center** — Content centering utility

## Elevation & Depth

VTEX uses a minimal elevation system — only 2 shadow levels plus focus rings.

### Shadows
| Token | Value | Use |
|---|---|---|
| `--sl-shadow-1` | `0 0.25rem 1rem 0 rgba(0,0,0,0.16)` | Dropdowns, popovers, menus |
| `--sl-shadow-2` | `0 1.5rem 3rem 0 rgba(0,0,0,0.16)` | Modals, drawers |

### Focus Rings
| Token | Value | Use |
|---|---|---|
| `--sl-focus-ring-base` | Double-ring (white gap + gray-5 outline) | Default focus indicator |
| `--sl-focus-ring-accent` | Double-ring (white gap + blue-6 outline) | Accent-colored focus |
| `--sl-focus-ring-critical` | Double-ring (white gap + red-6 outline) | Error state focus |

### Z-Index Scale
| Token | Value | Layer |
|---|---|---|
| `--sl-z-1` | 0 | Base content |
| `--sl-z-2` | 100 | Sticky elements |
| `--sl-z-3` | 200 | Dropdowns |
| `--sl-z-4` | 300 | Overlays |
| `--sl-z-5` | 400 | Popovers |
| `--sl-z-6` | 500 | Modals |
| `--sl-z-7` | 600 | Toasts |
| `--sl-z-8` | 700 | Tooltips |
| `--sl-z-9` | 800 | Skip links |
| `--sl-z-10` | 900 | Maximum priority |

## Shapes

### Border Radius
| Token | Value | Use |
|---|---|---|
| `--sl-radius-0` | 0rem | Sharp edges (tables, dividers) |
| `--sl-radius-1` | 0.25rem (4px) | Default — buttons, inputs, cards |
| `--sl-radius-2` | 0.5rem (8px) | Modals, popovers, large containers |
| `--sl-radius-3` | 0.75rem (12px) | Large cards, drawers |
| `--sl-radius-full` | 9999rem | Pills, circular badges, avatars |

### Border Tokens
| Token | Value | Use |
|---|---|---|
| `--sl-border-base` | 1px solid gray-3 | Default container borders |
| `--sl-border-base-strong` | 1px solid gray-5 | Emphasized borders |
| `--sl-border-accent` | 1px solid blue-3 | Active/focus borders |
| `--sl-border-accent-strong` | 1px solid blue-10 | Active input borders |
| `--sl-border-critical` | 1px solid red-3 | Error container borders |
| `--sl-border-critical-strong` | 1px solid red-8 | Error input borders |
| `--sl-border-success` | 1px solid green-3 | Success container borders |
| `--sl-border-warning` | 1px solid yellow-3 | Warning container borders |
| `--sl-border-informational` | 1px solid blue-3 | Info container borders |

## Components

### Core Components (Shoreline)
| Component | Description | States |
|---|---|---|
| **Button** | Primary CTA with label, optional icon | default, hover, pressed, disabled |
| **IconButton** | Icon-only actions (accessible label hidden) | default, hover, pressed, disabled |
| **Input** | Short text field with masks support | default, focus, error, disabled |
| **Textarea** | Multi-line text field | default, focus, error, disabled |
| **Select** | Dropdown with 5–7 options | default, open, selected, disabled |
| **Checkbox / CheckboxGroup** | Binary choices (max 5 per group) | checked, unchecked, indeterminate, disabled |
| **Radio / RadioGroup** | Single selection (max 5 per group) | selected, unselected, disabled |
| **Search** | Collection narrowing input | default, active, empty |
| **Filter** | Predefined criteria for collections | applied, unapplied, multi-select |
| **Table** | Data rows with sort, actions | sortable, selectable, loading |
| **Collection** | Table + Search + Filters + Pagination | — |
| **Pagination** | Page navigation for collections | — |
| **Tag** | Colored read-only labels | secondary, primary (varied bg colors) |
| **Alert** | Semantic messages with optional dismiss | informational, success, warning, critical |
| **Toast** | Temporary feedback on actions | auto-dismiss, persistent |
| **Tooltip** | Hover-revealed label | — |
| **Modal** | Overlay for minor sub-tasks | open, closing |
| **ConfirmationModal** | Irreversible action confirmation | destructive, standard |
| **Drawer** | Slide-in panel for detail work | open, closing |
| **Popover** | Interactive content overlay | open, closing |
| **Menu** | Dropdown action list | open, item focused |
| **Tab** | View switching (max 5 views) | active, inactive |
| **Link** | Navigation within/between pages | default, hover, visited |
| **Skeleton** | Loading placeholder | animating |
| **Spinner** | In-progress indicator (1–5s tasks) | — |
| **EmptyState** | No-content placeholder | no items, no access |
| **Page** | Full page structure | PageHeader, PageContent |
| **DatePicker / DateRangePicker** | Date selection with calendar | open, selected, error |
| **Calendar / RangeCalendar** | Visual date selection | — |
| **TimeInput** | Time value field | default, focus, error |
| **BarChart** | Data visualization | — |

### Layout Primitives
| Component | Purpose |
|---|---|
| **Flex** | Flexbox layout wrapper |
| **Grid / GridCell** | CSS Grid layout |
| **Stack** | Consistent vertical spacing |
| **Bleed** | Content overflow from container |
| **Center** | Horizontal centering |
| **Content / Container** | Width-constrained content |

### Accessibility Primitives
| Component | Purpose |
|---|---|
| **AccessibleIcon** | Icon with accessible label |
| **VisuallyHidden** | Screen reader–only content |
| **LocaleProvider** | Locale context for i18n |
| **Clickable** | Clickable surface primitive |
| **LinkBox** | Container that acts as link |

## Do's and Don'ts

### Do's
- ✅ Use semantic tokens (`--sl-bg-accent`, `--sl-fg-base`) rather than primitive color values directly
- ✅ Use the `--sl-space-gap` token (1rem) as default spacing between sibling elements
- ✅ Use `display-1` through `display-4` for headings — never raw font-size + weight combinations
- ✅ Keep border radius at `--sl-radius-1` (4px) for most interactive elements
- ✅ Apply `--sl-shadow-1` for floating elements, `--sl-shadow-2` only for modals/drawers
- ✅ Include focus rings on all interactive elements — use the double-ring pattern (gap + outline)
- ✅ Use Shoreline's composition pattern (`Provider` + `Trigger` + `Popover`) for complex overlays
- ✅ Limit Radio/Checkbox groups to 5 options; use Select or Combobox for more
- ✅ Use Collection component to combine Table + Search + Filters + Pagination together

### Don'ts
- ❌ Don't use more than 2 levels of shadow — the system intentionally stays flat
- ❌ Don't mix the legacy `@vtex/styleguide` tokens with Shoreline tokens in the same interface
- ❌ Don't use custom colors outside the defined scales (gray, blue, red, green, yellow, orange, teal, purple, pink, cyan)
- ❌ Don't use `font-size-1` (12px) for primary body text — it's for captions only
- ❌ Don't exceed `--sl-radius-3` (12px) for rectangular elements; reserve `radius-full` for pills/circles
- ❌ Don't set z-index values manually — always use the `--sl-z-*` scale
- ❌ Don't use modals for content that could be inline — modals block all page interaction
- ❌ Don't stack more than 5 tabs — consider navigation patterns instead
- ❌ Don't use Spinner for page-level loading — use Skeleton instead (up to 5s)
- ❌ Don't use Button without a visible text label unless it's an IconButton with accessible name

---

## Attribution
- Source: https://github.com/vtex/styleguide (Styleguide legacy) + https://github.com/vtex/shoreline (Shoreline DS)
- Documentation: https://shoreline.vtex.com
- Extracted: 2026-07-05
- Method: open-source repo
- License: Design tokens extracted from publicly available open-source repositories. No affiliation with VTEX.