Capitalize RFC 2119 keywords when appropriate

technical-reports/format/aliases.md

@@ -7,7 +7,7 @@ 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 a design token to reference another, its value MUST be a string containing the period-separated (.) path to the token it's referencing enclosed in curly brackets.
 
 For example:
 
@@ -28,11 +28,11 @@ For example:
 
 </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.
+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.
 
-Aliases may reference other aliases. In this case, tools should follow each reference until they find a token with an explicit value. Circular references are not allowed. If a design token file contains circular references, then the value of all tokens in that chain is unknown and an appropriate error or warning message should be displayed to the user.
+Aliases MAY reference other aliases. In this case, tools MUST follow each reference until they find a token with an explicit value. Circular references are not allowed. If a design token file contains circular references, then the value of all tokens in that chain is unknown and an appropriate error or warning message SHOULD be displayed to the user.
 
 <p class="ednote" title="JSON Pointer syntax">
   The format editors are currently researching JSON Pointer syntax to inform the exact syntax for aliases in tokens. <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-5">https://datatracker.ietf.org/doc/html/rfc6901#section-5</a>

technical-reports/format/design-token.md

@@ -36,7 +36,7 @@ Token names are case-sensitive, so the following example with 2 tokens in the sa
 
 </aside>
 
-However, some tools may need to transform names when exporting to other languages or displaying names to the user, so having token names that differ only in case is likely to cause identical and undesirable duplicates in the output. For example, an export tool that converts these tokens to Sass code may generate problematic output like this:
+However, some tools MAY need to transform names when exporting to other languages or displaying names to the user, so having token names that differ only in case is likely to cause identical and undesirable duplicates in the output. For example, an export tool that converts these tokens to Sass code would generate problematic output like this:
 
 <aside class="example">
 
