How to Create Adaptive Cards with the Adaptive Cards Designer (Step-by-Step)

Adaptive Cards are the small forms and summaries that bots and agents show inside Microsoft Teams, Copilot and website chats. This guide shows you how to create Adaptive Cards in Microsoft’s new Adaptive Cards Designer, step by step, without writing any code. You’ll build a real feedback card, test it, and copy JSON that works in the app you’re building for.

What is an Adaptive Card?

An Adaptive Card is a piece of user interface described in JSON, a plain-text data format. You describe the card once. The app that shows it, called the host, draws it with its own fonts, colors and buttons, so the same card fits in naturally in Teams, in Copilot or in a chat window on a website, in light or dark mode.

A card can show text, images and facts, and it can ask questions with text boxes, choices, dates and toggles. A button on the card sends the answers back to the bot or app that sent the card.

Every card states the schema version it needs, and hosts support different versions. Microsoft lists them in Adaptive Cards for agent design:

If a card asks for a newer version than the host supports, the host shows the card’s fallback text instead of the card (AdaptiveCard version). Step 12 shows how to get this right, because the designer always writes version 1.6.

What you’ll have at the end

A feedback card with a heading, a short description, a required rating question, a comments box and a Send feedback button. You’ll have tested it at four widths and in dark mode, and you’ll have its JSON, ready to paste into a bot, an agent or a flow.

Prerequisites

• A web browser on a computer. The designer has several panes side by side, so a big screen helps.
• Nothing else. The designer is free, and you don’t need an account, a sign-in or any installs.

Step 1: Open the Adaptive Cards Designer

Open adaptivecards.microsoft.com/designer.html. This is Microsoft’s current designer. The old address on adaptivecards.io now ends on a “page not found” page.

The designer has six areas:

• Toolbox (left): every element you can add, grouped into Elements, Inputs, Charts and Actions.
• Card canvas (middle): your card as people will see it. Select an element here to edit it.
• Card structure: the card as a tree. Use it to select the card itself, or an element that’s hard to click.
• Properties: the settings of whatever is selected.
• Card payload (bottom): the card’s JSON, which updates as you work.
• Validation and Sample data (bottom right): problems the designer finds, and test data for card templates.

Across the top is the toolbar: New card, Import, Export, a device width picker (it shows Standard), Undo, Redo, Copy card payload and Preview. The moon button at the far right switches to the dark theme.

Step 2: Start a new, empty card

Select New card. The Pick a sample as a starting point dialog opens with Microsoft’s sample cards, which are a good source of ideas later. For this guide, select Empty card.

Step 3: Add a title

In the Toolbox, find TextBlock near the bottom of Elements. Drag it onto the empty card and let go. A TextBlock with the text New TextBlock appears. It’s selected, so Properties shows its settings and Card payload shows its JSON.

Now set its properties:

1. In Text, replace New TextBlock with Share your feedback.
2. Check that Wrap is ticked. Wrapped text moves to the next line instead of being cut off on narrow screens.
3. Under Style, open Base style and choose Heading.

The Heading style does more than make the text bigger. It marks the text as a heading, so screen readers announce it as one (TextBlock style). It needs version 1.5 or later.

Step 4: Add a short description

Keep the title selected and double-click TextBlock in the Toolbox. Double-clicking adds the new element right below the one you’ve selected, which is quicker than dragging. In Text, type Tell us how the workshop went. Your answers help us plan the next one. Wrap is already ticked for new TextBlocks.

Step 5: Add a required rating question

With the description selected, double-click Input.ChoiceSet under Inputs. A choice set lets people pick from a list. It arrives with two sample choices and some sample text. Set it up like this:

