Decide/document/enforce? Property names changed in format output
morewry opened this issue · comments
The included output formats do a fair amount of transformation on the original property name. JavaScript formats output in camelCase, style formats (CSS Modules, Custom Properties, Sass, etc) mostly in kebab-case, and so on.
I see there being two potential aspects of naming conventions that Theo can reasonably address. The first is enforcing identifier validity, which I think most users would consider a requirement and the second is enforcing identifier conventionality, which I think is a more fraught topic. Also in there is what I might call type-ability.
Identifier validity means ensuring the formats output names that are valid (according to, say, the ECMAScript specification or CSS specification), ensuring the code generated will work and won't throw errors. Validity is objective, in the sense that something either works or it doesn't.
Identifier conventionality means adhering to the most common naming convention that developers use. This is a harder aspect to pin down. Certainly camelCase is very common in JavaScript, but I'd say the typical JavaScript conventions are a little more nuanced (camelCase for general variables, Pascal for constructors, etc) and you could argue quite convincingly that a design token property is a constant and falls into to realm of the equally-common UPPER_SNAKE_CASE convention. Conventionality is often subjective.
Type-ability is also subjective. But it's often a part of conventionality. ಠ_ಠ may be a valid JavaScript identifier, but it's a pain in butt to type and your coworkers will probably not enjoy dealing with that variable name.
I recently had occasion (#158) to take a look at the android.xml format and noticed that it did not ensure validity and that it converted the names to UPPERCASE. Since this isn't a validity concern, it's most likely related to conventionality. I have no particular personal insight into whether this is, in fact, the most common convention, but I did notice that none of the examples in the Android Developer documentation (https://developer.android.com/guide/topics/resources/providing-resources) showed UPPERCASE names.
This got me thinking––in combination with noting that relevant test fixtures only included input token property names in the UPPER_SNAKE_CASE format (see #161)––that there should probably be an intentional, documented rationale for and limits to how theo's included formats transform authors' chosen property names.
Personally, while the majority of the changes that are made right now are the ones I'd prefer, I'm wondering what the downsides would be preserving the author's original, chosen name for the property outside of the constraints of validity.
Yeah, I think you make a good point. Theo was originally created for our use cases at Salesforce and many of the formats are pretty opinionated based on what we needed at the time. After reading comments like this and #163, I'm starting to think that the documentation should encourage using custom formats.
We could keep adding more configuration options, but it seems like a better approach would be to focus on providing good sets of platform specific value transforms (DP for Android, rem to px, etc) and leave the actual output up to the consumer. Theo could still provide it's default formats, but under the hood, most of these are pretty straightforward and will start to get more complicated as we provide more configuration options.