Widget Components

A complete catalog of the surface components available for widget rendering. Use these in your capability descriptor's surfaceGuidance.components array.

Overview

Aiffinity owns all consumer-facing UI rendering. Providers describe what to show, not how to show it. Your capability descriptor includes a surfaceGuidance object that tells the widget selector which component types best represent your data. The selector then picks the optimal component based on the user's context, screen real estate, and the 7-dimension budget engine.

Each component type has a budget cost (1–3 units) that the budget engine deducts from the user's per-session attention budget. Lower-cost components are preferred when budget is tight.

{
  "component": "stat_row",
  "objective": "inform",
  "density": "compact",
  "props": {
    "label": "Portfolio Value",
    "value": "$42,180.00",
    "trend": {
      "direction": "up",
      "delta": "+2.4%",
      "period": "24h"
    },
    "icon": "chart.line.uptrend.xyaxis"
  }
}

{
  "component": "sparkline",
  "objective": "inform",
  "density": "compact",
  "props": {
    "label": "Steps This Week",
    "values": [8420, 6230, 10150, 9800, 7650, 11200, 9400],
    "labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    "currentValue": "9,400",
    "trend": { "direction": "up", "delta": "+12%" },
    "color": "green",
    "fill": true
  }
}

{
  "component": "progress_bar",
  "objective": "nudge",
  "density": "compact",
  "props": {
    "label": "Weekly Reading Goal",
    "progress": 0.65,
    "displayValue": "65%",
    "target": "5 books",
    "current": "3.25 books",
    "color": "orange"
  }
}

{
  "component": "ranked_list",
  "objective": "inform",
  "density": "standard",
  "props": {
    "title": "Top Repositories This Week",
    "items": [
      { "rank": 1, "label": "aiffinity-core", "value": "142 commits", "badge": "hot" },
      { "rank": 2, "label": "provider-sdk", "value": "87 commits" },
      { "rank": 3, "label": "design-tokens", "value": "54 commits" },
      { "rank": 4, "label": "landing-page", "value": "31 commits" },
      { "rank": 5, "label": "infra-charts", "value": "22 commits" }
    ],
    "maxItems": 5
  }
}

{
  "component": "action_row",
  "objective": "act",
  "density": "compact",
  "props": {
    "actions": [
      {
        "label": "Open Board",
        "url": "https://trello.com/b/abc123",
        "icon": "rectangle.stack",
        "style": "primary"
      },
      {
        "label": "Create Card",
        "url": "https://trello.com/b/abc123/new-card",
        "icon": "plus.rectangle",
        "style": "secondary"
      },
      {
        "label": "View Activity",
        "url": "https://trello.com/b/abc123/activity",
        "style": "tertiary"
      }
    ]
  }
}

{
  "component": "cta_banner",
  "objective": "act",
  "density": "standard",
  "props": {
    "headline": "Connect Your Calendar",
    "subtitle": "Get meeting prep cards, smart scheduling suggestions, and automatic context for every call.",
    "button": {
      "label": "Connect Google Calendar",
      "url": "https://api.aiffinity.me/v1/providers/runtime/auth/google-calendar",
      "style": "primary"
    },
    "dismissible": true,
    "icon": "calendar.badge.plus"
  }
}

{
  "component": "meeting_prep",
  "objective": "prepare",
  "density": "expanded",
  "props": {
    "title": "Weekly Product Sync",
    "startsAt": "2026-04-04T14:00:00Z",
    "duration": 30,
    "location": "Google Meet",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "attendees": [
      { "name": "Sarah Chen", "role": "Product Lead", "avatarUrl": null },
      { "name": "Marcus Johnson", "role": "Engineering", "avatarUrl": null },
      { "name": "Lisa Park", "role": "Design", "avatarUrl": null }
    ],
    "agenda": [
      "Q2 roadmap review",
      "Provider SDK beta feedback",
      "Widget component catalog status"
    ],
    "notes": "Sarah mentioned wanting to discuss the new onboarding flow. Marcus has a PR ready for the sandbox API.",
    "relatedLinks": [
      { "label": "Q2 Roadmap Doc", "url": "https://notion.so/abc123" },
      { "label": "SDK Beta Tracker", "url": "https://linear.app/xyz" }
    ]
  }
}

{
  "component": "compound_card",
  "objective": "inform",
  "density": "expanded",
  "props": {
    "title": "Shopify Store Overview",
    "branding": {
      "provider": "Shopify",
      "iconUrl": "https://cdn.aiffinity.me/provider-icons/shopify.png",
      "accentColor": "#96BF48"
    },
    "sections": [
      {
        "component": "stat_row",
        "props": {
          "label": "Revenue Today",
          "value": "$1,842.00",
          "trend": { "direction": "up", "delta": "+18%" }
        }
      },
      {
        "component": "sparkline",
        "props": {
          "label": "Orders (7d)",
          "values": [12, 18, 15, 22, 19, 28, 24],
          "color": "green",
          "fill": true
        }
      },
      {
        "component": "action_row",
        "props": {
          "actions": [
            { "label": "View Orders", "url": "https://mystore.myshopify.com/admin/orders", "style": "primary" },
            { "label": "Analytics", "url": "https://mystore.myshopify.com/admin/analytics", "style": "secondary" }
          ]
        }
      }
    ]
  }
}

Compound Card Structure

The compound_card component nests other components as sections. This is the only component that supports composition. Key rules:

• No nesting: A compound_card cannot contain another compound_card.
• 1–4 sections: The sections array must contain between 1 and 4 entries.
• Section budget: The compound card costs 3 budget units total, regardless of how many sections it contains. Individual section costs are not charged separately.
• Branding: The optional branding object adds a provider icon and accent color to the card header. Use this when the card aggregates data from a single external service.
• Layout: Sections render vertically in order. The renderer adds appropriate spacing between sections. You cannot control section layout — Aiffinity determines the optimal arrangement.

// Compound card with branding and 3 sections
{
  "component": "compound_card",
  "props": {
    "title": "GitHub Activity",
    "branding": {
      "provider": "GitHub",
      "iconUrl": "https://cdn.aiffinity.me/provider-icons/github.png"
    },
    "sections": [
      { "component": "stat_row", "props": { "label": "Open PRs", "value": "7" } },
      { "component": "stat_row", "props": { "label": "Issues Assigned", "value": "12" } },
      { "component": "action_row", "props": { "actions": [{ "label": "Open GitHub", "url": "https://github.com", "style": "primary" }] } }
    ]
  }
}

Budget Engine

The Aiffinity widget selector uses a 7-dimension budget system to control the density and cognitive load of widgets shown to each user. Every session starts with a budget allocation across all seven dimensions. Each widget consumes budget based on its component type and objective.

Component budget costs

Surface Guidance

Your capability descriptor includes a surfaceGuidance object that tells the widget selector how to render your data. The selector uses this guidance alongside the budget engine and user context to choose the optimal component and placement.

{
  "surfaceGuidance": {
    "intent": "ambient_context",
    "placement": ["home_widgets", "daily_brief"],
    "components": ["stat_row", "sparkline"]
  }
}

Fields

The components array should list your preferred types in descending order of richness. For example, ["compound_card", "sparkline", "stat_row"] tells the selector to try a compound card first, fall back to a sparkline if budget is tight, and use a stat row as a last resort.