1. Id: rating. Every input needs an Id. It’s the name the answer arrives under when someone submits the card (Input.ChoiceSet).
2. Label: How would you rate the workshop? Use the Label, not a separate TextBlock, so screen readers connect the question to its choices (accessibility tips).
3. Placeholder: delete the sample text. A placeholder only shows in the compact (drop-down) style.
4. Style: Expanded, which shows every choice as a radio button.
5. Under Choices, change the two Name and Value pairs to Excellent / excellent and Good / good. Select + (Add a new choice) and add Needs improvement / needs-improvement. The name is what people see, and the value is what your bot receives.
6. Under Validation, tick Required, then type Choose a rating. in Error message. The Error message box stays greyed out until Required is ticked.

Step 6: Add a comments box

Double-click Input.Text in the Toolbox, then set:

• Id: comments
• Multiline: ticked, so people can write more than one line
• Label: What should we improve?
• Placeholder: Type your suggestions, the grey hint shown in the empty box

Leave Required unticked, so suggestions stay optional.

Step 7: Add the Send feedback button

Double-click Action.Submit under Actions. Buttons go in the action bar at the bottom of the card. In Title, type Send feedback.

When someone selects the button, Action.Submit gathers the card’s inputs (rating and comments) and hands them to the host app, which decides what to do with them (Action.Submit). For a bot, that means the answers arrive at your bot. The Toolbox also has Action.Execute, the universal action for Teams and Outlook, but Bot Framework Web Chat doesn’t support it.

Step 8: Clear the Validation warning

Look at the Validation pane at the bottom right. Since the start it has shown one problem: The “speak” property should always be set as it provides a way for screen readers to describe the card to an end-user that relies on assistive technologies.

To fix it, select AdaptiveCard at the top of Card structure. That selects the card itself. In Properties, type a short summary of the card in Speak, for example Share your feedback about the workshop. Choose a rating, add any suggestions, then send. The warning disappears.

Tip: the same pane has Fallback text. A host shows it instead of the card when it can’t display the card’s version, so a sentence such as “Update your app to see this feedback form” is worth adding.

Step 9: Test the card in Preview

Select Preview in the toolbar. Preview your card at all widths shows the card at four widths: Very narrow, Narrow, Standard and Wide. Hosts show cards at different widths, from phones to wide desktop windows, so check that nothing is cut off or squashed.

You can use the preview cards. In the Very narrow card, select Send feedback without choosing a rating. The card shows your error message in red:

Now choose Good, type a suggestion and select Send feedback again. The error goes away. The designer has no bot to send the answers to, so nothing else happens. In Teams, this is when your bot receives them.

Select Close to leave Preview.

Step 10: Check the card in dark mode

Teams can run in dark mode, so check your card in it too. Select the moon button at the right end of the toolbar (Switch to dark theme) and make sure every part of the card is still easy to read. Select it again (Switch to light theme) to go back.

Step 11: Copy or export the card JSON

When the card looks right, take its JSON out of the designer:

• Copy card payload copies the JSON to your clipboard, ready to paste into your code, your agent or your flow.
• Export saves it as a file named adaptive-card.json.

Here’s the JSON the designer gave for the feedback card:

{
    "type": "AdaptiveCard",
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.6",
    "body": [
        {
            "type": "TextBlock",
            "text": "Share your feedback",
            "wrap": true,
            "style": "heading"
        },
        {
            "type": "TextBlock",
            "text": "Tell us how the workshop went. Your answers help us plan the next one.",
            "wrap": true
        },
        {
            "type": "Input.ChoiceSet",
            "label": "How would you rate the workshop?",
            "choices": [
                {
                    "title": "Excellent",
                    "value": "excellent"
                },
                {
                    "title": "Good",
                    "value": "good"
                },
                {
                    "title": "Needs improvement",
                    "value": "needs-improvement"
                }
            ],
            "id": "rating",
            "style": "expanded",
            "isRequired": true,
            "errorMessage": "Choose a rating."
        },
        {
            "type": "Input.Text",
            "label": "What should we improve?",
            "placeholder": "Type your suggestions",
            "id": "comments",
            "isMultiline": true
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Send feedback"
        }
    ],
    "speak": "Share your feedback about the workshop. Choose a rating, add any suggestions, then send."
}

