@amsterdam/design-system-tokens 3.3.0 → 4.0.0

package/src/brand/ams/typography.tokens.json

@@ -2,15 +2,22 @@
   "ams": {
     "typography": {
       "font-family": {
-        "$value": "'Amsterdam Sans', Arial, sans-serif",
-        "$type": "fontFamily"
+        "$value": ["Amsterdam Sans", "Arial", "sans-serif"],
+        "$type": "fontFamily",
+        "$description": "The corporate typeface with system fallbacks."
       },
       "hyphenate-limit-chars": {
-        "$value": "auto"
+        "$value": "auto",
+        "$description": "Lets the browser decide the minimum character count for hyphenation.",
+        "$extensions": {
+          "nl.amsterdam.type": "hyphenateLimitChars"
+        }
       },
       "body-text": {
+        "$description": "Text styles for running body copy. Font sizes scale fluidly between 320px and 1600px viewports.",
         "font-size": {
           "$value": "clamp(1.125rem, 1.0893rem + 0.1786vw, 1.25rem)",
+          "$description": "Scales from 18px to 20px.",
           "$extensions": {
             "nl.amsterdam.type": "fontSize"
           }
@@ -20,10 +27,11 @@
           "$type": "fontWeight"
         },
         "line-height": {
-          "$value": "1.8",
+          "$value": 1.6,
           "$extensions": {
-            "nl.amsterdam.type": "lineHeight"
-          }
+            "nl.amsterdam.subtype": "lineHeight"
+          },
+          "$type": "number"
         },
         "bold": {
           "font-weight": {
@@ -32,69 +40,85 @@
           }
         },
         "small": {
+          "$description": "For supporting text like captions and metadata.",
           "font-size": {
             "$value": {
               "value": 1,
               "unit": "rem"
             },
-            "$type": "dimension"
+            "$type": "dimension",
+            "$description": "Fixed at 16px; does not scale."
           },
           "line-height": {
-            "$value": "1.6",
+            "$value": 1.5,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         },
         "large": {
+          "$description": "For introductory or lead text.",
           "font-size": {
             "$value": "clamp(1.3125rem, 1.2411rem + 0.3571vw, 1.5625rem)",
+            "$description": "Scales from 21px to 25px.",
             "$extensions": {
               "nl.amsterdam.type": "fontSize"
             }
           },
           "line-height": {
-            "$value": "1.6",
+            "$value": 1.5,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         },
         "x-large": {
+          "$description": "For short prominent text, e.g. blockquotes.",
           "font-size": {
             "$value": "clamp(1.5rem, 1.3571rem + 0.7143vw, 2rem)",
+            "$description": "Scales from 24px to 32px.",
             "$extensions": {
               "nl.amsterdam.type": "fontSize"
             }
           },
           "line-height": {
-            "$value": "1.4",
+            "$value": 1.4,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         }
       },
       "heading": {
+        "$description": "Text styles for section headings. Larger headings use tighter line-heights for visual balance.",
         "font-weight": {
           "$value": "800",
           "$type": "fontWeight"
         },
         "text-wrap": {
-          "$value": "balance"
+          "$value": "balance",
+          "$description": "Distributes heading text evenly across lines for a more balanced appearance.",
+          "$extensions": {
+            "nl.amsterdam.type": "textWrap"
+          }
         },
         "1": {
           "font-size": {
             "$value": "clamp(2rem, 1.7143rem + 1.4286vw, 3rem)",
+            "$description": "Scales from 32px to 48px.",
             "$extensions": {
               "nl.amsterdam.type": "fontSize"
             }
           },
           "line-height": {
-            "$value": "1.2",
+            "$value": 1.2,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         },
         "2": {
@@ -105,10 +129,11 @@
             }
           },
           "line-height": {
-            "$value": "1.3",
+            "$value": 1.3,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         },
         "3": {
@@ -119,10 +144,11 @@
             }
           },
           "line-height": {
-            "$value": "1.3",
+            "$value": 1.3,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         },
         "4": {
@@ -133,10 +159,11 @@
             }
           },
           "line-height": {
-            "$value": "1.4",
+            "$value": 1.4,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         },
         "5": {
@@ -147,10 +174,11 @@
             }
           },
           "line-height": {
-            "$value": "1.4",
+            "$value": 1.4,
             "$extensions": {
-              "nl.amsterdam.type": "lineHeight"
-            }
+              "nl.amsterdam.subtype": "lineHeight"
+            },
+            "$type": "number"
           }
         }
       }

package/src/common/ams/inputs.tokens.json

