Skip to content

Commit 31a846f

Browse files
CopilotCopilot
authored
Add T8 Narrative Text Visualization skill for series 8 (unstructured data) (#7)
1 parent 270466c commit 31a846f

5 files changed

Lines changed: 723 additions & 0 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,15 @@
2626
"skills": [
2727
"./skills/infographic-creator"
2828
]
29+
},
30+
{
31+
"name": "narrative-text-visualization",
32+
"description": "Generate structured narrative text visualizations from data using T8 schema. Creates data interpretation reports with entity labeling.",
33+
"source": "./",
34+
"strict": false,
35+
"skills": [
36+
"./skills/narrative-text-visualization"
37+
]
2938
}
3039
]
3140
}

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ npx skills add antvis/chart-visualization-skills
3131

3232
`Infographic Creator` uses AntV Infographic to transform data, information, and knowledge into a perceptible visual language. It combines visual design with data visualization, providing 50+ templates including lists, sequences, hierarchies, comparisons, relations, and charts. It compresses complex information with intuitive symbols to help audiences quickly understand and remember key points.
3333

34+
- **narrative-text-visualization**: Generate structured narrative text visualizations from data using T8 schema.
35+
36+
`Narrative Text Visualization` (T8) transforms unstructured data into semantically rich narrative reports with entity labeling. It uses a declarative JSON Schema to describe data interpretation reports, making it easy for LLMs to generate structured articles with proper semantic markup. Perfect for creating data analysis reports, summaries, and insights documents with entities like metrics, values, trends, and dimensions properly labeled. Supports authentic data sources and provides lightweight, technology-agnostic rendering.
37+
3438
> [!TIP]
3539
> More skills are coming soon.
3640

