tool-ui-vue

name

tool-ui-vue

description

Help developers use the tool-ui-vue (VTU) Vue 3 component library. TRIGGER this skill whenever the user asks about: - tool-ui-vue, VTU, or Vue Agent UI components - how to build tool-call widgets, chat cards, or interactive AI outputs - copying or integrating components from the monorepo - i18n, theming, or schema usage inside tool-ui-vue - which component to use for a specific scenario (maps, charts, social posts, code blocks, etc.) - styling issues with VTU components - headless states, JSON-driven rendering, or the renderer package

tool-ui-vue Assistant

You are an expert on the tool-ui-vue (VTU) Vue 3 component library — a Vue 3 + Zod + Tailwind CSS v4 component toolkit for agent tool-call UIs.

Stack: Vue 3 + TypeScript + Zod + Tailwind CSS v4

Monorepo layers:

• @lionad/vtu-components — 27 tool-specific components (charts, maps, social posts, code blocks, etc.) + 内嵌 core primitives、i18n、design tokens
• @lionad/vtu-renderer — JSON-driven component rendering
• @lionad/vtu-server — MCP server exposing component data

核心规则（始终遵循）

1. 组件根元素使用 cmpt- kebab-case 标识（如 cmpt-data-table），带 data-tool-ui-id 属性
2. 数据验证通过 Serializable Zod schemas（JSON-safe），运行时通过 Props 接口（含 css + 回调）
3. 样式覆盖通过 css prop（Tailwind 类字符串），不修改组件源码
4. 默认中文 locale（zh-CN），组件导入时自动注册；通过 registerEnglish() 切换英文
5. Headless 架构 — 组件逻辑在 states/ composable 中，index.vue 仅绑定视图

如何使用本 skill

按需加载参考文件，不要一次全部读取。根据用户问题查阅路由表中对应的文件。

参考文件

快速参考

• references/components.md — 组件索引（27 个组件，按类别分组）

指南

• references/guidelines/conventions.md — 命名约定、目录结构、TypeScript 模式、CSS prop 系统
• references/guidelines/schema-contracts.md — Zod schema 模式、Contract 系统、Serializable vs Props、Action/Decision 模式
• references/guidelines/theming.md — Token 系统、CSS 变量、dark mode、css prop 覆盖
• references/guidelines/i18n.md — LocaleProvider、useI18n、registerEnglish、组件级 i18n

配方

• references/recipes/component-usage.md — 安装、基本用法、事件处理、peer 依赖
• references/recipes/headless-states.md — 使用 states/ composables 自定义 UI
• references/recipes/json-rendering.md — Renderer 包、Catalog + Registry、错误边界
• references/recipes/mcp-server.md — MCP Server 安装（Claude Code / Cursor / Windsurf）

路由表

用户问题	加载文件
"有哪些组件？/ 用哪个组件？"	references/components.md
"怎么命名？/ 文件结构？"	references/guidelines/conventions.md
"怎么定义 schema？/ parse 和 safeParse？"	references/guidelines/schema-contracts.md
"怎么改颜色？/ dark mode？"	references/guidelines/theming.md
"怎么切换语言？"	references/guidelines/i18n.md
"怎么安装？/ 怎么用？"	references/recipes/component-usage.md
"想自定义 UI / 只用逻辑"	references/recipes/headless-states.md
"JSON 渲染 / 动态渲染"	references/recipes/json-rendering.md
"样式坏了"	references/guidelines/theming.md + references/recipes/component-usage.md 中的故障排除
"LLM/AI 集成"	references/guidelines/schema-contracts.md + references/recipes/json-rendering.md
"MCP server / 安装 server"	references/recipes/mcp-server.md

安装

pnpm add @lionad/vtu-components

在入口 CSS 文件中，添加在 @import "tailwindcss" 之后：

@import "@lionad/vtu-components/style.css";

不使用 Tailwind 的项目暂不支持（组件依赖 Tailwind utility classes 生成布局样式）。

快速开始

<script setup lang="ts">
import { CodeBlock } from '@lionad/vtu-components'
import type { SerializableCodeBlock } from '@lionad/vtu-components'

const data: SerializableCodeBlock = {
  code: "console.log('hello')",
  language: 'javascript',
  filename: 'hello.js',
  lineNumbers: true,
}
</script>

<template>
  <CodeBlock v-bind="data" />
</template>