Design guidelines for Connected Apps

Guidelines for designing Connected Apps across Google products like the Gemini app and Search.

Overview

An MCP connected app enables a user to connect a large language model (LLM) on any applicable Google product to read and write your app's data. Because your app shares the conversational context, users can complete tasks effortlessly without switching tabs or apps. Review these guidelines to ensure your connected app is approved to go live across applicable Google products.

Create Connected Apps

When to use Connected Apps

Build Connected Apps for the following scenarios:

  • Tasks with a clear beginning and end, such as placing an order, making a booking, or locking in a schedule.
  • Actionable information that users can apply immediately.
  • Natural conversational workflows, like analyzing data, reviewing documents, or coordinating a project.
  • Core functionality that meaningfully expands what the AI can accomplish.

Your tools should ideally help users complete actions with AI's help, such as making a booking or writing a document. Focus on complex actions where the foundational model can simplify the process.

What to avoid

When designing Connected Apps, avoid the following patterns:

  • Dropdowns, context menus, and popover panels: These elements get clipped by container boundaries or clash with the host surface UI.
  • Nested scrolling: Avoid scrolling within a scrolling container.
  • Multi-layered views: Do not use breadcrumbs, or drill-in interfaces.
  • Lengthy processes: Avoid flows that exceed the scope of the display mode.
  • Standalone web apps: Do not replicate full web apps.
  • Under-delivering on the promise: When users see Connected Apps loading, they expect a baseline level of utility. Don't create an app just to render trivial functionality, such as a single button.
  • Automatic redirects: Do not launch external websites or native apps automatically without an explicit user click on a clearly marked external-link.

Container & layout

Host containers frame your connected app alongside model responses. These containers provide partner attribution, consistent borders, and responsive sizing across applicable Google products.

Container anatomy

  1. Header: Displays the partner's icon and official name.
  2. Content: Appears as an inline card or horizontal carousel.
  3. Response text pairing: Display modes always accompany model response text. Design around this combined layout.
  4. UI Style: Inherits host container styles across applicable Google products.

Responsive behavior

Connected Apps render across varying container widths and device viewports. Avoid fixed dimensions:

  • Reflow horizontally: Use flexible layouts that adapt cleanly between compact sidebars, mobile screens, and wide desktop feeds without horizontal clipping.
  • Fit content vertically: Let inline containers grow to fit their content up to a comfortable reading height. Never pad cards with fixed empty space or trap content in a vertical scrollbar.
  • Respect device inputs: Support native touch gestures and safe areas on mobile, and hover states on desktop.

What to avoid

  • Avoid double padding: Connected Apps include a default internal padding to meet system standards. Remove extra padding from internal content to avoid unintended spacing.
  • Avoid unbalanced corner radius: Keep internal shapes proportional to the host container's corner radius to avoid overly sharp or rounded corners.
  • Avoid adding your own stroke: Containers include system-defined border styling by default. Do not apply extra borders or strokes around internal components.

Display modes

Display modes define how your extension surfaces visual UI directly alongside applicable Google products' responses. Use one of two primary display modes: Inline Card or Fullscreen.

Inline cards

Inline cards are lightweight, single-purpose components embedded directly in the response flow. Use inline cards for quick confirmations, structured data inspection, or single-step actions.

When to use inline cards

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

Content density and truncation guardrails

  • Title clamping: Limit card titles to 1–2 lines with ellipsis truncation so headers never push actions out of view.
  • Body & metadata limits: Cap supporting copy at 2–3 lines and limit per-item metadata to 2–3 scannable attributes.
  • Concise CTA copy: Use verb-first action labels (for example, "Book table" or "Confirm order") and limit the card footer to at most 1 primary CTA and 1 optional secondary action.

Carousel definition: Carousels should contain between 3 and 8 cards to justify scrolling without causing fatigue, with all cards maintaining identical height and width dimensions. Clamp card titles to 1–2 lines and cap metadata at 2–3 fields per card.

Interactions for inline cards

Inline cards should focus on quick, direct actions that keep users in the conversation.

  • Inline actions: Allow users to perform actions directly within the card, such as editing text, adding items, or checking off tasks.
  • State updates: Reflect complex user actions directly in the thread instead of inside the entity. For example, when a user books a stay, generate an updated card displaying the "Reserved" label in the conversation.
  • Hover mechanics: Navigation icon buttons remain hidden by default and reveal on container hover.
  • Overflow scrims: Start state displays right edge scrim, Middle displays both edges, and End displays left edge.
  • Touch gestures: Uses native horizontal swipe with gap between carousel cards.
  • Card peeking: Start state uses a left padding, Middle uses don't have any, and End uses a right padding.

