@aurea-uds/tokens 0.1.0 → 0.3.0

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@aurea-uds/tokens",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Design tokens for Aurea UDS: the DTCG source and the CSS custom properties generated from it.",
-  "keywords": ["aurea", "design-system", "design-tokens", "dtcg"],
+  "keywords": [
+    "aurea",
+    "design-system",
+    "design-tokens",
+    "dtcg"
+  ],
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -16,8 +21,18 @@
     "dist",
     "src"
   ],
+  "scripts": {
+    "typecheck": "tsc --noEmit --module ESNext --moduleResolution bundler --target ES2022 css-import.type-test.ts"
+  },
   "exports": {
-    "./css": "./dist/aurea.tokens.css",
-    "./json": "./src/aurea.tokens.json"
+    "./css": {
+      "types": "./dist/aurea.tokens.css.d.ts",
+      "default": "./dist/aurea.tokens.css"
+    },
+    "./json": "./src/aurea.tokens.json",
+    "./native": {
+      "types": "./dist/aurea.tokens.native.d.ts",
+      "default": "./dist/aurea.tokens.native.js"
+    }
   }
 }

package/src/aurea.tokens.json

@@ -3,7 +3,7 @@
   "$extensions": {
     "ui.aurea": {
       "version": "1.7.0",
-      "source": "UI-KIT.html v1.7",
+      "source": "legacy-reference.html",
       "principles": [
         "preserve-current-visual-language",
         "semantic-tokens-only",
@@ -443,6 +443,14 @@
         "unit": "rem"
       }
     },
+    "sidebar-rail": {
+      "$type": "dimension",
+      "$description": "Grid column of the collapsed sidebar: the icon rail. It is the COLUMN, not the panel — the sidebar spends space-4 of margin on each side before it starts, which is why 4.5rem was measured wrong first and left the icon 2px outside the box. 5.5rem = 32px of margin + 2px of border + 16px of the panel's own padding + a 16px icon with room around it.",
+      "$value": {
+        "value": 5.5,
+        "unit": "rem"
+      }
+    },
     "topbar-height": {
       "$type": "dimension",
       "$value": {
@@ -655,11 +663,12 @@
       }
     },
     "text-muted": {
-      "$type": "dimension",
+      "$type": "color",
       "$value": "{muted-foreground}"
     },
     "success-400": {
       "$type": "color",
+      "$description": "The success tone: online status, success badge and alert icons.",
       "$value": {
         "colorSpace": "srgb",
         "components": [
@@ -696,6 +705,7 @@
     },
     "warning-400": {
       "$type": "color",
+      "$description": "The warning tone: away status, warning badge and alert icons.",
       "$value": "{brand-yellow}"
     },
     "warning-500": {
@@ -724,6 +734,7 @@
     },
     "danger-400": {
       "$type": "color",
+      "$description": "The danger TONE: dot of a failed status, border of an invalid field, icon of a danger alert. The colour that says \"wrong\", on text and on marks.",
       "$value": {
         "colorSpace": "srgb",
         "components": [
@@ -760,6 +771,7 @@
     },
     "info-400": {
       "$type": "color",
+      "$description": "The informational tone: running status, info badge and alert icons. Neutral news, not a problem.",
       "$value": {
         "colorSpace": "srgb",
         "components": [
@@ -829,10 +841,12 @@
     },
     "oracle-300": {
       "$type": "color",
+      "$description": "Reserved accent kept from the origin kit and deliberately unused by the core. It is not part of the Aurea palette contract — do not introduce it without a decision.",
       "$value": "{chart-1}"
     },
     "oracle-400": {
       "$type": "color",
+      "$description": "Reserved accent kept from the origin kit and deliberately unused by the core. It is not part of the Aurea palette contract — do not introduce it without a decision.",
       "$value": "{chart-2}"
     },
     "oracle-500": {
@@ -990,6 +1004,7 @@
     "dark": {
       "background": {
         "$type": "color",
+        "$description": "The page canvas — the furthest-back surface. Everything floats on top of it; nothing else should use it as a fill.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1001,6 +1016,7 @@
       },
       "foreground": {
         "$type": "color",
+        "$description": "Default body text, on the canvas and on the panel surfaces alike. The most used text colour in the system.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1012,6 +1028,7 @@
       },
       "card": {
         "$type": "color",
+        "$description": "Surface of a floating panel: card, topbar, content area. The Aurea identity is built on these, so this is the fill you reach for by default.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1023,6 +1040,7 @@
       },
       "card-foreground": {
         "$type": "color",
+        "$description": "Text on --card. Separate from --foreground so a panel can shift tone without the text following blindly.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1034,6 +1052,7 @@
       },
       "popover": {
         "$type": "color",
+        "$description": "Surface of a TRANSIENT layer — dialog, drawer, toast, menu, tooltip. It reads as sitting above --card, and that is what tells the eye the layer is temporary.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1045,6 +1064,7 @@
       },
       "popover-foreground": {
         "$type": "color",
+        "$description": "Text on --popover.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1056,14 +1076,17 @@
       },
       "primary": {
         "$type": "color",
+        "$description": "The Aurea yellow. INVARIANT between themes by contract — links, accents, the selected state. Never redefine it.",
         "$value": "{brand-yellow}"
       },
       "primary-foreground": {
         "$type": "color",
+        "$description": "Text and glyphs ON the yellow. Dark on purpose: yellow is a light colour in both themes.",
         "$value": "{brand-yellow-foreground}"
       },
       "secondary": {
         "$type": "color",
+        "$description": "Fill of the quiet-but-present control: secondary button, the current item of a navigation list, a segment that is on.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1075,6 +1098,7 @@
       },
       "secondary-foreground": {
         "$type": "color",
+        "$description": "Text on --secondary.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1086,6 +1110,7 @@
       },
       "muted": {
         "$type": "color",
+        "$description": "Fill for a de-emphasised block — the surface counterpart of --muted-foreground, not a text colour.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1097,6 +1122,7 @@
       },
       "muted-foreground": {
         "$type": "color",
+        "$description": "Secondary text: helper copy, captions, an item that is present but is not the point.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1108,6 +1134,7 @@
       },
       "accent": {
         "$type": "color",
+        "$description": "Hover surface of a control that has no fill of its own (ghost and outline buttons). The lightest possible \"something happened here\".",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1119,6 +1146,7 @@
       },
       "accent-foreground": {
         "$type": "color",
+        "$description": "Text on --accent.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1130,6 +1158,7 @@
       },
       "destructive": {
         "$type": "color",
+        "$description": "Surface of an action that destroys something: the danger button. For actions only — a MESSAGE about danger uses --danger-400 and --danger-bg.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1141,6 +1170,7 @@
       },
       "destructive-foreground": {
         "$type": "color",
+        "$description": "Text on --destructive.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1152,6 +1182,7 @@
       },
       "border": {
         "$type": "color",
+        "$description": "The default hairline between surfaces, and the most used border in the system. If you are unsure which border to use, it is this one.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1164,6 +1195,7 @@
       },
       "input": {
         "$type": "color",
+        "$description": "Border of a form control. Reserved: the core draws fields with --border, and this exists so a consumer can separate the two without forking the CSS.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1176,6 +1208,7 @@
       },
       "ring": {
         "$type": "color",
+        "$description": "Reserved alias for a focus ring in consumer code. The core uses --focus-strong; this exists so a consumer can theme their own controls consistently.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1187,6 +1220,7 @@
       },
       "chart-1": {
         "$type": "color",
+        "$description": "First series of a chart. The five chart tokens are an ORDERED sequence: use them in order, so two charts on the same page give the same series the same colour.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1198,6 +1232,7 @@
       },
       "chart-2": {
         "$type": "color",
+        "$description": "Second series of a chart. See --chart-1 for the rule.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1209,6 +1244,7 @@
       },
       "chart-3": {
         "$type": "color",
+        "$description": "Third series of a chart. See --chart-1 for the rule.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1220,6 +1256,7 @@
       },
       "chart-4": {
         "$type": "color",
+        "$description": "Fourth series of a chart. See --chart-1 for the rule.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1231,6 +1268,7 @@
       },
       "chart-5": {
         "$type": "color",
+        "$description": "Fifth series of a chart. Past five series a chart needs a different form, not a sixth colour.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1242,6 +1280,7 @@
       },
       "sidebar": {
         "$type": "color",
+        "$description": "Surface of the side panel. Its own token rather than --card, so the sidebar can be tinted apart from the content without touching every panel.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1253,6 +1292,7 @@
       },
       "sidebar-foreground": {
         "$type": "color",
+        "$description": "Text and navigation items inside the sidebar.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1264,14 +1304,17 @@
       },
       "sidebar-primary": {
         "$type": "color",
+        "$description": "Reserved: brand accent scoped to the sidebar, for a shell that needs a different emphasis from the page. Unused by the core.",
         "$value": "{brand-yellow}"
       },
       "sidebar-primary-foreground": {
         "$type": "color",
+        "$description": "Reserved: text on --sidebar-primary.",
         "$value": "{brand-yellow-foreground}"
       },
       "sidebar-accent": {
         "$type": "color",
+        "$description": "Hover surface of a sidebar item.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1283,6 +1326,7 @@
       },
       "sidebar-accent-foreground": {
         "$type": "color",
+        "$description": "Text of a sidebar item under the pointer.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1294,6 +1338,7 @@
       },
       "sidebar-border": {
         "$type": "color",
+        "$description": "The sidebar's own hairline: its outline, and the rule under the brand lockup.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1306,6 +1351,7 @@
       },
       "sidebar-ring": {
         "$type": "color",
+        "$description": "Reserved: focus ring scoped to the sidebar. The core uses the single system ring, --focus-strong.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1317,18 +1363,22 @@
       },
       "surface-1": {
         "$type": "color",
+        "$description": "Ring and separator colour for where a shape has to be punched out of the panel behind it — the border between overlapping avatars, the ring of a step dot.",
         "$value": "{card}"
       },
       "surface-2": {
         "$type": "color",
+        "$description": "One step up from the panel: hover of an interactive card, header row of a table. Use it when something must read as raised, not as coloured.",
         "$value": "{secondary}"
       },
       "surface-3": {
         "$type": "color",
+        "$description": "Neutral fill of a track or a placeholder — progress bar, skeleton. It is a background for something that is not text.",
         "$value": "{muted}"
       },
       "surface-inset": {
         "$type": "color",
+        "$description": "A recessed well: code block, log stream. It reads as carved INTO the panel, which is the opposite of --surface-2.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1340,6 +1390,7 @@
       },
       "surface-hover": {
         "$type": "color",
+        "$description": "Generic hover tint for a row or a disclosure that has no state of its own. When the element already carries meaning (selected, current), use --secondary instead.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1351,10 +1402,12 @@
       },
       "foreground-strong": {
         "$type": "color",
+        "$description": "Text that must out-contrast the default, for a heading that has to lift off the body. Reserved: the core does not use it, so reaching for it is a decision, not a default.",
         "$value": "{foreground}"
       },
       "subtle-foreground": {
         "$type": "color",
+        "$description": "The quietest text in the system — group labels, table headers, metadata. One step below --muted-foreground; below it there is nothing readable.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1366,6 +1419,7 @@
       },
       "border-strong": {
         "$type": "color",
+        "$description": "A border that must read as an EDGE and not as a hint: outline buttons, keyboard keys. Use it when the border IS the shape of the component.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1377,10 +1431,12 @@
       },
       "field-bg": {
         "$type": "color",
+        "$description": "Background of a form control: input, textarea, select, and the mark of a checkbox or radio. Fields sit slightly recessed from the panel.",
         "$value": "{muted}"
       },
       "overlay": {
         "$type": "color",
+        "$description": "The scrim behind a modal layer. Dims the page enough to push it back without hiding what is underneath.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1393,6 +1449,7 @@
       },
       "primary-hover": {
         "$type": "color",
+        "$description": "--primary under the pointer, on a filled surface.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1404,6 +1461,7 @@
       },
       "primary-active": {
         "$type": "color",
+        "$description": "--primary while pressed. Reserved: the core resolves the pressed state with geometry instead, so this is here for consumers who also want the colour shift.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1415,6 +1473,7 @@
       },
       "secondary-hover": {
         "$type": "color",
+        "$description": "--secondary under the pointer.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1426,30 +1485,37 @@
       },
       "focus": {
         "$type": "color",
+        "$description": "The soft focus colour, for the halo of a control that cannot carry an outline. The focus CONTRACT is built on --focus-strong.",
         "$value": "{primary}"
       },
       "focus-strong": {
         "$type": "color",
+        "$description": "The focus ring. One colour and one thickness across the whole system — and that uniformity is a gate (geometry.spec), not a convention.",
         "$value": "{primary}"
       },
       "primary-emphasis": {
         "$type": "color",
+        "$description": "A denser yellow for a small solid area that would look washed out at --primary — the primary badge.",
         "$value": "{primary}"
       },
       "primary-outline": {
         "$type": "color",
+        "$description": "Yellow at border strength — the outline of a selected card or of a primary badge, where a filled yellow would shout.",
         "$value": "{primary}"
       },
       "control-selected": {
         "$type": "color",
+        "$description": "The mark of a checked control — the box of a checkbox, the dot of a radio, the filled half of a switch. It is the state, not the container.",
         "$value": "{primary}"
       },
       "control-selected-foreground": {
         "$type": "color",
+        "$description": "The glyph drawn ON --control-selected: the tick, the dot.",
         "$value": "{primary-foreground}"
       },
       "selection": {
         "$type": "color",
+        "$description": "Background of text the user has selected. Set once, on ::selection.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1462,6 +1528,7 @@
       },
       "success-bg": {
         "$type": "color",
+        "$description": "The muted success fill behind text.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1474,6 +1541,7 @@
       },
       "warning-bg": {
         "$type": "color",
+        "$description": "The muted warning fill behind text.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1486,6 +1554,7 @@
       },
       "danger-bg": {
         "$type": "color",
+        "$description": "The muted danger fill, behind text: danger badge, alert, card. Never for a button — that is --destructive.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -1498,6 +1567,7 @@
       },
       "info-bg": {
         "$type": "color",
+        "$description": "The muted informational fill behind text.",
         "$value": {
           "colorSpace": "oklch",
           "components": [
@@ -2116,6 +2186,7 @@
     "comfortable": {
       "control-h-xs": {
         "$type": "dimension",
+        "$description": "Height of the smallest control. The density scale governs HEIGHT — never font size, spacing or radius; that contract is in packages/tokens/README.md.",
         "$value": {
           "value": 1.625,
           "unit": "rem"
@@ -2123,6 +2194,7 @@
       },
       "control-h-sm": {
         "$type": "dimension",
+        "$description": "Height of a small control: compact button, pagination, calendar arrow.",
         "$value": {
           "value": 1.875,
           "unit": "rem"
@@ -2130,6 +2202,7 @@
       },
       "control-h-md": {
         "$type": "dimension",
+        "$description": "Height of the default control, and the reference for anything that must line up beside one — a field, a segment, an avatar, a sidebar item.",
         "$value": {
           "value": 2.25,
           "unit": "rem"
@@ -2137,6 +2210,7 @@
       },
       "control-h-lg": {
         "$type": "dimension",
+        "$description": "Height of a large control.",
         "$value": {
           "value": 2.625,
           "unit": "rem"
@@ -2144,6 +2218,7 @@
       },
       "control-h-xl": {
         "$type": "dimension",
+        "$description": "Height of the largest control, for a single prominent call to action.",
         "$value": {
           "value": 3.125,
           "unit": "rem"
@@ -2151,6 +2226,7 @@
       },
       "row-h": {
         "$type": "dimension",
+        "$description": "Height of a table row. The one density token that is not about controls.",
         "$value": {
           "value": 3.0,
           "unit": "rem"
@@ -2158,6 +2234,7 @@
       },
       "card-pad": {
         "$type": "dimension",
+        "$description": "Inner padding of a panel. Density breathes here, which is why a compact layout feels tighter without anything having moved.",
         "$value": {
           "value": 1.25,
           "unit": "rem"
@@ -2165,6 +2242,7 @@
       },
       "section-gap": {
         "$type": "dimension",
+        "$description": "Vertical gap between sections of a page.",
         "$value": {
           "value": 1.5,
           "unit": "rem"