File talk:Template map of US states and District of Columbia.svg/Instructions

Note. The instructions are in this talk subpage because subpages are not allowed for file pages.
Note: See latest template map, and maps created with it. See fast method.
Note. See also: Commons: Map resources.
Note. See old template map, and old instructions.
Note. This all started in this long discussion. Which continued here. And then here.


Purpose

These SVG maps have user-editable sections (any text editor) to allow creation of more maps on more topics. Just paste in a list of states and values. See examples here:

Feel free to create map templates for other countries too. Cmglee may be able to help with that.

Latest template map

File:Template map of US states and District of Columbia.svg - By CMG Lee and TilmannR.

The template map can be used to create US SVG maps by pasting in a list of states with values.

Some maps created with the latest template

Note: See Category:English-language SVG choropleth maps of the United States with visible numbers. Made with templates for maps made with both the old and new templates.

See maps created or updated with the latest template:

Maps created or updated with this template
Border has been added via image wikitext. For example:
[[File:Drug overdose death rates per 100,000 by state. US map.svg|400px|none|border]]


Instruction summary. New map template

Note: Any SVG file created with this template can also be a template.
Note: This only works with the Firefox browser.
  1. Open the main SVG template file (or a subsequent SVG file with the same generator script) in a text editor.
  2. Replace (or amend) parts indicated with relevant data:
    • In the list following the line "const state_space_value...", amend the values, or paste in a new list of states and values. Remove commas from numbers. If a value is unavailable, leave the value blank.
    • Adjust title, description, font sizes, colors, etc, if necessary. All of this is done in the "SVG-specific JavaScript" section at the end.
  3. Delete the !-- on the line with GENERATOR_SCRIPT, and -- on the last line. This enables the script.
  4. Save as an SVG file in the text editor. Keep the file open as you may need to do additional editing.
  5. Open the SVG file in Firefox to generate the changes.
  6. The changes will be showing in the map.
  7. The map must be saved again from Firefox to keep the changes, and turn off the generator script.
  8. Save as "Web Page. Complete (*.svg;*.svgz)".
  9. Saving as "Web Page. SVG-only (*.svg;*.svgz)" does not turn off the script.
  10. Firefox will save using the name found in the file.
  11. Upload the changed SVG file to the Commons. Use any name you want.

Text editors

Any text editor will work. Right click the SVG map template, or other SVG map made with the template. From the context menu click "Open with". Click any text editor. If you don't see the one you want click "Choose another app", and scroll down until you find the text editor you prefer.

For example: Notepad, Notetab Light, and Notepad++. All 3 are free. Notepad++ is nice because it has syntax highlighting. It also has dark mode: Settings > Preferences > Dark mode.

More instructions

Note: See the old instruction page for the old template for some still-relevant info.

These instructions are for a list of states:

State Value
State Value
State Value

And so on.

States can be full names, or USPS 2-letter abbreviations. There can be a mix of the two in the list.

Other abbreviations and names will mess up the map. Such as for US territories. So delete all abbreviations and names that are not US states, or Washington DC.

Order of states does not matter. States that are missing from the list altogether, or missing data, will show "n/a" on the map. Or whatever value is entered in this parameter:

const no_data_value = 'n/a';

After uploading, don't forget to add the map to its topic category, and also to this category:

Washington, D.C.

DC or D.C. in the list works. As does Washington, D.C. (Wikipedia article title), Washington DC, District of Columbia, etc.

Tips for pasting in a list fast

You can paste a list directly from a spreadsheet or wikitable into an SVG file that is opened in a text editor.

Between the state and value can be a space, multiple spaces, a tab, multiple tabs, etc.. Try out other things and see.

Set the script generator as previously described. Save the file with the same name. The SVG extension will be maintained. Keep the file open for further editing if needed.

Open the saved SVG file in Firefox and look at the map. If changes are needed, edit the already-opened SVG file further in the text editor. Save again. Look at the map in Firefox again. Repeat as needed.

When OK, save the SVG file from Firefox to turn off the generator script, and to keep the changes.

Choose parameter values

If you are updating an existing map, then there are already parameter values. You can keep or change them as desired in the user-editable "SVG-specific JavaScript" section at the end of the SVG file. Or you can start with the latest template. It may be improved from when it was last used on a particular map.

To avoid problems the const out... entries must have the single quotes around them, and the semicolon at the end.

If a change is to leave blank a const out... entry that previously had something, then for it to work there must be at least the single quotes. Add the semi-colon for consistency. Otherwise the generator script will not work.

  • const out_title = 'State minimum wages, in dollars. Jan 1, 2026';
  • const out_desc = 'US map of state minimum wages, in dollars. Jan 1, 2026';
Text is only seen by screen readers and search engines. Text can be longer.

How to mark states with no data. Blank, n/a, N/A, etc.:

  • const no_data_value = 'n/a';

For the decimal place parameter see the relevant section farther down.

  • const decimal_place = 2;

Fonts

The font size for the title can be changed depending on the title width. The .value size can go up to 18px depending on the number of characters. All is adjustable below. 

