/design-card

Design a Doist Card UI for a Todoist extension — interactively build the layout, generate both raw card JSON and TypeScript code using @doist/ui-extensions-core, and preview the structure.

Load the ui-extensions skill before designing. Use references/doist-cards.md as the single source of truth for all element types, properties, and constraints.

Step 1: Understand the card's purpose

Ask in a single message:

• "What should this card do?" — offer common patterns:

  • Form — collect user input and submit
  • Information display — show data with formatting
  • Action confirmation — confirm before performing an action
  • Multi-step wizard — sequential screens with back/next
  • List/table display — show items in a structured layout

• "What surface is this card for?" — context menu, composer, or settings

Step 2: Design the card layout

Based on the purpose, design the card structure. Apply these Doist Card design principles:

Layout rules:

• Use TextBlock with size: "large" and weight: "bolder" for headers
• Use separator: true to visually divide sections
• Use ColumnSet with Column elements for side-by-side layout (width: "auto" or "stretch")
• Use Container to group related elements with optional backgroundImage or minHeight
• Set wrap: true on TextBlocks that may contain long text

Input patterns:

• Every input element MUST have a unique id — this is how action.inputs maps values
• Use label property on inputs for accessible form labels
• Use isRequired: true and errorMessage for validation
• Use placeholder text to guide users
• Use Input.ChoiceSet with style: "compact" for dropdowns, style: "expanded" for radio buttons
• Use Input.Text with rows: 3+ for multiline and inputStyle for semantic types (email, url, tel)

Action patterns:

• Place primary action first in the actions array
• Use style: "positive" for the primary action button
• Use style: "destructive" for dangerous actions (delete, remove)
• Use Action.Submit with data to pass identifiers back to the server
• Use Action.OpenUrl for external links
• Use Action.Clipboard for copy-to-clipboard
• Set associatedInputs: "auto" on submit actions to include form data

Step 3: Generate the raw card JSON

Output the complete card JSON. Every card must include these required root properties:

{
  "type": "AdaptiveCard",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "doistCardVersion": "0.6",
  "version": "1.4",
  "body": [],
  "actions": []
}

Set autoFocusId to the first input element's id if the card has inputs.

Validate every element against the schema in references/doist-cards.md:

• TextBlock: type, text required; size, weight, color, isSubtle, wrap, horizontalAlignment optional
• Image: type, url required; width, height, altText, aspectRatio, size, selectAction optional
• Input.Text: type, id required; placeholder, label, value, isRequired, errorMessage, rows, inputStyle, regex, inlineAction optional
• Input.ChoiceSet: type, id, choices required; label, value, isRequired, isSearchable, style, orientation, selectAction optional
• Input.Toggle: type, id, title required; value, label, wrap, isRequired, errorMessage, selectAction optional
• Input.Date: type, id required; label, value, min, max, isRequired, errorMessage optional
• Input.Time: type, id required; label, value, isRequired, errorMessage optional
• Container: type required; items, selectAction, minHeight, backgroundImage, verticalContentAlignment, bleed optional
• ColumnSet: type required; columns, horizontalAlignment optional
• Column: type required; items, width, verticalContentAlignment, selectAction optional
• ActionSet: type, actions required; horizontalAlignment optional
• RichTextBlock: type, inlines required; horizontalAlignment optional

Step 4: Generate TypeScript code

Generate the equivalent TypeScript code that builds the same card programmatically. Import from @doist/ui-extensions-core where types are available, otherwise use typed object literals:

import type { DoistCardResponse } from '../types'

export function buildMyCard(data?: Record<string, unknown>): DoistCardResponse {
  return {
    card: {
      type: 'AdaptiveCard',
      $schema: 'http://adaptivecards.io/schemas/adaptive-card.json',
      doistCardVersion: '0.6',
      version: '1.4',
      body: [
        // elements here
      ],
      actions: [
        // actions here
      ],
    },
  }
}

Make the card function accept parameters so it can be dynamic (e.g., pre-filling input values, showing different content based on data).

Step 5: Preview the card structure

Display an ASCII preview of the card layout:

+----------------------------------------+
| [Header Text]                    large |
|----------------------------------------|
| [Description text wraps across the     |
| full width of the card]               |
|----------------------------------------|
| Label:                                 |
| [________________________] text input  |
|                                        |
| Option:                                |
| ( ) Choice A                           |
| (*) Choice B                           |
| ( ) Choice C                           |
|----------------------------------------|
|              [Cancel]  [*Submit*]       |
+----------------------------------------+

Annotate the preview with element types so the mapping is clear.

Step 6: Write files

If the user has an existing extension project:

• Write the card builder to src/cards/[card-name].ts
• Write the JSON to src/cards/[card-name].json (useful for testing/debugging)
• Update any existing handler to import and use the new card

If standalone:

• Write both files to the current directory
• Explain how to integrate the card into a handler