# Matcha — Design System
> Matcha is a decentralized exchange (DEX) aggregator by 0x that allows users to search and trade over 9 million tokens across multiple networks with zero added fees.
- **Canonical:** https://uiuxskills.com/library/matcha
- **Source:** https://matcha.xyz/
- **Category:** Fintech & Crypto
- **Compatible tools:** claude, cursor, lovable, figma-make
- **Coverage:** 80%
- **License:** MIT
- **Last updated:** 2026-10-28T20:03:28.334Z

---

---
version: alpha
name: Matcha
tagline: Search, trade, done.
description: >-
  Matcha is a decentralized exchange (DEX) aggregator by 0x that allows users to search and trade
  over 9 million tokens across multiple networks with zero added fees.
tone: Professional, clean, approachable, and precise.
color-scheme: light
colors:
  primary: "#17181C"
  secondary: "#5E6073"
  accent: "#1FC06E"
  background: "#F7F7F8"
  surface: "#FFFFFF"
  surface-container: "#F4F4F6"
  on-primary: "#FFFFFF"
  on-surface: "#17181C"
  error: "#FF3B30"
  outline: "#EAEAEB"
  success: "#1FC06E"
typography:
  display-lg:
    fontFamily: gilroyFont, Helvetica, sans-serif
    fontSize: 48px
    fontWeight: 700
    lineHeight: "1.2"
    letterSpacing: "-0.02em"
  display-md:
    fontFamily: gilroyFont, Helvetica, sans-serif
    fontSize: 34px
    fontWeight: 700
    lineHeight: "1.2"
    letterSpacing: "-0.01em"
  headline-lg:
    fontFamily: gilroyFont, Helvetica, sans-serif
    fontSize: 24px
    fontWeight: 600
    lineHeight: "1.3"
    letterSpacing: 0em
  headline-md:
    fontFamily: Inter, sans-serif
    fontSize: 20px
    fontWeight: 600
    lineHeight: "1.4"
    letterSpacing: 0em
  headline-sm:
    fontFamily: Inter, sans-serif
    fontSize: 18px
    fontWeight: 600
    lineHeight: "1.4"
    letterSpacing: 0em
  body-md:
    fontFamily: Inter, sans-serif
    fontSize: 16px
    fontWeight: 400
    lineHeight: "1.5"
    letterSpacing: 0em
  body-sm:
    fontFamily: Inter, sans-serif
    fontSize: 14px
    fontWeight: 400
    lineHeight: "1.5"
    letterSpacing: 0em
  label-md:
    fontFamily: Inter, sans-serif
    fontSize: 14px
    fontWeight: 600
    lineHeight: "1.2"
    letterSpacing: 0.02em
  label-sm:
    fontFamily: Inter, sans-serif
    fontSize: 11px
    fontWeight: 500
    lineHeight: "1.2"
    letterSpacing: 0.04em
rounded:
  sm: 4px
  md: 8px
  lg: 16px
  xl: 24px
  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}"
    rounded: "{rounded.full}"
    padding: 12px 24px
    height: 48px
  button-primary-hover:
    backgroundColor: "{colors.secondary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 12px 24px
    height: 48px
  button-secondary:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.primary}"
    typography: "{typography.label-md}"
    rounded: "{rounded.full}"
    padding: 10px 20px
    borderColor: "{colors.outline}"
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.xl}"
    padding: 24px
    borderColor: "{colors.outline}"
  card-elevated:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.xl}"
    padding: 24px
    borderColor: "{colors.outline}"
  input-field:
    backgroundColor: "{colors.surface-container}"
    textColor: "{colors.on-surface}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: 12px 16px
  input-field-focus:
    backgroundColor: "{colors.surface-container}"
    textColor: "{colors.on-surface}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: 12px 16px
    borderColor: "{colors.accent}"
  link:
    textColor: "{colors.secondary}"
    typography: "{typography.label-md}"
  link-hover:
    textColor: "{colors.primary}"
    typography: "{typography.label-md}"
  badge:
    backgroundColor: "{colors.surface-container}"
    textColor: "{colors.secondary}"
    typography: "{typography.label-sm}"
    rounded: "{rounded.full}"
    padding: 4px 8px
  badge-success:
    backgroundColor: "{colors.background}"
    textColor: "{colors.success}"
    typography: "{typography.label-sm}"
    rounded: "{rounded.full}"
    padding: 4px 8px
  badge-error:
    backgroundColor: "{colors.background}"
    textColor: "{colors.error}"
    typography: "{typography.label-sm}"
    rounded: "{rounded.full}"
    padding: 4px 8px
  divider:
    backgroundColor: "{colors.outline}"
    height: 1px
  button-accent:
    backgroundColor: "{colors.accent}"
    typography: "{typography.label-md}"
    rounded: "{rounded.md}"
    padding: 8px 16px
