data-visualization-discipline

Data Visualization Discipline

This is the visualizationjudgment layer's sole authoritative source. Other skills reference it, they do not copy it—when a rule appears in two places, that is one more place that will contradict itself in the future.

Boundary: what is mine, what is not

Question	Ownership
What conclusion is this chart meant to lead the reader to? What chart type should be used? Mean or median? Can it be aggregated? How many colors?	This skill
How the report page is laid out, which component to use, what skin, interaction keybindings, browser rendering self-verification, recognition corpus register	`report-with-html:report-with-html`
How python-pptx renders native charts, secondary-axis lines not rendering in QuickLook, missing Chinese glyphs	`deck-creator:deck-creator`
What library to use to implement the chart	The chart stack already declared by the current project; if there is none, first research and choose a maintained library,hand-rolling a chart engine is forbidden

See the table at the end of the next section for the reference file list (anchored by stage, maintained in one place).

How this skill is organized (read this section before adding rules）

Rules are ordered bywhen you will think of it, not classified by topic:Define intent → validate data → choose form → encode → pre-delivery self-check。

Stages 1–4 each have a "handoff check", and stage 5 is the delivery gate (9 items)—together five checkpoints, and the one before delivery is the heaviest. This is not "one gate catching all rules"—that would swell the gate to a dozen-plus items, and once a checklist exceeds 9 items it starts getting skipped (Gawande). The mature approach ismultiple stops each minding its own: an aircraft has four checklists for taxi, takeoff, cruise, and landing, not one. So the criterion for this skill is:

Every rule must be caught by one of the five checkpoints. Not every rule has to enter the delivery gate.

This axis is not an aesthetic choice, it is an anti-bloat device. A rule set stacked by topic will keep growing—every incorporated accumulation adds a few more sections, and in the end no one can finish reading it, and no one knows where a new rule should go. So:

Before adding a new rule, first answer: at which stage is it recalled? By which checkpoint is its violation caught?

Can answer both → write it into that stage, state the criterion clearly in the body, and confirm that the checkpoint's artifact list will really expose it.
Can answer the stage but not the checkpoint → add it tothat stage's handoff check(stage handoffs are not subject to the 9-item budget, because it is asked only once at that moment). Only when it must be checked againbefore deliverydo you touch the delivery gate—and the delivery gate is a budget of 5–9 killer items, so adding one requires stating clearly who gets squeezed out. This admission rule also governs the existing inventory. The easiest thing to miss is not a new rule—it is theContent that was already in the file the day the rule was established—nobody ever went back and ran it through the filter("grandfather exemption"). But that can't be grounds to issue an unbounded license for refactoring either, so the criterion is scoped:Each time you make a substantive change to this file, take the opportunity to do the same check on the section you have already opened in this pass; do not open sections not involved in this pass just to hunt for problems.

After writing it, you must mechanically verify once—don't rely on memory—grep the new rule's keyword and see whether it shows up in thecheckpoint text.0 hits = it isn't attached to any checkpoint, go back to the items above and re-place it.

Three qualifications—if even one is missing, this action will lie to you:

The scope must be nailed down: the four "Phase N handoff check" reference blocks + the delivery gate'snumbered item body, artifact line, and exemption table. The exemption table must be searched, butits hits mean the opposite—see the next item.
>0 hits ≠ attached, you must read that occurrence. What was hit might be "this gate checks this thing" (truly attached), or it might be "this gate declares itdoesn't handlethis thing" (an exemption line).Hits only in exemption lines = counter-evidence: it precisely proves this rule is explicitly excluded from the check scope, equivalent to 0 hits, and you must go back and re-place it.

A ready-made example in this file: Gate 8's exemption line says "pure KPI number cards," while in Gate 8's body and artifact line 0 timesdoes that word appear. A new rule about "how KPI cards should be labeled" would, when grepped,onlyhit that one line—reading "this gate doesn't handle KPI cards" as "already attached," exactly backwards.
Search again with 2–3 synonyms: I once measured a false negative—searching "colorblind" got 0 hits in the whole document, but the file had consistently used "color vision deficiency" for the same thing; searching only one word would misjudge it as "not covered at all."
This action has verifying power only for the exit of "writing into the phase body". For something written directly into the handoff check, grepping inevitablyhits (that word is the one you just put in),which verifies nothing—that path must instead ask: "this sentence in the handoff check,is there a corresponding criterion in the body?" If not, it's a password with nowhere to be checked. For those judged to becase studies,skip this whole step: case studies shouldn't appear in checkpoints in the first place; 0 hits is the correct result, not a failure.

Why it must be mechanized: in one month in 2026-07 this admission rule wasviolated four times in a row by the same author—the most typical time, he had just finished writing a rule and on the spot forgot to attach a checkpoint, while directly above that rule was written "every rule must be caught by some checkpoint."All four times it was "I know this rule exists," and all four times it wasn't executed: The prose reminder is ineffective for the author himself; he is in the excitement of "I just figured something out," which is exactly the moment when he is least likely to turn back and self-check.The only thing that can save him is a runnable command.

Exception: positive actions are not gated. This skill has a rule that is not "what is forbidden" but "what should be done" (Stage 1, "When the drawing method has no obvious answer: produce candidates in batches"). This kind ofgenerativetechnique has no violation form by which failure can be judged—forcing a gate onto it would only cause false kills in the common case where "the drawing method is already obvious." The way to place it isto attach it to the nearest checkpoint as a conditional clause(after item 4 of the Stage 1 handoff), not to list it separately.
Can answermore thanone stage(both make sense, it is not that it cannot answer) → it most likely means it is two rules stuck together, split them apart, and each half goes to its own stage. Real example: "before making a chart, first ask whether it will be printed in black and white" can simultaneously argue for Stage 1 (audience × medium, asking early saves rework) and Stage 4 (the technical solution is homologous with "red and green cannot be the only channels")—the correct handling is to split:trigger conditiongoes into the Stage 1 handoff,technical solutionmerges into the existing Stage 4 rules. Cannot be split and is indeed one rule → put it in theearlierstage (early discovery is cheaper).
Cannot answer for any stage(none of them make sense) → either it does not belong to this skill (the medium implementation layer belongs to report-with-html / deck-creator, see the boundary table), or it is not a rule at all but awar story。

The anti-pattern section is a pure signposting table and does not write criteria—it has only two columns: "what form do you see" and "where to read." The same rule stated once in the body and once in the quick reference is one place that will fork in the future.

This rule itself has drifted: the first audit in 2026-07 counted 6 restatements and declared the work done after converging those 6; a month later, comparing item by item against the original sentences in the body: of the 29 items, 7 were originally signposts,16 were restatements from the body, and the other 6 wererules not present in the body at all(all of the "what should content be drawn as when it is not numbers" kind, because at the time the body covered only numeric charts).The lesson is that the criteria themselves must be mechanically executable—"is this in the body" must be checked by grepping the original sentences in the body, not counted from impression.

Reference file	When to read
`references/chart-selection-and-statistics.md`	Complete criteria and empirical sources for Stages 2–3: statistics, aggregation, chart types, color schemes
`references/visual-form-selection.md`	Stage 3, andwhen the content is not ready-made numbers: what shape qualitative / abstract / process content should be drawn as
`references/graphical-perception-science.md`	When challenged with "by what right is it drawn this way": sources from Cleveland & McGill / Bertin / Tufte / Few, and where these theories conflict with one another
`references/transaction-status-colors.md`	Stages 3–4, when transaction lists make it hard to distinguish charges, refunds, pending, canceled/failed: synthetic cases applying color semantics and a second channel, and verify by Gates 4–5 whether readers read it correctly
`references/monthly-budget-disclosure.md`	Stage 3, when a cumulative budget overview and monthly details coexist: use synthetic cases to distinguish monthly contribution from exact number lookup; interactive acceptance is handed to frontend-visual-qa
`references/operational-state-matrix.md`	Stage 2, monitoring, availability, or certificate status matrix: first distinguish current observations, unknown, and historical values, then check whether multi-path divergence and risks are visible

What to read first: if you are going to draw a chart by hand → just follow the five stages below; if the content is qualitative and you do not know what shape to draw it as → Stage 3 "When the content is not numbers" + visual-form-selection.md; if challenged with "on what grounds did you draw it this way" → graphical-perception-science.md cite empirical sources.

Stage 1 · Establish intent: who does this chart exist for

This stage determines whether the chart exists, not what it looks like. After finishing it, you should have: audience and format, the north star metric, and one sentence per chart: "The reader should conclude ___".

Meta-lesson: starting work without asking about business intent

What the client called out as thebiggest methodological problemis not ugly drawing, butstarting work without asking。

Visualization failures are almost never "not pretty enough," but ratherwrong judgment: treating process metrics as the protagonist, using warning colors to mark positive outcomes, treating extremes as the whole, giving the boss a screenful of interaction details, drawing charts with stale data, analyzing the wrong subject.

Before starting, ask each view: "What business question is it answering, who is it for, and what decision will be made after viewing it?" If the definition is uncertain, have the business side explain it specifically; do not assume on your own.

Visualization isthe expression of business judgment, not a drawing technique task.

What conclusion should this chart lead the reader to draw?

Original words: "What is this chart trying to express? What conclusion should the audience draw?" Again: "This is meaningless. Who do you want to show it to? What conclusion should they draw after seeing it?"

Criterion: write one sentence for each chart—"After reading this chart, the reader should conclude ___".If you cannot write that sentence, delete this chart, not change the drawing method.

First classify: a product has only one north star hard metric; everything else is downgraded. The north star = the one that directly measures business outcomes (in the dealer scenario = leads, not views), and visually it must be the most prominent; process metrics are deliberately downgraded and deleted if they should be.Before putting each metric on a chart, ask "Can it be tied to a decision (so-what → now-what)?" If not, it does not go in—this is the hard gate between "insight-driven" and "number listing."Deleting metrics is harder and more valuable than adding metrics.

war-story: the client repeatedly said "looking at numbers is useless" and "no meaningless numbers," and explicitly requested deleting completion rate and engagement rate—for the high-net-worth track they are negative signals. "High views ≠ high leads": 180,000 views producing 10 leads is worse than 50,000 views producing 18; letting views dominate the visuals will lead decision-makers astray into chasing traffic rather than outcomes.

Where this question most often fails:

Taking up a large layout area but achieving no effect = structural error. Original words: "You used more than half of a full PPT page to draw these three horizontal bar charts, but achieved no effect at all. This is a structural error I cannot accept." The criterion can be quantified: How much layout space a visual occupies determines how much insight it must deliver—occupying half a page yet only stating a common-sense point is a structural error, not "a slight waste."
Treating the author's data pipeline as insight: data extraction definitions, measurement coverage, "how many records did I capture"—that's what you care about; the audience wants business conclusions. Measurement completeness isfootnote-level definition, and never belongs in the main visual.Discriminating question: Show this visual to the final audience (boss / headquarters)—what decision will they make based on it?If the answer is about "whether you captured all the data or not" = pipeline noise, move it into the footnote.
Juxtaposing two quantities without being able to say why: juxtaposition itself is a claim; if you can't state the claim, don't juxtapose (see the dual-axis entry).
However many qualifiers you stuff into the title is how many things it's doing. Original words: "'Median single-item plays (by platform, not merged) · with viral extremes attached'—I can't understand it. What is this chart trying to express? You've mixed several different things." A chart name that needs three parentheses to be clear = it's three charts.When fixing one problem, don't pile the fix into the same chart too("by platform not merged" is a fix from the previous round; once stuffed into the title, this chart is simultaneously talking about the median, about by-platform, and about extremes).
Same unit of measure ≠ can share a chart: the series' "mechanism" must also be the same. That chart putclient information missing rate(electricity bill/rooftop—depends on whether the client is willing to say, commonly 70% across four companies) andsales-side action missing rate(whether follow-up was recorded—depends on whether sales did it, varying enormously from 0%–74%) into the same 9-series chart. Both have the unit "missing %" and the same unit of measure, butthe underlying mechanisms are completely different: readers can't make sense of them with the same explanation, hence "can't understand it."Criterion: can these series be explained with the same sentence for why they are high or low? If not → split into two charts, each telling one thing.
Chart-like imagery in decorative / atmospheric graphics (upward trend lines, dashboards, number cards) is subject to this same test, and is not exempt just because it's "only an illustration". The criterion is theshape-deletion test: delete this graphic from the image—what is lost, atmosphere or a data claim? If a claim is lost, it must answer "the reader should conclude ___." In pre-certification / no-data scenarios it can't answer, yet readers will read it as "this is what the data I'm about to see looks like." The reverse boundary also holds: abstract shapes that carry no axis, no numbers, and point to no real metric (glows / grids / gradients) are not charts and do not fall under this skill's jurisdiction—banning all decoration and letting fake charts pass as atmosphere are the same kind of thoughtlessness. The criterion only adjudicates "is this a data claim," not "can it be used"—when the adjudication holds but the conclusion sentence can't be answered, the action ispresent it to the owner for a decision; neither silent deletion nor silent retention is allowed: after the owner is informed, a decision to keep it is a legitimate closure; a reviewer deleting it first is equally an overreach (2026-08-12 login page battle case).

When the charting method has no obvious answer: batch out candidates, don't agonize over one version

Original words: "Make more visualizations for the clues, do a lot of them, different types, different dimensions, different data, and let me pick."

This skill is almost entirely in the "delete / cut / ban" direction—that is aconvergencetool. But there is a moment that requires the opposite action:the charting approach itself has no obvious answer(new metrics, new audiences, analysis angles never done before, cases that don't fit the "only charting approach" table below). At this point the correct actionis not to silently make one version and wait to be criticized, but to produce candidates in bulk across different types / dimensions / cuts, lay them all out at once, and let the owner choose.

This is not dumping the work back—the criterion is what you hand over：

✅ make it first, then let them choose: N charts actually drawn and laid out together; he glances and knows which one he wants (this is show, don't ask 's form during the divergence phase)
❌ ask without doing: "Do you want a bar chart or a line chart?"—that is outsourcing your work to him

Relationship to the convergence gate: the candidate stagedoes not go through the 9 gates(that would strangle divergence);after selection, only the chosen one enters the full stage 2–5 process.

Same-family capability: batch comparison of visual style directions → design-style-picker skill (what it does is "batch-generate different design directions for the user to choose," not guess a final draft).

Audience determines form: executives want static conclusion charts, operators want interaction

The same data shown to different people istwo different deliverables. First define "audience × usage scenario," then start.

Boss / headquarters / investors (reporting): take in at a glancestatic conclusion charts, no interaction / drill-down / piled-on details.
Operators / operations (daily): interactive tools with hover / drill-down / linked views.
Reporting needsone throughlinerunning through it, not fragmented.

war-story (2026-09-18): the favbase favorites workbench was misjudged as "the operator's daily tool" (interaction first, minimal explanation), and corrected: "this is not the operator's daily tool"—it is the browsing and curation interface for a team shared knowledge base, and a collaborator opening it for the first time must also understand "what this is, how to promote good things into the shared layer."For audience judgment, first check the subject in the user's own words("team shared," "show it to her," "for my own use"); do not default to "= the user's own daily operation"; when the subject is "we/team," the page must be self-sufficient for a first-time opener.

war-story: I wanted to make the four trends interactive (check boxes for accounts), and was rejected—original words: "The leader only needs to see one static, complete chart, not follow my eyes jumping around; he looks at the distribution of the four and this page is done." In a reporting scenario, interaction is a burden. Also: the "results screenshot" for a report and the "tool demo" for a product are two different things; don't mix them up.

But static does not equal isolated: original words "data without connections is meaningless"—a bunch of unrelated overview numbers is useless for decisions. (This sentence comes from aninteractive productcontext, where the fix was "make tabs able to jump";Put it on a static report. The fix is not to add interactivity, but to make relationships visible in the same chart.。）

A testable implementation: in a static chart, every number must have at least oneexplicitrelationship with a comparison number—same axis, same row, difference annotation, or "vs last week / vs benchmark."Deliverable: be able to write out this chart's comparison list(which number versus which number). If you can't write it, these numbers are isolated.

Six things that were done and then cut(conversion funnel / completion rate / benchmarking against the wrong object / all static / cards piling up vanity numbers / not asking intent)—their rules are scattered across the stages below.

Stage 1 handoff check——Before touching any data, you must have these four things in hand:

Audience × formOne sentence: reporting (→ static conclusion chart) or operating (→ interactive tool)?

Which metric is the north star, and why it qualifies as the north star—the criterion is "the audience directly relies on it when making decisions," not "it has the largest number."Purely qualitative deliverables(flowcharts / state diagrams, with no quantitative metric at all) are recorded as "not applicable"; items 1, 3, and 4 are still required. (This exemption also applies to Gate 1; it is written here becausethis is the first place it is needed, and making people see it only after flipping four hundred lines is as good as not writing it.)

For every planned chart, one sentence: "The reader should conclude ___",(for operational deliverables, use the variant "After reading, the reader should know the next step is to do ___" ; planned "charts"include decorative / hero images that the deletion-shape test rules are charts making a data claim—they will not be counted in the "chart list," and are precisely the category that most often bypasses this check entirely; for the criterion, see the decorative-chart bullet above).At this moment you have not looked at the data yet; what you write is the decision question this chart is meant to answer("should conclude which of the four is leading"), and at delivery Gate 1 calibrates it into the actual conclusion ("Guangzhou leads, at 3 times the second place").If you cannot write that sentence, delete the chart right here(the only exception: a decorative chart image cannot answer,so you do not delete it—present it to the owner for decision, see the decorative-chart bullet)—do not take it to validate data or choose a form; all that work is wasted.

Comparison list: for every number going on screen, what is its comparison object (vs last week / vs benchmark / another number on the same axis and row).

Conditional clause: if item 3 writes a conclusion sentence, butthe drawing method itself has no obvious answer(the "only drawing method" table in Stage 3 does not apply), the legitimate action isto produce candidates in bulk for the owner to choose from(see "when there is no obvious answer for the drawing method" above), not to force-pick one and move on. The candidate stage does not go through the gate; only after one is chosen does it enter Stage 2.

Why put it here instead of relying only on Gate 1: choosing the wrong north star will chain-decide the ordering and visual weight of all charts; discovering that only before delivery means redrawing everything. And writing these four things down before starting takes only a few minutes. Gate 1 checks the first three of them again before delivery—that is the last interception, not the first time to think.The comparison list in item 4 is checked only here, once: What it determines is "whether there is any relationship between these numbers"—that's something that happens before drawing. If you only discover before delivery that the numbers are isolated, it means redoing the entire page.

Stage 2 · Validate the data: does this number hold up?

No matter how correct the chart is, if the numbers are wrong the entire thing is false. The output of this stage is: for every number that goes on screen, you can explain why its statistic was chosen that way, whether the denominator is clean, and whether it can support the claim you want to make.

What decision will this number be used for? (determines the statistic)

Original words: "Great principle: look less at the mean; it is meaningless."

Choose by use, not by distribution shape: reporting a "typical value" → median + quantiles; estimating the "total pie" → mean (and state that it is used to infer the total); skewed / multimodal distribution / outliers → make the distribution itself visible, don't give just one number.

A large gap between mean and median is itself a skewness alarm. Under a multimodal distribution, don't report either alone—they will fall in the "nobody" position.

Skewness also has a time dimension, and it is easy to miss: for numbers aggregated by week / by month, first check whether it is contributed bya few days. If "64 leads this week" includes 32 from two days and the other five days fall back to single digits—that is apulsefrom a single piece of content going viral, not steady-state capability; using the weekly total to judge that "this account can perform" will overestimate its reproducibility.Criterion: what share of the total do the top-2 time points account for? If more than half, you must make this visible on the chart(draw at daily granularity, or note "of which X days contributed Y%").

Anscombe / Datasaurus prove that datasets with identical statistics can look completely different:look at the distribution plot before reporting aggregate numbers。

Before calculating any rate / proportion, first count how many "unknown" values are in the denominator—treating "don't know" as "no" is the most common silent falsification, and it systematically lowers any positive rate. After it was pointed out, I admitted it myself: "I fudged it—I forced a ratio using a field containing a large number of "unknown" values; the denominator did not exclude unknowns, and I treated "don't know" as a definite value." For the full criteria (whether unknowns enter the denominator, thresholds must be judged, and if coverage is too low don't draw a distribution), see references/chart-selection-and-statistics.md §1d。

Has the final period not finished yet? (the denominator for a time series is the number of days)

The most common silent falsification in weekly / monthly reports:the last period is not over yet, but it is drawn on the same line as complete periods. Its denominator is "days elapsed", not a week—so the number is naturally too small, and the "crash" readers see is caused by the calendar, not by the business.

Marking a color and an asterisk is not enough. Real validation: a four-panel weekly report drew the incomplete week in a light color + red asterisk + footnote, and a reader who just wanted the conclusion still got stuck—"so this 178 for Hunan, did it really drop, or is the week not over yet?This directly determines whether I should go question Hunan, but I can't judge it."

Choose one of three; there is no fourth approach：

Don't draw it—if the final period is incomplete, it does not go on the chart; the chart only draws up to the last complete period;
draw it on a separate line—Do not connect it into the same polyline / same group of bars as complete periods (connecting them is an invitation for the reader to make that invalid comparison);
Switch to a comparable basis—daily average, or a "same-basis progress comparison" (the first 4 days of this week vs. the first 4 days of last week).This conversion must be applied to all periods in this chart, not just the incomplete one—converting only the last point creates two bases within the same line, which is more insidious than the original problem (in the example, "the first 4 days of last week" is what this means; don't just read the three words "choose one of three").

Criterion: Can the reader tell, without looking at a footnote, that this final-period point is "not comparable"? If not, it's not done—footnotes are for people who scrutinize, not for people who glance.

One basis across the whole product: cutoff date, definition of a week, and source can only have one set each

If two kinds of "week," three cutoff dates, and two data sources appear on the same page, readers won't try to guess which is right; they willdiscount all the numbers on the entire page。

Actual reader quote: "One page, three cutoff bases, and I don't know which to trust." Elsewhere: "On the same page, 'one week' has two calculation methods, and I can't reconcile them." An even harsher one: "The top half says four outlets post 29–42 items per week in total, while the bottom half says 78 items were posted this week...The same type of number comes from two sources and differs by a factor of two; if that isn't explained clearly, I will discount all the numbers on this page."

Criterion: Write down these three things, and across the whole product there can be only one value for each—cutoff date、definition of the period(calendar week? rolling 7 days? Friday to Thursday?), anddata source. If they truly must differ (for example, two sources are different systems to begin with),align them explicitly on the chart once: state clearly where the difference comes from, andhow the reader should understand that difference—whether one is more accurate (say which), or both are accurate and the difference itself is what this chart is meant to convey.Do not just write each one separately in two footnotes—that is not an explanation, that is leaving the contradiction for the reader to discover.

Can this batch of data be merged? (Verify aggregation validity)

Quote: "What is the point of merging median play counts across different platforms? Why should different platforms be merged?"

Before merging, first prove it can be merged: stratify by the main grouping variables (platform / channel / region / period / basis version) and check once;if the directions are inconsistent, do not report only the aggregate number。

The "overall median" calculated from segments with incomparable bases does not describe any real population—it is neither the typical value for platform A nor that for platform B. The correct approach is to report them separately; if you want the overall picture, report the total.

The mechanism is Simpson's paradox (the two classic cases being Berkeley admissions and COVID CFR); see §2 for details.

Data is the foundation: real > pretty

No matter how correct the chart is, if the data is wrong the whole thing is fake.

For monitoring, availability, or certificate matrices, read first operations status matrix case: Use the project's observation contract to judge the current evidence, keeping unknowns, source failures, and multi-source disagreements visible. The status criteria are still maintained by the project implementation; this skill is responsible for what conclusions this evidence can support and whether readers can see the risks.

Real data is the bottom line—never fob people off with stale snapshots. Before plotting, first confirm: is this data "live right now" or "a snapshot from some day"? Key external numbers must be traceable to an authoritative real-time source.

war-story: I calculated a number from an old csv in the repo, the business side confirmed another number, then I pulled the real-time source + recalculated per the definition, and everything reproduced the confirmed value, provingit wasn't the data conflicting, it was my snapshot being stale + me not applying the definition。
Definitions often involve human judgment; key numbers are subject to human confirmation, and the definition is noted on the chart. Start date / end date / exclusions go in the footnote—the same metric under different definitions becomes a point of dispute.
KPI confidence tiers: contractual hard obligation / verbal alignment / benchmark threshold—these three have different confidence levels, so don't label them all as "contractual KPIs."
PII de-identification: for tables containing phone numbers / identity information, any chart shown to third parties must be de-identified (show "count + profile," not contact details).
Label data credibility: likes / reposts and similar have systematic distortion (bot inflation), so presentation must label credibility—don't treat it as genuine popularity.
Normalize dirty data before plotting: cross-platform fields are inconsistent, dates come in multiple formats, and column counts differ across sources—first do field mapping + tolerate missing columns + mark completeness.When data is missing, go straight to the business side to ask for it; don't make do with dirty data.

External presentation also has 5 red lines that "trigger refunds if violated"(lead tiering / don't use generic engagement rates for high-net-worth individuals / label distortion / a single week of bad data cannot falsify the methodology / don't own the conversion rate).

Correlations must be honest: use trends for weak correlations, never pretend to precise attribution

When the data can't support precise attribution,honest weak correlation > pretty fake precision。

war-story: leads were only recorded down to "platform + date," not to the specific video. So we usedweekly-aggregated trends side by sideto see whether two peaks are in sync, rather than fabricating "this video precisely brought in this lead," with a footnote explaining it.

What to cut, what to plot—distinguish in one sentence：What gets cut is conclusions the data can't support; what gets plotted is the missingness itself. If 30% of the denominator is unknown → plotting the unknown as an explicit segment is legitimate (that's a fact); forcing a "fillable rate" out of this data → cut (that number itself is wrong).

Downgrade before cutting: if you can honestly downgrade, downgrade (label as weak correlation + footnote); only cut when even a weak correlation can't hold up, or the number is necessarily wrong.

Corresponding iron rule: charts the data doesn't support get cut directly—good drawing can't save wrong data. A conversion funnel was once praised as "very well drawn, should be kept," but was ultimately still cut becausethere was no precise attribution and the calculated conversion rate was wrong—"there's nothing to tell with wrong data". Presentation quality and data credibility are two separate rulers; if the latter doesn't pass, no matter how high the former is, it can't be kept.

Why: Pretending to be precise will make decision-makers base decisions on false causality, which is far more dangerous than "we can only see a weak association."

Stage 2 handoff check— Before moving into form selection, answer four things for every number that will go on screen:

Statistic: What is its purpose (typical value / extrapolate a total) → based on that, did you choose mean or median? How many entries in the denominator are unknown, and how were they handled?

Source and definition: Is this numberreal-time at this momentor a snapshot from some day? Whose verification is authoritative for the key figures?And: right now, set one value each for the cutoff date, period definition, and data source of the entire deliverable, and write them down. This step issetting the spec, not verification—the chart has not been drawn yet, so there is nothing to verify; its role is to give every later chart something it can conform to. (If something truly must differ, write clearly right now where the difference comes from.) For each display unit in the operations matrix, mark the current evidence or the unknown reason according to the above case; multiple conflicting paths for the same target must not be hidden by an aggregate number.

Is the end of the time series complete: Has the last period finished? If not, handle it by choosing one of three options: "do not draw / start a separate line / switch to a comparable definition"—not by marking it light-colored and adding an asterisk。

Publishability: Does it contain PII (mobile phone numbers / identity information)—de-identification is an irreversible issue; once you pass this point there is no second chance; for metrics with systematic distortion (brushing/fake traffic), have you marked credibility?

Gate correspondence: Gate 6 (aggregation and attribution health check), Gate 7 (denominator health check).The nature of the data source(real-time or snapshot)and PII these two items are checked only once in this stage and do not enter the delivery gate—they are upstream in nature; if you discover only before delivery that a snapshot has expired, all the earlier work is wasted. Division of labor with Gate 3: This stagesets the spec(set the three values and write them down), Gate 3 verifies compliance(after all charts are drawn, compare them one by one to see whether anything has drifted). Both places mention the same three terms, but the actions are opposite—one is "decide," the other is "audit."Doing only the former will drift(once set, no one checks, and when drawing, everyone still writes their own version);doing only the latter is too late(only before delivery do you discover two week definitions, and all charts must be redrawn).

Stage 3 · Form selection: what should it be drawn as

Only after the data is confirmed usable does form come next. The order cannot be reversed—if you pick the chart type first and then discover the data does not support it, all the earlier work is wasted.

Chart type semantics: each chart answers only one class of question

Stacking = part-to-whole, not comparison of series

Original words: "Do not stack the number of leads; what is the point of stacking different dealers into one chart? What is the stacked chart for? A line chart is enough here."

One-sentence criterion: Does the reader want to comparethe partsor look atthe composition of the total? Compare the parts → Line chart(independent per series) or small multiples; only when the total composition is the sole concern and there are few time points → stacking is permissible.

Why: within stacked bars the judgment is by length and there isno shared baseline(Cleveland level 3), whereas juxtaposed bars use position judgment (level 1); structurally onlythe layer flush against the baselinehas a fixed, readable starting point, while every layer above it starts from a shifting point. The "fluctuation" of a middle layer in a stacked area chart is a superposition of the shifts of the layers above and below—anillusion。

There is also a more insidious one：zero is invisible in area/length encodings. If a series is 0 this period, it occupies no pixels at all—nothing on the chart tells the reader "this one was zero this week". First judge whether this zero supports the chart's conclusion or the reader's next step: decision-relevant zeros are often exactly what most needs to be seen; zeros with no narrative work should not be forced onto the screen just because they exist in the data table.

A real reader's exact words: "'Who is zero this week' is invisible on the chart. I onlysubtracted from the totaland then discovered: Suzhou W2 is 0, Hunan W1 and W3 are 0. I simply wouldn't notice one missing block of color, yet 'a certain one had not a single lead for an entire week' is exactlythe thing I most need to know。"

This is a structural consequence of the encoding, not a chart-maker's oversight: any chart that "represents quantity by area/length" (stacked, area, bar, treemap, bubble) has this blind spot. If the zero supports the conclusion,the fix is not to change the chart type, but to give the zero an explicit form that does not encode length—a direct 0-value label with role and unit, a grid background tone, a one-line ✓/✗ badge, so that "none" and "a tiny bit" look visually different; if it does not support the conclusion, hide it—do not leave a bare 0。

Same-family criterion: for any encoding where "none = no pixels," first ask—does this zero support the conclusion or an action? If yes, go on to answer "what does it look like, and what are its role and unit"; if no, hide it explicitly. You cannot both deny it any role in the conclusion and leave a dangling number for the reader to guess at.

Dual axis: mixing dimensions is forbidden, same quantity in different units is harmless

Exact words: "What is putting median plays and weekly publish volume in one chart supposed to show?"

Split it into two cases; don't apply a blanket rule:

Mixing dimensions(median plays vs publish volume, revenue vs growth rate, absolute value vs ratio) → forbidden. The two axis ranges can each be scaled arbitrarily, which means the author can manufacture any degree of correlation or crossing at will, and readers will read the artificially created proximity as a relationship.
The same quantity in two units(°C/°F, yuan/thousand yuan) → mathematically equivalent, harmless.

Alternatives: split into two charts stacked vertically sharing the x-axis ▸ index them onto the same axis ▸ use a scatterplot to address correlation directly ▸ demote the secondary series to an annotation.

Sankey/flow diagram: nodes are entities, not actions; apply the same color semantics to itself

2026-08-07 battle case: a "lead transfers among four dealers" Sankey diagram was sent back four times in a row, and the root cause every time was treating this chart type'sstructural defaultas a given, without first asking "where is this chart type inherently prone to go wrong?"

Criterion 1: Node names must be entities, not action phrases. If the left and right columns representtwo roles of the same set of entities (sender/receiver, export/import, source/destination), the right column's nodes should use thesame nameas the left column, and you should not create verb phrases as node names just to "disambiguate." The original words: "Why is your receiver an action?"— disambiguation should rely onstructureto solve it (give self-to-self quantities their own separate link), not on changing names.

Criterion 2: Self-to-self flow must not be cut or merged just because of the intuition that "the same entity should not flow to itself." There are three common wrong ways to handle it, from worst to least bad: ① delete the data entirely and degrade it into a text annotation outside the chart—erasing a piece of real data that may account for a considerable share of the total from the chart; ② forcibly merge "every entity's self-to-self" into one shared endpoint (for example, a single unified "local" node)— these four thick bands have nothing in common except that they are all literally called "local"; four different sources flow into the same endpoint, and readers will naturally look for "why are these four the same thing," and if they cannot find it, it is "incomprehensible"; ③ (correct) model "self-to-self" as src-X → dst-X this link itself, and then dst-X's total naturally equals "self-to-self" + "received from elsewhere"—this is the standard bipartite flow diagram drawing method (trade flow diagrams have "China · export" and "China · import" with the same name for the same reason); this is not an invention.

Criterion 3: The color semantics table (see "color is semantics" above) also governs Sankey diagrams, and it is even easier to fail here. Sankey diagram color bands usually allocate visual weight by "share size," so authors easily confuse "which category has the largest area" with "which category should use the emphasis color"—whereas the alert color (red) in the rules isexclusiveto negative things / things requiring intervention. If a category that is "large in area but actually an opportunity / room for development" is painted red, the reader's first reaction is "there is a problem here," and the semantics are read directly backwards.First judge whether this category is a positive result, an opportunity needing attention, or pure background in the argument, then apply the corresponding color from the color-is-semantics table, and do not follow the intuition of "large area gets the emphasis color."

Criterion 4: If the camera/interaction wants to "zoom in to look at a certain edge," the target is the node the edge reaches, not the entire edge itself. The path of a Sankey link naturally spans the entire width of the chart (from the leftmost source to the rightmost endpoint). Any camera/cropping logic that "frames this edge and then zooms in" will compute a bounding box close to the size of the whole chart, and the resulting zoom ratio will always equal 1 ("zoom does not take effect"). To achieve a real zoom-in, the target should be thenode the link reaches and its neighborhood, not the link's own bounding box.

The rest

Pie chart: usable when categories ≤3 and only "roughly what percentage" is needed; for comparison or many categories → bars.
Series ≥ 6 → split into small multiples, andall panels share the same x/y range, same axes, same color mapping. Five or fewer may remain a single chart, but if lines cross frequently and readers cannot follow one, split it too.
The value axis for bars must start at 0(For vertical bars look at y, for horizontal bars look at x; length encoding, a truncated axis directly inflates the Tufte lie factor);Line charts do not need it(position/slope encoding, forcing 0 would flatten real changes).

When the content is not numbers: first construct a dimension; if you cannot, do not turn it into a chart

The entire section above is about what chart type to choose when "you already have a batch of numbers". But many artifacts need to visualizequalitative content—processes, comparisons, checklists, plans, materials. The failure mode on this other side is completely different:it is not choosing the wrong chart type, it is having no visualization at all, merely putting text into a graphical container.

Overall criterion: first construct a dimension. Ask, "In this pile of content, what is ordered / has magnitude / has direction / has contrast?"—find that quantity and encode it as geometry (position / length / size / direction).If you cannot construct a dimension, do not force it into a chart, writing it as text is more honest; putting a colored border around text is not visualization.

The five most common kinds of "fake visualization":

Magnitude information written as text labels("≥9 high frequency", "large amount of change", "≥1M: 4 items ≥100K: 16 items"—this kind of purely textual ladder) → encode it as bar length / number of cells. Original words: "This kind of pure text is really hard for me to understand." Pointing at "Clue 4·50%": "This is not very easy to understand."
Two columns / grid of small squares, position carries no semantics at all → space must speak: up/down = high/low value, left/right = evolution, large/small = weight. Original words: "A listed, arranged little square with no meaning at all, I cannot see what the two of them can actually compare." Splitting a list into left and right columns = no analytical structure.
"Comparison" made into a side-by-side enumeration, without marking "what the other side is like" → add the comparison side, and make it theevidenceof insight (for the use of value stacks see references/visual-form-selection.md）。
The content itself is visual(finished clips / shots / screenshots / frames)yet abstract squares are drawn instead → switch to real images (real thumbnails / player / real screenshots), so readers can see for themselves.
Multidimensional data for a single object spread out into a row of text fields → condense it into a rich data card (rating cells + collapsible original text).

Operational artifacts have one more item: the concluding sentence for interface / workbench types is not "the reader should conclude ___", it is "after reading, the reader should know the next step is to do ___". Original words: "This alert workbench is a bit messy, I cannot tell what I should do." Messy = incomprehensible = the information architecture should be redone, not the styles adjusted.

The complete shape-selection toolbox (mapping tables, geometric component library, value stacks, multi-view decomposition, gap visualization) → references/visual-form-selection.md。

Draw one object only once

Original words: "One moment four progress bars, the next a four-cell grid, then again four square cards... completely violates the methodology." "Why should the four clues' trends require two charts instead of one continuous trend?"

The criterion has two layers, do not mix them up：

Within the same view(Same page / same screen): Count how many times the same batch of entities is drawn, and whether the shape differs each time—>1 time and different shapes = violation. The fix is tomerge into one place, or have each place answer a different question。
Cross-viewDo not judge by shape; judge by axis: each view claims a different decomposition axis (see references/visual-form-selection.md §Multi-view decomposition). So "one overview + one detail per dimension" is legal and does not count as duplication—don't use single-view criteria to kill it by mistake.

Before starting, first define theunique drawing methodfor this batch of entities, and don't switch while drawing.

Define the unique drawing method by "number of entities × number of dimensions"：

N entities × few attributes → one matrix: entities = fixed rows (in descending order by the North Star), attributes = columns, and the North Star column is made into bars (common baseline, highest precision). This is theuniquedrawing method for this batch of entities.

North Star = the metric the audience directly relies on when making decisions, not the largest number. In dealer scenarios it is usuallylead volume(result) rather than play count (process). If you're unsure about multiple metrics, ask the requester; don't decide on your own—wrong ordering will cascade through Gate 4 to all charts.
1 entity × multiple dimensions → one overview + one detail per dimension fordifferent analytical questions.
N entities × few attributes × time series(most common in weekly/monthly reports) → one homogeneous trend chart per metric(same entities, same shape, same color, same order) + optionally one snapshot matrix.Using the same shape to draw different metrics for the same batch of entities does not count as duplicate drawing—the criterion for duplication is "the same quantitydrawn twice," not "the same batch of entities appearing twice." The snapshot matrix answers "who is leading right now," while the trend chart answers "how it changed"—these are two different analytical questions.
Multiple sections coexisting → each section must bea different analytical question, not the same question with changed geometry.

The granularity of "the same batch of numbers": onlysame metric + same definition + same time rangecounts as duplication. The matrix's current-week value and the trend chart's last point overlap but do not count as duplication (one is a cross-sectional metric, the other looks at change over time); true duplication is "the same metric drawn as bars and also listed as a table."

For the boundary case of cumulative budget and monthly detail, see Monthly Budget Overview and Details。

Switch to the audience perspective to find duplication (the criterion is here; the artifact is collected by Gate 3)

Original words: "Have you reviewed our various legends from the audience's perspective?" "Why do the table and chart duplicate each other?"

Counting "how many times an entity is drawn" from the author's perspective will miss two types ofhidden duplication—the audience thinks at a glance "drawn again," while the author thinks "it's different":

The same data sliced again at a different granularity: Province distribution chart + city distribution chart; for municipalities/provincial capitals this causes "Shanghai Province = Shanghai City". The author was thinking of two dimensions, but viewers see the same set of numbers plotted twice.
Plot the same quantity again under a different name: In the combo, the "accounts posting this month" bars + the "cumulative participating accounts" line—what viewers see is two curves of account counts.

Upgrading the criterion: From the author's "how many times did I plot it" to the viewer's—"Would viewers think these two charts are telling the same thing?" List all the charts and ask this about every pair.

Which one to delete when deduplicating: The right answer is often "replace the duplicate one with the better one", not deleting the one the user named.A chart the user explicitly praised / asked for = must-have; when deduplicating, it is the one that stays—provided its data credibility passes(see "Associations must be honest": presentation quality and data credibility are two separate rulers; if a praised chart's data is untrustworthy, cut it anyway).

What is being praised (used to judge which chart is must-have)—what he praises is alwaysinsightandinformation delivery, never "good-looking":

"But I think yourinsight about play concentration and regional inversion is very good, keep it up." "On this page, thematrix and discrete trendsare both good" "It isreally strong on tables, and itscolor-coded markers, ah, are all pretty good"

Inference: The value of a chart = it carries anactionable insight, not aesthetics. To judge whether a chart is must-have, ask "Can another chart replace the insight it reveals?", not "Does it look good?"

Battle example: to eliminate the duplication between the "province account ranking × play ranking", the explicitly praisedinversion tornadowas deleted, and this was corrected; the right answer is "use the tornado to replace the two independent rankings"—both deduplicating and preserving the comparison chart the user wanted.

Table discipline

Original words: "Why write so many numbers in a table? Who has time to look at these numbers? Why write so much text in a table? Who has time to look at this text?"

The default failure mode of a table is "stuff everything in and let the reader find it".

In transaction lists, amount and status are easily read as the same thing; when debit/refund/not debited are hard to distinguish, read transaction status color case, and follow the column value judgment below and the color semantics in Phase 4.

For each column, first ask "does it have business value", and cut it if not—columns are not better the more complete they are.
Numerical values that can be turned into graphics should not stay in the table: proportion → bar, status → color badge, rating → filled bar. Leave the table forvalues that need precise lookup.
Compress text cells to the shortest: status / metadata labels are downgraded to small badges and do not deserve a column of their own.
Squeeze out blank space: Compact line height, single-line display, don't let content float in the middle of the cell—original words: "Can't you see there's a big blank space in the middle?"
Right-align numeric columns + tabular-nums, so digits align for vertical scanning and comparison; bold the row-start anchor column + nowrap.
Tone down the header(smaller gray text + heavy bottom rule)—the header is the skeleton, not the content.

Delete tables that duplicate a chart outright: the same batch of numbers should not be both drawn and listed.

Stage 3 handoff check—after completing this stage you should have in hand:

The single way to draw this batch of entities(write down that sentence: N entities × few attributes → one matrix / N entities × time → one isomorphic trend chart per metric);

The deduplicated list of charts and tables；

The column list for each table, with a sentence next to each column saying "what is its business value"—columns you can't answer for get cut at this step, don't carry them into the coding stage.

For each chart that uses area / length encoding, what is the zero-value treatment—first write whether it supports a conclusion / action; if yes, then write its explicit non-length form and role unit ("0 leads" / "add a row with a ✓✗ badge" / "grid background showing the empty cell"); if no, write "no decision-relevant zero value, hide it".

For any visual whose content is not ready-made numbers(process / comparison / list / material): write downwhat its dimension is and what geometry it is encoded into. If you can't write the dimension, change it back to text at this step—don't let it enter the coding stage in the form of "a graphical container holding text"; at that point it will only get its style tweaked, not changed back to text.

Gate correspondence: Gate 3 (pairwise comparison from the audience's perspective), Gate 8 (axis and tick-value scan). The value of a table's columns is checked only at this stage—the delivery gates don't re-check it, because columns that should be cut should have been cut long ago.

Stage 4 · Encoding: how quantities become shapes

Once the shape is decided, you still need to decide "which visual channel carries which quantity". Errors at this stage are the most insidious—the chart looks normal, but the proportions are wrong and the colors say the opposite.

Encoding channel discipline

General principle (Munzner): match the importance of the variable to the salience of the channel—the most important quantity uses the most efficient channel,one channel encodes only one thing。

Readers need to accurately read or compare quantities → position / length. Color intensity has the worst precision, and area is systematically underestimated.
Color carries only category or threshold, not quantity. When you want to use "color intensity to represent magnitude", you can only use a lightness scale, and only promise "see the order", not "read how many times apart".
On the position / length channel, the encoding of quantity must be purely linear 长度 = k·值，Additive constants are forbidden(the color channel is not subject to this constraint—it only promises "order" not proportion, so heatmap colors using sqrt a square root to compress extremes is legitimate). Original words: "Why are Southwest and the other four regions both at 2% playback share, but their two green bars have different widths? Why are the 4, 16, and 53 of the quality funnel not proportional in width?" 宽 = 140 + 值/max·440 This kind of "fixed base + ratio" directly destroys the sense of proportion—4:16:53 drawn out is not 4:16:53, and the audience sees through it at a glance.
The final visible painted span is what encodes length: the width / SVG path length in the formula is only an upstream value; what the viewer reads is the span after compositing the fill together with the visible border, stroke, line cap, marker, pseudo-elements, and so on. For quantitative marks, do not use min-width, fixed end caps, or fixed borders to inflate small values; very small positive values can preserve their true subpixel geometry, moving readability to an external number, parentheses, or a leader line. If the business truly needs a minimum dot that is "seen if it exists," draw it as aseparate presence mark explicitly declared not to encode quantity, and it must not be mixed into the measured bar length.
The numbers on the labels must come from the same source as the geometric encoding and use the same rounding. If "Southwest 1.6%" and "Other 2.2%" both round to the label "2%" while the bar widths are drawn from the true values, you getthe same label with different widths, a self-contradiction.Choose one of two fixes: either use the true values everywhere (label with one decimal place to distinguish them), or use the rounded integers everywhere (compute the bar widths from the integers as well).

Dynamic quantitative visualization: cause and effect must be co-located, co-timed, and from the same source

For a static chart, it is not enough for labels and geometry to match; animation makes the audienceautomatically pair temporally adjacent text and changes as cause and effect. If action A appears and only then does the increment from action B suddenly push the total up, the audience will misattribute B's growth to A—even if the data itself is not wrong, the animation is still telling a lie.

First pass the transition semantics baseline shared by all quantitative animations: preserve object identity and a common scale across frames;duration > 0 's tween must at one strictly internal moment 0 < p < 1 still be a valid data graphic, and only atomic jumps check just before and after the boundary. Pure time-series playback, filter transitions, and sorting animations do not need fictional actions or increments, but they must not use invalid intermediate frames to imply relationships that do not exist.

The trigger condition for causal binding depends on the narrative, not the chart type: when a quantitative mark changes over time and the frame uses action/event labels, incremental/cumulative narration, or an operation sequence to present some action as the cause of this change, apply the causal binding below. If pure time-series playback, filter transitions, or sorting animations have no action labels or causal claims, the causal subitem can be recorded as "not applicable," and only the transition semantics baseline above applies.

Each cumulative track first declares { track, unit, initialTotal }, then builds a quantitative change as one atomic event:{ id, track, operation, label, delta, from, to, at, duration, sourceMeasure?, groupId? }。operation explicitly state whether this is an addition, a reclamation,transfer-out、transfer-in or a reset;from / delta / to must use the track's same unit. When the label also has a source scale (such as "14k characters"), put it into sourceMeasure: { value, unit }，do not guess-convert the character count into context tokens。segment geometry [from, to], segment-attached label,+delta, cumulative value to, and playback/step anchor are all derived from this one event, and hard-coding them separately is forbidden.

Cross-track transfer is represented by a paired event sharing groupId : exactly one transfer-out and one transfer-in, with both ends sharing at / duration, each computing from / delta / toon its own track; the anchor order requires onlywithin each trackStrictly ordered; different tracks sharing the same beat is not prohibited. Create a separate transfer ledger row. { groupId, outEventId, inEventId, loss, conversion? }：loss is a non-negative axis unit, equal to the amount explicitly discarded / compressed / lost, and loss > 0 there must be a corresponding mark in the chart. When both tracks use the same unit, out.delta + in.delta + loss = 0must hold; when the units differ, an explicit conversion: { fromUnit, toUnit, rate, reason }must be given, first convert to the same unit, then verify conservation. You cannot use "transfer" to hide the discrepancy, nor merely explain in prose a discrepancy that has no structural field and no mark in the chart.

Same position: the action label must be attached to the mark / interval it actually occupies; if it does not fit, use parentheses or a leader line pointing to that segment. Titles, legends, and sidebars may restate it,but they cannot be the only mapping between the action and the geometry。
Same beat: the label, increment, interval growth, and cumulative value start at the same event-time coordinate and use the same normalized progress. Easing may change speed, but it cannot create a second clock; while the bar is still tweening, the cumulative value must also show the same progress, or all four must jump together at the boundary frame.
Same-frame reading order: action +Δ → cumulative T: a significant jump or two adjacent increases must be broken out event by event, and the viewer must read them in this order; the arrow here is a semantic relation,not two temporal stages of first playing the increment and then updating the total, and they must still be on the same beat in time. It is forbidden to suddenly replace the old total with the new total, letting the previous action take the blame for the next action.
Step mode must leave evidence frames: every causal change must have at least a pausable frame before the change and a pausable frame after it stabilizes; processes such as reclamation and transfer must also have visible intermediate frames. The keyboard gate / step must not skip the frame that establishes the causal relationship.
Density is not a reason to move labels away: when there are many events, keep only the direct annotation of the "current event"; completed events can be de-emphasized; do not permanently cover everything with all labels, and do not push the current label back to the title area for viewers to map themselves.

Explanatory copy without an anchor is not evidence: if, after deleting the explanatory text / insight sidebar under the title, readers no longer know which operation caused which segment of growth, then the geometry has not completed its expression; if decoding is unaffected after deletion, that copy should be deleted.

Color is semantics: warning colors are exclusively for negative, and positive outcomes must never use red

Original wording: "Why does this clue use the red warning color?"

Before choosing colors, first give each quantitya qualitative classification: positive / negative / neutral / alert.Alert colors must be exclusive and must not be reused for positive.

Nature of the quantity	Color use
Positive outcome (clue / growth / achievement)	Green, or neutral ink-black large text
Alert / abnormal / risk	Red (exclusive, not used elsewhere）
Needs attention / to-do	Amber
Neutral data	Ink / blue

Why: color is the viewer'sfirst glancesubconscious input, faster than text. Red ≈ alarm; putting it on good news causes instant misreading, and it also clashes with the alert red on monitoring pages—at a glance it looks like something has gone wrong.Before fixing a color, first ask "is this number good or bad".

Two supporting points:

Colors can borrow domain metaphors(energy projects use power-generation green / solar amber / data blue); colors carry their own industry language.But domain-metaphor colors must not clash with semantic colors—in the same artifact, if amber is already the semantic color for "to-do / in question," it cannot simultaneously be the domain color for "solar," otherwise readers cannot tell what this patch of amber is saying (general principle: one channel encodes one thing only). If they clash, give the domain concept a different channel (icon / position / label), not a different semantic color.
Accent colors used sparingly: the primary color is used only as an accent at key points.Testable criterion: count how many places the primary / accent color appears on one screen—more than 3 and it is no longer an accent.
Heat colors must compress extremes: use 0.05 + 0.5*sqrt(value/max) such as square-root scaling plus a base opacity floor, otherwise one extreme is uniquely dark and the rest are washed out, so no differences can be seen.

Number of colors and identity

Original words: "What are these colors supposed to express? There are 9 colors in one chart." "There are only four dealers, so why is the legend color different in every chart?"

The practical upper limit for categorical colors is 6–8(most ColorBrewer qualitative palettes cap out at 8–9; Adobe Spectrum: 6 colors start becoming hard to understand, 12 colors are extremely hard).What is counted is categorical colors(the ones encoding entities/categories);semantic colors(passing green / failing red / status badges) are counted separately and do not count toward this upper limit, but they themselves must be directionally consistent across the whole report. If exceeded,do not add a 9th color, but instead: merge the long tail into "other" ▸ split into small multiples ▸ highlight a few key series + make the rest uniformly gray ▸ annotate directly at line ends and delete the legend.
The same entity must have the same color, same position, and same order across charts（"Same position"= consistent position in presentations with fixed slots: matrix row order, legend order, small-multiple cell positions; in a line chart, the line positions are determined by the data, so "same position" here meanslegend order). The most common violation isletting the plotting library assign colors automatically by order of appearance—the same company ranks 2nd in chart 1 and 5th in chart 3, so the default coloring will inevitably be scrambled.The first move for a multi-chart report is to build an "entity → color" mapping table, reference it throughout, and pass it in explicitly.
The reverse constraint also holds (Qu & Hullman 2018):different fields must use different hues, and palettes must not overlap, otherwise readers will mistake two unrelated fields for the same one.
Semantic colors (good/bad, up/down, passing/failing) are directionally consistent across the whole report.
Red and green must not be the only means of distinction. About 8% of men have red-green color vision deficiency—and the "positive green / alert red" recommended in this section happens to be the most common pair.Every place that uses color to distinguish status must also have a second channel: shape, position, direct text labeling, or a lightness difference (red and green are often the same lightness in grayscale, so the lightness difference must actually be measured, not assumed). When categorical series colors are taken from tokens, they must likewise pass a color vision deficiency (CVD) check.

Every number must clearly state "what dimension, what unit"

Original words: "What does this number in the monthly publishing trend on your first page mean? What dimension, what number is it? What is its unit?"

For every number on the screen, the reader must be able to answer three things on the spot:What entity, what dimension, what unit it measures。

At least one place among the axis title / chart title / direct label value must state the unit clearly (items / ten-thousand views / % / people).
When multiple "quantities" appear on the same screen, each must indicate what it measures ("4 videos" and "4 leads" cannot both be written as just 4).
Definitions (cutoff date / start date / exclusions) go in footnotes, butunits and dimensions must be attached next to the numbers, not only in footnotes.
In dynamic visuals, 0 must also have a role: within the same local composition, it must be possible to tell whether it is an axis starting point,本次 +0, a cumulative value, or a remaining amount; when its position already pins it to the axis scale, there is no need to repeat "axis starting point", but a bare 0cannot be left floating where there is no corresponding mark. Hide zero values that do no narrative work; if they need to be shown, write their role clearly, and do not invent a nonzero value just to eliminate 0 .

Self-invented definitions must come with "how to read them": if terms you invented appear in the output (window / fluctuation multiple / covered days / normalized points), put on the first page acolumn-by-column plain-language dictionary(one sentence per column: "what it is, how it is calculated, what greater or less than means"). Original words: "Window, outside the window, clean background, what do these even mean? You cannot make me fully understand what you want to do just by looking at this table." Column names are self-explanatory only to the person who invented them.

Criterion: point randomly at a number on the chart—can you say "this is the Y dimension of entity X, unit Z" without looking anywhere else? If not, it is not labeled enough.

Chart house style: direct labeling replaces axes

This is the opposite ofthe accepted default of charts and chart libraries—not "a coordinate-system chart with data labels added", but "using direct labels to replace the coordinate system":

Label every mark directly: white value text embedded in bars, a value above each point on a line, values following bars in a bar chart. Readers never have to trace along the grid to look up axis ticks.
No ticks, no grid: draw only the necessary axis lines. Once all values are labeled, grid lines have no work to do (Tufte: chartjunk).
Draw thresholds / reference lines into the chart: dashed line + small inline label ("floor 50k", "inflection point · net profit 830k"),no legend, no footnote, attached next to the geometry.
Label density fallback (the clear exception for multi-point lines): when value labels exceed about 12–15, they begin to overlap each other; 4 series × 13 weeks = 52 labels will inevitably become a blur. At this pointlabel only the end point + extremes + key inflection points, and keep a lightweight y-axis scale as a fallback. Criterion:if you can label everything, label everything; if you cannot label everything, keep the axis—one of the two must hold—"neither fully labeled nor with an axis" is not allowed, because that would leave readers with no way to check unlabeled points.
When using a mature chart library,The mark specification is still calibrated according to this section,— the library's default coordinate system and skin are not the delivery standard.

Tone: visualization for high-priced products must have its tone set first

To support the "professional / high-priced / trustworthy" narrative (selling to clients, reporting to headquarters, pitching to investors),cheap AI default aesthetics will directly destroy the narrative— no matter how accurate the data is, it cannot support the story of "being able to deliver a high-priced system."

Typical AI slop signatures (if present, redo): Inter / Roboto fonts, purple gradients, large rounded-corner cards, rainbow color schemes, chart library default graphics, center-stacked "dashboards."

The tone of "selling expensive": warm white paper-feel background + hairline thin-line separators (no thick borders or heavy shadows) + number scannability (tabular-nums + stable column widths) + restrained colors + primary color used very sparingly as accents + almost no rounded corners.

Approach: set the tone before writing code; when giving design directions,give 2 options with previews for the user to choose, don't just silently make one version.Quality first, don't use deadline as an excuse to cut corners.

Webpages / dashboards are alwayslight theme(only terminal CLI is dark). Original words: "Removing this is correct, we don't want a black shell."

Stage 4 handoff check— after completing this stage you should have:

Entity → color mapping table(explicitly passed to the chart library, not relying on it to auto-assign colors by order of appearance);

Channel assignment table: which quantity goes to position / length, which goes to color (and color only encodes category or threshold). If length is used, attach a line of rendered geometry sampling:最小正值 + 一组拉开差距的值 → 理论跨度 → 最终 painted span → 是否被 min-width / border / cap / 伪元素扩张；

Tone comparison: list the fonts, corner radius values, and primary color occurrence counts you used, and check them item by item against the AI slop signature checklist (Inter / Roboto, purple gradients, large rounded corners, rainbow color schemes, chart library default graphics, center-stacked dashboards).These are all checklists that can be written down, not "I feel it's quite restrained."

Transition semantics table for quantitative animation: write 补间 / 原子跳变 → 对象身份锚点 → 共同尺度 → 内部帧或边界帧. When the dynamic causal narrative trigger conditions are met, also write 轨道 → 轴单位 → initialTotal and each event's operation / 动作 → from → +delta → to → 时间锚点 → 直接标注落点, confirming that all fields come from the same track and event; when the label additionally includes source scale, list it separately as sourceMeasure, and it must not be mixed into the same definition. When cross-track transfer exists, also provide the groupId → out / in 事件 → 同拍 → loss / conversion → 差额图内 mark pairing table. When there is no quantitative animation, mark the whole item as "not applicable"; when there is only pure playback/filtering/sorting, provide only the transition semantics table, and do not fabricate a causal table.

Gate correspondence: Gate 2 (hidden-text self-test), Gate 4 (color checkup), Gate 5 (reader decoding spot check), Gate 8 (axis and tick-value scan), Gate 9 (scale and dynamic semantics validation). Tone is checked only at this stage — it is a design-time decision, and discovering the font is wrong before delivery is already too late.

Stage 5 · Pre-delivery self-check

Pre-delivery self-check gates (9 items · the backbone of this skill)

The prerequisite for going through this gate: first actually render the artifact and look at it. All nine items below are checks on therendered final productQuestion—getting the code to run does not count as delivery; starting to fill the gate before rendering is equivalent to answering against an imagined chart. This item applies unconditionally and is not exempted by any exemption (the exemption table governs "whether this item must be answered," not "whether the chart must be viewed first").

This is a DO-CONFIRM checklist: first complete the work according to the rules above, then stop at the point of "about to hand over the deliverable" and confirm item by item. Each item requires anobservable artifact, not a self-assessment—"I think this chart is quite clear" cannot be judged as failed, while "count how many colors there are" can.

Write down the answer to each item; the one you cannot write is the one that failed:

Positioning + per-chart conclusion sentence First answer the two artifact-level questions:Who is the audience (reporting / operations) → does the form match (static conclusion chart / interactive tool)? Which metric is the North Star → is it the most visually prominent one? Then for each chart write down "the reader should conclude __" (operational artifacts—interfaces / workbenches / alert consoles—use the variant "after viewing, the reader should know the next step is __", see Stage 3).Delete charts for which you cannot write it(exception for decorative figure images: if you cannot answer, you do not delete it; present it to the owner for a decision—those decided to be kept get a separate line at the end of the conclusion-sentence list: "decorative figure · presented to owner · kept", not counted in the chart count or sentence count). If a conclusion sentence contains causality ("A brings about B"), the basis must also be marked. Each conclusion sentence must be followed by a sentence "so the audience should do __"—a sentence that is syntactically complete but cannot be attached to any action ("publication volume stable at 29–42") can pass the gate literally, but that chart should be deleted. This is the artifact form of the main text's so-what → now-what criterion:the gate does not merely require the sentence to exist; it requires it to point to an action. Finally answer oneartifact-levelquestion:What is the one thing most worthy of attention in this period → on which chart is it explicitly marked?（When the artifact has no concept of a time period—evergreen artifacts such as architecture diagrams / SOP flowcharts / compliance archives—read "this period" as "this output": the one thing most worthy of attention in this thing.Do not force a sentence just to satisfy the format, because a hollow headline produced that way exactly violates what this rule is meant to prevent.) (Annotation, large text, circled notes, a separate line conclusion—not "its data is in some chart", but "the reader will see it at a glance".) Having all per-chart conclusion sentences does not equal the artifact having a conclusion: each chart says its own thing, and the reader still has to assemble it themselves.The most important thing is precisely the easiest to bury in the color blocks—a real reader has to pick through cell by cell to discover "the source with the most submissions has zero leads," and that is the biggest thing on the whole page. When the artifact contains no quantitative metrics(purely qualitative flowchart / state diagram), record the North Star item as "Not applicable: purely qualitative artifact has no quantitative metrics"—audience + form and conclusion sentences are still required. This is the only exemption in Polaris, written here because the exemption list starts from clause 2. (Outputs: one line for audience + format determination, one line for Polaris, a list of conclusion sentences with figure count = sentence count,one line for this issue's headline + where it is marked）
Text-covering self-test First actually cover the text(render a screenshot with the text layer hidden, or turn off all labels),then read from that imagethe specific relationships, and finallycompare them one by one with the conclusion sentences in clause 1— if something is in the conclusion sentences but cannot be read after covering the text, that image failed to visualize it. Writing the list from memory or from the data does not count(this is the same loophole as clause 9, "reading from the generated code does not count"): the author knows A>B, but when the two bars are almost equal in length the difference lives only in the labels, and it cannot be read once they are covered, yet a faker writes it anyway. Legitimate downgrade when source code is unavailable and only the finished bitmap exists(give this a proper status, otherwise honest people have no path and are forced to fill it in from memory):do not re-render; instead look only at the geometry and do not read any labels at all— covering the text area with a hand / cropping it out also works — then still read the relationships from the shapes, still compare them one by one with the conclusion sentences, and state clearly "downgrade reason: only the finished bitmap, no source code to re-render".What is downgraded is the method of obtaining the image, not the act of "reading": you still must actually look at the image and read it; writing the list from memory or from the data still never counts. The text-covering test tests the "relationship structure", not "identity": who is who only needs to be anchored by color / position. What qualitative / geometric figures read isstructural relationships(order, direction, branching, emphasis), not numerical comparison. For dynamic causal diagrams, this gate only checks what is still readable after hiding all text:magnitude, order, and interval structure, and does not require naming the actions; gate 9 separately makes onethat covers only the external narrative and keeps the in-figure direct annotationsscreenshot, specifically to check action identity and interval binding. The two pieces of evidence have different responsibilities and must not be passed off as the same screenshot. (Outputs: text-covering screenshot + list of relationships read from the screenshot + one-by-one comparison with the conclusion sentences, all three complete)
Pairwise comparison from the audience's perspective List allfigures and tables, and for each pair ask "would the audience think these two are about the same thing?" (a figure and a table presenting the same set of numbers also counts as duplication.) For those judged "no", also write out what makes them different("Figure 1 is the trend of metric A, Figure 2 is metric B, different quantities") — a row of bare "no"s is formally compliant and has zero information value; this is the only clause in this gate that can be filled in mechanically. For those judged "the same quantity", do one more arithmetic step: do the numbers in the two places match? If they do not match, it is a hard bug, not something a footnote can save — a real reader encountered "about 30 items per week" on the top half of the page and "78 items this week" on the bottom half, and his reaction was "I will discount every number on this page". At the same time, check the definitions: does the whole deliverable have only one set each of cutoff date, period definition, and data source? Mechanical conditions that trigger this step: when the same number appears in ≥2 places in the same artifact (hero, body text, readout sentence, gap bar all count), it must be mutually checkable—either produced or asserted at a single point by the generation script, or a place-by-place comparison record must be left in this gate's artifact. If both places rely on the same hand-written number, nothing will contradict it (2026-09-17: "5 test orders" was hand-written into four places and never asserted by the generation script, passing two rounds of review, until the acceptance tester independently enumerated and caught that it was actually 6 orders). Also answer one sentence for each chart: what kind of question does its chart type answer(part-to-whole / comparing series / seeing trends / seeing distributions / seeing correlations),is what the reader needs to do that kind? If not, change the chart type.This question must be asked here—gate 8 checks only axes, gate 9 checks only scales; a stacked chart used to compare series can pass all green under those two gates, and that is exactly the kind of error called out most harshly. (Artifact: pairwise list + verdict and one-sentence reason for each pair + number comparison for the same quantity in two placesone line + whether every chart obeys the three values set in stage 2(list the ones that do not) + one line per chart: "chart type → the question it answers → the question the reader needs"）
Color checkup Does an entity→color mapping table exist? Do all charts reference it? Is the same entity in every chartcolor, position, orderconsistent? In every chart, are thecategory colors ≤ 8？ semantic directions correct—does alert red appear only on the negative direction? Are good / bad and up / down color directions consistent across the artifact? Judge the four sub-questions separately, and each may be marked not applicable: if the artifact has only one chart → the mapping table and cross-chart consistency items are not applicable; if there are no category colors → the color-count item is not applicable;the semantic color direction item must be answered whenever the artifact uses any red / green / amber semantic color, and if none is used, record "no semantic colors". Is there a second channel besides red and green—everywhere state is distinguished by color, does shape / position / text / brightness difference occupy at least one more? (Artifact: the mapping table itself + category color count per chart + one sentence "alert colors are used only in ___" + one sentence "the second channel for state is ___")
Reader decoding spot check Randomly spot-checkat most 3numbers on screen; if fewer than 3, check all of them. For each, write "this is the Y dimension of entity X, unit Z"; if you cannot answer, it is not labeled enough. When dynamic screens show bare 0, current / target, or delta / total, at least one of the spot checks must hit this kind of easily confused number; unless it is an unambiguously positioned axis tick, the decoding sentence must state its role in the current state. If the artifact containsself-invented terminology(window / covered days / normalized points, etc.), does the first page have a column-by-column plain-language dictionary? Self-invented visual encodings must likewise be decodable——What do your invented lightness shades / dashed-vs-solid lines / dot-pattern fills / semi-transparency mean? Does the chart say? (Real battlefield case: a bar turns lighter to mean "this week's data is incomplete," the legend explains nothing, and the reader's first reaction is "is this another entity group?")Criterion: any encoding that is not the universal convention of "color = category, length = quantity" must have its meaning written right there. (Product: at most 3 decoding sentences; if fewer than 3 numbers, decode all + whether a dictionary page exists)
Aggregation and Attribution Checkup For each aggregate number:What is its use (typical value / infer total) → based on that, was mean or median chosen? Have you checked for divergence between mean and median? Has stratified checking been done, are the directions consistent, are the definitions comparable? For any number totaled by time(this week total X items / this month total):What share of the total do the top-2 time points account for? Over half = a pulse, not a steady state; the chart must make this visible. For any chart claiming conversion / attribution(funnel, conversion rate, "A brings B"): the data supporting this chainreally exists? If it does not, downgrade to weak association or cut it. (Product: one line per aggregate number "use → statistic → stratification result";for time totals add another line "top-2 time points / total = __%"；If not stratified, you must write all three: "not stratified + why not + what happens if the direction is inconsistent"——writing just the words "not stratified" is confessing and then being let go)
Denominator Checkup For each rate / proportion: what is the denominator total, and how many of those are unknown? Are the unknown ones excluded or explicitly drawn? (Product: write each rate as 分子/分母（其中未知 N 条，处理：排除 / 画出））
Axes and Value Labels Scan Are there dual axes with mixed units? Do the bars'value axisstart from 0 (for vertical bars look at y, for horizontal bars look at x)? Is the axis itself faithful——are the tick intervals on a time axis / ordered axis uniform? (Months with no data must leave a gap and must not be skipped: position is also an encoding of quantity, and skipping a slot amounts to drawing the position encoding as nonlinear. This item also applies to full line charts and is not exempted along with Gate 9.) Label density: either label every value or keep axis ticks——one of the two must hold, and it is not allowed to have neither all labels nor an axis. (Product: yes / no + location; one line for the labeling strategy)
Proportion and Dynamic Semantics Verification Pick a chart with length encoding, measure the geometric values of three marks against their true values; are the proportions consistent? Are the label rounding bins from the same source as the geometry? The sample must includethe minimum positive value, plus a set of values whose gap is large enough to measure stably; the latter verifies proportions, while the former specifically verifies whether it is inflated by a minimum width or fixed decoration. Do the structural hard gate first, then measure the numbers: any min-width, fixed padding / border, stroke cap, marker, or pseudo-elements: as long as the visible quantitative span is extended beyond the theoretical interval, it is a direct FAIL; even if the selected large-value pair happens to fall within a lie-factor of 0.95–1.05, it cannot be whitewashed—that is a distortion diagnosis for the entire chart, not an implementation tolerance for an additive base. If decoration is contained within the theoretical interval and does not change the final endpoints, it is not a violation. Measurement must lock onto the same real rendering conditions: record the viewport, browser zoom, and DPR, use the span from the common zero baseline to the visible end, and uniformly use CSS px. For HTML, first read the quantitative element's getBoundingClientRect(), and also audit box-sizing / min-width / padding / border / transform / ::before / ::after; when the visible paint crosses the DOM rect, convert the screenshot pixel endpoints back to CSS px. For SVG, first map the geometric endpoints to the screen through the actual transform, then audit stroke-width / linecap / marker / filter; when there is outward expansion, likewise take the visible endpoints in the screenshot as authoritative. DOM endpoints by default allow 0.5 CSS px of rounding error; screenshot endpoints by default allow 1 device pixel ÷ DPR, and a more permissive threshold must be stated before measurement with the instrument reason; you cannot loosen it after seeing the results. subpixel marks do not infer exact ratios from screenshots: use DOM / SVG screen geometry to prove that the real layout span is from the same source as the true value, then use screenshots to confirm there is no common visible base width; move readability to external labels. Real bugs are often in the rendering layer (min-width holding up small bars, border end caps enlarging small values, container clipping). For any quantitative animation, first perform a transition semantics check: a tween animation must capture 变化前 → 严格内部帧（0 < p < 1）→ 稳定后, and the second frame must not pass off the end boundary as a substitute; verify the object identity, the common scale, and whether the intermediate graphics are still valid. An atomic jump has no internal frames, so instead capture before/after the boundary and prove that all relevant marks switch at the same boundary. If the dynamic causal narrative trigger conditions of Phase 4 are met, then perform causal synchronization and sampling: at strictly internal frames of the tween, verify whether the action label,+delta, interval endpoints, and cumulative value are the same event and the same progress; for atomic jumps, verify whether the four switch at the same boundary. Collect evidence for every transition that would change the Gate 1 conclusion/current headline; among the remaining events, if there is a group of adjacent ordinary transitions, sample one group. If there is no ordinary adjacent group, cover all remaining events and record "no ordinary adjacent group"; do not force a sample. Step-by-step playback must be able to stop at a stable evidence frame for each event. Then perform acausal occlusion test: occlude external narration such as titles / legends / sidebars, but keep the direct annotations inside the chart; can the viewer still point out "which action caused which segment, and why the total changed"? If not, it is not bound. Division of labor between structural assertions and visual sampling: all causal events use program assertions to - from = delta; for each continuous track, assert that the anchors are strictly ordered within the track,first.from = initialTotal、events[i].from = events[i-1].to、events[i+1].at > events[i].at + events[i].duration, the stable-frame cumulative value = event.to, and the final cumulative value = last.to. Each event has at at + duration a reachable stable step anchor; autoplay must also actually render that stable frame. Reset is an explicit operation. Each transfer groupId must be matched to exactly one transfer-out and one transfer-in, with the same at / duration at both ends; when in the same unit, assert out.delta + in.delta + loss = 0 and loss >= 0，loss > 0 the same amount of in-figure difference mark must be found; when units differ, an explicit conversion from the ledger must be used to normalize before making the same conservation assertion. Axis rebase is not a data event, and one must not take the opportunity to change cumulative values. Asserting only from source code cannot replace transition/causal screenshots, and looking at only a few screenshots cannot replace full-event assertions. (Output: one line for rendering conditions and measurement tolerance + three sets of "true value → theoretical span → final painted span", among which the smallest positive-value sample and its fixed decoration audit are marked; when there is quantitative animation, add transition three frames/boundary comparison; when dynamic causal narrative is hit, add a causal synchronization table + causal occlusion screenshots + full-event assertion results; when there is cross-track transfer, add paired / same-frame / conservation / difference mark results)

This gate cannot self-certify as green: items 1, 3, 4, 5, 6, 7, 8, and 9 all require specific content or numbers to be written down; if you cannot write them, it was not done—there is no answer of "I checked it."

Exemptions are judged by conditions, not by chart type(a gate that wrongly kills healthy inputs costs the whole gate being reflexively bypassed next time—so exemptions must be complete and easy to judge):

Item	Under what conditions it is recorded as "not applicable"
2	The output is a pure table / has no graphical mark at all (after redaction, nothing readable would remain anyway)
3	Only the "pairwise comparison" subitem may be recorded as not applicable: there is only one visual output in this instance (only one chart, or only one table).The "per-chart chart-type semantics" subitem is never exempt—chart-type misuse iswithin a single chartan error that can be made (a stacked chart being used to compare series), which is exactly the error this skill worries about most; exempting it along with "there is only one chart" is equivalent to opening a back door for the situation that most needs to be blocked
4	There is only one entity / single series,or there is only one chart in this instance(there is no cross-chart identity to speak of); when there is no categorical color, the color-count item is separately recorded as not applicable
5	There are no numbers on the chart at all (pure qualitative geometry / process diagram)—butboth the dictionary subitem for self-invented terminology and the decoding subitem for self-invented visual encoding must still be answered: qualitative outputs may likewise contain self-invented status jargon, and self-invented encodings such as dashed/solid lines / halftone dots / transparencyare precisely most common in qualitative charts
6	There is no mean / median / rate-type aggregate number at all, and there is no conversion / attribution claim
7	There is no rate / proportion in the chart
8	There is no axis and no bar (pure qualitative geometry, pure KPI number cards, an axisless dashboard… parentheses are examples, not exhaustive:the criterion is "is there an axis / is there a bar," not "quantitative or qualitative"）
9	Proportion subitem: no mark with length encoding (all line / scatter / pure qualitative geometry);Transition semantics subitem: no quantitative mark that changes over time;Dynamic causality subitem: The causal narrative trigger condition for stage 4 is not met — including no quantitative mark that changes over time, or pure time playback / filtering / sorting with no action labels, causal claims, or action sequences presenting actions as causes of change. A dynamic line chart must still be checked as long as it has such causal narrative. Record the three items as not applicable separately; only when all three are not applicable is the whole item not applicable

To record "not applicable", write out which condition was triggered(e.g. "Item 9 proportion sub-item not applicable: all line chart, no length encoding; transition semantics sub-item not applicable: static chart, no quantitative mark that changes over time; dynamic causality sub-item not applicable: only expresses post-filter state changes, no action labels or causal claims") — writing just the three words "not applicable" is equivalent to skipping.

Outside the main text

The following three sections do not belong to any stage: one section coversrework period(not the delivery period), one section isquick reference(does not repeat the main text), one section covershow this skill itself grows。

After being criticized: step back and do a systematic analysis, don't patch point by point

Original words: "rather than just individual patching and fixing... you must step back and think, systematic analysis, what concepts are in here? What dimensions? What entities? How are they counted?" "You can go top-down, from whole to parts, and give 1~3 pages. It must be a systematic presentation, not a pile of data, not repetitive verbosity."

When receiving feedback that "this chart doesn't work",the default reaction should not be to fix those named spots one by one— what is named is often the symptom.

When to step back (don't overreact to single-point criticism): when ≥2 placesare named, or the criticism points tostructure("can't understand it", "no throughline", "poor information density", "who are you showing this to") → step back and redo the following three things. Single-point, local criticism pointing to a specific value or a certain color → just fix that spot in place.

When stepping back, do these three things:

List clearly: whatconcepts / dimensions / entitiesare in this artifact? How is each counted?
Whole → parts: first give an overview, then break down along different axes (see references/visual-form-selection.md §Multi-view decomposition).
Only then startchanging the chart.

Anti-pattern: treating "patching and fixing" as the response — changing the three named spots, with the overall structure unchanged, and the same problems criticized again next round.

Anti-patterns (redo if any appear)

This section is a quick-reference table, not a second set of rules. Each entry only gives "what form you see" and "where to read the criterion" — writing the same rule twice is a copy that will diverge in the future.New rules must not be written only here: if something cannot be written into any stage, it means it has no checkpoint to catch it; handle it according to "how this skill is organized".

Seeing this form	Where the criterion is
Sentences / bullets / table text with a colored border added to pass as a visualization	Gate 2 text-occlusion self-test · Stage 3 "when the content is not numbers"
Magnitude information written as text labels ("≥9 high frequency", "4 items/16 items/53 items")	Stage 3 "when the content isn't numbers"
Two columns / small grid squares, position carries no semantics	Stage 3 "when the content isn't numbers"
"Comparison" made into a side-by-side enumeration, without labeling how the counterpart is doing	Stage 3 "when the content isn't numbers"
The content itself is visual (finished video / screenshot) yet abstract squares are drawn	Stage 3 "when the content isn't numbers"
Multi-dimensional data for a single object spread out into a row of text fields	Stage 3 "when the content isn't numbers"
The viewer doesn't know "what am I supposed to do"	Stage 3 "when the content isn't numbers" § operational artifacts
Drawing data-retrieval definitions / measurement coverage as a chart, mistaking it for insight	Stage 1 "what conclusion do you want the reader to draw from this chart"
Starting work without asking about business intent	Stage 1 "meta-lesson"
Process metrics more prominent than hard business metrics	Stage 1 north star tiering
A row of cards stacked with incomprehensible vanity numbers	Stage 1 north star tiering (deleting metrics is worth more than adding metrics)
The chart title needs multiple parenthetical qualifiers to be clear	Stage 1 § number of qualifiers in the title = number of things
Series within the same chart have different mechanisms	Stage 1 § same dimension ≠ can share a chart
Chart imagery in decorative / hero images goes live without a shape-deletion verdict or presentation to the owner	Stage 1 "what conclusion do you want the reader to draw from this chart" decorative image bullet (shape-deletion test)
Treating "unknown / null" as a negative value and counting it into the proportion	Stage 2 § denominator unknown · gate 7
Building a funnel / conversion rate without reliable attribution	Stage 2 "correlation must be honest" · gate 6
Using stale snapshots / not labeling definitions / not de-identifying PII	Stage 2 handoff check
Using stacked charts to compare trends across series	Stage 3 "chart type semantics"
Dual axes with mixed dimensions	Stage 3 "chart type semantics"
Nodes in the right column of a Sankey diagram named with action phrases like "transferred to X" / "X retained"	Stage 3 "Sankey diagram / flow diagram" criterion one
In a Sankey diagram, "self-to-self" volume is deleted or multiple entities share a single endpoint	Stage 3 "Sankey diagram / flow diagram" criterion two
In a Sankey diagram, the category with the largest share is colored alert red	Stage 3 "Sankey diagram / flow diagram" criterion three · Stage 4 "color is semantics"
The camera/crop wants to frame an entire Sankey edge and then zoom in, but the computed zoom ratio always equals 1	Stage 3 "Sankey diagram / flow diagram" criterion four
The chart and table present the same batch of numbers · table piled on screen	Stage 3 "draw each object only once" · "table discipline"
The source proportions are correct, but min-width / borders / end caps / pseudo-elements widen small marks; or the label value ≠ the final painted span	Stage 4 "encoding channel discipline" · gate 9
The animation's intermediate frames are not valid data graphics, or the action label is only in the title/sidebar, or the label appears first and the bar segment/total suddenly jumps a beat later	Stage 4 "Dynamic Quantitative Visualization" · Gate 9
One chart > 8 category colors · The same entity changes color and position across charts	Stage 4 "Number of Colors and Identity" · Gate 4
Positive results use alert red	Stage 4 "Color Is Semantics" · Gate 4
Adjacent but differently meaning numbers placed next to each other · A dynamic frame left hanging with a bare, role-less `0` · Internal jargon appears on screen	Stage 4 "Label Every Number with Its Dimension and Unit" · Gate 5
chart library default styles / Inter font / purple gradient / large rounded corners	Stage 4 "Tone"
Dark shell (webpage / dashboard)	Stage 4 "Tone"
Deliver as soon as the code runs, without taking screenshots to check the visuals	Gate 9 (must be measured from the rendered output)

Iteration: corrections must be written back on the spot

Correctionis this skill's eval set, but it only holds when it lands somewhere that will be read in the future.

show, don't ask: make something real and show it to them, converge through real feedback, don't go ask with a proposal. The matrix chart went through 6 iterations, and only after showing a screenshot of each version to the user did it converge to acceptance—describing a proposal cannot buy that kind of feedback。

When corrected, seriously investigate the root cause, don't be stubborn: the moment it's pointed out, immediately acknowledge it + analyze why it's wrong + fix it correctly. (These two points and the write-back below are one set: show gets the correction, investigating the root cause clarifies why, and write-back keeps it from happening again.)

Copy the original words verbatim, don't paraphrase—precise words carry calibration signals, and paraphrasing flattens them out. "This is completely meaningless, who are you trying to show it to?" teaches a hard boundary; "the user hopes the chart has a clear purpose" teaches nothing.
Write back on the spot, change both layers: change both the output and this skill's rules. Changing only the output = invisible to every future run.
When writing back, check whether this skill happens to teach exactly the practice that was just banned—a correction often falsifies an existing instruction, and keeping the old one guarantees recurrence.

But relying only on corrections will grow systematic blind spots—so blind testing must be done regularly

Almost every item in this skill was reverse-engineered from a single criticism. This means it systematically covers onlyhas been criticized beforeforms; equally fatal ones that happen not to have been criticized are invisible to it—andcan never be discovered from the inside, because the people reviewing it and the people writing it share the same list of criticisms.

Blind testing method(proven effective in 2026-07, producing 5 rules completely absent from the main text in one run):

Take areal, rejected output(not a made-up example);
send in a fresh-context agent,give it only the chart, not this skill, and have it play the real audience ("you are the client-side decision-maker, you just want the conclusion"); The boundary of "give only the chart": giveAudience identity + one sentence of business context("four dealers doing short-video customer acquisition"),you don't givethis skill, you don't give your design rationale, you don't give "what I want you to discover." The criterion is—what you give iswhat a real reader already knows(he knows what his company is doing), what you don't give iswhat the chart is supposed to convey(who's good and who's bad, whom to intervene with). A real decision-maker doesn't look at the chart in a vacuum; putting him in a vacuum is actually unrealistic.
Ask three things: what conclusion can you draw from each chart / where is it hard to understand or suspicious / how would you go back and have someone redo it;
Take every item it reportsand grep it back into this file one by one—whatever you can't grep is a blind spot.

Why you must "not give the skill": a reviewer who has been given the skill will evaluate this file within this file's own framework, and can only verify self-consistency, not completeness.A reader who hasn't been given the skill is the only channel that can form a judgment independently of this file.

Three commandments: ① the grep criterion will itself lie to you ("not comparable" hit three times, all false positives from other contexts)—you must look at context, and set up a control group of "known-covered" items to prove the grep itself works—method: pick 3–5 specific rules from this file that youare certain are covered(such as "the same entity must have the same color across charts"), usethe same grep criterionto check them, and all of them must hit; if any are missed, the criterion itself is flawed (case / line wrapping / synonymous wording), fix the criterion first before looking at conclusions; ② gaps found by blind testing go back into place according to the admission rules above,you may not stuff them directly into the anti-pattern quick reference; ③ rerun once after every substantive change to this skill—blind spots will regrow as the content changes.

The 5 items from the first blind test: a cycle not completed by the end and a complete cycle on the same axis, zero invisible in area encoding, inconsistent definitions across deliverables, the same quantity not matching across two charts, this period's biggest anomaly not explicitly marked.Not one of them was in the original criticism list.

Next Step

After chart judgment is done, hand it to the implementation layer according to the form of the deliverable:

图表方案已定（图型 / 统计量 / 配色映射 / 布局）。

A) HTML 报告页 → report-with-html:report-with-html（架构、组件货架、皮、渲染自验）
B) 可编辑 PPT → deck-creator:deck-creator（python-pptx 原生图表 + 渲染陷阱）
C) 当前项目的图表栈里实现 → 用项目已声明的库，mark 规格按本 skill 的 house 风格校准