[RFC] Adopt more explicit function arguments about polished HOT 7 CLOSED

My 2c as someone fairly confident with CSS, I think API quirks like this are better left exposed directly to the consumer, since they're an unavoidable part of the platform. For example, as soon as you need to drop from styling with polished into styling with CSS or have to change an element's style using inline styles, you're straight back to the "native" interface. So it makes your knowledge less portable.

The CSS spec has a huge surface area, not just around value syntax but plenty of properties that seem oddly named or things that only work in pairs, but I've never seen an abstraction over the top that works well enough for long enough that it ends up being a net benefit.

That said, offering an API with both short and long hand args doesn't cost you much and might help folks come back and read their code later, so it might be worth adding, but I wouldn't make it the primary API

from polished.

I believe the proposed API would be great for a beginner, but I can imagine a more advanced CSS user finding it somewhat verbose.

Maybe the explicit API could be exposed in a subdirectory, similar to Lodash's FP, something among the lines of styled-components/fancy.

from polished.

I believe I have a solution for v2 that will allow us to both support this without causing much overhead as well as make it opt-in on a per module basis with no modifications to the module itself.

from polished.

I could see us merging that in for sure. What do you think @bhough @nikgraf?

from polished.

I would definitely would want to keep the existing api in place given that the original goal was to make these as portable as possible from libraries like bourbon. Though I do believe this is another case (as @nikgraf and I were discussing on #104) where the idea of having multiple APIs for the same mixin has come up, and whether that should be seen as flexible or confusing.

from polished.

@rtsao first of all: lostyle looks really cool, good job there 👏

I really like this proposal and usually I'm more in favour of having one way of doing things, but in for the sake of making it easy for most people we followed the approach of accepting different signatures. Mostly inspired by the Robustness principle

Be conservative in what you do, be liberal in what you accept from others

I'm not too fond of a polished/fancy version (yet). Might be a nice idea to test features, but ideally we can keep it simple right now.

I vote for add improving the API while keeping the old signature as well. This can be simply done with dynamic type checks in the beginning of each functions same as we did in rgb, rgba, hsl or hsla. See https://github.com/styled-components/polished/blob/master/src/color/rgb.js#L13-L14

from polished.

@nikgraf @mxstbr curious thoughts on including this as part of V2. Are we sold on expanding the apis of existing modules (where appropriate) to allow shorthand and explicit styles?

from polished.