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)
<!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:
npm install @antv/t8
# or
yarn add @antv/t8
Using in React
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
<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
<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
1---
2name: narrative-text-visualization
3description: Generate structured narrative text visualizations from data using T8 Syntax. Use when users want to create data interpretation reports, summaries, or structured articles with semantic entity annotations. T8 is designed for unstructured data visualization where T stands for Text and 8 represents a byte of 8 bits, symbolizing deep insights beneath the text.
4metadata:
5 source: https://skillmd.com/skills/antvis/narrative-text-visualization
6---
7
8# Narrative Text Visualization Skill
9
10This 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.
11
12## What is T8
13
14T8 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.
15
16**Key Features:**
17- **LLM-Friendly**: The syntax is intuitive and can be easily generated by AI models
18- **Declarative & Readable**: Write what you want, not how to build it
19- **Framework Agnostic**: Works with React, Vue, or vanilla JavaScript
20- **Standardized Styling**: Professional appearance by default
21- **Built-in Data Visualizations**: Mini charts (pie, line) are native to the syntax
22- **Lightweight**: Less than 20KB before gzip
23
24## Workflow
25
26To generate narrative text visualizations, follow these steps:
27
28### 1. Understand the Requirements
29
30Analyze the user's request to determine:
31- The topic or data to be analyzed
32- The type of narrative needed (report, summary, article)
33- The key insights to highlight
34- Any specific data sources or metrics
35
36### 2. Generate T8 Syntax Content
37
38Create narrative text using T8 Syntax following the specification below. The content must include:
39- Proper document structure (headings, paragraphs, lists)
40- Entity annotations for all meaningful data points
41- Appropriate metadata for entities (origin, assessment, etc.)
42
43### 3. Generate Frontend Code
44
45Create HTML, React, or Vue code to render the T8 content based on user's preferred framework.
46
47### 4. Validate Output
48
49Ensure:
50- All data is from authentic sources
51- Minimum content length (800 words or equivalent)
52- Proper entity annotations throughout
53- Clear structure and logical flow
54
55---
56
57## T8 Syntax Specification
58
59T8 Syntax is a Markdown-like language for creating narrative text with semantic entity annotations. It makes data analysis reports more expressive and visually appealing.
60
61### Document Structure
62
63#### Headings (6 levels)
64
65Use standard Markdown heading syntax:
66
67```
68# Level 1 Heading (Main Title)
69## Level 2 Heading (Section)
70### Level 3 Heading (Subsection)
71#### Level 4 Heading
72##### Level 5 Heading
73###### Level 6 Heading
74```
75
76**Rules:**
77- Each heading must be on its own line
78- Add one space after the `#` symbols
79- Headings create visual hierarchy in the rendered output
80
81#### Paragraphs
82
83Regular text paragraphs are separated by blank lines:
84
85```
86This is the first paragraph with some content.
87
88This is the second paragraph, separated by a blank line.
89```
90
91**Rules:**
92- Paragraphs can span multiple lines
93- Use blank lines to separate distinct paragraphs
94- Text within a paragraph flows naturally
95
96#### Lists
97
98T8 Syntax supports both unordered and ordered lists.
99
100**Unordered Lists:**
101```
102- First item
103- Second item
104- Third item
105```
106
107**Ordered Lists:**
108```
1091. First step
1102. Second step
1113. Third step
112```
113
114**Rules:**
115- Each list item must be on its own line
116- Add one space after the bullet marker (`-`, `*`) or number
117- Lists can contain entities and text formatting
118
119### Text Formatting
120
121T8 Syntax supports inline text formatting using Markdown syntax:
122
123**Bold Text:** `This is **bold text** that stands out.`
124
125**Italic Text:** `This is *italic text* for emphasis.`
126
127**Underline Text:** `This is __underlined text__ for importance.`
128
129**Links:** `Visit [our website](https://example.com) for more information.`
130
131**Rules:**
132- Formatting markers must be balanced (opening and closing)
133- Formatting can be combined with entities
134- Links use `[text](URL)` syntax where URL starts with `http://`, `https://`, or `/`
135
136### Entity Annotation Syntax
137
138The core feature of T8 Syntax is **entity annotation** - marking specific data points with semantic meaning and metadata.
139
140#### Basic Entity Syntax
141
142```
143[displayText](entityType)
144```
145
146- `displayText`: The text shown to readers
147- `entityType`: The semantic type of this entity
148
149**Example:**
150```
151The [sales revenue](metric_name) reached [¥1.5 million](metric_value) this quarter.
152```
153
154#### Entity with Metadata
155
156```
157[displayText](entityType, key1=value1, key2=value2, key3="string value")
158```
159
160**Metadata Rules:**
161- Separate multiple metadata fields with commas
162- Numbers and booleans: write directly (e.g., `origin=1500000`, `active=true`)
163- Strings: wrap in double quotes (e.g., `unit="元"`, `region="Asia"`)
164
165**Example:**
166```
167Revenue grew by [15.3%](ratio_value, origin=0.153, assessment="positive") compared to last year.
168```
169
170### Entity Types Reference
171
172Use these entity types to annotate different kinds of data:
173
174| Entity Type | Description | When to Use | Examples |
175| -------------------- | ------------------------------------ | ---------------------------------------------- | -------------------------------------------------------- |
176| `metric_name` | Name of a metric or KPI | When mentioning what you're measuring | "revenue", "user count", "market share" |
177| `metric_value` | Primary metric value | The main number/value being reported | "¥1.5 million", "50,000 users", "250 units" |
178| `other_metric_value` | Secondary or supporting metric value | Additional metrics that provide context | "average order value: $120" |
179| `delta_value` | Absolute change/difference | When showing numeric change between periods | "+1,200 units", "-$50K", "increased by 500" |
180| `ratio_value` | Percentage change/rate | When showing percentage change | "+15.3%", "-5.2%", "grew 23%" |
181| `contribute_ratio` | Contribution percentage | When showing what % something contributes | "accounts for 45%", "represents 30% of total" |
182| `trend_desc` | Trend description | Describing direction/pattern of change | "steadily rising", "declining trend", "stable" |
183| `dim_value` | Dimensional value/category | Geographic, categorical, or segmentation data | "North America", "Enterprise segment", "Q3" |
184| `time_desc` | Time period or timestamp | When specifying when something occurred | "Q3 2024", "January-March", "fiscal year 2023" |
185| `proportion` | Proportion or ratio | When expressing parts of a whole | "3 out of 5", "60% of customers" |
186| `rank` | Ranking or position | When indicating order or position in a list | "ranked 1st", "top 3", "5th place" |
187| `difference` | Comparative difference | When highlighting difference between two items | "difference of $50K", "gap of 200 units" |
188| `anomaly` | Unusual or unexpected value | When pointing out outliers or anomalies | "unusual spike", "unexpected drop" |
189| `association` | Relationship or correlation | When describing connections between metrics | "strongly correlated", "linked to", "related" |
190| `distribution` | Data distribution pattern | When describing how data is spread | "evenly distributed", "concentrated in", "spread across" |
191| `seasonality` | Seasonal pattern or trend | When describing recurring seasonal patterns | "seasonal peak", "holiday period", "Q4 surge" |
192
193### Common Metadata Fields
194
195Add these optional fields to provide richer data context:
196
197#### `origin` (number)
198
199The raw numerical value behind the displayed text.
200
201**Examples:**
202- `[¥1.5M](metric_value, origin=1500000)`
203- `[23.7%](ratio_value, origin=0.237)`
204- `[5.2K users](metric_value, origin=5200)`
205- `[3 out of 4](proportion, origin=0.75)`
206
207**Why use it:** Enables data visualization, sorting, and calculations
208
209#### `assessment` (string)
210
211Evaluates whether a change is positive, negative, or neutral.
212
213**Valid values:** `"positive"`, `"negative"`, `"equal"`, `"neutral"`
214
215**Examples:**
216- `[increased 15%](ratio_value, assessment="positive")`
217- `[dropped 8%](ratio_value, assessment="negative")`
218- `[remained flat](trend_desc, assessment="equal")`
219
220**Why use it:** Enables visual indicators (colors, icons) for good/bad trends
221
222#### `unit` (string)
223
224The unit of measurement for the value.
225
226**Examples:**
227- `[¥1,500,000](metric_value, unit="元", origin=1500000)`
228- `[150](metric_value, unit="units")`
229
230#### `detail` (any)
231
232Additional context or breakdown data for chart rendering. Required for certain entity types.
233
234**Required for these entity types:**
235- `rank`: Array of numbers representing ranking data
236 - Example: `[top performer](rank, detail=[5, 8, 12, 15, 20])`
237- `difference`: Array of numbers showing comparative values
238 - Example: `[gap narrowing](difference, detail=[100, 80, 60, 40])`
239- `anomaly`: Array of numbers highlighting outliers
240 - Example: `[unusual spike](anomaly, detail=[10, 12, 11, 45, 13])`
241- `association`: Array of {x, y} objects for correlation data
242 - Example: `[strong correlation](association, detail=[{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":6}])`
243- `distribution`: Array of numbers showing data spread
244 - Example: `[uneven distribution](distribution, detail=[5, 15, 45, 25, 10])`
245- `seasonality`: Object with data array and optional range
246 - Example: `[Q4 peak](seasonality, detail={"data":[10,12,15,30],"range":[0,40]})`
247
248**Optional for other types:**
249- `[steady growth](trend_desc, detail=[100, 120, 145, 180, 210])`
250
251---
252
253## Data Requirements
254
255**Critical**: All data must be from publicly authentic sources:
256- Official announcements/financial reports
257- Authoritative media (Reuters, Bloomberg, TechCrunch, etc.)
258- Industry research institutions (IDC, Canalys, Counterpoint Research, etc.)
259- **Never use fictional, AI-guessed, or simulated data**
260- Use specific numbers (e.g., "146 million units", "7058 units"), not vague approximations
261
262---
263
264## Complete T8 Syntax Example
265
266```
267# 2024 Smartphone Market Analysis
268
269## Market Overview
270
271Global [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.
272
273The **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").
274
275## Key Findings
276
2771. [Asia-Pacific](dim_value) remains the __largest market__
2782. [Premium devices](dim_value) showed **strong growth**
2793. Budget segment faced *headwinds*
280
281## Regional Breakdown
282
283### Asia-Pacific
284
285[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.
286
287Key markets:
288- [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
289- [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])
290- [Southeast Asia](dim_value): [180M units](metric_value, origin=180000000) - [stable](trend_desc, assessment="equal")
291
292For detailed methodology, visit [our research page](https://example.com/methodology).
293```
294
295---
296
297## Using T8 in HTML, React, and Vue
298
299### Using in HTML (via CDN)
300
301```html
302<!DOCTYPE html>
303<html lang="en">
304<head>
305 <meta charset="UTF-8">
306 <meta name="viewport" content="width=device-width, initial-scale=1.0">
307 <title>T8 Narrative Text</title>
308</head>
309<body>
310 <div id="container"></div>
311
312 <!-- Import T8 from unpkg CDN -->
313 <script src="https://unpkg.com/@antv/t8/dist/t8.min.js"></script>
314
315 <script>
316 // T8 is available as a global variable
317 const { Text } = window.T8;
318
319 // Initialize T8 instance
320 const text = new Text(document.getElementById('container'));
321
322 // Render narrative text using T8 Syntax
323 const narrativeText = `
324# Sales Report
325
326This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).
327
328[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
329 `;
330
331 text.theme('light').render(narrativeText);
332 </script>
333</body>
334</html>
335```
336
337**Installation:**
338```bash
339npm install @antv/t8
340# or
341yarn add @antv/t8
342```
343
344### Using in React
345
346```tsx
347import { Text } from '@antv/t8';
348import { useEffect, useRef } from 'react';
349
350function T8Component() {
351 const containerRef = useRef<HTMLDivElement>(null);
352
353 useEffect(() => {
354 if (!containerRef.current) return;
355
356 // Initialize T8 instance
357 const text = new Text(containerRef.current);
358
359 // Render narrative text using T8 Syntax
360 const narrativeText = `
361# Sales Report
362
363This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).
364
365[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
366 `;
367
368 text.theme('light').render(narrativeText);
369
370 // Cleanup on unmount
371 return () => {
372 text.unmount();
373 };
374 }, []);
375
376 return <div ref={containerRef} />;
377}
378
379export default T8Component;
380```
381
382### Using in Vue 3
383
384```vue
385<template>
386 <div ref="containerRef"></div>
387</template>
388
389<script setup lang="ts">
390import { Text } from '@antv/t8';
391import { ref, onMounted, onBeforeUnmount } from 'vue';
392
393const containerRef = ref<HTMLDivElement>();
394let textInstance: Text | null = null;
395
396onMounted(() => {
397 if (!containerRef.value) return;
398
399 // Initialize T8 instance
400 textInstance = new Text(containerRef.value);
401
402 // Render narrative text using T8 Syntax
403 const narrativeText = `
404# Sales Report
405
406This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).
407
408[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
409 `;
410
411 textInstance.theme('light').render(narrativeText);
412});
413
414onBeforeUnmount(() => {
415 if (textInstance) {
416 textInstance.unmount();
417 }
418});
419</script>
420```
421
422### Using in Vue 2
423
424```vue
425<template>
426 <div ref="container"></div>
427</template>
428
429<script>
430import { Text } from '@antv/t8';
431
432export default {
433 name: 'T8Component',
434 data() {
435 return {
436 textInstance: null,
437 };
438 },
439 mounted() {
440 // Initialize T8 instance
441 this.textInstance = new Text(this.$refs.container);
442
443 // Render narrative text using T8 Syntax
444 const narrativeText = `
445# Sales Report
446
447This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).
448
449[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
450 `;
451
452 this.textInstance.theme('light').render(narrativeText);
453 },
454 beforeDestroy() {
455 if (this.textInstance) {
456 this.textInstance.unmount();
457 }
458 },
459};
460</script>
461```
462
463---
464
465## Writing Guidelines and Best Practices
466
467### Content Requirements
468
4691. **Minimum Length:** No less than 800 words (adjust based on data complexity)
4702. **Structure:** Clear hierarchy with logical flow between sections
4713. **Analysis:** Don't just list numbers - explain their significance and context
4724. **Tone:** Natural, fluent, objective, and professional
4735. **Entity Usage:** Annotate ALL meaningful data points - metrics, values, trends, times, changes, percentages
474
475### Entity Annotation Best Practices
476
4771. **Be Comprehensive:** Mark all quantitative data, not just major figures
4782. **Use Appropriate Types:** Choose the entity type that best describes the semantic meaning
4793. **Add Metadata:** Include `origin`, `assessment`, and other relevant fields when applicable
4804. **Natural Flow:** Entities should blend seamlessly into readable prose
481
482### What to Annotate
483
484✅ **DO annotate:**
485- All numeric values (revenue, counts, measurements)
486- All percentages (changes, contributions, proportions)
487- Metric names and KPIs
488- Time periods
489- Geographic regions and categories
490- Trend descriptions
491- Comparisons and changes
492
493❌ **DON'T annotate:**
494- Generic text without specific data meaning
495- Connecting phrases and transitions
496- Context that doesn't represent measurable concepts
497
498---
499
500## Output Format
501
502When generating T8 Syntax content for the user:
5031. Output the T8 Syntax content directly without wrapping in code blocks
5042. Provide the frontend code (HTML/React/Vue) based on user preference
5053. Ensure all entities are properly annotated with appropriate metadata
5064. Verify that content meets minimum length and quality requirements
507
508The rendered output provides:
509- Rich semantic markup for data entities
510- Interactive entity highlighting
511- Clear visual hierarchy
512- Professional report-style formatting
513- Responsive design for all devices
514
515---
516
517## Reference Links
518
519- T8 GitHub Repository: https://github.com/antvis/T8
520- T8 Documentation: https://github.com/antvis/T8/blob/main/site/en/tutorial/quick-start.md
521- T8 Syntax Reference: https://github.com/antvis/T8/blob/main/prompt.md