Adding an explanation of the colors used in `tmap_design_mode()`

[Nowosad]

Do I remember that the colors were explained in R console in the previous version? It would be good to add them again (also possibly with some suggestions on how to control them?).

[mtennekes]

Yes indeed, good point

[mtennekes]

The colors not explained yet, but information in the console added: 6fe3bf8

[mtennekes]

Done. It wasn't as easy as in v3, but at least there is some info. I've added two options, tmap_design_mode(overall = TRUE) and tmap_design_mode(overall = FALSE).

Please review @Nowosad

[Nowosad]

@mtennekes the current design mode is not showing any visualization layers (e.g., polygons, texts, etc.) -- is it on purpose? They were a part of the design mode before.

library(tmap)
library(spData)
tmap_design_mode()
#> design.mode: ON (overall layout)
tm_shape(nz) +
  tm_polygons(fill = "Median_income")
#> ---------------W (in)-H (in)-asp---
#> | device        7.000 5.000 1.400 |
#> | plot area     4.702 4.800 0.979 |
#> | facets area   3.424 4.800 0.713 |
#> | map area      3.324 4.800 0.692 |
#> -----------------------------------
#> Color codings:
#> - light blue  outer margins
#> - dark blue   buffers around outside cells
#> - light green outside cells
#> - dark green  x and ylab cells
#> - pink        panels
#> - red         margins for outside grid labels
#> - orange      margins around maps for grid labels
#> - yellow      map area

^{Created on 2025-07-25 with reprex v2.1.1}

An example of the previous tmap_design_mode behavior:

[Nowosad]

(Also: @mtennekes where can I find the list of actual colors (either as R names or hex codes) that are used in the design mode?)

[mtennekes]

Yes, that is on purpose. Now the "overall" type will just show the overall grid (without map/components), and the "components" type (overall = FALSE) does show the layers.

I did that on purpose, because often the background of the map is white, which would make the yellow box invisible.

Not sure what is the most user-friendly approach to show them (or perhaps just write a vignette about it)?

The actual colors are cols4all::c4a("brewer.paired")

[Nowosad]

Thanks, @mtennekes.

Two ideas/suggestions:

1. The overall argument name is hard to understand (by me, at least). If I understand correctly, the first option (TRUE) shows areas, and the second one shows lines -- maybe we could use that -- e.g., have the show argument (or scope) with either "areas" or "lines". What do you think? (Another idea is to overwrite the design.mode argument with not only logical options, but the two mentioned above)
2. Have you considered adding a third argument (e.g., include_elements) -- if it is true, then map elements are also shown (similarly to how the design mode worked before)?

library(tmap)
library(spData)
tmap_design_mode(TRUE, overall = TRUE)
#> design.mode: ON (overall layout)
tm_shape(nz) +
  tm_polygons(fill = "Median_income")
#> ---------------W (in)-H (in)-asp---
#> | device        7.000 5.000 1.400 |
#> | plot area     4.702 4.800 0.979 |
#> | facets area   3.424 4.800 0.713 |
#> | map area      3.324 4.800 0.692 |
#> -----------------------------------
#> Color codings:
#> - light blue  outer margins
#> - dark blue   buffers around outside cells
#> - light green outside cells
#> - dark green  x and ylab cells
#> - pink        panels
#> - red         margins for outside grid labels
#> - orange      margins around maps for grid labels
#> - yellow      map area

tmap_design_mode(TRUE, overall = FALSE)
#> design.mode: ON (component layout)
tm_shape(nz) +
  tm_polygons(fill = "Median_income")
#> ---------------W (in)-H (in)-asp---
#> | device        7.000 5.000 1.400 |
#> | plot area     4.702 4.800 0.979 |
#> | facets area   3.424 4.800 0.713 |
#> | map area      3.324 4.800 0.692 |
#> -----------------------------------
#> Color codings:
#> - orange      map component grid lines
#> - red         item positioning lines

^{Created on 2025-07-26 with reprex v2.1.1}

[mtennekes]

Good suggestion to set show to either "areas" or "lines". A third element include_elements (or include_content) is trickier:

• for the lines it is a bit of work because the lines are part of the elements (so then I'll need to hide all elements in the plot functions).
• the the areas it is much easier, but it less useful because not all areas are visible due to the background color of various elements. I could set all those background to NULL (which will result in something that is comparable to v3) but this is a bit of work.

[Nowosad]

@mtennekes include_elements (or include_content) -- I think it still may be useful for the areas -- I can imagine looking at the design mode with areas first to get the general understanding (even though some are not visible) and then moving to the design mode without areas to fine-tune things.

[mtennekes]

Managed to merge both 'types', so now it has no arguments anymore, similar to v3:

tmap_design_mode()
tm_shape(World) +    
	tm_polygons("HPI") +    
	tm_add_legend(frame=FALSE,
				  labels = c('lab1','lab2'),
				  type = 'polygons', 
				  fill=c('red','green'),position=c('left','top')) + tm_facets(by = "continent")

---------------W (in)-H (in)-asp---
| device        11.590  5.829  1.989 |
| plot area     11.127  5.595  1.989 |
| facets area   10.277  5.595  1.837 |
| map area       2.469  2.548  0.969 |
--------------------------------------
Color codings:
- light blue  outer margins
- dark blue   buffers around outside cells
- light green outside cells
- dark green  x and ylab cells
- pink        panels
- red         margins for outside grid labels
- orange      margins around maps for grid labels
- yellow      map area

So backgrounds are removed, and lines are plotted in black.

Finally something useful again :-) Let me know if you have further suggestions, otherwise we can close this

[Nowosad]

@mtennekes great progress. One suggestion -- maybe add the meaning of the black lines to the "Color codings:" text? (Also, have you tested other colors for these lines, e.g., white?)

[mtennekes]

Done.

Colored the components lavender. I've done some tests with line color and style, but so far the black ones work best imho. Added explanation.