@@ -1,13 +1,17 @@
 {
   "ams": {
     "inputs": {
+      "$description": "Shared base styles for all form input components: text inputs, selects, text areas, etc.",
       "background-color": {
-        "$value": "{ams.color.background}",
-        "$type": "color"
+        "$value": "{ams.color.background.default}",
+        "$extensions": {
+          "nl.amsterdam.type": "color"
+        }
       },
       "border-color": {
         "$value": "currentColor",
-        "$type": "color"
+        "$type": "color",
+        "$description": "Uses currentColor so the border adapts to the text colour, including in error states."
       },
       "border-style": {
         "$value": "solid",
@@ -23,11 +27,15 @@
       },
       "color": {
         "$value": "{ams.color.text.default}",
-        "$type": "color"
+        "$extensions": {
+          "nl.amsterdam.type": "color"
+        }
       },
       "font-family": {
         "$value": "{ams.typography.font-family}",
-        "$type": "fontFamily"
+        "$extensions": {
+          "nl.amsterdam.type": "fontFamily"
+        }
       },
       "font-size": {
         "$value": "{ams.typography.body-text.font-size}",
@@ -37,44 +45,51 @@
       },
       "font-weight": {
         "$value": "{ams.typography.body-text.font-weight}",
-        "$type": "fontWeight"
+        "$extensions": {
+          "nl.amsterdam.type": "fontWeight"
+        }
       },
       "line-height": {
-        "$value": "1.4",
+        "$value": 1.4,
+        "$description": "Tighter than body text (1.6) to keep inputs compact. Buttons also use this to match.",
         "$extensions": {
-          "nl.amsterdam.type": "lineHeight"
-        }
+          "nl.amsterdam.subtype": "lineHeight"
+        },
+        "$type": "number"
       },
       "outline-offset": {
         "$value": "{ams.focus.outline-offset}",
-        "$type": "dimension",
         "$extensions": {
-          "nl.amsterdam.subtype": "space"
+          "nl.amsterdam.subtype": "space",
+          "nl.amsterdam.type": "dimension"
         }
       },
       "padding-block": {
         "$value": "{ams.space.s}",
-        "$type": "dimension",
         "$extensions": {
-          "nl.amsterdam.subtype": "space"
+          "nl.amsterdam.subtype": "space",
+          "nl.amsterdam.type": "dimension"
         }
       },
       "padding-inline": {
         "$value": "{ams.space.m}",
-        "$type": "dimension",
         "$extensions": {
-          "nl.amsterdam.subtype": "space"
+          "nl.amsterdam.subtype": "space",
+          "nl.amsterdam.type": "dimension"
         }
       },
       "disabled": {
         "color": {
           "$value": "{ams.color.interactive.disabled}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         }
       },
       "hover": {
         "box-shadow": {
           "$type": "shadow",
+          "$description": "An inset shadow that reinforces the border on hover without shifting the layout.",
           "$value": {
             "inset": true,
             "offsetX": {
@@ -97,15 +112,20 @@
       "invalid": {
         "border-color": {
           "$value": "{ams.color.interactive.invalid.default}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "hover": {
           "border-color": {
             "$value": "{ams.color.interactive.invalid.hover}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           },
           "box-shadow": {
             "$type": "shadow",
+            "$description": "An inset shadow using the hover variation of the invalid interactive colour.",
             "$value": {
               "inset": true,
               "offsetX": {
@@ -129,7 +149,9 @@
       "placeholder": {
         "color": {
           "$value": "{ams.color.text.secondary}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         }
       }
     }

package/src/common/ams/links.tokens.json

@@ -1,9 +1,12 @@
 {
   "ams": {
     "links": {
+      "$description": "Shared base styles for all link-like components.",
       "color": {
         "$value": "{ams.color.interactive.default}",
-        "$type": "color"
+        "$extensions": {
+          "nl.amsterdam.type": "color"
+        }
       },
       "text-decoration-thickness": {
         "$value": {
@@ -12,7 +15,8 @@
         },
         "$type": "dimension",
         "$extensions": {
-          "nl.amsterdam.hint": "2px"
+          "nl.amsterdam.hint": "2px",
+          "nl.amsterdam.subtype": "space"
         }
       },
       "text-underline-offset": {
@@ -27,9 +31,12 @@
         }
       },
       "hover": {
+        "$description": "On hover the underline thickens and moves closer to the text.",
         "color": {
           "$value": "{ams.color.interactive.hover}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "text-decoration-thickness": {
           "$value": {
@@ -38,7 +45,8 @@
           },
           "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.hint": "3px"
+            "nl.amsterdam.hint": "3px",
+            "nl.amsterdam.subtype": "space"
           }
         },
         "text-underline-offset": {
@@ -54,36 +62,53 @@
         }
       },
       "subtle": {
+        "$description": "For links that are already recognisable from context, e.g. in navigation menus. No underline by default; underline appears on hover.",
         "text-decoration-line": {
-          "$value": "none"
+          "$value": "none",
+          "$extensions": {
+            "nl.amsterdam.type": "textDecorationLine"
+          }
         },
         "hover": {
           "text-decoration-line": {
-            "$value": "underline"
+            "$value": "underline",
+            "$extensions": {
+              "nl.amsterdam.type": "textDecorationLine"
+            }
           }
         }
       },
       "contrast": {
+        "$description": "For links on coloured backgrounds where the default blue lacks sufficient contrast.",
         "color": {
           "$value": "{ams.color.interactive.contrast}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "hover": {
           "color": {
             "$value": "{ams.color.interactive.contrast}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           }
         }
       },
       "inverse": {
+        "$description": "For links on dark backgrounds.",
         "color": {
           "$value": "{ams.color.interactive.inverse}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "hover": {
           "color": {
             "$value": "{ams.color.interactive.inverse}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           }
         }
       }

package/src/components/ams/accordion.tokens.json

@@ -3,38 +3,43 @@
     "accordion": {
       "gap": {
         "$value": "{ams.space.s}",
-        "$type": "dimension",
         "$extensions": {
-          "nl.amsterdam.subtype": "space"
+          "nl.amsterdam.subtype": "space",
+          "nl.amsterdam.type": "dimension"
         }
       },
       "button": {
         "color": {
           "$value": "{ams.color.interactive.default}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "cursor": {
-          "$value": "{ams.cursor.interactive}"
+          "$value": "{ams.cursor.interactive}",
+          "$extensions": {
+            "nl.amsterdam.type": "cursor"
+          }
         },
         "gap": {
           "$value": "{ams.space.s}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         },
         "outline-offset": {
           "$value": "{ams.focus.outline-offset}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         },
         "padding-block": {
           "$value": "{ams.space.s}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         },
         "padding-inline": {
@@ -47,7 +52,9 @@
         "hover": {
           "color": {
             "$value": "{ams.color.interactive.hover}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           }
         }
       }

package/src/components/ams/action-group.tokens.json

@@ -3,9 +3,9 @@
     "action-group": {
       "gap": {
         "$value": "{ams.space.m}",
-        "$type": "dimension",
         "$extensions": {
-          "nl.amsterdam.subtype": "space"
+          "nl.amsterdam.subtype": "space",
+          "nl.amsterdam.type": "dimension"
         }
       }
     }

package/src/components/ams/alert.tokens.json

@@ -2,12 +2,16 @@
   "ams": {
     "alert": {
       "background-color": {
-        "$value": "{ams.color.background}",
-        "$type": "color"
+        "$value": "{ams.color.background.default}",
+        "$extensions": {
+          "nl.amsterdam.type": "color"
+        }
       },
       "border-color": {
         "$value": "{ams.color.feedback.info}",
-        "$type": "color"
+        "$extensions": {
+          "nl.amsterdam.type": "color"
+        }
       },
       "border-style": {
         "$value": "solid",
@@ -24,79 +28,93 @@
       "severity-indicator": {
         "background-color": {
           "$value": "{ams.color.feedback.info}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "padding-block": {
           "$value": "{ams.space.m}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         },
         "padding-inline": {
           "$value": "{ams.space.s}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         }
       },
       "content": {
         "gap": {
           "$value": "{ams.space.s}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         },
         "padding-block": {
           "$value": "{ams.space.m}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         },
         "padding-inline": {
           "$value": "{ams.space.m}",
-          "$type": "dimension",
           "$extensions": {
-            "nl.amsterdam.subtype": "space"
+            "nl.amsterdam.subtype": "space",
+            "nl.amsterdam.type": "dimension"
           }
         }
       },
       "error": {
         "border-color": {
           "$value": "{ams.color.feedback.error}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "severity-indicator": {
           "background-color": {
             "$value": "{ams.color.feedback.error}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           }
         }
       },
       "success": {
         "border-color": {
           "$value": "{ams.color.feedback.success}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "severity-indicator": {
           "background-color": {
             "$value": "{ams.color.feedback.success}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           }
         }
       },
       "warning": {
         "border-color": {
           "$value": "{ams.color.feedback.warning}",
-          "$type": "color"
+          "$extensions": {
+            "nl.amsterdam.type": "color"
+          }
         },
         "severity-indicator": {
           "background-color": {
             "$value": "{ams.color.feedback.warning}",
-            "$type": "color"
+            "$extensions": {
+              "nl.amsterdam.type": "color"
+            }
           }
         }
       }