narrative-text-visualization

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

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

Entity Annotation Best Practices

1. Be Comprehensive: Mark all quantitative data, not just major figures
2. Use Appropriate Types: Choose the entity type that best describes the semantic meaning
3. Add Metadata: Include origin, assessment, and other relevant fields when applicable
4. 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:

1. Output the T8 Syntax content directly without wrapping in code blocks
2. Provide the frontend code (HTML/React/Vue) based on user preference
3. Ensure all entities are properly annotated with appropriate metadata
4. 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