Re: [community-group] Design token additional properties (description, type, extensions) need to be in 5.2.x instead of 5.3, 5.4 etc. (#154)

Agreed, that would be more consistent.

However, I've recently been wondering if we should restructure our outline more dramatically than that:

The `$description` exists for both groups and tokens, _and_ it has the same purpose in both cases (i.e. it provides a description of the group or token it's added to). Currently, `$extensions` only exists on tokens, but there's a proposal (which I agree with) to add it to groups too (#106).

The `$type` property also exists for both groups and tokens. Although it's meaning is slightly different in each case (On tokens it sets that token's type. On groups it sets a default type that is inherited by any child tokens which do not have their own `$type` property), everything else about it is the same in both cases.

Several new properties are being proposed (e.g. `$deprecated`, `$usedFor`, etc.) and I think many of those will be applicable to groups and tokens too.

If our spec keeps the same heading structure, we're likely end up with a lot of duplication.

I've therefore been wondering whether we should reorganise our outline into something like this:

1. Entities
    1. Design tokens
        * Explain the purpose and syntax of design tokens
    1. Groups
        * Explain the purpose and syntax of groups
1. Properties
    1. `$value`
        * Explanation of which entities this prop can be applied to (groups only, tokens only or both), it's purpose, permitted values, etc. 
    3. `$type`
    4. `$description`
    5. `$extensions`
    6. ...

While I'm pretty sure that would make the spec easier to write and maintain, the more important factor (IMHO) is whether that would make it easier to read and understand. Keen to hear what you all think!

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


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Tuesday, 5 July 2022 17:05:37 UTC