Terminology standards and synonym handling

Problem

Define strict product terminology for chart and visualization concepts while preserving backward-compatible interpretation of user vocabulary and synonyms. Examples include reserving map for geographic maps, preferring encoding over mapping for visual channels, and distinguishing shaded tables from true heat maps so the product and docs stay precise without becoming brittle to user phrasing.

Context

The graph library already owns chart-type naming and visual-language decisions, so terminology choices here will directly affect product copy, AI prompting guidance, schema labels, chart detection, and documentation. Current code and docs already expose terms such as heatmap, map, and encoding, but those terms are not governed by a single standard, which creates drift risk between internal implementation language and user-facing language.

Relevant places to inspect include dataface/core/compile/types.py for chart type names and labels, dataface/core/compile/chart_type_detection.py for automatic chart recommendations, and dataface/ai/skills/building-dataface-dashboards/ for agent-facing vocabulary. Existing documentation already hints at some desired distinctions, such as using color as an encoding and warning that dense heatmaps are often better expressed as tables, but there is no canonical glossary or synonym policy yet.

Constraints: - Internal terminology should become more precise and opinionated over time. - User input cannot require perfect adherence to Dataface vocabulary. - Existing charts, prompts, configs, and docs may already rely on legacy terms. - Some words have overloaded meanings across visualization, cartography, and software engineering, so the standard needs both preferred terms and disallowed/soft-deprecated usage.

Possible Solutions

1. Publish a strict internal glossary only. Trade-off: improves writing discipline quickly, but does not help the product interpret user language or preserve backward compatibility.

2. Add a synonym layer only at the AI and parsing boundary. Trade-off: helps user intent recognition, but allows internal docs, schemas, and UI copy to keep drifting because there is no canonical preferred vocabulary.

3. Recommended: define a terminology standard plus an alias policy. Create a canonical vocabulary for product, docs, UI, and schema labels; explicitly reserve terms like map for geographic maps; define preferred replacements such as encoding instead of mapping; and maintain a compatibility layer that recognizes user synonyms, legacy names, and ambiguous phrasing before translating them into canonical Dataface concepts. Trade-off: more upfront design work, but it balances brand clarity with practical user empathy and creates one place to review future terminology decisions.

4. Rename visible concepts immediately and remove old terms aggressively. Trade-off: maximizes consistency fast, but risks breaking user expectations, existing examples, and AI workflows that still depend on historical phrasing.

Plan

1. Inventory current terminology across chart types, docs, AI skills, prompts, and schema labels.
2. Define a canonical glossary with three buckets: preferred terms, accepted aliases, and disallowed/misleading terms.
3. Identify high-impact ambiguous cases such as map, heatmap, table heat, encoding, mapping, and other chart-type labels that may conflict with Dataface's visual language goals.
4. Propose where alias handling should live for backward compatibility: AI prompt interpretation, chart type detection, schema normalization, docs redirects, or UI affordances.
5. Recommend a rollout strategy that improves internal consistency first while preserving interpretation of legacy/user vocabulary.
6. Convert the chosen policy into follow-up implementation tasks for docs, compiler/schema surfaces, AI skills, and migration messaging.

Implementation Progress

Review Feedback

• [ ] Review cleared