Skip to content

Text Labels ​

A label is what a screen reader says, and what the text chat prints, when someone lands on a node. Good labels are short, lead with the data, and say just enough to tell one node from another.

Guidelines ​

Lead with the value. People navigate to find numbers. Put the number first, then name what it belongs to.

ChartGoodAlso fineToo wordy
Bar5, Apple5, Fruit: AppleCount: 5, Fruit: Apple. Data point.
Stacked bar5, Apple, Store B5, Fruit: Apple, Store: BCount: 5, Fruit: Apple, Store: B

Keep group names descriptive. A bare B could mean anything, so say Store B. Short key names are fine: Store: B works too.

Skip the key for the value when it is obvious. In a bar chart of counts, 5 is clearly the count. Naming it adds words without adding meaning.

Scatterplots are the exception. Two bare numbers are easy to mix up, so name both by default: Horsepower: 130, MPG: 18. Experts who know the chart may prefer 130, 18. Let them choose.

Groups name themselves, then summarize. Apple. 3 stores. A longer version can add what matters most: Apple. 3 stores. Total 12. Store B is highest at 5.

Alt text for the whole chart follows one formula: what kind of chart, what it shows, and one key takeaway. Bar chart of fruit counts. Strawberries are highest at 6. Use it as the root node's label too.

Let people choose ​

No one label style suits everyone. In "Customization is Key" (Jones, Pedraza Pineros, Hajas, Zong, and Satyanarayan, CHI 2024), blind and low-vision participants found charts easier to use when they could customize the text. The paper names four things to let people control. The settings below cover each one:

Goal from the paperSetting here
PresenceKey names: none, groups only, or all
VerbosityGroups: short or detailed
OrderingOrder: value first or value last
DurationSettings are saved in this browser

Novices tend to want keys. Experts tend to want speed. The settings change every label in the demo.

Label settings
Key names
Order
Groups
Preview
Bar5, Apple
Stacked bar5, Apple, Store B
ScatterplotHorsepower: 130, MPG: 18
GroupApple. 3 stores.
Chart

Text chat (works on touch screens)

Inspector (tree view)

Current node: none

How it is built ​

Labels are functions. Data Navigator calls semantics.label each time it announces a node, so a function can read the current settings and build the label then. No rebuild is needed.

js
// Label building with end-user settings. Labels are functions, so a change applies
// the next time a node is announced, in both keyboard and text chat.

const STORAGE_KEY = 'dn-pattern-label-settings';
export const defaultSettings = {
    keys: 'auto', // 'auto' (author's choice per chart), 'never', 'groups' (only group names), or 'always'
    order: 'value-first', // 'value-first' or 'value-last'
    groups: 'short' // 'short' or 'detailed'
};

const load = () => {
    try {
        return { ...defaultSettings, ...JSON.parse(localStorage.getItem(STORAGE_KEY) || '{}') };
    } catch {
        return { ...defaultSettings };
    }
};
let settings = load();

export const getSettings = () => settings;
export const setSettings = next => {
    settings = { ...settings, ...next };
    try {
        localStorage.setItem(STORAGE_KEY, JSON.stringify(settings));
    } catch {
        // storage can be blocked; settings still apply for this visit
    }
};

/*
    values:      the numbers, e.g. [{ key: 'Count', value: 5 }]
    categories:  the groups, e.g. [{ key: 'Fruit', value: 'Apple' }, { key: 'Store', value: 'B', bare: 'Store B' }]
    keysByDefault: whether this chart needs key names when keys is 'auto' (true for scatterplots)

    'bare' is how a category reads with no key name. "B" alone is unclear, so it reads "Store B".
*/
export const pointLabel = ({ values = [], categories = [], keysByDefault = false }, s = settings) => {
    const auto = s.keys === 'auto' && keysByDefault;
    const valueKeys = s.keys === 'always' || auto;
    const groupKeys = valueKeys || s.keys === 'groups';
    const show = (part, keyed) => (keyed ? `${part.key}: ${part.value}` : (part.bare ?? part.value));
    const nums = values.map(v => show(v, valueKeys));
    const cats = categories.map(c => show(c, groupKeys));
    return (s.order === 'value-first' ? [...nums, ...cats] : [...cats, ...nums]).join(', ');
};

// A group names itself, then gives a short or detailed summary.
export const groupLabel = ({ name, short, detail }, s = settings) =>
    `${name}. ${s.groups === 'detailed' && detail ? `${short} ${detail}` : short}`;
js
const n = structure.nodes;
n.chart.semantics = { label: alt };
n.fruits.semantics = {
    label: () => groupLabel({ name: 'Fruit', short: '3 fruits.', detail: 'Apple, Banana, Cherry.' })
};
n.stores.semantics = { label: () => groupLabel({ name: 'Store', short: '3 stores.', detail: 'A, B, C.' }) };
fruits.forEach(f => {
    const rows = fruitStores.filter(d => d.fruit === f);
    n[`fruit-${f.toLowerCase()}`].semantics = {
        label: () =>
            groupLabel({
                name: f,
                short: '3 stores.',
                detail: `Total ${total(rows)}. Store ${top(rows).store} is highest at ${top(rows).count}.`
            })
    };
});
stores.forEach(s => {
    const rows = fruitStores.filter(d => d.store === s);
    n[`store-${s.toLowerCase()}`].semantics = {
        label: () =>
            groupLabel({
                name: `Store ${s}`,
                short: '3 fruits.',
                detail: `Total ${total(rows)}. ${top(rows).fruit} is highest at ${top(rows).count}.`
            })
    };
});
fruitStores.forEach(d => {
    n[d.id].semantics = {
        label: () =>
            pointLabel({
                values: [{ key: 'Count', value: d.count }],
                // "B" alone is unclear, so with no key it reads "Store B"
                categories: [
                    { key: 'Fruit', value: d.fruit },
                    { key: 'Store', value: d.store, bare: `Store ${d.store}` }
                ]
            })
    };
});
js
const n = structure.nodes;
n.chart.semantics = { label: alt };
n.horsepower.semantics = {
    label: () => groupLabel({ name: 'Horsepower', short: '4 ranges.', detail: '46 to 230.' })
};
n.mpg.semantics = {
    label: () => groupLabel({ name: 'Miles per gallon', short: '4 ranges.', detail: '11 to 46.6.' })
};
[
    ['horsepower', 'Horsepower', 'mpg', 'MPG'],
    ['mpg', 'MPG', 'horsepower', 'horsepower']
].forEach(([key, name, other, otherName]) => {
    Object.values(structure.dimensions[key].divisions).forEach(div => {
        const rows = Object.values(div.values);
        const vals = rows.map(d => d[other]);
        n[div.id].semantics = {
            label: () =>
                groupLabel({
                    name: `${name} ${range(div.numericalExtents)}`,
                    short: `${rows.length} car${rows.length === 1 ? '' : 's'}.`,
                    detail: rows.length ? `${otherName} ${Math.min(...vals)} to ${Math.max(...vals)}.` : ''
                })
        };
    });
});
cars.forEach(d => {
    n[d.id].semantics = {
        label: () =>
            pointLabel({
                values: [
                    { key: 'Horsepower', value: d.horsepower },
                    { key: 'MPG', value: d.mpg }
                ],
                // two bare numbers are easy to mix up, so keys are on by default here
                keysByDefault: true
            })
    };
});

Each part of a data point label carries its key, its value, and an optional bare form. bare is how the part reads with no key, so Store B stays clear even when key names are off.

Released under the MIT License.