What to avoid for inline cards

  • Avoid nested scrolling: Never include an internal vertical scrollbar.
  • Avoid multi-view drilling: Do not use breadcrumbs, multi-tab views, and multi-step drill-downs are prohibited inside an inline card. Move complex flows to fullscreen.
  • Avoid visible controls over menus: Do not use dropdowns, popovers, and contextual menus, as they cause container clipping and z-index collisions.
  • Avoid duplicate inputs: Do not place another input inside the card, since applicable Google products already have the input.
  • Avoid internal vertical scrolling: Don't place scrollable containers inside cards; it cause scroll-trapping and degrade mobile navigation.
  • Avoid popovers: As they cover content and clutter the UI, don't use tooltips or popover overlays to reveal key details.
  • Avoid dropdown menus: Don't bury actions inside dropdown selectors. Expose primary actions as explicit buttons.
  • Avoid hide scroll overflow in carousels: Ensure the adjacent card peaks into view so users know more content is available to scroll.
  • Avoid custom error components: Do not use custom error states; the host UI will provide a standard error component consistently across the entire experience.
  • Avoid using modals: MCP Apps do not support modals; if you need more space, provide an option to switch to full screen mode instead.

Full screen

Use the full screen mode as an immersive canvas for rich, multi-step tasks or data-heavy workflows that cannot be contained within an inline card.

When to use full screen

  • Browsing dense content like real estate listings, menus, or interactive maps.
  • Complex workflows, such as editing canvases or diagrams that need dedicated space beyond an inline card.
  • Data and analysis, such as viewing rich dashboards, data visualizations, and detailed analytic tools requiring focused attention.

Layout and interactions for full screen

  1. Header: Display a system provided header bar with app attribution and actions.
  2. Safe area insets: Maintain clear spacing beneath the header bar to prevent content overlap.
  3. Close and open: Display a button to open in full screen, and a close button in the header of the full screen view.

What to avoid for full screen

  • Avoid replicating your native app: Use full screen to deepen engagement on focused, multi-step tasks.
  • Avoid duplicate inputs: Since applicable Google products already have the input, partners should not place another input inside the view.
  • Avoid floating panels: Do not use floating modals or floating draggable inspector toolbars, as they clutter the interface and collide with host surface overlays.
  • Avoid overlapping safe areas: Keep interactive elements clear of the host surface toolbar and system indicators, such as status bars and the home bar.

Interaction guidelines

How users manipulate content inside a connected app, how actions synchronize with the host conversation, and when to hand off complex workflows to an external app or website.

App UI versus conversation division of labor

Design your connected app and conversational prompts as complementary layers:

  • Use the connected app UI for direct manipulation: Use the UI for spatial browsing such as panning a map, comparing structured options, multi-field form controls, and visual selections where typing text prompts would be tedious or ambiguous.
  • Use the host conversation for open-ended intent: Use the conversation for natural-language follow-ups, multi-step synthesis, and broad exploratory queries.

Progressive disclosure

  • Progressive disclosure: Start with the most compact display mode that answers the user's need (Inline Card or Carousel), revealing secondary details on demand (Show more) and escalating to full screen only when deep exploration is required.
  • Visible controls over hidden menus: Expose primary actions as explicit buttons or toggles rather than burying them inside hover-only toolbars, right-click context menus, or long-press gestures that fail on mobile viewports.

External handoffs and linking out

Some capabilities exceed the scope of an embedded iframe or require native OS and hardware features. When to link out to your app or site:

  • Native OS or hardware-dependent features (for example, live navigation, camera or sensor capture, or continuous background audio and location tracking).
  • Regulated or security-sensitive flows (for example, final payment checkout or identity verification).
  • Deep workspaces beyond full screen (for example, full-featured authoring suites or complex enterprise dashboards).

Designing the handoff

  • Show a clear external-link affordance: Always pair external handoff buttons with an explicit launch indicator (such as the open_in_new icon) and a destination-specific label (for example, "Open in Google Maps").
  • Deep-link with preserved context: Pass all parameters established in the conversation into the deep-link URL via the host's external-link API (openLink) so users never have to re-enter their selections after switching apps.