motion:
  duration-short: 200ms
  duration-medium: 500ms
  easing-standard: cubic-bezier(0.4, 0, 0.2, 1)
elevation:
  sm: 0 1px 2px rgba(0, 0, 0, 0.05)
  md: 0 4px 6px rgba(0, 0, 0, 0.1)
  lg: 0 10px 15px rgba(0, 0, 0, 0.2)
---

## Overview

Matcha's visual identity is clean, contemporary, and highly accessible, designed to make decentralized trading feel safe and effortless. It pairs a light, spacious background with high-contrast dark primary elements and a signature matcha-green accent that injects a fresh, consumer-friendly energy into a highly technical space. This balance of professional precision and approachable simplicity builds immediate trust and clarity for users navigating complex financial transactions.

## Colors

The color strategy focuses on high readability and a clean, light-mode aesthetic that mirrors traditional financial software while remaining fresh. A deep, high-contrast primary dark tone anchors the interface, while the signature matcha-green accent highlights success states and primary interactive pathways.

*   `colors.primary` (#17181C): Deep ink used for primary text, main headings, and high-priority call-to-action buttons to establish strong visual hierarchy.
*   `colors.secondary` (#5E6073): Muted slate used for secondary text, labels, and supporting UI elements to reduce visual noise.
*   `colors.accent` (#1FC06E): The signature Matcha green, used for branding, success states, and active indicators.
*   `colors.background` (#F7F7F8): The main canvas color, providing a clean, light-gray backdrop that reduces eye strain.
*   `colors.surface` (#FFFFFF): Pure white used for cards, dialogs, and the main swap interface container to separate interactive zones from the background.
*   `colors.surface-container` (inferred) (#F4F4F6): A slightly darker surface variant used for input fields and nested containers.
*   `colors.on-primary` (#FFFFFF): Text and icon color used on top of primary dark backgrounds.
*   `colors.on-surface` (#17181C): Text and icon color used on top of white surface elements.
*   `colors.error` (#FF3B30): Used for negative price movements, error badges, and destructive actions.
*   `colors.outline` (inferred) (#EAEAEB): Used for subtle borders, dividers, and structural separation.
*   `colors.success` (#1FC06E): Used for positive price movements, completed transactions, and success badges.

## Typography

The typography system pairs the geometric, premium feel of Gilroy for high-impact displays with the highly legible, neutral characteristics of Inter for functional data and body copy. This combination ensures that financial metrics and interactive controls remain perfectly readable at any scale.

*   `typography.display-lg` (inferred): Set in Gilroy, used for main hero headlines to create an impactful first impression.
*   `typography.display-md`: Set in Gilroy, used for secondary hero elements and major section headers.
*   `typography.headline-lg`: Set in Gilroy, used for card titles and prominent financial figures like token prices.
*   `typography.headline-md` (inferred): Set in Inter, used for medium-sized section headers and modal titles.
*   `typography.headline-sm` (inferred): Set in Inter, used for small card headers and feature titles.
*   `typography.body-md`: Set in Inter, the default body text size, optimized for readability in descriptions and paragraphs.
*   `typography.body-sm`: Set in Inter, used for secondary body copy, tooltips, and supporting metadata.
*   `typography.label-md`: Set in Inter, used for interactive labels, button text, and navigation links.
*   `typography.label-sm`: Set in Inter, used for tiny uppercase labels, table headers, and micro-copy.

## Layout

*   Matcha utilizes a clean, modular grid system structured around a maximum container width of 1200px, with generous section margins (`spacing.2xl`) and card paddings (`spacing.lg`) that give financial data breathing room.
*   The observed page pattern follows a top-to-bottom section order of `nav`, `hero`, `features`, and `footer`.
*   The hero composition features a centered, high-impact headline followed by a split-screen layout featuring a detailed token chart on the left and the primary swap interface card on the right.
*   The layout is fully responsive, collapsing from a side-by-side desktop view into a single-column stack on mobile devices, using `spacing.md` to maintain tight, clean gaps while prioritizing the swap card at the top of the viewport.

## Elevation & Depth

The interface employs soft, layered shadows to elevate interactive modules above the flat, light-gray background canvas.

*   `elevation.sm`: Used for small interactive badges, tooltips, and subtle hover states.
*   `elevation.md`: Applied to primary container cards, dropdowns, and interactive modules like token charts.
*   `elevation.lg`: Reserved for major modal overlays, drawers, and the main swap interface card to establish clear depth.

## Shapes

The brand's shape language is defined by highly rounded corners, which soften the technical complexity of decentralized finance and make the platform feel approachable. Main interface containers and cards use `rounded.xl` or `rounded.lg` to establish a soft, friendly structure.

Interactive elements like buttons and badges utilize `rounded.full` to create pill-shaped touch targets that feel tactile and modern. Smaller input fields and nested elements scale down to `rounded.md` or `rounded.sm` to maintain geometric harmony within larger containers.

## 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`

### button-primary
The primary action button uses a solid `{colors.primary}` background with `{colors.on-primary}` text, styled with `{typography.label-md}` and `{rounded.full}`. It is used for the main call-to-action on a page or card, such as initiating a wallet connection or confirming a trade.

### button-primary-hover
This state transitions the primary button background to `{colors.secondary}` while keeping `{colors.on-primary}` text. Use this to provide immediate visual feedback when a user hovers over a primary action.

### button-secondary
The secondary button features a `{colors.surface}` background, `{colors.primary}` text, and a subtle `{colors.outline}` border with `{rounded.full}`. Use this for secondary or alternative actions that run parallel to the primary task.

### card
The standard card component uses a flat `{colors.surface}` background with `{rounded.xl}` corners and `{colors.outline}` borders. It is used to group related financial information, token details, or features into a clean, modular container.

### card-elevated
This variant adds depth to the standard card by applying `{elevation.md}` or `{elevation.lg}`. Use this to highlight the main interactive zone of the page, such as the swap module, separating it from the background canvas.

### input-field
The input field uses a `{colors.surface-container}` background with `{rounded.md}` corners and `{typography.body-md}` text. It is used for entering token amounts, search queries, or custom slippage values.

### input-field-focus
When focused, the input field displays a `{colors.accent}` border to indicate active user input. Use this state to guide the user's focus during data entry.

### link
The text link uses `{colors.secondary}` with `{typography.label-md}`. Use this for inline navigation, external documentation links, or minor actions.

### link-hover
Upon hover, the link transitions to `{colors.primary}` to indicate interactivity. Use this to provide clear, subtle feedback on text-based navigation.

### badge
The default badge uses a `{colors.surface-container}` background with `{colors.secondary}` text and `{rounded.full}` corners. Use this for neutral metadata, network labels, or inactive states.

### badge-success
This badge uses a `{colors.background}` background with `{colors.success}` text. Use this to highlight positive price movements, completed transactions, or verified tokens.

### badge-error
This badge uses a `{colors.background}` background with `{colors.error}` text. Use this to flag negative price movements, failed transactions, or high-slippage warnings.

### divider
The divider is a thin line with a height of 1px, colored with `{colors.outline}`. Use this to separate distinct sections of financial data or list items within a card.

### button-accent
The accent button features a `{colors.accent}` background with `{rounded.md}` corners and `{typography.label-md}`. Use this for specific high-priority actions that require the signature brand color, such as promotional features or special swap states.

## Do's and Don'ts

| Do | Don't |
| --- | --- |
| Use `{colors.primary}` for all primary action buttons like `{components.button-primary}` to ensure maximum contrast. | Never use sharp corners on buttons; always apply `{rounded.full}` to preserve the friendly brand aesthetic. |
| Apply `{colors.accent}` to highlight active states, brand logos, and success indicators. | Do not apply heavy, dark shadows; always use the soft, transparent values defined in `{elevation.md}` or `{elevation.sm}`. |
| Ensure all main interface modules are contained within a `{components.card}` using `{rounded.xl}` corners. | Do not crowd the interface; ensure at least `{spacing.lg}` of padding is maintained inside all container cards. |
| Use `{typography.display-md}` for prominent page headings to establish clear visual hierarchy. | Never use non-brand fonts; stick strictly to the `{typography.body-md}` and heading font stacks. |
| Separate distinct financial data sections using a `{components.divider}` colored with `{colors.outline}`. | Do not use `{colors.error}` for neutral or positive financial metrics; reserve it strictly for negative trends or system errors. |
| Maintain consistent spacing around interactive elements using `{spacing.md}` and `{spacing.lg}`. | Avoid placing dark text directly on `{colors.primary}` backgrounds; always use `{colors.on-primary}` for high contrast. |
| Use `{colors.surface-container}` for input fields to distinguish them from the main `{colors.surface}` card background. | Do not use `{rounded.full}` on `{components.input-field}` elements; stick to `{rounded.md}` to maintain structural distinction from buttons. |
| Apply `{typography.label-sm}` to tiny uppercase labels and table headers to keep data scannable. | Do not use `{typography.display-lg}` for standard body text or paragraphs, as it disrupts the visual hierarchy. |

## Content Style

*   **CTA Style**: Call-to-action buttons use action-oriented, imperative verbs in sentence case. Labels are kept short, direct, and functional (e.g., "Connect EVM wallet", "Switch to USDC") to drive immediate user action without ambiguity.
*   **Heading Tone**: Headlines are clear, benefit-driven, and direct. They focus entirely on speed, simplicity, and efficiency (e.g., "Swap any token in seconds") without unnecessary marketing fluff or technical jargon.
*   **Copy Density**: The layout maintains low to medium copy density. Information is chunked into scannable cards, bullet points, and short paragraphs to prevent cognitive overload, ensuring that financial data remains the central focus.

## Imagery & Icons

The visual system relies on a minimal-icons treatment, utilizing clean, flat vector icons and official token logos. Icons are styled with simple strokes or solid fills, utilizing the brand's `{colors.primary}` and `{colors.accent}` colors to maintain a cohesive look. No complex illustrations or photographic elements are used, ensuring the interface remains lightweight, fast-loading, and focused entirely on the utility of the trading experience.

---

## Companion prompt

## Role
You are an AI assistant generating UI components and layouts for Matcha, a minimal and accessible decentralized trading platform with a professional, clean, and precise tone. Content, copy, and information architecture remain owned by the product team.

## How to use design.md
1. Reference every visual value by token name — `{colors.primary}`, `{typography.body-md}`, `{rounded.full}` — never hardcode hex values, pixel sizes, or font names.
2. Use only the components listed under `components:` — `button-primary`, `card`, `input-field`, `badge-success`, etc. Do not invent variants the spec does not define.
3. Apply the shape language from Shapes: `{rounded.xl}` or `{rounded.lg}` on cards, `{rounded.full}` on all buttons and badges without exception.
4. Follow Layout: constrain content to 1200px max-width, use `{spacing.2xl}` for section margins, `{spacing.lg}` for card padding, and collapse to a single-column stack below 768px.
5. Treat the Do's and Don'ts as authoritative. If a user request conflicts — for example, requesting sharp-cornered buttons or using `{colors.error}` for a neutral metric — surface the conflict before proceeding.

## Output contract

**Must:**
- Use token names for all colors, typography, spacing, and radii.
- Include hover, focus, and disabled states for every interactive component the spec defines.
- Apply `{colors.on-primary}` for text on `{colors.primary}` backgrounds; `{colors.on-surface}` for text on `{colors.surface}`.
- Match CTA copy style: imperative, sentence case, short (e.g., "Connect EVM wallet").
- Use `{components.divider}` with `{colors.outline}` to separate distinct data sections.
- Use flat, stroke or solid vector icons colored with `{colors.primary}` or `{colors.accent}` only.

**Must NOT:**
- Invent colors, radii, font families, or spacing values outside the spec.
- Apply generic system defaults when a brand token exists.
- Place any text other than `{colors.on-primary}` on `{colors.primary}` backgrounds.
- Add emoji, filler text, or unsolicited marketing copy.
- Rewrite, replace, or extend page copy, navigation items, or headings.
- Use `{colors.error}` for neutral or positive financial data.

## When in doubt
- If a value is unspecified, ask the user before inventing one.
- Prefer composing existing components over introducing new tokens.
- For ambiguous backgrounds, default to `{colors.surface-container}` for inputs and nested containers, `{colors.surface}` for cards.
- For ambiguous text roles, default to `{colors.on-surface}` on light surfaces and `{colors.secondary}` for supporting metadata.
- Tokens marked "(inferred)" in the spec are approximations; defer to any authoritative token source the product team provides.
