diff --git a/technical-reports/format/groups.md b/technical-reports/format/groups.md index 4234be9..c924cf3 100644 --- a/technical-reports/format/groups.md +++ b/technical-reports/format/groups.md @@ -6,18 +6,18 @@ A file may contain many tokens and they may be nested arbitrarily in groups like ```json { - "token uno": { + "token-uno": { "value": "token value 1" }, - "token group": { - "token dos": { + "token-group": { + "token-dos": { "value": "token value 2" }, - "nested token group": { - "token tres": { + "nested-token-group": { + "token-tres": { "value": "token value 3" }, - "Token cuatro": { + "token-cuatro": { "value": "token value 4" } } @@ -56,11 +56,37 @@ The names of items in a group are case sensitive. As per the guidance in the [de The format editors acknowledge existing best-practices for token naming, but place no direct constraints on naming via the specification.
-## Additional group properties +## Additional group metadata properties + +Groups MAY include additional metadata properties. To minimize naming collisions with items in the group, all metadata properties are nested inside an object whose key is `metadata`. `metadata` is therefore a reserved word within groups, meaning that tokens and nested groups MUST NOT be called `metadata`. + + ### Description -Groups may include an optional `description` property. +Groups may include an optional `description` metadata property. For example: @@ -69,9 +95,13 @@ For example: ```json { "brand": { - "description": "Design tokens from our brand guidelines", + "metadata": { + "description": "Design tokens from our brand guidelines" + }, "color": { - "description": "Our brand's primary color palette", + "metadata": { + "description": "Our brand's primary color palette" + }, "acid green": { "value": "#00ff66" }, @@ -91,17 +121,11 @@ Suggested ways tools may use this property are: - A GUI tool that lets users browse or select tokens could display this info alongside the corresponding group or as a tooltip - Export tools could output this as a source code comment -