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:Poverty rates 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.

  • 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;

Troubleshooting

To avoid problems the const out... entries in the generator script must have the single quotes around them, and the semicolon at the end. Even if left blank the single quotes and semicolon must be there. Otherwise the generator script will not work.

An extra single quote or apostrophe will prevent the generator script from working. So you can't use contractions (it's) or possession (Sarah's) without additional steps.

const out_note1 and const out_note2 use \n for line breaks.

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; }

Borders

There are color ranges where each of the colors below is best with plain black text. Color names work too:

  • Gray borders: .state { stroke:#808080; } or { stroke:gray; }
  • White borders: .state { stroke:#ffffff; } or { stroke:white; }
  • Yellow borders: .state { stroke:#ffff00; } or { stroke:yellow; }

You can try out any color name or hex code you want. See web colors and shades of gray. See discussion, and color tests:

Color

For info on colors, color contrast, color blindness, and much more, see:

Color contrasts

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

See WCAG Conformance Levels: How High Should You Aim? Excerpt (emphasis added): "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."

  • https://webaim.org/resources/contrastchecker/?fcolor=000000&bcolor=XXXXXX - It is set for black text (#000000). Click on "Color picker" (under XXXXXX) to see the color chart. Pick color, and then pull the slider on the right of the color picker image to a preferred shade. Then click OK it so it shows up in the XXXXXX spot. The contrast ratio number for that number then shows up below, along with the pass/fail WCAG contrast results. Use slider at the bottom of the background box to bring it to 7:1 or higher. To reset the tool remove the hex color in the background box.

In the template map SVG code:

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

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

You can choose white (#FFFFFF) and any other background color that passes the 7:1 contrast ratio.

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

Or you can use 2 background colors of different hues. There are many colors that pass the 7:1 contrast ratio.

See a few background color pairs below that work with black text (#000000), and pass the 7:1 contrast ratio. Along with some links to example maps.

.min .max map
.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:#ffff00; } File:Poverty rates by state. US map.svg. May 3, 2026 upload.
 
 

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

 

Plots below of the WCAG contrast-ratio threshold 7:1 between normal-size black text and the RGB components of an sRGB color in decimal (left) and hexadecimal (right). See hex color. For each curve denoting the blue component, points above the curve exceed 7:1 contrast. For simplicity, all red and green combinations in the yellow region exceed 7:1 regardless of blue value.

Text colors of bylines and notes

Some options:

Blue text color #0000FF easily passes all contrast tests against white background (#FFFFFF). Primary blue with RGB value: 0% red, 0% green, and 100% blue. See:

 

Red text color #B30000 just passes all contrast tests against white background (#FFFFFF). Primary red color does not pass all the tests. See:

 

In thumbnails it is difficult to read small text with this color unless it is bold text.

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, then download the SVG file for it. Then convert it to PNG or JPG with various tools. See Google search:

Divergent color pairs (multi-color pairs) produce many intermediate colors. You will note in the Color Blindness Simulator that almost all map color pairs work because even when viewed by colorblind readers the resulting colors and shades almost always still have enough distinction to separate the data slices.

If you want the least amount of change of colors by colorblind readers see: File talk:Template map of US states and District of Columbia.svg#Colorblind-friendly pairs. A safe pairing is blue with yellow . Darkest shade of blue (255) that barely gets 7:1 contrast with black text is #0099ff

 

.n_a states

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

In the past it was a solid color:

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

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 an SVG map looks at various sizes. Especially the readability of the text.

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.

In Firefox one can hold down the ctrl key and use the mouse scroll wheel to change the map size. This is only true if "Zoom text only" box is not checked in settings.

Font-family

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

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

Fonts: Liberation Sans, Arial, Helvetica, 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.

Arial is before Helvetica because Helvetica is not found preinstalled on Windows devices. Arial is preinstalled on both PCs and Macs. Windows devices far outnumber Apple devices.

It is prudent to keep this font family in order to allow wide use of the maps. 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). See Wikipedia:SVG help#font-family property.

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