Design guidelines - Claude.ai Documentation

MCP Apps are interactive interfaces that appear within Claude’s conversational flow. These guidelines are for developers designing an MCP App’s UI.

If you haven’t built and connected an MCP App yet, see Get started with MCP Apps.

Use the guidelines to pick a display mode, adapt to mobile, match Claude’s visual design with the host’s style variables, and decide which interactions belong in your app and which belong in chat.

The Figma UI kit has components and patterns to start from.

Design for the conversation

Design your app as an extension of the conversation rather than a separate app that appears alongside it. Your app inherits conversational context and helps users accomplish meaningful tasks without breaking flow. These principles follow from that:

Conversational: fit naturally into dialogue, and don’t force users to learn new interaction patterns
Contextual: use conversation history to inform what you display and when
Integrated: inherit styling and conventions from the containing environment
Adaptive: handle variable sizing, mobile viewports, and diverse accessibility needs gracefully

Choose what to build as an MCP App

An MCP App works best for a task the user can finish inside the conversation. Good candidates include:

Tasks that fit naturally into conversation, like data analysis, document review, or project coordination
Communication and collaboration context, like message search results, conversation threads, or team member profiles
Tasks with a clear start and end, like booking, ordering, or scheduling
Information users can act on immediately
Functionality that extends Claude’s capabilities meaningfully

Avoid these patterns:

Long-form or static content better suited for external viewing
Complex multi-step workflows that exceed the display mode’s scope
Deep navigation such as drill-ins, breadcrumbs, or multiple views
Nested scrolling, because inline cards should auto-fit content height
Menus and popovers: dropdowns, context menus, and popover panels can get clipped by container boundaries or create z-index conflicts with the host UI, so prefer visible controls like segmented buttons, toggles, or inline options
Chat inputs or conversational UI that replicate Claude’s own features

Display modes

An MCP App appears in the conversation as an inline card, an inline carousel, or a full screen view. Each mode suits different content and carries its own constraints on desktop and on mobile.

Inline card

An inline card is a compact component embedded directly in the conversation. Keep it focused. Use an inline card for:

Status updates and confirmations
Simple data displays or selections
Brief summaries with optional expansion
Quick actions that continue the conversation

Inline card example showing a compact component

Inline card example showing a data display

Inline cards have these constraints:

Height auto-fits to content, with no nested scrolling
At most 2 actions, placed at the bottom of the card
At most 4-5 data points
No drill-ins, breadcrumbs, or multiple views
No menus or popovers, only visible controls

On mobile, inline cards render full-width within the conversation. Make every tap target at least 44pt, and adapt content to narrower viewports without horizontal scrolling.

Inline carousel

An inline carousel shows items side by side for browsing options. Users swipe or scroll horizontally to explore. Use an inline carousel for:

Product listings or search results
Location or venue options
Media galleries
Any set of comparable items

Inline carousel example showing browsable items

Inline carousels have these constraints:

3-8 items for scannability
Each card has an image, a title, up to 3 lines of metadata, and an optional CTA
1 optional CTA per card
Consistent card dimensions within a carousel
Consistent visual hierarchy across cards

On mobile, carousel cards are optimized for horizontal swipe. Design for thumb reach by keeping primary actions in the lower portion of cards, and let the next card peek into view to signal that the row scrolls.

Full screen

Full screen mode gives complex interactions an immersive interface. The conversation composer remains available, so users can continue talking to your app through Claude. Use full screen for:

Data visualizations and dashboards
Detailed analysis tools
Document editing
Content that benefits from focused attention
Rich tasks requiring more space than inline allows

Full screen mode with data visualization

Full screen mode has these constraints:

Your app provides its own fullscreen button, and a close button appears in the native header bar
The composer is always visible, so design your UX to work with it
No floating panels, so use collapsible sidebars, tabs, or pagination to disclose details
The chat sheet maintains conversational context

On mobile, your app fills the entire screen with the chat input and navigation bar overlaid on top, so keep critical UI within the safe area. Use the full viewport width, and support both portrait and landscape where it makes sense.

Mobile guidelines

MCP Apps on mobile follow the same principles as on web, but the constrained viewport and touch-based interaction require specific adaptations. On mobile, Claude renders apps in a native WebView, WKWebView on iOS and WebView on Android, rather than a sandboxed iframe. Apps on mobile have no camera, microphone, or location access, and users must add a connector on web or desktop before it appears on mobile.

Host context for layout