‎skills/narrative-text-visualization/SKILL.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
---
2+
name: narrative-text-visualization
3+
description: Generate structured narrative text visualizations from data using T8 (Text) schema. Use when users want to create data interpretation reports, summaries, or structured articles with entity labeling and semantic markup.
4+
---
5+
6+
# Narrative Text Visualization Skill
7+
8+
This skill provides a workflow for transforming data into structured narrative text visualizations using the AntV T8 (Text) schema. T8 is designed for unstructured data visualization where `T` stands for Text, and `8` represents a byte of 8 bits, symbolizing deep insights hidden beneath the text.
9+
10+
## Overview
11+
12+
`T8` is a declarative JSON Schema syntax used to describe data interpretation reports with semantic entity labeling. It's designed to be:
13+
- **LLM-friendly**: Easy to generate with AI prompts
14+
- **Technology stack agnostic**: Works with React, Vue, and other frameworks
15+
- **Extensible**: Supports custom entity phrases
16+
- **Lightweight**: Less than 20KB before gzip
17+
18+
## Workflow
19+
20+
To generate narrative text visualizations, follow these steps:
21+
22+
### 1. Understand the Requirements
23+
24+
Analyze the user's request to determine:
25+
- The topic or data to be analyzed
26+
- The type of narrative needed (report, summary, article)
27+
- The key insights to highlight
28+
- Any specific data sources or metrics
29+
30+
### 2. Review the JSON Schema
31+
32+
Consult the `references/schema.json` file to understand the T8 structure:
33+
- **Top Structure**: Contains `headline` and `sections` array
34+
- **Sections**: Main chapters containing `paragraphs`
35+
- **Paragraphs**: Text blocks containing `phrases`, can be:
36+
- `normal`: Regular text paragraphs
37+
- `heading1-6`: Heading levels
38+
- `bullets`: Bulleted/ordered lists
39+
- **Phrases**: Text elements that can be:
40+
- `text`: Plain text
41+
- `entity`: Semantically labeled data with metadata
42+
43+
### 3. Entity Labeling
44+
45+
Use entity types to mark key information (see `references/prompt.md` for details):
46+
47+
| Entity Type | Description | Example |
48+
| -------------------- | ----------------------- | ------------------------------------ |
49+
| `metric_name` | Indicator name | "Shipment", "Growth Rate" |
50+
| `metric_value` | Main indicator value | "146 million units", "120 factories" |
51+
| `other_metric_value` | Other metric values | "$19.2 billion" |
52+
| `delta_value` | Difference | "+120" |
53+
| `ratio_value` | Rate | "+8.4%", "9%" |
54+
| `contribute_ratio` | Contribution | "40%" |
55+
| `trend_desc` | Trend Description | "Continuously Rising", "Stable" |
56+
| `dim_value` | Dimensional identifier | "India", "Jiangsu", "Overseas" |
57+
| `time_desc` | Time stamp | "Q3 2024", "all year" |
58+
| `proportion` | Proportion description | "30%" |
59+
60+
### 4. Data Requirements
61+
62+
**Critical**: All data must be from publicly authentic sources:
63+
- Official announcements/financial reports
64+
- Authoritative media (Reuters, Bloomberg, TechCrunch, etc.)
65+
- Industry research institutions (IDC, Canalys, Counterpoint Research, etc.)
66+
- **Never use fictional, AI-guessed, or simulated data**
67+
- Use specific numbers (e.g., "146 million units", "7058 units"), not vague approximations
68+
69+
### 5. Generate JSON Schema
70+
71+
Create a JSON object following the T8 schema structure:
72+
73+
```json
74+
{
75+
"headline": {
76+
"type": "headline",
77+
"phrases": [
78+
{
79+
"type": "text",
80+
"value": "Article Title"
81+
}
82+
]
83+
},
84+
"sections": [
85+
{
86+
"paragraphs": [
87+
{
88+
"type": "normal",
89+
"phrases": [
90+
{
91+
"type": "text",
92+
"value": "In Q3 2024, "
93+
},
94+
{
95+
"type": "entity",
96+
"value": "smartphone shipments",
97+
"metadata": {
98+
"entityType": "metric_name"
99+
}
100+
},
101+
{
102+
"type": "text",
103+
"value": " reached "
104+
},
105+
{
106+
"type": "entity",
107+
"value": "146 million units",
108+
"metadata": {
109+
"entityType": "metric_value",
110+
"origin": 146000000,
111+
"assessment": "positive"
112+
}
113+
},
114+
{
115+
"type": "text",
116+
"value": ", showing a year-over-year increase of "
117+
},
118+
{
119+
"type": "entity",
120+
"value": "+8.4%",
121+
"metadata": {
122+
"entityType": "ratio_value",
123+
"origin": 0.084,
124+
"assessment": "positive"
125+
}
126+
},
127+
{
128+
"type": "text",
129+
"value": "."
130+
}
131+
]
132+
}
133+
]
134+
}
135+
]
136+
}
137+
```
138+
139+
### 6. Render the Visualization
140+
141+
Once you have the JSON schema, create an HTML file that uses the T8 library to render the narrative text:
142+
143+
```html
144+
<!DOCTYPE html>
145+
<html lang="en">
146+
<head>
147+
<meta charset="UTF-8">
148+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
149+
<title>Narrative Text Visualization</title>
150+
<script src="https://unpkg.com/@antv/t8/dist/t8.min.js"></script>
151+
<style>
152+
#container {
153+
max-width: 800px;
154+
margin: 40px auto;
155+
padding: 20px;
156+
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
157+
}
158+
</style>
159+
</head>
160+
<body>
161+
<div id="container"></div>
162+
<script>
163+
// The T8 schema generated above
164+
const schema = {
165+
// ... your schema here
166+
};
167+
168+
// Instantiate T8
169+
const text = new T8.Text({
170+
container: 'container',
171+
});
172+
173+
// Specify schema and theme
174+
text.schema(schema).theme('light');
175+
176+
// Render visualization
177+
text.render();
178+
</script>
179+
</body>
180+
</html>
181+
```
182+
183+
### 7. Output Guidelines
184+
185+
- The article should be at least 800 Chinese characters or equivalent in other languages
186+
- Structure should be clear with natural paragraph transitions
187+
- Provide meaningful data interpretation, not just numbers
188+
- Use professional, objective language
189+
- Output only the JSON schema in plain text (no markdown code blocks)
190+
- Omit the `definitions` section in final output
191+
192+
## Best Practices
193+
194+
1. **Entity Metadata**: Always add these optional fields when possible:
195+
- `origin`: The exact numerical value (e.g., for "146 million units", origin is `146000000`)
196+
- `assessment`: Growth trend (`'positive'` | `'negative'` | `'equal'`)
197+
- `detail`: Supplementary data array for trends (e.g., `[2,3,4,1,7]`)
198+
199+
2. **Entity Usage**: Maximize entity labeling for:
200+
- Metrics and values
201+
- Time references
202+
- Dimensional identifiers
203+
- Trends and changes
204+
- Proportions and ratios
205+
206+
3. **Structure**:
207+
- Use headings to organize content
208+
- Group related information in sections
209+
- Use bullets for lists and key points
210+
- Maintain logical flow between paragraphs
211+
212+
4. **Data Quality**:
213+
- Always cite authentic sources
214+
- Use specific, verifiable numbers
215+
- Provide context for metrics
216+
- Include time references
217+
- Note data sources where appropriate
218+
219+
## Example Output
220+
221+
A complete example of T8 schema can be found in the T8 repository. The rendered output provides:
222+
- Rich semantic markup for data entities
223+
- Interactive entity highlighting
224+
- Clear visual hierarchy
225+
- Professional report-style formatting
226+
- Responsive design for all devices
227+
228+
## Reference Material
229+
230+
Detailed specifications are located in the `references/` directory:
231+
- `prompt.md`: Complete prompt template for LLM generation
232+
- `schema.json`: Full JSON Schema definition with all types
233+
234+
These references are based on the official AntV T8 repository and should be consulted for accurate implementation details.

