@maggioli-design-system/styles 17.3.0 → 17.5.0

package/dist/dtcg/globals.tokens.json

@@ -1,44 +1,54 @@
 {
   "magma": {
+    "$description": "The semantic layer: the roles UI code paints with. The colour roles follow the mode, the named theme and the contrast preference; rhythm and width are the spaces and the widths of the design language.",
     "pref": {
+      "$description": "The preferences the mds-pref components write on the html element: read them to adapt, never set them by hand.",
       "$extensions": {
         "it.maggioli.magma": {
           "cssOnly": [
             {
               "css": "--magma-pref-mode",
-              "value": "light"
+              "value": "light",
+              "description": "The active mode preference, as the mds-pref components write it: read it, never set it."
             },
             {
               "css": "--magma-pref-theme-scheme",
-              "value": "light"
+              "value": "light",
+              "description": "The active theme-scheme preference, as the mds-pref components write it: read it, never set it."
             },
             {
               "css": "--magma-pref-theme",
-              "value": "default"
+              "value": "default",
+              "description": "The active theme preference, as the mds-pref components write it: read it, never set it."
             },
             {
               "css": "--magma-pref-consumption",
-              "value": "high"
+              "value": "high",
+              "description": "The active consumption preference, as the mds-pref components write it: read it, never set it."
             },
             {
               "css": "--magma-pref-animation",
-              "value": "no-preference"
+              "value": "no-preference",
+              "description": "The active animation preference, as the mds-pref components write it: read it, never set it."
             },
             {
               "css": "--magma-pref-contrast",
-              "value": "no-preference"
+              "value": "no-preference",
+              "description": "The active contrast preference, as the mds-pref components write it: read it, never set it."
             }
           ]
         }
       }
     },
     "backdrop": {
+      "$description": "The scrim behind modals and drawers: its colour, opacity, blur, entrance and stacking level.",
       "animation-duration": {
         "$type": "duration",
         "$value": {
           "value": 300,
           "unit": "ms"
         },
+        "$description": "How long the scrim takes to fade in.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-backdrop-animation-duration",
@@ -49,6 +59,7 @@
       "opacity": {
         "$type": "number",
         "$value": 0.1,
+        "$description": "How much the scrim darkens the page.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-backdrop-opacity",
@@ -62,6 +73,7 @@
           "value": 4,
           "unit": "px"
         },
+        "$description": "How much the scrim blurs the page behind it.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-backdrop-blur",
@@ -80,6 +92,7 @@
           ],
           "hex": "#000000"
         },
+        "$description": "The colour of the scrim, black in both modes; the elevation shadows draw with it too.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-backdrop-color",
@@ -90,6 +103,7 @@
       "z-index": {
         "$type": "number",
         "$value": 4000,
+        "$description": "The stacking level of the scrim, between modals and dropdowns.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-backdrop-z-index",
@@ -109,6 +123,7 @@
           "hex": "#000000",
           "alpha": 0.1
         },
+        "$description": "The scrim as one colour, with its opacity.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-backdrop",
@@ -119,12 +134,14 @@
       }
     },
     "outline": {
+      "$description": "The focus ring, and the transparent ring of an element without focus: the focus effects move between the two.",
       "animation-duration": {
         "$type": "duration",
         "$value": {
           "value": 1.5,
           "unit": "s"
         },
+        "$description": "How long one pulse of the focus ring takes.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-animation-duration",
@@ -138,6 +155,7 @@
           "value": 6,
           "unit": "px"
         },
+        "$description": "The gap of the ring without focus, wider than the focus one: the focus ring closes in from it, or pulses out to it.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-blur-offset",
@@ -151,6 +169,7 @@
           "value": 2,
           "unit": "px"
         },
+        "$description": "The gap between the focus ring and the element.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-focus-offset",
@@ -170,6 +189,7 @@
           "hex": "#000000",
           "alpha": 0
         },
+        "$description": "The colour of the ring without focus: transparent.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-blur-color",
@@ -180,6 +200,7 @@
       "focus-color": {
         "$type": "color",
         "$value": "{palette.tone.neutral.05}",
+        "$description": "The colour of the focus ring.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-focus-color",
@@ -197,6 +218,7 @@
           },
           "style": "solid"
         },