.title  { font-size:30px; }
.byline1 { font-size:17px; text-anchor:start; }
.byline2 { font-size:17px; text-anchor:start; }
.source { font-size:17px; font-style:italic; text-anchor:start; }
.note1  { font-size:15px; font-weight:bold; fill:#0000FF; text-anchor:start; }
.note2  { font-size:15px; }
.legend { font-size:30px; }
.state  { font-size:17px; letter-spacing:-1; }
.value  { font-size:17px; letter-spacing:-1; }

Color contrasts

Be sure both ends of the color range pass the contrast tests with black text (#000000):

It is better to pass both the AA and AAA tests for normal text. If both ends of the color range pass the tests, then everything in between passes too.

See WCAG Conformance Levels: How High Should You Aim? Excerpt: "A contrast of 7 to 1 allows users with approximately 20/80 vision to perceive the content without assistive technology. In other words, this Level AAA success criterion allows the web page or content to be used by a wider range of people, without requiring the application of assistive technology, making the content much more accessible."

.min for minimum, .max for maximum. The min and max colors can be reversed if preferred. 

.min    { fill:#ffff00; }
.max    { fill:#ff6600; }

You can choose white (#FFFFFF) and any other background color that passes the contrast checker tests when used with black text.

Or instead of white use shades of a single hue. Such as this map.

Or you can use 2 background colors of different hues. See these background color pairs below that work with black text (#000000), and pass all the contrast tests. Along with some links to example maps. The first map is very accessible by colorblind people. See: File talk:Template map of US states and District of Columbia.svg#Colorblind-friendly pairs.

map .min .max
.min { fill:#ffff00; } .max { fill:#CE6BFF; }
 
 
.min { fill:#ffff00; } .max { fill:#ff6600; }
 
 
.min { fill:#999900; } .max { fill:#ffff00; }
 
 
.min { fill:#99ffff; } .max { fill:#ff6600; }
 
 
.min { fill:#0099ff; } .max { fill:#ffff99; }
 
 

With any of these colors, and the intermediate colors, black text (#000000) passes all the contrast tests. For example, black text (#000000) with #FF6600 passes all the contrast tests:

 

White text (#FFFFFF) with #FF6600 fails all the contrast tests:

For info on colors, color contrast, and much more, see this section and the following sections:

Color blindness

Maps can be checked for their accessibility by colorblind people here:

  • Coblis. Color Blindness Simulator. Use PNG or JPG versions of the maps. 1280px wide is a good size. The simulator can change quickly between views if the image isn't too big in kilobytes.

If it is the latest map, the PNG versions are linked under the image on the file page. If you are looking at a map other than the latest upload, you can convert it to PNG or JPG with various tools. See Google search:

.n_a states

.n_a { fill:#eeeeee; }
 
 very light gray for states with no info.

The diagonal lines in the .n_a states:
.n_a { fill:url(#pattern_n_a); }

Decimal place parameter

This saves some time, since you don't have to do it in a spreadsheet. Numbers are rounded correctly.

  • const decimal_place = 1;

Decimal place is the position of a digit to the right of the decimal point in a decimal number. The parameter is for how many digits to show on the map. 0 = no digits to the right of the decimal point are shown. 1 = 1 digit shown to the right of the decimal point. 2 = 2 digits shown.

Divide large numbers by 10, 100, 1000, etc.

You may need to lower large numbers such as yearly wages by dividing them by 1000. Title of map would say that the wages are in "thousands of dollars". To see how:

It explains how to multiply or divide in a spreadsheet.

View map in browser at different widths

You may want to see how your SVG map looks at thumbnail, medium, or large sizes. Especially the readability of the text. You can change the font sizes as described in the parameters section above.

Open the SVG map in any browser. Changing the window size of the browser changes the size of the map. That is because the map adjusts its width to fit inside the browser width.

Font-family

Here is the font-family in the map SVG code:

font-family="Liberation Sans,Helvetica,Arial,sans-serif"

Fonts: Liberation Sans, Helvetica, Arial, and sans-serif.

These fonts all have about the same line length (A-Z, 0-9, etc.) in File:SVG Text Font Test.svg. Except for sans-serif whose metrics would depend on the sans-serif font provided by the device it is being viewed on.

It is prudent to keep this font family in order to allow wide use of the maps. See Wikipedia:SVG help#font-family property. It is a font-list with similar fonts that at least contain one font for each Operating System such as Wikimedia (e.g. Liberation Sans), Windows (e.g. Arial), Linux (e.g. Liberation Sans), Mac (e.g. Helvetica). Also on Fandom and Shoutwiki (e.g. Liberation Sans).

Liberation Sans is a common free font found on nearly all wikis. It is important that it is listed first because some wiki software at times may not look past the first font in the font family list before using a default sans serif font for the wiki. See: Phab:T64986. That font could have any font metrics, with the possibility of text extending beyond where it should be.

Many maps and charts on the web are in the public domain

See Template:PD-map and Template:PD-chart. There is no need to create another free map or chart here if it already exists on the web.

Possible maps and charts

America's Health Rankings

US dental care maps and stats:

KFF. "More than 800 up-to-date health indicators at the state level can be mapped, ranked, and downloaded":

US Centers for Disease Control and Prevention

Map workshops of the Graphic Labs

You can get help here:

See also