Re: [community-group] [RFC] Format specification (#1)

Now that we have a sizable group of representatives from various companies and projects, it's perhaps time for us to become more active.

I'll start my summarising my reading of this thread so far (and please do correct me if you disagree or if I miss out anything!) and then suggest a few areas I think we need to focus on.

**Summary of thread so far**
* Everyone here is an agreement that a standardised file format for design tokens is a good idea
* I think there's a consensus (or at least, no disagreement) that:
    * We should start small and "not boil the ocean"
    * The format should be human readable
    * Support for categories / groups of tokens is desirable
       * But, the file format should not prescribe a particular organisation of design tokens
    * Support for aliases (aka references) is desirable (i.e. one token can reference the value of another)
    * Tokens should have (optional) descriptions
    * Tokens should be allowed to contain other, optional meta-data as well
    * Tokens should have explicit data types
* Theming and notions of inheritance or overrides have spawned a [separate discussion thread](https://github.com/design-tokens/community-group/issues/2). I suggest that this is a higher-level concern that would build on a low-level file format, rather than be an integral feature of that file format. What do you think?
* Other features that have been proposed and/or discussed - but arguably don't need to be part of the initial version of the spec - are:
    * Allowing multiple values for the same token (e.g. for variations between platforms).
    * Allowing proprietary vendor data per token (so tools can save any auxiliary info they need along with the design token)
   * Saving the spec version that a file conforms to (so that, if there are breaking changes between future versions of the format spec, tools can easily determine whether or not they can reliably parse a given design token file)
   * The format should be able to express relationships between tokens (perhaps via adjustment functions and math operations). E.g. tokenA = 2 * tokenB

**Suggested next steps**
I think we need to agree some ways of working.

For instance, all discussions so far are in Github issues (and to a lesser extent PR comments). A [Gitter channel](https://gitter.im/design-tokens/community) was set up but has barely been used. Also a W3C Community Group is being setup, which will provide us with things like a mailing list.

I think long threads like the comments on this issue are not great for technical discussions about specific features because, as they grow ever longer, it becomes harder to track different threads. We could start creating lots of issues for specific topics (e.g. one for file format, one for data types, one for categories, etc.), but I fear that will then make it harder to keep track of the bigger picture of how everything hangs together.

What I therefore propose is that we do a PR that adds an _initial_ skeleton file format spec as a markdown file. It could use the TypeScript pseudo code from this issue as a starting point, or it could be more of a narrative akin to what I started doing for [UDT](https://github.com/universal-design-tokens/udt/blob/master/packages/spec/docs/README.md) (which is very much work-in-progress and will hopefully be superseded by whatever we cook up here). I don't think it matters to much since whatever we start with will evolve quite substantially over time. Then we successively add or edit it via PRs.

Those PRs should aim to focus on a single issue (e.g. adding a chapter about X, amending the definition of Y, fixing a typo, etc.). Each goes through a peer review and, if accepted and merged, becomes part of the emerging spec.

At some point, once it's mature enough, we can version and release a snapshot of that spec. The same process continues though in order to produce future iterations of the spec.

This of course raises the question of who are the maintainers that can merge a PR? So far I think it's only @kaelig, but I suggest we have a few more to avoid bottlenecks when folks are busy with other things or on vacation. (A related question is whether or not the same set of people should become "chairs" of the W3C community group)

Besides very specific discussions via PRs, I think there is value in having a place for broader discussions. So far it's kind of been this comment thread, but I don't think it should remain that way. We may eventually have many Github issues, so how would a newcomer _know_ that the comments in one particular issue are for general chit-chat. That doesn't feel very intuitive to me.

I propose we choose _one_ place where these general discussions happen (so that people don't have to keep tabs on multiple sources). It could be Gitter or the mailing list we'll get from the W3C community group. My preference would be the latter since it feels more official and also has a publicly accessible archive.

I'm sure there's more stuff to figure out - but I'm putting these suggestions forward to get the ball rolling. :-)

-- 
GitHub Notification of comment by c1rrus
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/1#issuecomment-522962582 using your GitHub account

Received on Tuesday, 20 August 2019 10:58:25 UTC