update(spec): Add type property to file and group levels (#87)

* update(spec): Add `type` property to file and group levels

Update spec to reflect decision: #63 (comment)

* Fix prettier errors

Co-authored-by: Kevin Powell <[email protected]>

.editorconfig

@@ -10,7 +10,7 @@ trim_trailing_whitespace = true
 end_of_line = lf
 
 # Markdown syntax specifies that trailing whitespaces can be meaningful,
-# so let’s not trim those. e.g. 2 trailing spaces = linebreak (<br />)
+# so let's not trim those. e.g. 2 trailing spaces = linebreak (<br />)
 # See https://daringfireball.net/projects/markdown/syntax#p
 [*.md]
 trim_trailing_whitespace = false

CHARTER.md

@@ -6,7 +6,7 @@ Start Date: Sep 2, 2019
 Last Modifed: Sep 2, 2019  
 W3C page: <https://www.w3.org/community/design-tokens/>
 
-The DTCG’s goal is to provide standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale.
+The DTCG's goal is to provide standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale.
 
 ## Scope of Work
 
@@ -47,7 +47,7 @@ The group MAY produce test suites to support the Specifications. Please see the
 
 The group operates under the [Community and Business Group Process](https://www.w3.org/community/about/agreements/). Terms in this Charter that conflict with those of the Community and Business Group Process are void.
 
-As with other Community Groups, W3C seeks organizational licensing commitments under the [W3C Community Contributor License Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/). When people request to participate without representing their organization’s legal interests, W3C will in general approve those requests for this group with the following understanding: W3C will seek and expect an organizational commitment under the CLA starting with the individual’s first request to make a contribution to a group [Deliverable](#deliverables). The section on [Contribution Mechanics](#contrib) describes how W3C expects to monitor these contribution requests.
+As with other Community Groups, W3C seeks organizational licensing commitments under the [W3C Community Contributor License Agreement (CLA)](http://www.w3.org/community/about/agreements/cla/). When people request to participate without representing their organization's legal interests, W3C will in general approve those requests for this group with the following understanding: W3C will seek and expect an organizational commitment under the CLA starting with the individual's first request to make a contribution to a group [Deliverable](#deliverables). The section on [Contribution Mechanics](#contrib) describes how W3C expects to monitor these contribution requests.
 
 The [W3C Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/) applies to participation in this group.
 
@@ -69,17 +69,17 @@ All GitHub repositories attached to the Community Group must contain a copy of t
 
 The group will conduct all of its technical work in public. If the group uses GitHub, all technical work will occur in its GitHub repositories (and not in mailing list discussions). This is to ensure contributions can be tracked through a software tool.
 
-Meetings may be restricted to Community Group participants, but a public summary or minutes must be posted to the group’s public mailing list, or to a GitHub issue if the group uses GitHub.
+Meetings may be restricted to Community Group participants, but a public summary or minutes must be posted to the group's public mailing list, or to a GitHub issue if the group uses GitHub.
 
 ## Decision Process<a name="decision"></a>
 
-This group will seek to make decisions where there is consensus. Groups are free to decide how to make decisions (e.g. Participants who have earned Committer status for a history of useful contributions assess consensus, or the Chair assesses consensus, or where consensus isn’t clear there is a Call for Consensus [CfC] to allow multi-day online feedback for a proposed course of action). It is expected that participants can earn Committer status through a history of valuable contributions as is common in open source projects. After discussion and due consideration of different opinions, a decision should be publicly recorded (where GitHub is used as the resolution of an Issue).
+This group will seek to make decisions where there is consensus. Groups are free to decide how to make decisions (e.g. Participants who have earned Committer status for a history of useful contributions assess consensus, or the Chair assesses consensus, or where consensus isn't clear there is a Call for Consensus [CfC] to allow multi-day online feedback for a proposed course of action). It is expected that participants can earn Committer status through a history of valuable contributions as is common in open source projects. After discussion and due consideration of different opinions, a decision should be publicly recorded (where GitHub is used as the resolution of an Issue).
 
 If substantial disagreement remains (e.g. the group is divided) and the group needs to decide an Issue in order to continue to make progress, the Committers will choose an alternative that had substantial support (with a vote of Committers if necessary). Individuals who disagree with the choice are strongly encouraged to take ownership of their objection by taking ownership of an alternative fork. This is explicitly allowed (and preferred to blocking progress) with a goal of letting implementation experience inform which spec is ultimately chosen by the group to move ahead with.
 
-Any decisions reached at any meeting are tentative and should be recorded in a GitHub Issue for groups that use GitHub and otherwise on the group’s public mail list. Any group participant may object to a decision reached at an online or in-person meeting within 7 days of publication of the decision provided that they include clear technical reasons for their objection. The Chairs will facilitate discussion to try to resolve the objection according to the [decision process](#decision).
+Any decisions reached at any meeting are tentative and should be recorded in a GitHub Issue for groups that use GitHub and otherwise on the group's public mail list. Any group participant may object to a decision reached at an online or in-person meeting within 7 days of publication of the decision provided that they include clear technical reasons for their objection. The Chairs will facilitate discussion to try to resolve the objection according to the [decision process](#decision).
 
-It is the Chairs’ responsibility to ensure that the decision process is fair, respects the consensus of the CG, and does not unreasonably favour or discriminate against any group participant or their employer.
+It is the Chairs' responsibility to ensure that the decision process is fair, respects the consensus of the CG, and does not unreasonably favour or discriminate against any group participant or their employer.
 
 ## Chair Selection
 

CONTRIBUTING.md

@@ -2,14 +2,14 @@
 
 This repository is being used for work in the [W3C Design Tokens Community Group](https://www.w3.org/community/design-tokens/), governed by the [W3C Community License Agreement (CLA)](https://www.w3.org/community/about/agreements/cla/). To make substantive contributions, you must join [the Community Group](https://www.w3.org/community/design-tokens/).
 
-For more details, read the [Contribution Mechanics section](https://github.com/design-tokens/community-group/blob/main/CHARTER.md#contrib) of the working group’s charter.
+For more details, read the [Contribution Mechanics section](https://github.com/design-tokens/community-group/blob/main/CHARTER.md#contrib) of the working group's charter.
 
 ---
 
 If you are not the sole contributor to a contribution (pull request), please identify all
 contributors in the pull request comment.
 
-To add a contributor (other than yourself, that’s automatic), mark them one per line as follows:
+To add a contributor (other than yourself, that's automatic), mark them one per line as follows:
 
 ```
 +@github_username

README.md

@@ -12,7 +12,7 @@ Design tokens were created by the Salesforce design system team, and the name co
 
 Sharing design properties such as a color palette across many tools and platforms should be simple.
 
-The DTCG’s goal is to provide standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale.
+The DTCG's goal is to provide standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale.
 
 We believe that a common way to share design tokens will unlock efficiency opportunities for plugins, design system teams, product teams, and end-users of design tools.
 
@@ -92,5 +92,5 @@ See [CONTRIBUTING.md](https://github.com/design-tokens/community-group/blob/main
 
 We acknowledge that the format specification is only part of an ecosystem, supporting methods and practices that relate to scaling design tokens:
 
-> Design Tokens are a methodology. IMHO, saying “design tokens are just variables” is like saying “responsive design is just media queries”. It’s a technology-agnostic architecture and process for scaling design across multiple platforms and devices, including native, and more.
+> Design Tokens are a methodology. IMHO, saying "design tokens are just variables" is like saying "responsive design is just media queries". It's a technology-agnostic architecture and process for scaling design across multiple platforms and devices, including native, and more.
 > — [@jina on Twitter](https://twitter.com/jina/status/1062808011301965825)

technical-reports/README.md

@@ -41,7 +41,9 @@ npm run dev
 
 We use the [W3C's ReSpec tool](https://respec.org/docs/) to generate our technical reports. Although knowledge of HTML and Markdown is sufficient for simple edits, we recommend that authors familiarise themselves with ReSpec's features.
 
-To making editing our format specification more convenient and to reduce the likelihood of merge conflicts, we have split out the main chapters into separate Markdown files. The `format/index.html` then includes them all using [ReSpec's `data-include` feature](https://respec.org/docs/#data-include). For example:
+To making editing our format specification more convenient and to reduce the likelihood of merge conflicts, we have split out the main chapters into separate Markdown files. The `format/index.html` then includes them all using [ReSpec's `data-include` feature](https://respec.org/docs/#data-include).
+
+For example:
 
 ```html
 <section

technical-reports/format/aliases.md

@@ -7,7 +7,9 @@ Aliases are useful for:
 - Expressing design choices
 - Eliminating repetition of values in token files (DRYing up the code)
 
-For a design token to reference another, its value should be a string containing the period-separated (.) path to the token it’s referencing enclosed in curly brackets. For example:
+For a design token to reference another, its value should be a string containing the period-separated (.) path to the token it's referencing enclosed in curly brackets.
+
+For example:
 
 <aside class="example">
 
@@ -26,7 +28,7 @@ For a design token to reference another, its value should be a string containing
 
 </aside>
 
-When a tool needs the actual value of a token it must resolve the reference - i.e. lookup the token being referenced and fetch its value. In the above example, the "alias name" token’s value would resolve to 1234 because it references the token whose path is `{group name.token name}` which has the value 1234.
+When a tool needs the actual value of a token it must resolve the reference - i.e. lookup the token being referenced and fetch its value. In the above example, the "alias name" token's value would resolve to 1234 because it references the token whose path is `{group name.token name}` which has the value 1234.
 
 Tools should preserve references and therefore only resolve them whenever the actual value needs to be retrieved. For instance, in a design tool, changes to the value of a token being referenced by aliases should be reflected wherever those aliases are being used.
 

technical-reports/format/composite-types.md

@@ -9,7 +9,7 @@ If so, which composites should be included initially?
 
 </div>
 
-The types described in the previous chapter are all for singular values (a color, a dimension, etc.). However, it can often be useful to group related values as a single token so that they can be used or referenced as a single unit. A typical example of this is a “typography style” as found in many design tools, which is a combination of the font name, weight, style, and color.
+The types described in the previous chapter are all for singular values (a color, a dimension, etc.). However, it can often be useful to group related values as a single token so that they can be used or referenced as a single unit. A typical example of this is a "typography style" as found in many design tools, which is a combination of the font name, weight, style, and color.
 
 Other examples might be:
 
@@ -74,7 +74,7 @@ At first glance, groups and composite types might look very similar. However, th
 
 ## Type checking
 
-Just as with “normal” types for tokens, using a custom, composite type will allow tools to check that the values you use match the expected type. In our color pair example above, attempting to do the following would be invalid and tools should ignore the token and show an error to the user, since “Comic Sans MS” is not a valid color value.
+Just as with "normal" types for tokens, using a custom, composite type will allow tools to check that the values you use match the expected type. In our color pair example above, attempting to do the following would be invalid and tools should ignore the token and show an error to the user, since "Comic Sans MS" is not a valid color value.
 
 <aside class="example" title="Invalid type">
 

technical-reports/format/design-token.md

@@ -14,12 +14,12 @@
 
 </aside>
 
-An object with a “**value**” property is a token. Thus, “value” is a reserved word in our spec, meaning you can’t have a token whose name is “value”. The parent object’s key is the token name.
+An object with a "**value**" property is a token. Thus, "value" is a reserved word in our spec, meaning you can't have a token whose name is "value". The parent object's key is the token name.
 
 The example above therefore defines 1 design token with the following properties:
 
-- Name: “token name”
-- Value: “token value”
+- Name: "token name"
+- Value: "token value"
 
 Name and value are both **required**.
 
@@ -90,11 +90,13 @@ Please raise concerns if these limitations create problems for implementers.
 
 ## Additional properties
 
-While “value” is the only required property for a token, a number of additional properties may be added:
+While "value" is the only required property for a token, a number of additional properties may be added:
 
 ## Description
 
-A plain text description explaining the token’s purpose. Tools MAY use the description in various ways. For example:
+A plain text description explaining the token's purpose. Tools MAY use the description in various ways.
+
+For example:
 
 - Style guide generators could display the description text alongside a visual preview of the token
 - IDEs might display the description as a tooltip for auto-completion (similar to how API docs are displayed)
@@ -122,17 +124,43 @@ The **description** property must be a plain JSON string, for example:
 
 ## Type
 
-Declares the type of the token. [See “Types”](#types) for more information.
+Design tokens always have an unambiguous type, so that tools can reliably interpret their value.
 
-<div class="issue" data-number="63" title="Token types optional or required">
-  Are token types optional or required?
-</div>
+If a token's type is not explicitly specified via the `type` property, then the token's type MUST be determined as follows:
+
+- If the token's value is a reference, then its type is the type of the token being referenced.
+- Otherwise, if any of the token's parent groups have a `type` property, then the token's type is inherited from the closest parent group with a `type` property.
+- Otherwise, the token's type is whichever of the basic JSON types (`string`, `number`, `boolean`, `object`, `array` or `null`) its value is.
+
+Tools MUST NOT attempt to guess the type of a token by inspecting the contents of its value.
+
+The `type` property can be set on different levels:
+
+- at the group level
+- at the token level
+
+The `type` property must be a plain JSON string, whose value is one of the [types](#types) defined in this specification.
+
+For example:
+
+<aside class="example">
+
+```json
+{
+  "Button background": {
+    "value": "#777777",
+    "type": "color"
+  }
+}
+```
+
+</aside>
 
 ## Extensions
 
 The **extensions** property is an object where tools MAY add proprietary, user-, team- or vendor-specific data to a design token. When doing so, each tool MUST use a vendor-specific key whose value may be any valid JSON data.
 
-- The keys SHOULD be chosen such that they avoid the likelihood of a naming clash with another vendor’s data. The [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) is recommended for this purpose.
+- The keys SHOULD be chosen such that they avoid the likelihood of a naming clash with another vendor's data. The [reverse domain name notation](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) is recommended for this purpose.
 - Tools that process design token files MUST preserve any extension data they do not themselves understand. For example, if a design token contains extension data from tool A and the file containing that data is opened by tool B, then tool B MUST include the original tool A extension data whenever it saves a new design token file containing that token.
 
 <aside class="example">
@@ -153,7 +181,7 @@ The **extensions** property is an object where tools MAY add proprietary, user-,
 
 </aside>
 
-In order to maintain interoperability between tools that support this format, teams and tools should restrict their usage of extension data to optional meta-data that is not crucial to understanding that token’s value.
+In order to maintain interoperability between tools that support this format, teams and tools should restrict their usage of extension data to optional meta-data that is not crucial to understanding that token's value.
 
 Tool vendors are encouraged to publicly share specifications of their extension data wherever possible. That way other tools can add support for them without needing to reverse engineer the extension data. Popular extensions may also be incorporated as standardized features in future revisions of this specification.