What to avoid

  • Avoid automatic redirects: Never navigate users out of the host surface automatically. Leaving the host surface must always require an explicit user click.
  • Avoid "teaser" or link-only cards: Do not build a connected app whose sole purpose is to render a static banner or button that bounces users out to your website.
  • Avoid unannounced context switches: Never style an external link identically to an in-card action without indicating that it opens an external app or browser tab.

Visual guidelines

Applicable Google products prioritize lightweight, neutral UI elements and softened contrast to reduce cognitive load.

Visual principles

Applies core design principles to govern visual density and aesthetics across Connected Apps:

  • Lighter and minimal UI: Reduce strokes and container elements to maintain clean visual density.
  • Neutral color balance: Prioritize neutral gray shades, reserving accent colors for primary CTAs.
  • Elevation: Apply soft surface fills, confining drop shadows exclusively to full screen mode and carousel navigation controls.
  • Style inheritance: Apply colors, typography, and corner radii so apps feel native across every applicable Google product.

Color

Applicable Google products organize color into two functional groups: System colors for structural layout and Accent colors for primary brand moments. Relying on these semantic roles ensures clear visual hierarchy and automatic theme adaptation across products.

System color roles

Map structural colors to consistent UI roles across Connected Apps:

  • Background surfaces: Use host-provided neutral surface colors for card containers and nested groupings. Avoid overriding container backgrounds with custom solid fills, gradients, or patterns.
  • Text & content hierarchy: Use primary content colors for titles and key values, secondary muted tones for body copy and supporting labels, and semantic status colors (positive, warning, critical) for operational metadata.
  • Borders & dividers: Use subtle system outline colors for structural borders and dividers to separate content without adding heavy visual weight.
  • Primary accent: Use the system accent or your partner brand color for primary call-to-action buttons.

Partner brand application areas

Guide partner brand color placement across Connected Apps:

  • Recommended: Apply brand colors selectively to primary CTA buttons, logos, and key highlight moments.
  • Not recommended: Avoid applying brand colors to card backgrounds, body text, titles, structural borders, or secondary interactive controls.

Theming & light/dark mode

Connected Apps must feel cohesive across both Light and Dark themes as well as dynamic surface palettes:

  • Use semantic tokens over static hex values: Bind surfaces, text, and borders to the host surface's semantic color tokens so your interface adapts automatically between Light and Dark modes.
  • Adapt brand accents for both themes: Ensure your brand accent color maintains accessible contrast in both themes—providing a slightly lighter or desaturated variant in Dark mode if your default brand color appears too dark or overly vibrant against dark surfaces.
  • Use theme-ready media and logos: Export icons, logos, and illustrations with transparent backgrounds so they don't display stark white bounding boxes in Dark mode.

Icons

Connected Apps use clean, outlined iconography to maintain visual harmony and scannability across applicable Google products.

Icon style & sizing

Guide icon geometry, color, and size thresholds across Connected Apps:

  • Outlined, rounded geometry: Use monochrome outlined icons with uniform stroke weights and rounded caps (such as Google Material Symbols Outlined), or a harmonized partner icon set that matches the host interface's visual weight.
  • Neutral tinting: Tint functional UI icons using primary or secondary content colors rather than brand colors so icons support the reading hierarchy without competing with primary CTAs.
  • Sizing boundaries: Keep icons between 16px (for compact inline metadata) and 32px (for prominent card or feature headers) to preserve legibility and proportion across viewports.

Accessibility

Applicable Google products enforce accessibility compliance aligned with WCAG 2.1 AA and Material Design 3 standards.

Core accessibility pillars

  • Color contrast: Enforce a minimum 4.5:1 WCAG AA contrast ratio for text against surface backgrounds across Light and Dark themes.
  • Minimum text size: Enforces 13pt type size.
  • Touch targets: Enforce a minimum 48x48px for mobile and 24x24px for desktop interactive target area for controls.
  • Keyboard focus: Preserve a visible focus indicator ring and a logical tab traversal order across interactive card components.
  • Dynamic media alt text: Provide descriptive alt text for all partner-supplied images, thumbnails, map pins, and data visualizations.
  • Live state announcements (aria-live): Use aria-live="polite" regions to announce dynamic in-card state changes such as expanding "Show more" rows, filtering items, or completing an inline action.
  • Reduced motion (prefers-reduced-motion): Respect the user's prefers-reduced-motion media query by replacing skeleton shimmer effects and carousel slide transitions with static or instant state changes.
  • Content overflow and truncation: Clamp long text blocks to 3–5 lines with an accessible "Read more" action to prevent layout breaking and maintain readability.