Home Docs Claude Documentation 25 Sep 2026

One change · claude-docs

Design guidelines changedconnectors/building/mcp-apps/design-guidelines

Nearest release: v2.1.283, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 25 Sep 2026 18:00 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 25 Sep 2026 18:07 UTC.

Upstream edited 25 Sep 2026 18:00 UTC

Recorded here 25 Sep 2026 18:07 UTC

Lines+155added

Lines−125removed

From line 1 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits2to this page, all time

## Design for the conversation ## Choose what to build as an MCP App #### Safe areas #### Borderless inline content ### Declare supported display modes ### Color ### Typography ### Borders ### Icons ### Spacing ### Accessibility ### Decide between app and chat interactions ### Reveal complexity progressively ### Prefer visible controls over hidden menus ### Color tokens ### Typography tokens ### Radius tokens ### Border width tokens ### Shadow tokens ## Related resources ## Overview ## What makes a good MCP App ### Display modes ### App vs. chat interactions ### Start simple ### Visible controls over hidden menus ## Accessibility

The whole hunk

from line 1, old and new numbered

lines

from line 1

11# Design guidelines

3> Visual and interaction design guidelines for MCP Apps in Claude

3> Design MCP Apps that feel native to Claude: display modes, mobile layout, visual style, interaction patterns, and the host's style variables.

5## Overview

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

7MCP Apps are interactive interfaces that appear within Claude's conversational flow. Think of them as natural extensions of the conversation, not separate apps that happen to appear alongside it. Your app inherits conversational context and helps users accomplish meaningful tasks without breaking flow.

7<Note>

8 If you haven't built and connected an MCP App yet, see [Get started with MCP Apps](/docs/connectors/building/mcp-apps/getting-started).

9</Note>

810

9**Core principles:**

