Narrative Text Visualization Skill

This skill provides a workflow for transforming data into structured narrative text visualizations using T8 Syntax - a declarative Markdown-like language for creating data narratives with semantic entity annotations.

What is T8

T8 is a text visualization solution under the AntV technology stack designed specifically for insight-based narrative text display. Instead of manually constructing DOM elements, you write simple, human-readable syntax that describes your data narrative.

Key Features:

LLM-Friendly: The syntax is intuitive and can be easily generated by AI models
Declarative & Readable: Write what you want, not how to build it
Framework Agnostic: Works with React, Vue, or vanilla JavaScript
Standardized Styling: Professional appearance by default
Built-in Data Visualizations: Mini charts (pie, line) are native to the syntax
Lightweight: Less than 20KB before gzip

Workflow

To generate narrative text visualizations, follow these steps:

1. Understand the Requirements

Analyze the user's request to determine:

The topic or data to be analyzed
The type of narrative needed (report, summary, article)
The key insights to highlight
Any specific data sources or metrics

2. Generate T8 Syntax Content

Create narrative text using T8 Syntax following the specification below. The content must include:

Proper document structure (headings, paragraphs, lists)
Entity annotations for all meaningful data points
Appropriate metadata for entities (origin, assessment, etc.)

3. Generate Frontend Code

Create HTML, React, or Vue code to render the T8 content based on user's preferred framework.

4. Validate Output

Ensure:

All data is from authentic sources
Minimum content length (800 words or equivalent)
Proper entity annotations throughout
Clear structure and logical flow

T8 Syntax Specification

T8 Syntax is a Markdown-like language for creating narrative text with semantic entity annotations. It makes data analysis reports more expressive and visually appealing.

Document Structure

Headings (6 levels)

Use standard Markdown heading syntax:

# Level 1 Heading (Main Title)
## Level 2 Heading (Section)
### Level 3 Heading (Subsection)
#### Level 4 Heading
##### Level 5 Heading
###### Level 6 Heading

Rules:

Each heading must be on its own line
Add one space after the
```
#
```
symbols
Headings create visual hierarchy in the rendered output

Paragraphs

Regular text paragraphs are separated by blank lines:

This is the first paragraph with some content.

This is the second paragraph, separated by a blank line.

Rules:

Paragraphs can span multiple lines
Use blank lines to separate distinct paragraphs
Text within a paragraph flows naturally

Lists

T8 Syntax supports both unordered and ordered lists.

Unordered Lists:

- First item
- Second item
- Third item

Ordered Lists:

1. First step
2. Second step
3. Third step

Rules:

Each list item must be on its own line
Add one space after the bullet marker (
```
-
```
,
```
*
```
) or number
Lists can contain entities and text formatting

Text Formatting

T8 Syntax supports inline text formatting using Markdown syntax:

Bold Text:

This is **bold text** that stands out.

Italic Text:

This is *italic text* for emphasis.

Underline Text:

This is __underlined text__ for importance.

Links:

