> ## Documentation Index > Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # UI Resources Guide > Design patterns, accessibility, and testing for UI Resource templates This guide covers design principles, common patterns, and testing strategies for UI Resource templates. For template syntax and configuration, see the [UI Resources reference](../features/ui-resources). ## When to Use UI Resources UI Resources turn plain text responses into visual components. Use them when: | Scenario | Why it helps | | -------------------- | -------------------------------------------------------- | | **Product displays** | Images, prices, and buttons are more effective than text | | **Status tracking** | Visual progress indicators are clearer than text status | | **Data tables** | Structured data is easier to scan in table format | | **Action options** | Buttons with clear labels improve conversion | | **Contact cards** | Professional display of contact information | Skip UI Resources for simple text answers, speed-critical conversations, or plain-text contexts (terminal interfaces). *** ## Design Principles ### 1. Mobile-First Templates display in chat widgets that are often mobile-sized. Start with small screens: ```css theme={null} .card { width: 100%; padding: 16px; } @media (min-width: 480px) { .card { max-width: 400px; padding: 24px; } } ``` ### 2. Clear Hierarchy Guide users' eyes to the most important information first: ```html theme={null}

{{ product_name }}

{{ description }}

SKU: {{ sku }} View
``` ### 3. Consistent Branding Use CSS custom properties for your design system: ```css theme={null} :root { --primary: #0069ED; --success: #10B981; --warning: #F59E0B; --error: #EF4444; --text-primary: #111827; --text-secondary: #6B7280; --border: #E5E7EB; } ``` ### 4. Graceful Degradation Always handle missing data: ```html theme={null} {% if product_image %} {{ product_name }} {% else %}
No image available
{% endif %}

{{ product_name | default('Product') }}

``` *** ## Common Patterns ### Product Card ```html theme={null}
{% if image_url %} {{ name }} {% endif %}

{{ name }}

{{ description | truncate(120) }}

{% if original_price and original_price > price %} ${{ original_price }} {% endif %} ${{ price }}
{{ 'In Stock' if in_stock else 'Out of Stock' }} View Details
``` ### Status Card ```html theme={null}
{{ status_type | default('Status') }} {{ status }}
{% if reference_id %}
Reference: {{ reference_id }}
{% endif %} {% if steps %}
{% for step in steps %}
{% if step.completed %}✓{% else %}{{ loop.index }}{% endif %}
{{ step.title }} {% if step.date %}{{ step.date }}{% endif %}
{% endfor %}
{% endif %} {% if action_url %} {{ action_text | default('View Details') }} {% endif %}
``` ### Action Buttons ```html theme={null}
{% if title %}

{{ title }}

{% endif %} {% if description %}

{{ description }}

{% endif %}
{% for action in actions %} {% if action.icon %}{{ action.icon }}{% endif %} {{ action.label }} {% if action.description %}{{ action.description }}{% endif %} {% endfor %}
``` ### Data Table ```html theme={null}
{% if title %}

{{ title }}

{% endif %} {% for header in headers %}{% endfor %} {% for row in rows %} {% for cell in row %}{% endfor %} {% else %} {% endfor %}
{{ header }}
{{ cell }}
No data available
``` *** ## Accessibility ### Semantic HTML Use proper HTML elements — headings, paragraphs, lists, and `
` instead of generic divs: ```html theme={null}

{{ product_name }}

{{ description }}

Buy Now
``` ### Images Always provide meaningful alt text: ```html theme={null} {{ product_name }} - {{ product_category }} ``` ### Color Contrast Ensure readable text and provide non-color indicators: ```css theme={null} .error { color: #dc2626; border-left: 3px solid #dc2626; /* Visual indicator beyond color */ } ``` ### Focus States Make interactive elements keyboard-accessible: ```css theme={null} .btn:focus, a:focus { outline: 2px solid #0069ED; outline-offset: 2px; } ``` ### Screen Readers Add ARIA labels where visual meaning is not conveyed by text: ```html theme={null} ``` *** ## Testing Templates ### Create Test Scenarios Test with different data in the template preview: **All data provided:** ```json theme={null} { "product_name": "Premium Widget", "price": 99.99, "in_stock": true, "features": ["Feature A", "Feature B"] } ``` **Minimal data (only required fields):** ```json theme={null} { "product_name": "Basic Widget", "price": 29.99 } ``` **Edge cases:** ```json theme={null} { "product_name": "A very long product name that might cause layout issues", "price": 1234567.89, "in_stock": false, "features": [] } ``` ### Checklist * [ ] Renders with all data provided * [ ] Renders with only required fields * [ ] Long text does not break the layout * [ ] Missing images show a placeholder * [ ] Looks correct on mobile widths * [ ] Buttons and links are clickable * [ ] Colors have sufficient contrast * [ ] No external dependencies that might break *** ## Performance Tips * **Keep templates light** — avoid loading external frameworks via CDN * **Specify image dimensions** to prevent layout shift: `` * **Use `loading="lazy"`** for images below the fold * **Include only necessary CSS** — skip unused utility classes * **Prefer CSS over JavaScript** for interactions (hover effects, accordions via `
`) *** ## Related * [UI Resources](../features/ui-resources) — Template syntax, configuration, and Jinja2 reference * [UI Resource Tool](../tools/ui-resource-tool) — Tool configuration * [AI Template Editor](../features/ai-template-editor) — Edit templates with natural language