11Use the guidelines to [pick a display mode](#display-modes), [adapt to mobile](#mobile-guidelines), match Claude's [visual design](#visual-design) with the host's [style variables](#style-variables), and decide which [interactions](#interaction-patterns) belong in your app and which belong in chat.

1012

11* **Conversational.** Fit naturally into dialogue. Don't force users to learn new interaction patterns.

12* **Contextual.** Use conversation history to inform what you display and when.

13* **Integrated.** Inherit styling and conventions from the containing environment.

14* **Adaptive.** Handle variable sizing, mobile viewports, and diverse accessibility needs gracefully.

1613<Tip>

17 See our [Figma UI kit](https://www.figma.com/community/file/1597641111449594397/mcp-apps-for-claude) for components and patterns to help you get started.

14 The [Figma UI kit](https://www.figma.com/community/file/1597641111449594397/mcp-apps-for-claude) has components and patterns to start from.

1815</Tip>

1916

20## What makes a good MCP App

17## Design for the conversation

2118

22**Good candidates:**

19Design 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:

2320

24* Tasks that fit naturally into conversation like data analysis, document review, or project coordination

25* Communication and collaboration context like message search results, conversation threads, or team member profiles

26* Tasks with a clear start and end like booking, ordering or scheduling

21* **Conversational**: fit naturally into dialogue, and don't force users to learn new interaction patterns

22* **Contextual**: use conversation history to inform what you display and when

23* **Integrated**: inherit styling and conventions from the containing environment

24* **Adaptive**: handle variable sizing, mobile viewports, and diverse accessibility needs gracefully

26## Choose what to build as an MCP App

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

30* Tasks that fit naturally into conversation, like data analysis, document review, or project coordination

31* Communication and collaboration context, like message search results, conversation threads, or team member profiles

32* Tasks with a clear start and end, like booking, ordering, or scheduling

2733* Information users can act on immediately

2834* Functionality that extends Claude's capabilities meaningfully

2935

30**Patterns to avoid:**

36Avoid these patterns:

3137

3238* Long-form or static content better suited for external viewing

3339* Complex multi-step workflows that exceed the display mode's scope

34* Deep navigation (no drill-ins, breadcrumbs, or multiple views)

35* Nested scrolling (inline cards should auto-fit content height)

36* Menus and popovers (dropdowns, context menus, and popover panels can get clipped by container boundaries or create z-index conflicts with the host UI — prefer visible controls like segmented buttons, toggles, or inline options)

37* Chat inputs or conversational UI (don't replicate Claude's features)

40* Deep navigation such as drill-ins, breadcrumbs, or multiple views

41* Nested scrolling, because inline cards should auto-fit content height

42* 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

43* Chat inputs or conversational UI that replicate Claude's own features

3844

3945## Display modes

4046

47An 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.

4149### Inline card

4250

43Compact components embedded directly in conversation. Good for summaries, confirmations, and quick actions. Keep them focused.

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

4452

45**When to use:**

4753* Status updates and confirmations

4854* Simple data displays or selections

4955* Brief summaries with optional expansion

from line 59

5359

5460<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/inline-card-2.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=344f114b1012838b4805b48d496201c0" alt="Inline card example showing a data display" width="1999" height="1423" data-path="images/mcp-apps/inline-card-2.png" />

5561

56**Constraints:**

62Inline cards have these constraints:

5763

58* Height: auto-fits to content (no nested scrolling)

59* Max actions: 2, placed at the bottom of the card

60* Max data points: 4-5

64* Height auto-fits to content, with no nested scrolling

65* At most 2 actions, placed at the bottom of the card

66* At most 4-5 data points

6167* No drill-ins, breadcrumbs, or multiple views

62* No menus or popovers — use visible controls instead

68* No menus or popovers, only visible controls

6369

64**On mobile:** Inline cards render full-width within the conversation. Ensure all tap targets are at least 44pt. Content should adapt to narrower viewports without horizontal scrolling.

70On 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.

6571

6672<img src="https://mintcdn.com/claude-ai/sLZLADaApRAVEV6C/images/mcp-apps/inline-card-mobile.png?fit=max&auto=format&n=sLZLADaApRAVEV6C&q=85&s=3d2afa48da4f1d31cce9c0bb91a18807" alt="Inline card mobile examples" width="1999" height="838" data-path="images/mcp-apps/inline-card-mobile.png" />

6773

6874### Inline carousel

6975

70Side-by-side items for browsing options. Users swipe or scroll horizontally to explore.

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

7177

72**When to use:**

7478* Product listings or search results

7579* Location or venue options

7680* Media galleries

from line 82

7882

7983<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/inline-carousel-1.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=ef6b5615726ad25708ebdedf586226ae" alt="Inline carousel example showing browsable items" width="1999" height="1423" data-path="images/mcp-apps/inline-carousel-1.png" />

8084

81**Constraints:**

85Inline carousels have these constraints:

8286

8387* 3-8 items for scannability

84* Each card: image + title + metadata (max 3 lines) + optional CTA

88* Each card has an image, a title, up to 3 lines of metadata, and an optional CTA

8589* 1 optional CTA per card

86* Maintain consistent card dimensions within a carousel

87* Cards should have consistent visual hierarchy

90* Consistent card dimensions within a carousel

91* Consistent visual hierarchy across cards

8892

89**On mobile:** Carousel cards are optimized for horizontal swipe. Design for thumb reach — keep primary actions in the lower portion of cards. Peek the next card to signal scrollability.

93On 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.

9094

9195<img src="https://mintcdn.com/claude-ai/sLZLADaApRAVEV6C/images/mcp-apps/inline-carousel-mobile.png?fit=max&auto=format&n=sLZLADaApRAVEV6C&q=85&s=2bf64edd4fdefe8a37188ca4f2f32f4e" alt="Inline carousel mobile examples" width="1999" height="1022" data-path="images/mcp-apps/inline-carousel-mobile.png" />

9296

9397### Full screen

9498

95Immersive interfaces for complex interactions. The conversation composer remains available so users can continue talking to your app through Claude. Apps provide their own fullscreen button. A close button appears in the native header bar when in fullscreen mode. In fullscreen mode, avoid the use of floating panels. Use collapsible sidebars, tabs or pagination to disclose details.

99Full 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:

96100

97**When to use:**

99101* Data visualizations and dashboards

100102* Detailed analysis tools

101103* Document editing

from line 108

106108

107109<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/fullscreen-2.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=8523c5ae46ab7492586044ff5fabea32" alt="Full screen mode with data visualization" width="1999" height="1423" data-path="images/mcp-apps/fullscreen-2.png" />

108110

109**Constraints:**

111Full screen mode has these constraints:

110112

111* Your app provides its own fullscreen button; a close button appears in the native header bar

112* The composer is always visible — design your UX to work with it

113* No floating panels — use collapsible sidebars, tabs, or pagination to disclose details

114* Chat sheet maintains conversational context

113* Your app provides its own fullscreen button, and a close button appears in the native header bar

114* The composer is always visible, so design your UX to work with it

115* No floating panels, so use collapsible sidebars, tabs, or pagination to disclose details

116* The chat sheet maintains conversational context

115117

116**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.

118On 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.

117119

118120<img src="https://mintcdn.com/claude-ai/sLZLADaApRAVEV6C/images/mcp-apps/fullscreen-mobile.png?fit=max&auto=format&n=sLZLADaApRAVEV6C&q=85&s=d2802346090fd1a7af6a1bdc1d7c3263" alt="Full screen mobile examples" width="1999" height="716" data-path="images/mcp-apps/fullscreen-mobile.png" />

119121

120122## Mobile guidelines

121123

122MCP apps on mobile share the same principles as web, but the constrained viewport and touch-based interaction require specific adaptations.

124MCP 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.

123125

124On mobile, Claude renders apps in a native WebView (WKWebView on iOS, WebView on Android) rather than a sandboxed iframe. Current mobile-only constraints: no camera/mic/location access, and connectors must be added via web or desktop before they appear on mobile.

125

126126### Host context for layout

127127

128The host passes layout hints via `hostContext`.

128The 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.

129129

130**Safe areas.** The interactive portion of your app should be rendered inside of the safe area to ensure it's not obscured by the mobile navigation bar or chat input and respects the chat screen's content margins. The user won't be able to interact with anything rendered outside the safe area (e.g. buttons obscured by a mobile navigation bar). Read `hostContext.safeAreaInsets.{top, right, bottom, left}` (in pixels) 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 are not 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.

130#### Safe areas

131131

132Render 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.

133

134Read `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.

135

132136<img src="https://mintcdn.com/claude-ai/sLZLADaApRAVEV6C/images/mcp-apps/safe-area-fullscreen.png?fit=max&auto=format&n=sLZLADaApRAVEV6C&q=85&s=d789bcbba50a3bff53d677478421de30" alt="Safe area insets in full screen mode on web and mobile" width="1999" height="1153" data-path="images/mcp-apps/safe-area-fullscreen.png" />

133137

134**Borderless inline.** Set `_meta.ui.prefersBorder` to true or false to explicitly determine whether your content should render with a border. If no value is specified, content will be rendered 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.

138#### Borderless inline content

135139

136<img src="https://mintcdn.com/claude-ai/sLZLADaApRAVEV6C/images/mcp-apps/safe-area-borderless-mobile.png?fit=max&auto=format&n=sLZLADaApRAVEV6C&q=85&s=9936d8064beb2fc37e39b10ab1e727a9" alt="Safe area insets for borderless inline apps on mobile" width="1999" height="1857" data-path="images/mcp-apps/safe-area-borderless-mobile.png" />

140Set `_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.

137141

138Apps always fill the container width—there are no fixed breakpoints. Design responsively from 320px up to fullscreen using container queries and the hostContext CSS variables.

142In 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.

139143

140### Display modes

144<img src="https://mintcdn.com/claude-ai/sLZLADaApRAVEV6C/images/mcp-apps/safe-area-borderless-mobile.png?fit=max&auto=format&n=sLZLADaApRAVEV6C&q=85&s=9936d8064beb2fc37e39b10ab1e727a9" alt="Safe area insets for borderless inline apps on mobile" width="1999" height="1857" data-path="images/mcp-apps/safe-area-borderless-mobile.png" />

141145

142Declare which modes your app supports via `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`.

146### Declare supported display modes

143147

148Declare 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`.

149

144150### Content security policy

145151

146Declare external origins per `ui://` resource via `_meta.ui.csp`:

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

147153

148154```json theme={null}

149155{

from line 165

159165}

160166```

161167

162By default, all external origins are blocked. `frameDomains` (embedding third-party iframes) is currently restricted in Claude pending security review.

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

163169

164170### Viewport and layout

165171

166* Design for variable widths (320pt minimum, up to tablet)

172* Design for variable widths, from a 320pt minimum up to tablet

167173* Respect safe areas on notched devices

168* Full-width layouts — don't add side margins that waste mobile screen real estate

169* Content should reflow gracefully; avoid fixed-width layouts

174* Use full-width layouts, without side margins that waste mobile screen space

175* Let content reflow gracefully, and avoid fixed-width layouts

170176

171177<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/mobile-viewport-layout.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=d2244b6ff7e2d6c5e7b2c36fd2d901ed" alt="Viewport and layout do's and don'ts" width="1718" height="1238" data-path="images/mcp-apps/mobile-viewport-layout.png" />

172178

173179### Touch targets

174180

175* Minimum tap target: 44 x 44pt (per Apple HIG / Material guidelines)

176* Add sufficient spacing between interactive elements to prevent mis-taps

177* Prefer larger, thumb-friendly buttons over small text links

178* Place primary actions within natural thumb reach (lower portion of screen)

181* Minimum tap target of 44 x 44pt, per the Apple HIG and Material guidelines

182* Sufficient spacing between interactive elements to prevent mis-taps

183* Larger, thumb-friendly buttons rather than small text links

184* Primary actions within natural thumb reach, in the lower portion of the screen

179185

180186<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/mobile-touch-targets.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=95bd5b4393d85a67b74e894331d5f4b0" alt="Touch target do's and don'ts" width="1718" height="1238" data-path="images/mcp-apps/mobile-touch-targets.png" />

181187

182188### Scrolling and gestures

183189

184On mobile touch devices, the conversation view owns vertical scrolling. When your app is rendered inline, vertical pan gestures that start inside it are passed to the conversation scroll instead of to your content. This keeps a tall widget from trapping the user and is why inline apps should fit their content height rather than relying on an internal vertical scroll container—the host caps inline height and clips content that exceeds it.

190On 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.

185191

186Horizontal gestures (ex: carousels or panning a map) and taps work normally.

192Horizontal gestures, such as swiping a carousel or panning a map, and taps work normally.

187193

188If your app genuinely needs its own vertically scrollable viewport, request fullscreen presentation with `ui/request-display-mode` instead of rendering inline (see [Full screen](#full-screen)).

194If 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](#full-screen).

189195

190196### Transitions

191197

192198* Inline cards expand to fullscreen with a smooth transition

193* Provide a clear visual affordance for expansion (fullscreen button or tap-to-expand)

194* Fullscreen close returns to the conversation at the same scroll position

199* Provide a clear visual affordance for expansion, such as a fullscreen button or tap-to-expand

200* Closing fullscreen returns to the conversation at the same scroll position

195201

196202<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/mobile-transitions.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=343fe75a1428c1874568c10e02de9aa8" alt="Transition from inline card to full screen" width="1718" height="1222" data-path="images/mcp-apps/mobile-transitions.png" />

197203

198204### Dark mode

199205

200All views must support both light and dark themes. Use the host's style tokens — they automatically adapt. Never hardcode colors. Test both modes.

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

201207

202208<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/mobile-dark-mode.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=79df1abf42e75b052ad7c28ac71c4413" alt="Dark mode examples on mobile" width="1999" height="1315" data-path="images/mcp-apps/mobile-dark-mode.png" />

203209

204210### Loading states

205211

206Show skeleton screens while content loads. Match the layout structure of the final content so the transition feels seamless. Avoid spinners for inline content — skeletons feel more native.

212Show 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.

207213

208214<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/mobile-loading-states.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=9e7df0fa2294bbcbcc24bf079cbc5ff6" alt="Loading state examples on mobile" width="1718" height="1130" data-path="images/mcp-apps/mobile-loading-states.png" />

209215

210216## Visual design

211217

212MCP 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.

218MCP 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.

213219

214**Design guidance**

220### Color

215221

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

222Use 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.

217223

218224<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/color-tokens.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=173ce1948ae87b9e72b0854b5d27f4e1" alt="Color token examples for light and dark mode" width="1999" height="1863" data-path="images/mcp-apps/color-tokens.png" />

219225

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

226### Typography

221227

228Stick 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.

229

222230<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/typography.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=51ce152aab3d975ae57c5e5792dc6097" alt="Typography scale examples" width="1999" height="936" data-path="images/mcp-apps/typography.png" />

223231

224232<Note>

225 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. [Download and install the fonts from here](https://brand.anthropic.com/typography) for local development.

233 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](https://brand.anthropic.com/typography).

226234</Note>

227235

228**Borders.** Using a limited set of corner radii and thickness will keep your app feeling native to the surrounding UI.

236### Borders

229237

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

239

230240<img src="https://mintcdn.com/claude-ai/IPtAfld1XUBVOx8m/images/mcp-apps/borders.png?fit=max&auto=format&n=IPtAfld1XUBVOx8m&q=85&s=1755cc995399c9d6bf25a1405ff139f4" alt="Border radius examples" width="1999" height="201" data-path="images/mcp-apps/borders.png" />

231241

232**Icons.** Use monochromatic, outlined icons that match the host's icon color tokens. Icons should support understanding, not be essential to it.

242### Icons

233243

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

245

234246<img src="https://mintcdn.com/claude-ai/IXMfN0TT8kfXbN6T/images/mcp-apps/icons.png?fit=max&auto=format&n=IXMfN0TT8kfXbN6T&q=85&s=1454f1f3e5e13107cbe543e8d6d617df" alt="Icon style examples" width="1320" height="768" data-path="images/mcp-apps/icons.png" />

235247

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

248### Spacing

237249

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

251

252### Accessibility

253

254Your 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.

255

238256## Interaction patterns

239257

240### App vs. chat interactions

258Some 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.

241259

242Understanding the boundary between your app's interactions and Claude's conversational interface helps you build something that feels cohesive.

260### Decide between app and chat interactions

243261

244**Handle within your app:**

262Handle these within your app:

245263

246264* Direct manipulation like sliders, toggles, and selections

247265* Filtering or sorting data you're already displaying

248266* Expanding and collapsing content sections

249* Confirming or executing a prepared action ("Mark complete," "Send," "Save")

250* Interacting with visualizations like hover states or clicking data points

267* Confirming or executing a prepared action, such as "Mark complete," "Send," or "Save"

268* Interacting with visualizations, like hover states or clicking data points

251269

252Prefer controls with visible options (segmented buttons, toggle chips, inline tabs) over menus and dropdowns, which can conflict with the host container.

270Push these to the chat input:

253271

254**Push to chat input:**

255

256272* Text entry and freeform input

257273* Follow-up questions or requests for clarification

258274* Requests to modify, refine, or redo something

from line 277

261277

262278If 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.

263279

264### Start simple

280### Reveal complexity progressively

265281

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

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

267283

268### Visible controls over hidden menus

284### Prefer visible controls over hidden menus

269285

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

286Prefer 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.

271287

272## Accessibility

273

274Maintain high contrast standards (WCAG AA minimum). Support keyboard navigation and provide text alternatives for visual content. Test with assistive technologies. Your app must be usable by everyone.

275

276288## Style variables

277289

278MCP Apps automatically receive style variables from the host client. Reference these CSS custom properties to create interfaces that feel native to Claude.

290MCP 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](/docs/connectors/building/mcp-apps/transparent-theming) shows how to apply them at runtime.

279291

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

292### Color tokens

281293

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

295

282296| | Light mode | Dark mode |

283297| :--------------------------- | :-------------- | :-------------- |

284298| **Background** | | |

from line 337

323337| `color-ring-success` | `#437426 (50%)` | `#599130 (50%)` |

324338| `color-ring-warning` | `#805C1F (50%)` | `#A87829 (50%)` |

325339

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

340### Typography tokens

327341

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

343

328344| Family | |

329345| :----------------------------- | :----------------------------- |

330346| `font-sans` | `"Anthropic Sans, sans-serif"` |

from line 375

359375| `font-heading-2xl-line-height` | `1.1` |

360376| `font-heading-3xl-line-height` | `1` |

361377

362**Radius tokens** provide border radius values

378### Radius tokens

363379

380Radius tokens provide border radius values.

381

364382| Radius | |

365383| :------------------- | :------- |

366384| `border-radius-xs` | `4px` |

from line 388

370388| `border-radius-xl` | `12px` |

371389| `border-radius-full` | `9999px` |

372390

373**Border width tokens** provide width values

391### Border width tokens

374392

393Border width tokens provide border width values.

394

375395| | |

376396| :--------------------- | :------ |

377397| `border-width-regular` | `0.5px` |

378398

379**Shadow tokens** provide drop-shadow values

399### Shadow tokens

380400

401Shadow tokens provide drop-shadow values.

402

381403| | |

382404| :---------------- | :----------------------------------------------------------------------- |

383405| `shadow-hairline` | `0 1px 2px 0 rgba(0, 0, 0, 0.05)` |

from line 409

387409

388410### Example usage

389411

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

413

390414```css theme={null}

391415.my-app {

392416 background: var(--color-background-primary);

from line 433

409433 border-radius: var(--border-radius-md);

410434}

411435```

436

437## Related resources

438

439* [Blend your MCP App with Claude's theme](/docs/connectors/building/mcp-apps/transparent-theming): apply the style variables and keep your background transparent

440* [Set `ui.domain` for Claude](/docs/connectors/building/mcp-apps/getting-started#set-ui-domain-for-claude): compute the sandbox origin Claude expects for your app

441* [Submit a connector](/docs/connectors/building/submission#carousel-screenshots-for-mcp-apps): screenshot specifications for listing an MCP App in the directory

412442