Re: [community-group] Clarify if manually typing and reading token files is a primary concern (#149)

After discussing further with the editors we believe favoring “human authoring” over “ease-of-parsing” is a principle we wish to standardize. We believe human authoring and flexibility within the spec will play a large role in community adoption of the specification. We know that many design system practitioners author and maintain token files directly, without the aid of a tool, and we want to ensure the syntax of our spec is approachable and understandable.

**At this time our decision making will favor putting more responsibility on a parser or tool to support a readable, human authorable format, instead of putting more responsibility on a human to support an easier-to-parse format. Code should do the heavy lifting, token authors should not.**

We also understand the specification has to lead to token files that are parsable and portable. If part of the specification is vague, it can introduce errors in portability, and we will take steps to update the spec when those areas are identified.
Unfortunately there’s not a decision tree or a concrete mechanism we can use to apply this principle to each decision, since context informs us on a case-by-case basis. To help illustrate this principle in practice here’s an example where we feel this principle has informed our decision making process:

**Group level `$type` inheritance.**
`$type` is a required property for all design tokens. To make that requirement easier for humans to author $type can be inherited from the group level. Specifying it on each individual token would be easier for a tool to parse, but we’d rather provide flexibility for human authors by letting tools do the heavy lifting.

Here’s two contrasting code examples to illustrate. In this particular case the definition of “easier for a human to author” means “less keystrokes required to author and maintain.”

**Easier to parse**
```
{
 "spacing" : {
  "1x": {
   "$value": "0.25rem",
   "$type": "dimension",
  },
  "2x": {
   "$value": "0.5rem",
   "$type": "dimension",
  },
  "4x": {
   "$value": "1rem",
   "$type": "dimension",
  },
  "8x": {
   "$value": "2rem",
   "$type": "dimension",
  },
  "16x": {
   "$value": "4rem",
   "$type": "dimension",
  }
 }
}
```

**Easier for a human to author**
```
{
 "spacing" : {
  "$type": "dimension",
  "1x": {
   "$value": "0.25rem",
  },
  "2x": {
   "$value": "0.5rem",
  },
  "4x": {
   "$value": "1rem",
  },
  "8x": {
   "$value": "2rem",
  },
  "16x": {
   "$value": "4rem",
  }
 }
}
```

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


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

Received on Thursday, 8 December 2022 20:14:37 UTC