better documentation

Author: edisile

static/sass/_snapcraft_snap-details.scss

@@ -111,30 +111,39 @@
     container: pkgname / inline-size;
 
     &__name {
-      --length: 40; // default value, it should be overridden via inline styles on the element
-      --fs-ratio: 1.765; // height/width (1rem/1ch) ratio measured in the browser
-      // we take the full width of the container and divide it by the number of characters in the
-      // package name (+2 to account for the parentheses): this is the horizontal space that each
-      // character has on average; we multiply this by the fs-ratio to get the font size
+      // package name string length; 40 is the maximum length the store backend
+      // supports and this is just a default value, it should be overridden via inline styles on
+      // the element
+      --length: 40;
+
+      // font size/character width (1rem/1ch) ratio, a magic number
+      // measured in the browser
+      --fs-width-ratio: 1.77;
+
+      // we take the full width of the container (100cqw) and divide it by the number of
+      // characters in the package name (+2 to account for the parentheses): this is the horizontal
+      // space that each character will use on average; we multiply this by the font size/character
+      // width ratio to get the font size
       --target-font-size: calc(
-        (100cqw / (2 + var(--length))) * var(--fs-ratio)
+        (100cqw / (2 + var(--length))) * var(--fs-width-ratio)
       );
 
-      // we limit the font size to the smallest and largest available sizes
-      --max-font-size: #{map-get($settings-text-h1-mobile, font-size)}rem; // size of the title
-      --min-font-size: #{map-get($settings-text-h5-mobile, font-size)}rem; // smallest size we allow
+      // we limit the actual font size value to the smallest and largest heading font sizes
+      --font-size: clamp(
+        var(--min-font-size),
+        var(--target-font-size),
+        var(--max-font-size)
+      );
+      --min-font-size: #{map-get($settings-text-h6-mobile, font-size)}rem;
+      --max-font-size: #{map-get($settings-text-h1-mobile, font-size)}rem;
 
       @media (min-width: $breakpoint-heading-threshold) {
-        --min-font-size: #{map-get($settings-text-h5, font-size)}rem;
+        --min-font-size: #{map-get($settings-text-h6, font-size)}rem;
         --max-font-size: #{map-get($settings-text-h1, font-size)}rem;
       }
 
       display: inline-block;
-      font-size: clamp(
-        var(--min-font-size),
-        var(--target-font-size),
-        var(--max-font-size)
-      );
+      font-size: var(--font-size);
       white-space: nowrap;
 
       .p-tooltip__message {