@@ -60,25 +60,12 @@ Due to the syntax used for [token aliases](#aliases-references) the following ch
 - `}` (right curly bracket)
 - `.` (period)
 
-### Token value type
-
-Token values may be any valid JSON type:
-
-- `string`
-- `number`
-- `array`
-- `object`
-- `boolean`
-- `null`
-
-Additionally, tokens may be defined with a more specific [Token Type](#types)
-
 <div class="issue" data-number="55" title="Object vs Array">
 
 The structure in the example above is a JSON object, an **unordered** set of name/value pairs.
 
 - Objects can't contain members with duplicate keys
-- Ordering of object members may not be preserved (as per [RFC 7159](https://tools.ietf.org/html/rfc7159#section-4)), meaning token retrieval may or may not result in the same ordering as the input
+- Ordering of object members is not guaranteed (as per [RFC 7159](https://tools.ietf.org/html/rfc7159#section-4))
 
 Please raise concerns if these limitations create problems for implementers.
 
@@ -90,20 +77,20 @@ 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:
 
-- 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)
-- Design tools might display the description as a tooltip or alongside tokens wherever they can be selected
-- Export tools might render the description to a source code comment alongside the variable or constant they export.
+- Style guide generators MAY display the description text alongside a visual preview of the token
+- IDEs MAY display the description as a tooltip for auto-completion (similar to how API docs are displayed)
+- Design tools MAY display the description as a tooltip or alongside tokens wherever they can be selected
+- Export tools MAY render the description to a source code comment alongside the variable or constant they export.
 
-The **description** property must be a plain JSON string, for example:
+The **description** property MUST be a plain JSON string, for example:
 
 <aside class="example">
 
@@ -139,7 +126,7 @@ 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.
+The `type` property MUST be a plain JSON string, whose value is one of the [types](#types) defined in this specification.
 
 For example:
 
@@ -158,7 +145,7 @@ For example:
 
 ## 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 **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.
 - 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.
@@ -181,9 +168,9 @@ 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.
+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 could also be incorporated as standardized features in future revisions of this specification.
 
 <p class="ednote" title="Extensions section">
   The extensions section is not limited to vendors. All token users can add additional data in this section for their own purposes.

technical-reports/format/file-format.md

@@ -10,11 +10,11 @@ JSON was chosen as an interchange format on the basis of:
 
 ## Media type (MIME type)
 
-When serving design token files via HTTP / HTTPS or in any other scenario where a media type (formerly known as MIME type) needs to be specified, the following MIME type should be used for design token files:
+When serving design token files via HTTP / HTTPS or in any other scenario where a media type (formerly known as MIME type) needs to be specified, the following MIME type SHOULD be used for design token files:
 
 - `application/design-tokens+json`
 
-However, since every design token file is a valid JSON file and it may not always be possible to configure web servers as needed, it is also acceptable to use the plain JSON media type: `application/json`. The above, more specific media type is preferred and should be used wherever possible.
+However, since every design token file is a valid JSON file, they MAY be served using the JSON media type: `application/json`. The above, more specific media type is preferred and SHOULD be used wherever possible.
 
 Tools that can open design token files MUST support both media types.
 

technical-reports/format/groups.md

@@ -1,6 +1,6 @@
 # Groups
 
-A file may contain many tokens and they may be nested arbitrarily in groups like so:
+A file MAY contain many tokens and they MAY be nested arbitrarily in groups like so:
 
 <aside class="example">
 
@@ -27,7 +27,7 @@ A file may contain many tokens and they may be nested arbitrarily in groups like
 
 </aside>
 
-The names of the groups leading to a given token (including that token's name) are that token's _path_, which is a computed property. **It is not specified in the file**, but parsers that conform to this spec must be able to expose the path of a token. The above example, therefore, defines 4 design tokens with the following properties:
+The names of the groups leading to a given token (including that token's name) are that token's _path_, which is a computed property. **It is not specified in the file**, but parsers that conform to this spec MUST be able to expose the path of a token. The above example, therefore, defines 4 design tokens with the following properties:
 
 - Token #1
   - Name: "token uno"
@@ -60,7 +60,7 @@ The names of items in a group are case sensitive. As per the guidance in the [de
 
 ### Description
 
-Groups may include an optional `description` property.
+Groups MAY include an optional `description` property.
 
 For example:
 
@@ -85,7 +85,7 @@ For example:
 
 </aside>
 
-Suggested ways tools may use this property are:
+Suggested ways tools MAY use this property are:
 
 - A style guide generator could render a section for each group and use the description as an introductory paragraph
 - A GUI tool that lets users browse or select tokens could display this info alongside the corresponding group or as a tooltip
@@ -99,7 +99,7 @@ Groups may support additional properties like type and description. Should other
 
 ### Type
 
-Groups may include an optional `type` property so a type property does not need to be manually added to every token. [See supported "Types"](#types) for more information.
+Groups MAY include an optional `type` property so a type property does not need to be manually added to every token. [See supported "Types"](#types) for more information.
 
 If a group has a `type` property it acts as a default type for any tokens within the group, including ones in nested groups, that do not explicity declare a type via their own `type` property. For the full set of rules by which a design token's type is determined, please refer to the [design token type property chapter](#type-0).
 
@@ -186,13 +186,13 @@ For example:
 
 ### GUI tools
 
-Tools that let users pick or edit tokens via a GUI may use the grouping structure to display a suitable form of progressive disclosure, such as a collapsible tree view.
+Tools that let users pick or edit tokens via a GUI MAY use the grouping structure to display a suitable form of progressive disclosure, such as a collapsible tree view.
 
 ![Progressive disclosure groups](./group-progressive-disclosure.png)
 
 ### Export tools
 
-Token names are not guaranteed to be unique within the same file. The same name can be used in different groups. Also, export tools may need to export design tokens in a uniquely identifiable way, such as variables in code. Export tools should therefore use design tokens' paths as these _are_ unique within a file.
+Token names are not guaranteed to be unique within the same file. The same name can be used in different groups. Also, export tools MAY need to export design tokens in a uniquely identifiable way, such as variables in code. Export tools SHOULD therefore use design tokens' paths as these _are_ unique within a file.
 
 For example, a [translation tool](#translation-tool) like [Style Dictionary](https://amzn.github.io/style-dictionary/) might use the following design token file: