Units of properties are not pixels, they are density-independent pixels

[louwers]

Some properties, like circle-radius list the unit as pixels:

Paint property. Optional number in range [0, ∞). Units in pixels. Defaults to 5. Supports feature-state and interpolate expressions. Transitionable.

In the case of native, they are actually density-independent pixels. So the amount of pixels depends on the pixel ratio (also called pixel density). I think this is also true for MapLibre GL JS? (cc @ibesora)

[HarelM]

I'm not 100% sure, but I see all kind of scaling in the code related to device pixel ratio.
Feel free to change the wording if you think it will be clearer or write a note somewhere about it instead of making it longer for each field.

[louwers]

We could use 'dp' instead of 'device-independent pixel'. https://en.wikipedia.org/wiki/Device-independent_pixel

[HarelM]

I'm not sure dp is intuitive to everyone as opposed to pixels.
Did you get a feedback that the current docs are confusing?
I agree that they are not 100% accurate, but they are easily understandable I belive.
In any case, I don't have strong feelings either way.

[ibesora]

I think this is also true for MapLibre GL JS?

Yeah, there are lots of places around the code where devicePixelRatio is being used when dealing with pixel sizes.

The correct term is dp although I agree I'm not sure it's intuitive. Maybe we can just add a note somewhere in the docs saying that pixels in the docs means dp?

[louwers]

I think that might actually be more confusing. Also, it's a spec, we should use the correct term in my opinion.

We could link each mention of dp to an explanation. Or write (device-independent) pixels.

[sargunv]

Unsure if y'all are using Material for Mkdocs, but if so, the Abbreviations feature seems perfect for this use case: https://squidfunk.github.io/mkdocs-material/reference/tooltips/#adding-abbreviations

DP (or dips) is probably the correct generic term, and the tooltip can clarify that's the same as a CSS px on web

[HarelM]

Thanks for the tip, we are using mkdocs material for the docs.