Visit [our website](https://example.com) for more information.

Rules:

Formatting markers must be balanced (opening and closing)
Formatting can be combined with entities
Links use
```
[text](URL)
```
syntax where URL starts with
```
http://
```
,
```
https://
```
, or
```
/
```

Entity Annotation Syntax

The core feature of T8 Syntax is entity annotation - marking specific data points with semantic meaning and metadata.

Basic Entity Syntax

[displayText](entityType)

```
displayText
```
: The text shown to readers
```
entityType
```
: The semantic type of this entity

Example:

The [sales revenue](metric_name) reached [¥1.5 million](metric_value) this quarter.

Entity with Metadata

[displayText](entityType, key1=value1, key2=value2, key3="string value")

Metadata Rules:

Separate multiple metadata fields with commas
Numbers and booleans: write directly (e.g.,
```
origin=1500000
```
,
```
active=true
```
)
Strings: wrap in double quotes (e.g.,
```
unit="元"
```
,
```
region="Asia"
```
)

Example:

Revenue grew by [15.3%](ratio_value, origin=0.153, assessment="positive") compared to last year.

Entity Types Reference

Use these entity types to annotate different kinds of data:

Entity Type	Description	When to Use	Examples
`metric_name`	Name of a metric or KPI	When mentioning what you're measuring	"revenue", "user count", "market share"
`metric_value`	Primary metric value	The main number/value being reported	"¥1.5 million", "50,000 users", "250 units"
`other_metric_value`	Secondary or supporting metric value	Additional metrics that provide context	"average order value: $120"
`delta_value`	Absolute change/difference	When showing numeric change between periods	"+1,200 units", "-$50K", "increased by 500"
`ratio_value`	Percentage change/rate	When showing percentage change	"+15.3%", "-5.2%", "grew 23%"
`contribute_ratio`	Contribution percentage	When showing what % something contributes	"accounts for 45%", "represents 30% of total"
`trend_desc`	Trend description	Describing direction/pattern of change	"steadily rising", "declining trend", "stable"
`dim_value`	Dimensional value/category	Geographic, categorical, or segmentation data	"North America", "Enterprise segment", "Q3"
`time_desc`	Time period or timestamp	When specifying when something occurred	"Q3 2024", "January-March", "fiscal year 2023"
`proportion`	Proportion or ratio	When expressing parts of a whole	"3 out of 5", "60% of customers"
`rank`	Ranking or position	When indicating order or position in a list	"ranked 1st", "top 3", "5th place"
`difference`	Comparative difference	When highlighting difference between two items	"difference of $50K", "gap of 200 units"
`anomaly`	Unusual or unexpected value	When pointing out outliers or anomalies	"unusual spike", "unexpected drop"
`association`	Relationship or correlation	When describing connections between metrics	"strongly correlated", "linked to", "related"
`distribution`	Data distribution pattern	When describing how data is spread	"evenly distributed", "concentrated in", "spread across"
`seasonality`	Seasonal pattern or trend	When describing recurring seasonal patterns	"seasonal peak", "holiday period", "Q4 surge"

Common Metadata Fields

Add these optional fields to provide richer data context:

origin

(number)

The raw numerical value behind the displayed text.

Examples:

```
[¥1.5M](metric_value, origin=1500000)
```
```
[23.7%](ratio_value, origin=0.237)
```
```
[5.2K users](metric_value, origin=5200)
```
```
[3 out of 4](proportion, origin=0.75)
```

Why use it: Enables data visualization, sorting, and calculations

assessment

(string)

Evaluates whether a change is positive, negative, or neutral.

Valid values:

"positive"

"negative"

"equal"

"neutral"

Examples:

[increased 15%](ratio_value, assessment="positive")

[dropped 8%](ratio_value, assessment="negative")

[remained flat](trend_desc, assessment="equal")

Why use it: Enables visual indicators (colors, icons) for good/bad trends

unit

(string)

The unit of measurement for the value.

Examples:

[¥1,500,000](metric_value, unit="元", origin=1500000)

```
[150](metric_value, unit="units")
```

detail

(any)

Additional context or breakdown data for chart rendering. Required for certain entity types.

Required for these entity types:

rank

: Array of numbers representing ranking data

Example:

[top performer](rank, detail=[5, 8, 12, 15, 20])

difference

: Array of numbers showing comparative values

Example:

[gap narrowing](difference, detail=[100, 80, 60, 40])

anomaly

: Array of numbers highlighting outliers

Example:

[unusual spike](anomaly, detail=[10, 12, 11, 45, 13])

association

: Array of {x, y} objects for correlation data

Example:

[strong correlation](association, detail=[{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":6}])

distribution

: Array of numbers showing data spread

Example:

[uneven distribution](distribution, detail=[5, 15, 45, 25, 10])

seasonality

: Object with data array and optional range

Example:

[Q4 peak](seasonality, detail={"data":[10,12,15,30],"range":[0,40]})

Optional for other types:

[steady growth](trend_desc, detail=[100, 120, 145, 180, 210])

Data Requirements

Critical: All data must be from publicly authentic sources:

Official announcements/financial reports
Authoritative media (Reuters, Bloomberg, TechCrunch, etc.)
Industry research institutions (IDC, Canalys, Counterpoint Research, etc.)
Never use fictional, AI-guessed, or simulated data
Use specific numbers (e.g., "146 million units", "7058 units"), not vague approximations

Complete T8 Syntax Example

# 2024 Smartphone Market Analysis

## Market Overview

Global [smartphone shipments](metric_name) reached [1.2 billion units](metric_value, origin=1200000000) in [2024](time_desc), showing a [modest decline of 2.1%](ratio_value, origin=-0.021, assessment="negative") year-over-year.

The **premium segment** (devices over $800) showed *remarkable* [resilience](trend_desc, assessment="positive"), growing by [5.8%](ratio_value, origin=0.058, assessment="positive"). [Average selling price](other_metric_value) was [$420](metric_value, origin=420, unit="USD").

## Key Findings

1. [Asia-Pacific](dim_value) remains the __largest market__
2. [Premium devices](dim_value) showed **strong growth**
3. Budget segment faced *headwinds*

## Regional Breakdown

### Asia-Pacific

[Asia-Pacific](dim_value) remains the largest market with [680 million units](metric_value, origin=680000000) shipped, though this represents a [decline of 180 million units](delta_value, origin=-180000000, assessment="negative") from the previous year.

Key markets:
- [China](dim_value): [320M units](metric_value, origin=320000000) - down [8.5%](ratio_value, origin=-0.085, assessment="negative"), [ranked 1st](rank, detail=[320, 180, 90, 65, 45]) globally, accounting for [47%](contribute_ratio, origin=0.47, assessment="positive") of regional sales
- [India](dim_value): [180M units](metric_value, origin=180000000) - up [12.3%](ratio_value, origin=0.123, assessment="positive"), [ranked 2nd](rank, detail=[320, 180, 90, 65, 45])
- [Southeast Asia](dim_value): [180M units](metric_value, origin=180000000) - [stable](trend_desc, assessment="equal")

For detailed methodology, visit [our research page](https://example.com/methodology).

Using T8 in HTML, React, and Vue

Using in HTML (via CDN)

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>T8 Narrative Text</title>
</head>
<body>
  <div id="container"></div>

  <!-- Import T8 from unpkg CDN -->
  <script src="https://unpkg.com/@antv/t8/dist/t8.min.js"></script>
  
  <script>
    // T8 is available as a global variable
    const { Text } = window.T8;

    // Initialize T8 instance
    const text = new Text(document.getElementById('container'));

    // Render narrative text using T8 Syntax
    const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
    `;

    text.theme('light').render(narrativeText);
  </script>
</body>
</html>

Installation:

bash

npm install @antv/t8
# or
yarn add @antv/t8

Using in React

tsx

import { Text } from '@antv/t8';
import { useEffect, useRef } from 'react';

function T8Component() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // Initialize T8 instance
    const text = new Text(containerRef.current);

    // Render narrative text using T8 Syntax
    const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
    `;

    text.theme('light').render(narrativeText);

    // Cleanup on unmount
    return () => {
      text.unmount();
    };
  }, []);

  return <div ref={containerRef} />;
}

export default T8Component;

Using in Vue 3

vue

<template>
  <div ref="containerRef"></div>
</template>

<script setup lang="ts">
import { Text } from '@antv/t8';
import { ref, onMounted, onBeforeUnmount } from 'vue';

const containerRef = ref<HTMLDivElement>();
let textInstance: Text | null = null;

onMounted(() => {
  if (!containerRef.value) return;

  // Initialize T8 instance
  textInstance = new Text(containerRef.value);

  // Render narrative text using T8 Syntax
  const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
  `;

  textInstance.theme('light').render(narrativeText);
});

onBeforeUnmount(() => {
  if (textInstance) {
    textInstance.unmount();
  }
});
</script>

Using in Vue 2

vue

<template>
  <div ref="container"></div>
</template>

<script>
import { Text } from '@antv/t8';

export default {
  name: 'T8Component',
  data() {
    return {
      textInstance: null,
    };
  },
  mounted() {
    // Initialize T8 instance
    this.textInstance = new Text(this.$refs.container);

    // Render narrative text using T8 Syntax
    const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
    `;

    this.textInstance.theme('light').render(narrativeText);
  },
  beforeDestroy() {
    if (this.textInstance) {
      this.textInstance.unmount();
    }
  },
};
</script>

Writing Guidelines and Best Practices

Content Requirements

Minimum Length: No less than 800 words (adjust based on data complexity)
Structure: Clear hierarchy with logical flow between sections
Analysis: Don't just list numbers - explain their significance and context
Tone: Natural, fluent, objective, and professional
Entity Usage: Annotate ALL meaningful data points - metrics, values, trends, times, changes, percentages

Entity Annotation Best Practices

Be Comprehensive: Mark all quantitative data, not just major figures
Use Appropriate Types: Choose the entity type that best describes the semantic meaning
Add Metadata: Include
```
origin
```
,
```
assessment
```
, and other relevant fields when applicable
Natural Flow: Entities should blend seamlessly into readable prose

What to Annotate

✅ DO annotate:

All numeric values (revenue, counts, measurements)
All percentages (changes, contributions, proportions)
Metric names and KPIs
Time periods
Geographic regions and categories
Trend descriptions
Comparisons and changes

❌ DON'T annotate:

Generic text without specific data meaning
Connecting phrases and transitions
Context that doesn't represent measurable concepts

Output Format

When generating T8 Syntax content for the user:

Output the T8 Syntax content directly without wrapping in code blocks
Provide the frontend code (HTML/React/Vue) based on user preference
Ensure all entities are properly annotated with appropriate metadata
Verify that content meets minimum length and quality requirements

The rendered output provides:

Rich semantic markup for data entities
Interactive entity highlighting
Clear visual hierarchy
Professional report-style formatting
Responsive design for all devices

Reference Links

T8 GitHub Repository: https://github.com/antvis/T8
T8 Documentation: https://github.com/antvis/T8/blob/main/site/en/tutorial/quick-start.md
T8 Syntax Reference: https://github.com/antvis/T8/blob/main/prompt.md

narrative-text-visualization

NPX Install

Tags

SKILL.md Content

Narrative Text Visualization Skill

What is T8

Workflow

1. Understand the Requirements

2. Generate T8 Syntax Content

3. Generate Frontend Code

4. Validate Output

T8 Syntax Specification

Document Structure

Headings (6 levels)

Paragraphs

Lists

Text Formatting

Entity Annotation Syntax

Basic Entity Syntax

Entity with Metadata

Entity Types Reference

Common Metadata Fields

`origin`
(number)

`assessment`
(string)

`unit`
(string)

`detail`
(any)

Data Requirements

Complete T8 Syntax Example

Using T8 in HTML, React, and Vue

Using in HTML (via CDN)

Using in React

Using in Vue 3

Using in Vue 2

Writing Guidelines and Best Practices

Content Requirements

Entity Annotation Best Practices

What to Annotate

Output Format

Reference Links