Directive grouping syntax feels like a footgun

[itsMapleLeaf]

Just a general thoughtdump. I looked through the grouping syntax docs, and when I look at this:

tw`ring(& pink-700 offset(4 pink-200))`

...especially the latter part offset(4 pink-200), I see a drastic decrease in clarity as to what's actually going on here. It reminds me of, and has the same downsides as nested blocks in CSS and Sass; looking at any individual part of the style in a vaccuum, it's harder to "trace" up the tree to see what styles are being applied. It feels very "write only", and I can only imagine this issue getting worse with more complex examples.

Maybe it's just unfamiliarity bias on my part, but I feel like the terseness of this doesn't outweigh the readability barrier, almost to the point that it shouldn't be included in the library at all. What do you think?

[sastan]

You are not wrong. In our opinion it has great advantages in reducing the class name noise. As with any language you can make it too complicated. For example i really like w(1/2 sm:1/3 md:1/4) and its more clear to me then w-1/2 sm:w-1/3 md:w-1/4 because all width classes are grouped.

As with a lot of things there will be preferences. You can use twind in the classic tailwind way and introduce grouping very sparingly.

Maybe we should find better examples for the docs and add a hint/warning to not obscure the intention.

[sastan]

@itsMapleLeaf Could you take a look at the new Thinking in Groups (added by @gojutin)? Does this help or should we add something more?

[itsMapleLeaf]

I like the walkthrough style of this guide, and I can see the readability benefits. Though I'm still not a fan of the syntax overall. The self-referencing bit is probably the worst offender to me here, but I'll just chalk that up to personal bias 🤷