+        "$description": "The ring of an element without focus: transparent.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-blur",
@@ -214,6 +236,7 @@
           },
           "style": "solid"
         },
+        "$description": "The focus ring: width, style and colour.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-outline-focus",
@@ -223,9 +246,11 @@
       }
     },
     "disabled": {
+      "$description": "How disabled components fade.",
       "opacity": {
         "$type": "number",
         "$value": 0.5,
+        "$description": "The opacity of disabled components.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-disabled-opacity",
@@ -235,9 +260,11 @@
       }
     },
     "overlay": {
+      "$description": "The scrim of mds-modal: its colour and blur are the backdrop ones, its opacity is its own.",
       "opacity": {
         "$type": "number",
         "$value": 0.5,
+        "$description": "How much the modal scrim darkens the page.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-overlay-opacity",
@@ -248,6 +275,7 @@
       "color": {
         "$type": "color",
         "$value": "{magma.backdrop.color}",
+        "$description": "The colour of the modal scrim: the backdrop colour.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-overlay-color",
@@ -258,6 +286,7 @@
       "blur": {
         "$type": "dimension",
         "$value": "{magma.backdrop.blur}",
+        "$description": "How much the modal scrim blurs the page: the backdrop blur.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-overlay-blur",
@@ -277,6 +306,7 @@
           "hex": "#000000",
           "alpha": 0.5
         },
+        "$description": "The scrim of mds-modal as one colour, with its opacity.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-overlay",
@@ -287,6 +317,7 @@
       }
     },
     "on": {
+      "$description": "Ink on the scrims.",
       "backdrop": {
         "$type": "color",
         "$value": {
@@ -298,6 +329,7 @@
           ],
           "hex": "#fcfcfc"
         },
+        "$description": "Text and icons on the scrim, such as the close icon of a modal: light in both modes, as the scrim is black in both.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-on-backdrop",
@@ -307,9 +339,11 @@
       }
     },
     "selection": {
+      "$description": "The colours of selected text.",
       "background": {
         "$type": "color",
         "$value": "{palette.label.sky.09}",
+        "$description": "The background of selected text.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-selection-background",
@@ -320,6 +354,7 @@
       "color": {
         "$type": "color",
         "$value": "{palette.label.sky.01}",
+        "$description": "The colour of selected text.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-selection-color",
@@ -329,12 +364,14 @@
       }
     },
     "corner": {
+      "$description": "The corner axis: the shape of the corners, and how much of its height a corner may take.",
       "$extensions": {
         "it.maggioli.magma": {
           "cssOnly": [
             {
               "css": "--magma-corner-shape",
-              "value": "squircle"
+              "value": "squircle",
+              "description": "The shape of the corners: set it through data-corner-shape, which changes the radius scale with it."
             }
           ]
         }
@@ -342,6 +379,7 @@
       "cap": {
         "$type": "number",
         "$value": 0.5,
+        "$description": "The part of its height a corner may take, for the controls whose radius is past half their height.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-corner-cap",
@@ -351,9 +389,11 @@
       }
     },
     "header": {
+      "$description": "The stacking level of the header.",
       "z-index": {
         "$type": "number",
         "$value": 1000,
+        "$description": "The z-index of the header, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-header-z-index",
@@ -363,9 +403,11 @@
       }
     },
     "notification": {
+      "$description": "The stacking level of notifications.",
       "z-index": {
         "$type": "number",
         "$value": 2000,
+        "$description": "The z-index of notifications, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-notification-z-index",
@@ -375,9 +417,11 @@
       }
     },
     "modal": {
+      "$description": "The stacking level of modals.",
       "z-index": {
         "$type": "number",
         "$value": 3000,
+        "$description": "The z-index of modals, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-modal-z-index",
@@ -387,9 +431,11 @@
       }
     },
     "dropdown": {
+      "$description": "The stacking level of dropdowns.",
       "z-index": {
         "$type": "number",
         "$value": 5000,
+        "$description": "The z-index of dropdowns, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-dropdown-z-index",
@@ -399,9 +445,11 @@
       }
     },
     "tooltip": {
+      "$description": "The stacking level of tooltips.",
       "z-index": {
         "$type": "number",
         "$value": 6000,
+        "$description": "The z-index of tooltips, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-tooltip-z-index",
@@ -411,9 +459,11 @@
       }
     },
     "theme": {
+      "$description": "The stacking level of the theme overlay.",
       "overlay-z-index": {
         "$type": "number",
         "$value": 7000,
+        "$description": "The z-index of the theme overlay, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-theme-overlay-z-index",
@@ -423,9 +473,11 @@
       }
     },
     "context": {
+      "$description": "The stacking level of context menus.",
       "menu-z-index": {
         "$type": "number",
         "$value": 8000,
+        "$description": "The z-index of context menus, on the stacking scale of the floating layers: slot your own layers between its steps.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-context-menu-z-index",
@@ -435,21 +487,25 @@
       }
     },
     "view": {
+      "$description": "The view transitions between pages.",
       "$extensions": {
         "it.maggioli.magma": {
           "cssOnly": [
             {
               "css": "--magma-view-transition-navigation",
-              "value": "auto"
+              "value": "auto",
+              "description": "Whether a navigation between pages animates as a view transition."
             }
           ]
         }
       }
     },
     "radius": {
+      "$description": "The radius scale of the active corner shape: what components and UI code round corners with.",
       "none": {
         "$type": "dimension",
         "$value": "{radius.none}",
+        "$description": "No rounding.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-none",
@@ -460,6 +516,7 @@
       "3xs": {
         "$type": "dimension",
         "$value": "{radius.squircle-3xs}",
+        "$description": "The 3xs corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-3xs",
@@ -470,6 +527,7 @@
       "2xs": {
         "$type": "dimension",
         "$value": "{radius.squircle-2xs}",
+        "$description": "The 2xs corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-2xs",
@@ -480,6 +538,7 @@
       "xs": {
         "$type": "dimension",
         "$value": "{radius.squircle-xs}",
+        "$description": "The xs corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-xs",
@@ -490,6 +549,7 @@
       "sm": {
         "$type": "dimension",
         "$value": "{radius.squircle-sm}",
+        "$description": "The sm corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-sm",
@@ -500,6 +560,7 @@
       "md": {
         "$type": "dimension",
         "$value": "{radius.squircle-md}",
+        "$description": "The md corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-md",
@@ -510,6 +571,7 @@
       "lg": {
         "$type": "dimension",
         "$value": "{radius.squircle-lg}",
+        "$description": "The lg corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-lg",
@@ -520,6 +582,7 @@
       "xl": {
         "$type": "dimension",
         "$value": "{radius.squircle-xl}",
+        "$description": "The xl corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-xl",
@@ -530,6 +593,7 @@
       "2xl": {
         "$type": "dimension",
         "$value": "{radius.squircle-2xl}",
+        "$description": "The 2xl corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-2xl",
@@ -540,6 +604,7 @@
       "3xl": {
         "$type": "dimension",
         "$value": "{radius.squircle-3xl}",
+        "$description": "The 3xl corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-3xl",
@@ -550,6 +615,7 @@
       "4xl": {
         "$type": "dimension",
         "$value": "{radius.squircle-4xl}",
+        "$description": "The 4xl corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-4xl",
@@ -560,6 +626,7 @@
       "5xl": {
         "$type": "dimension",
         "$value": "{radius.squircle-5xl}",
+        "$description": "The 5xl corner radius, on the scale of the active corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-5xl",
@@ -570,6 +637,7 @@
       "full": {
         "$type": "dimension",
         "$value": "{radius.full}",
+        "$description": "The pill, the same under every corner shape.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--magma-radius-full",
@@ -582,6 +650,7 @@
   "depth": {
     "$type": "number",
     "$value": 1,
+    "$description": "The depth axis, from 0 to 1: how strong the elevation shadows are. data-theme-depth=\"flat\" sets it to 0.",
     "$extensions": {
       "it.maggioli.magma": {
         "css": "--depth",
@@ -590,7 +659,9 @@
     }
   },
   "mds": {
+    "$description": "Globals the components share.",
     "elevation": {
+      "$description": "The shadows of the raised and overlay surfaces, scaled by the depth axis.",
       "raised": {
         "$type": "shadow",
         "$value": [
@@ -651,6 +722,7 @@
             }
           }
         ],
+        "$description": "The shadow of a raised surface, such as a card.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--mds-elevation-raised",
@@ -719,6 +791,7 @@
             }
           }
         ],
+        "$description": "The shadow of an overlay surface, such as a dropdown or a popover.",
         "$extensions": {
           "it.maggioli.magma": {
             "css": "--mds-elevation-overlay",

package/dist/tailwind/base.css

@@ -88,8 +88,81 @@
     @apply max-w-title;
   }
 
-  p {
-    @apply max-w-title;
+  /* p takes the cap of the reset, max-w-text (the reading measure, #1204): a cap written
+   * here, in a later layer, would win over it. */
+
+  /* The room of mds-status-bar (#1203): while a bar is visible at the end of the window, the page
+   * ends that far above it, and a field reached with Tab stops above it too (WCAG 2.4.11). No
+   * script measures the bar: the room is its tallest for its content, from its own sheet, plus
+   * rhythm/between-fields. It is a box after the body, not a padding of html: a page that zeroes
+   * the padding of html out of any layer, as many resets do, wins over every layer and would drop
+   * it. A page that scrolls in a box of its own reads the same room from --magma-status-bar-room.
+   * A shorter bar leaves the rest empty, never covered.
+   *
+   * The tallest bar: the margin of its area (800), the inset of the bar (600 twice), the
+   * description on a line of its own (one line of caption, the limit of its content), the gap to
+   * the actions (400) and their row (a button, 900). Up to 480px the bar takes the width of the
+   * window and its actions stack (actions/stacked): each action after the first adds a button and
+   * rhythm/inline, up to three (actions/at-most-three). */
+
+  html:has(mds-status-bar[visible]) {
+    --magma-status-bar-room: calc(
+      --spacing(800) + 2 * --spacing(600) + var(--text-size-info-caption--line-height) +
+        --spacing(400) + --spacing(900) + var(--magma-rhythm-between-fields)
+    );
+
+    scroll-padding-bottom: var(--magma-status-bar-room);
+  }
+
+  html:has(mds-status-bar[visible])::after {
+    content: '';
+    display: block;
+    height: var(--magma-status-bar-room);
+  }
+
+  @media (width <= 480px) {
+    html:has(mds-status-bar[visible] > :nth-child(2)) {
+      --magma-status-bar-room: calc(
+        --spacing(800) + 2 * --spacing(600) + var(--text-size-info-caption--line-height) +
+          --spacing(400) + 2 * --spacing(900) + var(--magma-rhythm-inline) +
+          var(--magma-rhythm-between-fields)
+      );
+    }
+
+    html:has(mds-status-bar[visible] > :nth-child(3)) {
+      --magma-status-bar-room: calc(
+        --spacing(800) + 2 * --spacing(600) + var(--text-size-info-caption--line-height) +
+          --spacing(400) + 3 * --spacing(900) + 2 * var(--magma-rhythm-inline) +
+          var(--magma-rhythm-between-fields)
+      );
+    }
+  }
+
+  /* The bar of mds-header (#1189, surfaces/band): the header stands in the flow, sticky, so the
+   * page starts under it by itself; while it stays put it covers the top of the window, and a
+   * field reached with Shift+Tab stops under it (WCAG 2.4.11), rhythm/between-fields lower, as at
+   * the bar of mds-status-bar. No script measures the bar: it is one row, its inset (400 twice) and
+   * a button (900); the floating bar (`inline`) stands its margin lower, 600, and 400 up to 767px
+   * (--mds-header-inline-margin, -mobile). */
+
+  html:has(mds-header) {
+    scroll-padding-top: calc(
+      2 * --spacing(400) + --spacing(900) + var(--magma-rhythm-between-fields)
+    );
+  }
+
+  html:has(mds-header[appearance='inline']) {
+    scroll-padding-top: calc(
+      --spacing(600) + 2 * --spacing(400) + --spacing(900) + var(--magma-rhythm-between-fields)
+    );
+  }
+
+  @media (width <= 767px) {
+    html:has(mds-header[appearance='inline']) {
+      scroll-padding-top: calc(
+        --spacing(400) + 2 * --spacing(400) + --spacing(900) + var(--magma-rhythm-between-fields)
+      );
+    }
   }
 
   /* The box of the hydrated components (against Tailwind's preflight) is kept by