ChatGPT App UI Guidelines: Display Modes, Design System, and Visual Rules
Your ChatGPT App lives inside someone else's product. Learn the five display modes, the Apps SDK UI design system, color and typography rules, and accessibility requirements.
Building a ChatGPT App means your UI lives inside someone else's product. Your app doesn't get its own window, its own navigation, or its own design system. It renders inside the ChatGPT conversation — alongside the AI's text responses, other apps, and the chat input.
This constraint is actually an advantage. When your app follows ChatGPT's UI guidelines, it feels native. Users don't have to learn a new interface. The experience is seamless.
But it means you need to understand the rules. This guide covers the display modes, design system, visual guidelines, and accessibility requirements for ChatGPT Apps.
Display Modes
ChatGPT Apps can render in five different display modes. The mode you choose depends on the complexity of your content and how much screen space it needs.
Inline
The default mode. Inline content renders directly in the chat thread, flowing with the conversation like a message. Use this for simple text responses, status updates, confirmations, and lightweight content that doesn't need interactive UI.
Inline content has no border or container — it blends with the conversation. Keep it concise. If your content needs structure, interaction, or visual hierarchy, use a card or fullscreen mode instead.
Inline Cards
A compact widget embedded in the conversation thread. Cards have a defined boundary, a focused purpose, and light interactivity. They're the right choice for showing a single item with details (a product, a flight, a listing), a summary with one or two actions (confirm booking, view details), or a status display with minimal interaction (order status, delivery tracking).
Cards should focus on a single purpose. Don't try to pack an entire workflow into a card. If the user needs to scroll, filter, or navigate between views, you need a larger display mode.
Carousels
A horizontal swipeable list of 3 to 8 similar items. Carousels are ideal for search results — hotel options, product listings, course recommendations — where the user needs to compare several items of the same type.
Each carousel item should have a consistent structure: image, title, key details, and an action. Don't mix different content types in the same carousel. All items should be the same kind of thing (all hotels, all products, all flights).
Keep carousels between 3 and 8 items. Fewer than 3 makes the swipe gesture feel unnecessary. More than 8 overwhelms the user and makes comparison difficult.
Fullscreen
A richer interactive experience that takes over the main content area while keeping the chat composer visible at the bottom. Use fullscreen for complex interactions: multi-step forms, detailed product pages, maps with interactive markers, document editors, or configuration wizards.
Fullscreen mode gives you the most space and the most freedom, but it also demands the most from your design. The user should always know how to return to the conversation (the chat composer stays visible), and the content should justify the larger format.
Picture-in-Picture
A floating window that persists as the user continues the conversation. Picture-in-Picture is designed for parallel activities: games, quizzes, timers, music players, or any experience that benefits from running alongside the ongoing chat.
Use this sparingly. A floating window adds visual complexity to the conversation, and not every app justifies persistent screen presence. The best use cases are genuinely concurrent — the user interacts with your app and the conversation at the same time.
The Design System: Apps SDK UI
OpenAI provides a component library called the Apps SDK UI. It includes pre-built, reusable components that match ChatGPT's native appearance: buttons, cards, lists, inputs, toggles, tabs, modals, and more.
Using the SDK UI components is strongly recommended. They handle responsive layout, platform-specific styling (iOS vs. Android vs. web), dark mode, and accessibility out of the box. Building custom components from scratch means reimplementing all of this yourself — and risking an app that looks out of place.
The SDK UI also provides design tokens for spacing, typography, and color, so your custom elements can match the system look and feel even when you're building beyond the provided components.
Visual Guidelines
Color
ChatGPT Apps use a system color palette for text, icons, backgrounds, and borders. This palette adapts automatically to light and dark mode.
Your brand colors should be used sparingly — on primary action buttons, badges, and small accent elements. Don't paint entire sections in your brand colors. The goal is for your app to feel like part of ChatGPT, with your brand identity expressed through subtle accents rather than wholesale theming.
The system palette provides semantic colors: primary text, secondary text, dividers, backgrounds, and interactive states (hover, pressed, disabled). Use these for all structural UI elements.
Typography
ChatGPT Apps use platform system fonts: SF Pro on iOS, Roboto on Android, and the system sans-serif on web. Custom fonts are not supported.
This is intentional. System fonts load instantly (no web font requests), render consistently across devices, and match the native platform look. Your app's text will feel like it belongs on the user's device.
Follow the type scale provided by the SDK UI for headings, body text, captions, and labels. Don't create custom font sizes — the scale is designed for readability at every level and adapts to the user's accessibility settings.
Spacing and Layout
The SDK UI uses a consistent spacing grid. Padding, margins, and gaps follow a standard scale that keeps elements aligned and visually balanced.
Corner radii are standardized across components. Use the provided radius tokens rather than custom values. Consistent rounding makes your app feel polished and native.
For layout, prefer vertical stacking for mobile-first design. Horizontal layouts work in carousels and comparison views, but most card and fullscreen content should flow vertically.
Icons and Images
Icons should be simple, monochrome, and outlined — matching the style used throughout ChatGPT. Avoid filled icons, multicolor icons, or icons with heavy visual weight. The SDK UI provides a set of standard icons; use these where possible.
Images should maintain proper aspect ratios. Don't stretch or distort images to fit containers. Use standard aspect ratios (1:1 for thumbnails, 16:9 for banners, 4:3 for product images) and crop or letterbox as needed.
Every meaningful image needs alt text. Decorative images (backgrounds, separators) can have empty alt attributes, but any image that conveys information — product photos, maps, charts — must have a descriptive alt text for screen readers.
Accessibility Requirements
ChatGPT Apps must meet WCAG AA accessibility standards. This isn't optional — it's a requirement for submission.
Contrast. All text and interactive elements must meet WCAG AA minimum contrast ratios: 4.5:1 for normal text, 3:1 for large text and UI components. The system color palette is designed to meet these ratios, so use it consistently.
Responsive text sizing. Your app must respect the user's text size preferences. If a user has increased their system font size for accessibility, your app's text should scale accordingly. Using the SDK UI type scale handles this automatically.
Interactive element labeling. Every button, link, input, and interactive element must have an accessible label. If the element has visible text, that's the label. If it's icon-only, provide an aria-label. Screen reader users should be able to understand every action available in your app.
Focus management. Keyboard and assistive technology users must be able to navigate your app's interactive elements in a logical order. Ensure that focus states are visible and that tab order follows the visual layout.
Common Mistakes to Avoid
Overloading cards. A card should do one thing. If your card has tabs, nested scrolling, and multiple CTAs, it should be a fullscreen view instead.
Ignoring dark mode. If you hardcode colors instead of using design tokens, your app will look broken in dark mode. Use the system palette and your colors adapt automatically.
Custom fonts. They won't load. Use system fonts and the provided type scale.
Too many carousel items. Eight is the maximum. If you have more results, let the user refine their search rather than swiping through twenty cards.
Missing loading states. When your backend takes time to respond, the widget should show a loading indicator. An empty widget with no feedback feels broken.
Testing and Measuring Your UI
Following the guidelines gets your app approved. Measuring what happens after launch tells you whether the UI actually works for users.
Are users interacting with your cards or scrolling past them? Do they complete the full carousel or stop at the first item? Where do they drop off in fullscreen workflows? Which CTA buttons get clicked and which are ignored?
These questions require analytics built for the ChatGPT App interaction model. Yavio is an open-source platform that captures widget interactions, tool calls, and user journeys — giving you the data to iterate on your UI decisions with evidence, not guesswork.
Yavio is open source (MIT). Try Yavio Cloud free or self-host with Docker.