The host passes layout hints to your app through hostContext. Apps always fill the container width, with no fixed breakpoints, so design responsively from 320px up to fullscreen using container queries and the hostContext CSS variables.

Safe areas

Render the interactive portion of your app inside the safe area so the mobile navigation bar and chat input don’t obscure it and it respects the chat screen’s content margins. The user can’t interact with anything rendered outside the safe area, such as a button under the mobile navigation bar. Read hostContext.safeAreaInsets.{top, right, bottom, left}, which are pixel values, and apply them as padding on your root container, or as scroll-padding on scroll-snap containers so items come to rest inside the visible region. Safe areas aren’t mobile-specific: on web and desktop the composer can overlay the bottom of an inline app, so avoid placing interactive controls flush against any edge.

Safe area insets in full screen mode on web and mobile

Borderless inline content

Set _meta.ui.prefersBorder to true or false to control whether your content renders with a border. If you don’t set it, content renders borderless on web and bordered on mobile. In borderless mode your content runs edge-to-edge with no host padding, so honoring safeAreaInsets becomes essential. The bordered card’s built-in padding otherwise absorbs most of them. Borderless works well for carousels and other horizontally scrolling content that should bleed to the screen edges while in motion: apply safeAreaInsets.left and .right as scroll-padding-inline on the scroll container so items at rest sit clear of the device edges but can scroll underneath them.

Safe area insets for borderless inline apps on mobile

Declare supported display modes

Declare which modes your app supports through appCapabilities.availableDisplayModes in ui/initialize. The host responds with the modes it supports, and your app can request a switch with ui/request-display-mode. Modes are inline, fullscreen, and pip.

Content security policy

All external origins are blocked by default. Declare the origins each ui:// resource needs through _meta.ui.csp:

{
  "_meta": {
    "ui": {
      "csp": {
        "connectDomains": ["https://api.example.com"],
        "resourceDomains": ["https://cdn.example.com"],
        "baseUriDomains": []
      }
    }
  }
}

The frameDomains field, for embedding third-party iframes, is restricted in Claude pending security review.

Viewport and layout

Design for variable widths, from a 320pt minimum up to tablet
Respect safe areas on notched devices
Use full-width layouts, without side margins that waste mobile screen space
Let content reflow gracefully, and avoid fixed-width layouts

Touch targets

Minimum tap target of 44 x 44pt, per the Apple HIG and Material guidelines
Sufficient spacing between interactive elements to prevent mis-taps
Larger, thumb-friendly buttons rather than small text links
Primary actions within natural thumb reach, in the lower portion of the screen

Scrolling and gestures

On mobile touch devices, the conversation view owns vertical scrolling. When your app is rendered inline, vertical pan gestures that start inside it go to the conversation scroll instead of to your content, so a tall widget can’t trap the user. The host also caps inline height and clips content that exceeds it, so fit your inline app to its content height rather than relying on an internal vertical scroll container. Horizontal gestures, such as swiping a carousel or panning a map, and taps work normally. If your app needs its own vertically scrollable viewport, request fullscreen presentation with ui/request-display-mode instead of rendering inline, as described in Full screen.

Transitions

Inline cards expand to fullscreen with a smooth transition
Provide a clear visual affordance for expansion, such as a fullscreen button or tap-to-expand
Closing fullscreen returns to the conversation at the same scroll position

Transition from inline card to full screen

Dark mode

All views must support both light and dark themes. Use the host’s style tokens, which adapt automatically, and never hardcode colors. Test both modes.

Loading states

Show skeleton screens while content loads, and match the layout structure of the final content so the swap is smooth. Avoid spinners for inline content, because skeletons feel more native.

Visual design

MCP Apps should feel native to their environment while maintaining consistent visual hierarchy and accessibility standards. You can still express your brand through accent colors, custom controls, and content.

Color

Use host tokens for all structural elements: backgrounds, text, borders, and icons. You can use your own brand colors for accents and identity, but the core UI should use the provided palette.

Typography

Stick to the three-level size scale of heading, body, and caption, and the two weights of regular and emphasized. This creates clear hierarchy without visual noise.

The Figma Community File uses Anthropic Sans and Anthropic Serif. When your app runs inside Claude, the host client provides Anthropic Sans at runtime through style variables. For local development, download and install the fonts.

Borders

Use a limited set of corner radii and border thicknesses to keep your app feeling native to the surrounding UI.

Icons

Use monochromatic, outlined icons that match the host’s icon color tokens. Icons should support understanding rather than be essential to it.

Spacing