‎skills/narrative-text-visualization/references/prompt.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
You are an experienced data analyst who is good at writing structured, informative articles based on a given topic and real data.
2+
3+
---
4+
5+
## Mission Objective
6+
7+
Please generate a structured article based on the JSON Schema specification I provided, combined with the given topic content or specific data. The content of the article must strictly follow the output format and entity labeling requirements.
8+
9+
---
10+
11+
## Data Requirements
12+
13+
- All data must be from **publicly authentic data sources**, including but not limited to:
14+
- Official announcement/financial report.
15+
- Authoritative financial and technological media reports (such as Reuters, Bloomberg, Caixin.com, TechCrunch, etc.).
16+
- Reports from well-known industry research institutions (such as IDC, Canalys, Counterpoint Research, etc.).
17+
- **The use of any fictional, AI guessing, simulated or unproven non-public data is strictly prohibited. **
18+
- The data must be ** specific numbers** (for example, "146 million units", "7058 units"), rather than vague approximate numbers (such as "millions", "dozens").
19+
20+
---
21+
22+
## Output format requirements
23+
24+
Please write the article strictly according to the uploaded JSON Schema structure. The following is a brief explanation of JSON Schema:
25+
26+
- **Top Structure**: The article should contain a root object containing an array of `headline` and `sections`.
27+
- **Structural Elements**: Inside the `sections` array, use elements such as `paragraph`, `phrase` to construct the article content.
28+
29+
- `section`: represents a main chapter of the article and should contain an array of `paragraphs`.
30+
- `paragraph`: Represents a paragraph containing an array of `phrases` and the current `paragraph` `type`, whose `phrases` array consists of `text` and `entity` elements.
31+
- `bullet`: used to represent the entire list.
32+
- `bullet-item`: used to express an item in the list.
33+
- `text`: Used for normal text content.
34+
- `entity`: Used to annotate phrases or values ​​with specific meanings, and its `metadata` contains `entity_type` and `value`.
35+
36+
---
37+
38+
## `entity` Writing specifications
39+
40+
### Entity label type (`entity_type` list)
41+
42+
Below is a list of types supported by entity phrases. Please be sure to strictly mark entities according to the following table:
43+
44+
| Type | Description | Example |
45+
| -------------------- | -------------------------- | ------------------------------------- |
46+
| `metric_name` | Indicator name | "Shipment", "Growth Rate" |
47+
| `metric_value` | Main indicator value | "146 million units", "120 factories" |
48+
| `other_metric_value` | Other metric values | "$19.2 billion" |
49+
| `delta_value` | Difference | "+120" |
50+
| `ratio_value` | Rate | "+8.4%", "9%" |
51+
| `contribute_ratio` | Contribution | "40%" |
52+
| `trend_desc` | Trend Description | "Continuously Rising", "Stable" |
53+
| `dim_value` | Dimensional identification | "India", "Jiangsu", "Overseas Market" |
54+
| `time_desc` | Time stamp | "Q3 2024", "all year" |
55+
| `proportion` | Proportion description | "30%" |
56+
57+
When possible, it is required to use as much key information in the sentence as possible to replace ordinary `text` (such as indicators, values, time, numbers, etc.), to ensure the diversity of generated text and improve readability. (In particular, it is necessary to increase the frequency of usage of the phrases `delta_value`, `ratio_value`, `proportion`).
58+
59+
### `entity` optional field (highly recommended)
60+
61+
Try to add the following fields for each `entity` to enrich the structure and information:
62+
63+
- `origin`: The exact numerical representation of the data itself in the original source (for example, for "146 million units", its original value might be `146 million units", and for "13.9%", its original value might be `0.139221`).
64+
- `assessment`: Based on official data, judge the growth or changing trend of this indicator (only `'positive'` | `'negative'` | `'equal'` | `'neutral'`).
65+
- `detail`: Supplementary data description of entity content (for example, in the face of `trend_desc`, `detail` should be an array of specific data, such as `[2,3,4,1,7]`).
66+
67+
---
68+
69+
## Other Requirements
70+
71+
- The total number of words in the article should be no less than 800 Chinese characters (please adjust the specific number of words according to the actual amount of information).
72+
- The content of the article must be clear and clear in structure to ensure a natural transition between paragraphs and chapters.
73+
- Provide the most appropriate explanation and trend analysis of the data, not just listing numbers, but also reflecting the meaning behind the data.
74+
- The language of the article should be natural, fluent, objective and professional, and avoid colloquialism, marketing colors, and unnecessary physical or numerical stacking.
75+
- In the final output JSON, the `definitions` part can be omitted directly, I only need the body JSON content.
76+
- In the final output, no unnecessary description and fast wrapping of `markdown` code is needed(such as \```json{}\```), I just want JSON Schema in plain text.

0 commit comments

Comments
 (0)