Every step shows up in it: body holds the two TextBlocks and the two inputs, actions holds the button, and speak is the summary for screen readers.

Step 12: Set the version for your host

Look at line 4: "version": "1.6". The designer always writes 1.6, the newest schema version. That’s right for Bot Framework Web Chat, but Teams, Copilot Chat and Dynamics 365 live chat support up to 1.5, and they show the fallback text instead of a card that asks for 1.6.

The designer has no setting for this. Microsoft’s design guidance mentions a Target version option, but the designer at adaptivecards.microsoft.com doesn’t show one. Typing the version into the Card payload editor doesn’t stick either. Here the editor shows 1.5 after the change:

As soon as the card changed, the version went back to 1.6. Copy card payload gave 1.6 in every test, even straight after 1.5 was typed in, and the exported file said 1.6 too. The full investigation, with every test and what Microsoft’s documentation says, is in Fixed: Adaptive Cards Designer Changes the Card Version to 1.6.

So set the version in your copy of the JSON. For Teams or Copilot, change line 4 to:

"version": "1.5",

Everything in this card works in 1.5. The newest feature it uses, the Heading style, arrived in 1.5 itself. If you add more elements from the Toolbox later, check the version each one needs on its page in the Adaptive Cards documentation.

Where to Use Your Card

• A Teams bot or agent: send the card from your code, or build the same card with the Teams SDK card builders for C#, TypeScript and Python (Building Adaptive Cards).
• Copilot Studio: paste the JSON into an Adaptive Card node. Copilot Studio supports versions up to 1.6, but each channel has its own limit (Use Adaptive Cards in Copilot Studio).
• More examples: browse the other Adaptive Card posts on JD Bots.

Clean Up

There’s nothing to clean up. The designer runs in your browser and doesn’t create anything in any account. Use Export if you want to keep a copy of your card as a file.

Common Mistakes

Troubleshooting

FAQ

Is the Adaptive Cards Designer free?

Yes. It runs in your browser, and you don’t need an account or a sign-in.

Which version should my card use?

The newest version your host supports: 1.5 for Teams, Copilot Chat and Dynamics 365 live chat, 1.6 for Bot Framework Web Chat, and 1.0 to 1.2 for Outlook Actionable Messages (schema and host compatibility).

Can I start from a ready-made card?

Yes. New card opens Microsoft’s sample cards. Pick one and change it to suit you. Microsoft keeps the samples, with instructions, in the Microsoft Teams Adaptive Card Samples repository.

What are Badge, Carousel, Icon and the charts in the Toolbox?

Newer elements that Microsoft documents on the Adaptive Cards site for Teams and Copilot scenarios. Check each element’s page there before you use it in another host.

Do I have to use the designer?

No. A card is just JSON, so you can write it by hand, or build it in code with the Teams SDK card builders. The designer lets you see the card while you build it.

Conclusion

You created an Adaptive Card in the Adaptive Cards Designer: a heading, a description, a required rating, a comments box and a Send feedback button. You tested it at every width and in dark mode, cleared the Validation warning, and took out its JSON with the right version for your host. Next, send it from your bot or agent, or open New card and adapt one of Microsoft’s samples.

Additional Resources

• Adaptive Cards documentation (Microsoft)
• Adaptive Cards Designer
• Adaptive Cards for agent design (Microsoft Learn)
• AdaptiveCard element reference (Microsoft Learn)
• TextBlock element reference (Microsoft Learn)
• Input.ChoiceSet reference (Microsoft Learn)
• Action.Submit reference (Microsoft Learn)
• Universal Action Model (Microsoft Learn)
• Accessibility tips for Adaptive Cards (Microsoft Learn)
• Use Adaptive Cards in Copilot Studio (Microsoft Learn)
• Building Adaptive Cards with the Teams SDK (Microsoft Learn)
• Microsoft Teams Adaptive Card Samples (GitHub)