Maintain generous padding and logical groupings. Balance information density with readability, adapting to viewport constraints.

Accessibility

Your app must be usable by everyone. Maintain high contrast at WCAG AA minimum, support keyboard navigation, and provide text alternatives for visual content. Test with assistive technologies.

Interaction patterns

Some interactions belong inside your app and others belong in Claude’s chat input. Drawing that boundary correctly, revealing complexity progressively, and keeping controls visible make your app feel cohesive with the conversation.

Decide between app and chat interactions

Handle these within your app:

Direct manipulation like sliders, toggles, and selections
Filtering or sorting data you’re already displaying
Expanding and collapsing content sections
Confirming or executing a prepared action, such as “Mark complete,” “Send,” or “Save”
Interacting with visualizations, like hover states or clicking data points

Push these to the chat input:

Text entry and freeform input
Follow-up questions or requests for clarification
Requests to modify, refine, or redo something
Navigation to different contexts or topics
Anything that benefits from Claude’s interpretation

If the interaction requires language understanding or generates a response from Claude, it goes through chat. If it’s a direct UI action on content your app already controls, handle it in the app.

Reveal complexity progressively

Reveal complexity only when users need it. The inline card might show a summary, and fullscreen mode can offer the detailed view.

Prefer visible controls over hidden menus

Prefer controls with visible options, such as segmented buttons, toggle chips, and inline tabs, over menus and dropdowns. Menus conflict with the host container and are harder to use on mobile.

Style variables

MCP Apps automatically receive style variables from the host client. Reference these CSS custom properties to create interfaces that feel native to Claude. Blend your MCP App with Claude’s theme shows how to apply them at runtime.

Color tokens

Color tokens cover backgrounds, text, and borders, and semantic accent colors signal status. All tokens automatically adapt to light and dark mode.

	Light mode	Dark mode
Background
`color-background-primary`	`#FFFFFF`	`#30302E`
`color-background-secondary`	`#F5F4ED`	`#262624`
`color-background-tertiary`	`#FAF9F5`	`#141413`
`color-background-inverse`	`#141413`	`#FAF9F5`
`color-background-ghost`	`#FFFFFF (0%)`	`#30302E (0%)`
`color-background-info`	`#D6E4F6`	`#253E5F`
`color-background-danger`	`#F7ECEC`	`#602A28`
`color-background-success`	`#E9F1DC`	`#1B4614`
`color-background-warning`	`#F6EEDF`	`#483A0F`
`color-background-disabled`	`#FFFFFF (50%)`	`#30302E (50%)`
Text
`color-text-primary`	`#141413`	`#FAF9F5`
`color-text-secondary`	`#3D3D3A`	`#C2C0B6`
`color-text-tertiary`	`#73726C`	`#9C9A92`
`color-text-inverse`	`#FFFFFF`	`#141413`
`color-text-ghost`	`#73726C (50%)`	`#9C9A92 (50%)`
`color-text-info`	`#3266AD`	`#80AADD`
`color-text-danger`	`#7F2C28`	`#EE8884`
`color-text-success`	`#265B19`	`#7AB948`
`color-text-warning`	`#5A4815`	`#D1A041`
`color-text-disabled`	`#141413 (50%)`	`#FAF9F5 (50%)`
Border
`color-border-primary`	`#1F1E1D (40%)`	`#DEDCD1 (40%)`
`color-border-secondary`	`#1F1E1D (30%)`	`#DEDCD1 (30%)`
`color-border-tertiary`	`#1F1E1D (15%)`	`#DEDCD1 (15%)`
`color-border-inverse`	`#FFFFFF (30%)`	`#141413 (15%)`
`color-border-ghost`	`#1F1E1D (0%)`	`#DEDCD1 (0%)`
`color-border-info`	`#4682D5`	`#4682D5`
`color-border-danger`	`#A73D39`	`#CD5C58`
`color-border-success`	`#437426`	`#599130`
`color-border-warning`	`#805C1F`	`#A87829`
`color-border-disabled`	`#1F1E1D (10%)`	`#DEDCD1 (10%)`
Ring
`color-ring-primary`	`#141413 (70%)`	`#FAF9F5 (70%)`
`color-ring-secondary`	`#3D3D3A (70%)`	`#C2C0B6 (70%)`
`color-ring-inverse`	`#FFFFFF (70%)`	`#141413 (70%)`
`color-ring-info`	`#3266AD (50%)`	`#80AADD (50%)`
`color-ring-danger`	`#A73D39 (50%)`	`#CD5C58 (50%)`
`color-ring-success`	`#437426 (50%)`	`#599130 (50%)`
`color-ring-warning`	`#805C1F (50%)`	`#A87829 (50%)`

