tool-ui-specs

Category: Tools & Productivity | Uploader: thiagovarela | Downloads: 0 | Version: v1.0（Latest）
Generate structured web UI payloads for clankie tool results and extension configuration using details.uiSpec and json-render shadcn components. Use when asked to make tool output render as cards, forms, lists, tables, or other rich UI in the web app.
Changelog: Source: GitHub https://github.com/thiagovarela/clankie
Directory Structure

Current level: extensions/clankie-json-ui-render/skills/tool-ui-specs/
📄 SKILL.md 6.2 KB
SKILL.md

---
name: tool-ui-specs
description: Generate structured web UI payloads for clankie tool results and extension configuration using details.uiSpec and json-render shadcn components. Use when asked to make tool output render as cards, forms, lists, tables, or other rich UI in the web app.
---

# Tool UI Specs

Use this skill when generating structured UI for the clankie web app.

## Rendering model

Always prefer `details.uiSpec`.

For this package, `render_json_ui` should always return json-render payloads instead of `details.renderHint`, even for content that could also be shown as markdown, json, lists, or tables.

Use `details.uiSpec` for:

- cards with grouped content
- multiple sections
- settings-like forms
- dashboards / summaries
- list-like content rendered as structured child nodes
- data previews rendered inside card sections

## Preferred tool path

If the `render_json_ui` tool is available, prefer calling it instead of hand-authoring a long JSON payload in chat. It produces valid `details.uiSpec` results that the web client can render directly.

Use direct payload authoring only when:
- you are writing extension/tool code
- or the user explicitly wants the raw payload

## Tool result contract

For tool results, keep a normal text summary in `content` and put structured rendering metadata in `details`.

```ts
return {
  content: [{ type: "text", text: "Summary for the agent and transcript." }],
  details: {
    uiSpec: {
      root: "some-root-id",
      elements: {
        // JSON Render node map
      },
      actions: {
        // optional action descriptions
      },
    },
  },
};
```

## Supported uiSpec shape

The web UI expects:

```ts
{
  root: string,
  elements: Record<string, unknown>,
  actions?: Record<string, { description?: string }>
}
```

Each element is usually shaped like:

```ts
{
  type: "Card" | "Stack" | "Text" | "Input" | "Button" | "Switch" | "Select",
  props?: Record<string, unknown>,
  children?: string[],
  on?: Record<string, {
    action: string,
    params?: Record<string, unknown>
  }>
}
```

## Components and patterns

Use simple, predictable compositions.

### Card with vertical stack

```json
{
  "root": "demo-card",
  "elements": {
    "demo-card": {
      "type": "Card",
      "props": {
        "title": "Workspace summary",
        "description": "Generated from a tool result"
      },
      "children": ["demo-stack"]
    },
    "demo-stack": {
      "type": "Stack",
      "props": {
        "direction": "vertical",
        "gap": "md"
      },
      "children": ["intro", "status"]
    },
    "intro": {
      "type": "Text",
      "props": {
        "text": "2 files changed, 1 warning remains."
      }
    },
    "status": {
      "type": "Text",
      "props": {
        "text": "Review the warning before shipping.",
        "variant": "muted"
      }
    }
  }
}
```

### Form-like controls

Use bindings when local UI state is useful.

```json
{
  "root": "settings-card",
  "elements": {
    "settings-card": {
      "type": "Card",
      "props": {
        "title": "Preview settings"
      },
      "children": ["settings-stack"]
    },
    "settings-stack": {
      "type": "Stack",
      "props": {
        "direction": "vertical",
        "gap": "md"
      },
      "children": ["enabled", "name", "echo"]
    },
    "enabled": {
      "type": "Switch",
      "props": {
        "label": "Enabled",
        "checked": { "$bindState": "/enabled" }
      }
    },
    "name": {
      "type": "Input",
      "props": {
        "label": "Name",
        "value": { "$bindState": "/name" }
      }
    },
    "echo": {
      "type": "Text",
      "props": {
        "text": { "$state": "/name" }
      }
    }
  }
}
```

## State bindings

Use these binding forms:

- `{ "$state": "/path" }` to read state
- `{ "$bindState": "/path" }` for two-way binding

For extension configuration UIs, state often starts from `initialState`, for example:

- `/config/enabled`
- `/config/model`
- `/availableModels`

## Actions

You may declare actions in `on` handlers and optionally document them in `actions`.

Example:

```json
{
  "save-button": {
    "type": "Button",
    "props": {
      "label": "Save",
      "variant": "primary"
    },
    "on": {
      "press": {
        "action": "saveExtensionConfig",
        "params": {
          "enabled": { "$state": "/config/enabled" },
          "model": { "$state": "/config/model" }
        }
      }
    }
  }
}
```

### Important limitation

For `details.uiSpec` inside ordinary tool results, prefer display-first UIs. The current web app renders the UI, but backend action handling is primarily wired for extension configuration screens. Do not assume arbitrary tool-result buttons can trigger real backend logic unless the caller explicitly says that plumbing exists.

So:

- for tool results: prefer read-only or local-state UI
- for extension settings: actions like save are appropriate

## Do not use renderHint in this package

For `clankie-json-ui-render`, do not return `details.renderHint`.

Even when the source content is naturally a list, table, JSON blob, code sample, or markdown-like text, convert it into a structured `details.uiSpec` tree.

## Good defaults

- Use stable element ids like `summary-card`, `summary-stack`, `save-button`
- Keep trees shallow
- Prefer one `Card` root with one `Stack` child
- Keep text concise
- Include a useful text fallback in `content`
- Only use components and props that are clearly necessary

## Avoid

- raw HTML
- JSX
- deeply nested trees without need
- unsupported component names
- inventing backend actions for normal tool-result UIs
- putting the whole payload in `content` instead of `details`

## Recommended response shape for LLM-authored tool code

```ts
return {
  content: [{ type: "text", text: "Short human-readable summary." }],
  details: {
    uiSpec: {
      root: "result-card",
      elements: {
        "result-card": {
          type: "Card",
          props: { title: "Result", description: "Structured output" },
          children: ["result-stack"],
        },
        "result-stack": {
          type: "Stack",
          props: { direction: "vertical", gap: "md" },
          children: ["result-text"],
        },
        "result-text": {
          type: "Text",
          props: { text: "Rendered by json-render." },
        },
      },
    },
  },
};
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
tool-ui-specs

Directory Structure

SKILL.md

Report

Notice