Typography tokens

Typography tokens include the font family, sizes, weights, and line heights.

Family
`font-sans`	`"Anthropic Sans, sans-serif"`
`font-mono`	`"ui-monospace, monospace"`
Weight
`font-weight-normal`	`400`
`font-weight-medium`	`500`
`font-weight-semibold`	`600`
`font-weight-bold`	`700`
Size
`font-text-xs-size`	`12px`
`font-text-sm-size`	`14px`
`font-text-md-size`	`16px`
`font-text-lg-size`	`20px`
`font-heading-xs-size`	`12px`
`font-heading-sm-size`	`14px`
`font-heading-md-size`	`16px`
`font-heading-lg-size`	`20px`
`font-heading-xl-size`	`24px`
`font-heading-2xl-size`	`28px`
`font-heading-3xl-size`	`36px`
Line-height
`font-text-xs-line-height`	`1.4`
`font-text-sm-line-height`	`1.4`
`font-text-md-line-height`	`1.4`
`font-text-lg-line-height`	`1.25`
`font-heading-xs-line-height`	`1.4`
`font-heading-sm-line-height`	`1.4`
`font-heading-md-line-height`	`1.4`
`font-heading-lg-line-height`	`1.25`
`font-heading-xl-line-height`	`1.25`
`font-heading-2xl-line-height`	`1.1`
`font-heading-3xl-line-height`	`1`

Radius tokens

Radius tokens provide border radius values.

Radius
`border-radius-xs`	`4px`
`border-radius-sm`	`6px`
`border-radius-md`	`8px`
`border-radius-lg`	`10px`
`border-radius-xl`	`12px`
`border-radius-full`	`9999px`

Border width tokens

Border width tokens provide border width values.


`border-width-regular`	`0.5px`

Shadow tokens

Shadow tokens provide drop-shadow values.


`shadow-hairline`	`0 1px 2px 0 rgba(0, 0, 0, 0.05)`
`shadow-sm`	`0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)`
`shadow-md`	`0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)`
`shadow-lg`	`0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)`

Example usage

This CSS applies the host tokens to an app container, a card, and a button:

.my-app {
  background: var(--color-background-primary);
  color: var(--color-text-primary);
  font-size: var(--font-text-md-size);
  line-height: var(--font-text-md-line-height);
}

.card {
  background: var(--color-background-secondary);
  border-color: var(--color-border-primary);
  border-width: var(--border-width-regular);
  border-radius: var(--border-radius-md);
}

.button {
  background: var(--color-background-inverse);
  color: var(--color-text-inverse);
  font-weight: var(--font-weight-semibold);
  border-radius: var(--border-radius-md);
}

Blend your MCP App with Claude’s theme: apply the style variables and keep your background transparent
Set ui.domain for Claude: compute the sandbox origin Claude expects for your app
Submit a connector: screenshot specifications for listing an MCP App in the directory

​Design for the conversation

​Choose what to build as an MCP App

​Display modes

​Inline card

​Inline carousel

​Full screen

​Mobile guidelines

​Host context for layout

​Safe areas

​Borderless inline content

​Declare supported display modes

​Content security policy

​Viewport and layout

​Touch targets

​Scrolling and gestures

​Transitions

​Dark mode

​Loading states

​Visual design

​Color

​Typography

​Borders

​Icons

​Spacing

​Accessibility

​Interaction patterns

​Decide between app and chat interactions

​Reveal complexity progressively

​Prefer visible controls over hidden menus

​Style variables

​Color tokens

​Typography tokens

​Radius tokens

​Border width tokens

​Shadow tokens

​Example usage

​Related resources

Design for the conversation

Choose what to build as an MCP App

Display modes

Inline card

Inline carousel

Full screen

Mobile guidelines

Host context for layout

Safe areas

Borderless inline content

Declare supported display modes

Content security policy

Viewport and layout

Touch targets

Scrolling and gestures

Transitions

Dark mode

Loading states

Visual design

Color

Typography

Borders

Icons

Spacing

Accessibility

Interaction patterns

Decide between app and chat interactions

Reveal complexity progressively

Prefer visible controls over hidden menus

Style variables

Color tokens

Typography tokens

Radius tokens

Border width tokens

Shadow tokens

Example usage

Related resources