@beehexa/design-tokens 2611.3.2 → 2611.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @beehexa/design-tokens
 
-Source-checkout development package (`0.0.0`, `private: true`), not a registry release number. Managers must authorize a release before the GitHub runner stamps the real version. CI stages checked tarballs; npm maintainer approval with 2FA is required before publication.
+Source-checkout development package (`0.0.0`, `private: true`), not a registry release number. Managers must authorize a release before the GitHub runner stamps the real version and publishes checked tarballs through npm Trusted Publishing/OIDC.
 
 ## Use the installed package
 
@@ -27,7 +27,9 @@ const spacing: TokenName = 'space.200';
 - `tokenInfo` is keyed by the same token names. It contains `name`, `path`, `type`, `description`, raw alias-bearing `value`, optional source `dark`/`vi` extensions, `cssVar`, and fully resolved `resolved`/`darkResolved`/`viResolved`. These descriptions explain individual decisions; they are not a replacement for the complete usage rules in `@beehexa/design-rules`.
 - Generated declarations preserve literal token keys and values. `TokenName` is `keyof typeof tokens.light`; a misspelled key is not widened into `Record<string, string>`.
 - `@beehexa/design-tokens/css` retains native `rem`. It defines `--bh-*` on `:root`, honors explicit `data-theme="light"`/`"dark"`, uses system dark preference only without an explicit light selection, and applies Vietnamese typography via `:lang(vi)` with resets on other explicit languages. It does not set the application's root font size.
-- `@beehexa/design-tokens/css/pixels` uses the identical generator and selectors, converting every `rem` literal to pixels at **16 px per rem**, including compound values. Import this instead of, not alongside, native CSS when integrating the dashboard's current 14px root. This compatibility choice is migration debt, not a 14px design-scale exemption or permission to change token values.
+- `@beehexa/design-tokens/css/pixels` uses the identical generator and selectors, converting every `rem` literal to pixels at **16 px per rem**, including compound values. It is an optional numeric compatibility entrypoint, not the dashboard integration: use native CSS with a 16px root and `font.body.default` (14px) on the body. Never import both CSS variants.
+- Both CSS subpaths include package-owned side-effect declarations, so strict TypeScript consumers with `noUncheckedSideEffectImports` need no ambient module shims. The runtime exports still resolve to the actual CSS files.
+- Source `font.features` is `"cv05", "cv08"`. Generated CSS applies it universally with `!important`, preserving these features across semantic `font` shorthand resets. Add local opt-in features through `--bh-font-features`, not a competing feature property.
 - `@beehexa/design-tokens/dtcg/color.json` (and every other original `tokens/*.json`) exposes the unchanged source data.
 - `@beehexa/design-tokens/package.json` exposes installed origin/version metadata.
 

package/dist/css.d.ts

@@ -0,0 +1,2 @@
+// CSS is imported for side effects only; no JavaScript bindings.
+export {};

package/dist/dtcg/border.json

@@ -19,7 +19,7 @@
       "accent": {
         "$type": "dimension",
         "$value": "4px",
-        "$description": "4 px. A status or emphasis bar on one edge: alerts, banners, rows with an error, callouts and quotes. Pair with a status or brand border colour."
+        "$description": "4 px. A status or emphasis bar on one edge: rows with an error, callouts and quotes. Pair with a status or brand border colour."
       }
     }
   }

package/dist/dtcg/color.json

@@ -1166,7 +1166,7 @@
       "$root": {
         "$type": "color",
         "$value": "{color.brand.white}",
-        "$description": "Cards, panels, dialogs. One step lighter than the page in dark.",
+        "$description": "Cards and panels. One step lighter than the page in dark.",
         "$extensions": {
           "design.beehexa": {
             "dark": "{color.graphite.2}"
@@ -1186,12 +1186,66 @@
       "subtle": {
         "$type": "color",
         "$value": "{color.graphite.2}",
-        "$description": "Sidebars, table headers, quiet areas."
+        "$description": "Shared global header/sidebar shell surface, mobile navigation drawer, table headers and quiet areas."
+      },
+      "overlay": {
+        "$root": {
+          "$type": "color",
+          "$value": "{color.brand.white}",
+          "$description": "Menus, popovers, select lists, toasts, dialogs and drawers. One step lighter than color.surface in dark, so a floating layer reads above cards.",
+          "$extensions": {
+            "design.beehexa": {
+              "dark": "{color.graphite.3}"
+            }
+          }
+        },
+        "hover": {
+          "$type": "color",
+          "$value": "{color.graphite.2}",
+          "$description": "Menu item or option on hover, inside color.surface.overlay.",
+          "$extensions": {
+            "design.beehexa": {
+              "dark": "{color.graphite.4}"
+            }
+          }
+        },
+        "pressed": {
+          "$type": "color",
+          "$value": "{color.graphite.3}",
+          "$description": "Menu item or option when pressed, inside color.surface.overlay.",
+          "$extensions": {
+            "design.beehexa": {
+              "dark": "{color.graphite.5}"
+            }
+          }
+        },
+        "selected": {
+          "$root": {
+            "$type": "color",
+            "$value": "{color.graphite.3}",
+            "$description": "Selected option inside color.surface.overlay. Always add a second cue: a check or bold text.",
+            "$extensions": {
+              "design.beehexa": {
+                "dark": "{color.graphite.5}"
+              }
+            }
+          },
+          "hover": {
+            "$type": "color",
+            "$value": "{color.graphite.4}",
+            "$description": "Selected option on hover, inside color.surface.overlay. In dark it stays on graphite 5, as graphite 6 fails text and border contrast; the check mark carries the state.",
+            "$extensions": {
+              "design.beehexa": {
+                "dark": "{color.graphite.5}"
+              }
+            }
+          }
+        }
       },
       "inverse": {
         "$type": "color",
         "$value": "{color.graphite.12}",
-        "$description": "Inverse surface: tooltips, toasts. Text on top: text.inverse."
+        "$description": "Inverse surface: tooltips. Text on top: text.inverse."
       },
       "scrim": {
         "$type": "color",

package/dist/dtcg/content.json

@@ -0,0 +1,19 @@
+{
+  "content": {
+    "$description": "Reusable application-content identity and empty-state geometry. Identity colours never encode operational status.",
+    "partner-logo": {
+      "size": { "$type": "dimension", "$value": "2.5rem", "$description": "Neutral square partner-logo tile; preserves the brand image aspect ratio." },
+      "image-size": { "$type": "dimension", "$value": "1.75rem", "$description": "Maximum contained partner mark inside the standard partner-logo tile." }
+    },
+    "avatar": {
+      "size": { "$type": "dimension", "$value": "2.5rem", "$description": "Default person or permission-member identity avatar; a visual identity, not a hit target." }
+    },
+    "identity-mark": {
+      "size": { "$type": "dimension", "$value": "2.75rem", "$description": "System/provider identity container when shown beside content labels." },
+      "image-size": { "$type": "dimension", "$value": "1.5rem", "$description": "Contained system/provider identity glyph within the identity-mark container." }
+    },
+    "empty-illustration": {
+      "size": { "$type": "dimension", "$value": "6rem", "$description": "Empty-state illustration container. Standard icons inside retain their own source icon sizes." }
+    }
+  }
+}

package/dist/dtcg/diagram.json

@@ -0,0 +1,48 @@
+{
+  "diagram": {
+    "$description": "Operational execution diagrams. Descriptive states are not business statuses; selection is an independent outer ring. See tools/mermaid.",
+    "canvas": { "$type": "color", "$value": "{color.surface.page}", "$description": "Opaque drawing and image-export sheet; pair with node and edge text." },
+    "node-fill": { "$type": "color", "$value": "{color.surface}", "$description": "Default and indeterminate node fill." },
+    "node-border": { "$type": "color", "$value": "{color.border.bold}", "$description": "Meaningful default and indeterminate node boundary." },
+    "node-title": { "$type": "color", "$value": "{color.text}", "$description": "Node title on node-fill." },
+    "node-desc": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Descriptive node and inspector text on neutral surfaces." },
+    "tile-bg": { "$type": "color", "$value": "{color.background.neutral}", "$description": "Step-category glyph plate; not a status." },
+    "tile-glyph": { "$type": "color", "$value": "{color.icon}", "$description": "Step-category glyph on tile-bg." },
+    "state-ran-ok": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Solid boundary of a step that ran without a reported failure. Descriptive completion evidence, not success green or warning orange." },
+    "ran-ok-fill": { "$type": "color", "$value": "{color.surface}", "$description": "Ran step fill; retain text and completion marker as non-colour cues." },
+    "fail-stroke": { "$type": "color", "$value": "{color.border.danger}", "$description": "Failed node boundary; pair with fail-fill and a failure marker." },
+    "fail-fill": { "$type": "color", "$value": "{color.background.danger.subtle}", "$description": "Failed execution node fill." },
+    "fail-title": { "$type": "color", "$value": "{color.text.danger}", "$description": "Failure title on fail-fill." },
+    "fail-desc": { "$type": "color", "$value": "{color.text.danger}", "$description": "Failure description on fail-fill." },
+    "unreached-fill": { "$type": "color", "$value": "{color.surface.subtle}", "$description": "Never-reached node fill; not a disabled control." },
+    "unreached-stroke": { "$type": "color", "$value": "{color.border.bold}", "$description": "Solid never-reached boundary with an explicit state label." },
+    "unreached-title": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Never-reached title on unreached-fill." },
+    "unreached-desc": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Never-reached description on unreached-fill." },
+    "nottaken-stroke": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Dashed not-taken boundary; dashes and label distinguish it from never reached." },
+    "nottaken-fill": { "$type": "color", "$value": "{color.surface}", "$description": "Not-taken branch fill." },
+    "nottaken-title": { "$type": "color", "$value": "{color.text}", "$description": "Not-taken title on nottaken-fill." },
+    "nottaken-desc": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Not-taken description on nottaken-fill." },
+    "badge-bg": { "$type": "color", "$value": "{color.surface}", "$description": "Repeat-count plate; repetition alone is not a warning." },
+    "badge-text": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Descriptive repeat count on badge-bg." },
+    "badge-border": { "$type": "color", "$value": "{color.border.bold}", "$description": "Repeat-count outline." },
+    "edge": { "$type": "color", "$value": "{color.border.bold}", "$description": "Meaningful neutral relation line and arrow." },
+    "edge-label-text": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Relation label on edge-label-bg." },
+    "edge-label-bg": { "$type": "color", "$value": "{color.surface.page}", "$description": "Opaque relation label plate." },
+    "panel-bg": { "$type": "color", "$value": "{color.surface}", "$description": "Inspector evidence surface." },
+    "panel-border": { "$type": "color", "$value": "{color.border}", "$description": "Decorative inspector divider, not an interactive boundary." },
+    "code-bg": { "$type": "color", "$value": "{color.surface}", "$description": "Structured key/value evidence surface; full code blocks use color.code roles." },
+    "code-key": { "$type": "color", "$value": "{color.text.subtle}", "$description": "Evidence field label on code-bg; not a link." },
+    "code-value": { "$type": "color", "$value": "{color.text}", "$description": "Evidence field value on code-bg." },
+    "selection-ring": { "$type": "color", "$value": "{color.border.focus}", "$description": "Independent outer selection/hover ring on canvas; never replace run-state paint." },
+    "node-font": { "$type": "font", "$value": "{font.body.default}", "$description": "Default Mermaid node label; inherits Vietnamese line-height." },
+    "card-width": { "$type": "dimension", "$value": "15rem", "$description": "240px measurable execution-step label card width; preserve fixed layout topology." },
+    "tile-size": { "$type": "dimension", "$value": "2.75rem", "$description": "44px step-category glyph tile inside execution-card labels, not an interaction target." },
+    "glyph-size": { "$type": "dimension", "$value": "2rem", "$description": "32px category symbol ink size within tile-size; this is a glyph, not display text." },
+    "preview-height": { "$type": "dimension", "$value": "45rem", "$description": "720px embedded authoring preview budget shared by the diagram and adjacent step-detail panel; fullscreen fills its host instead." },
+    "minimum-height": { "$type": "dimension", "$value": "20rem", "$description": "320px minimum authoring-preview viewport budget. Read-only split diagrams instead shrink with their enclosing pane." },
+    "evidence-height": { "$type": "dimension", "$value": "13.75rem", "$description": "220px embedded structured-result viewer height; content scrolls within this budget." },
+    "evidence-minimum-height": { "$type": "dimension", "$value": "12rem", "$description": "192px minimum pane budget for multiple request bodies so one expanded part does not hide another." },
+    "padding": { "$type": "dimension", "$value": "{space.100}", "$description": "Internal Mermaid node padding." },
+    "export-padding": { "$type": "dimension", "$value": "{space.300}", "$description": "Breathing room around fitted and exported drawing bounds." }
+  }
+}

package/dist/dtcg/editor.json

@@ -0,0 +1,129 @@
+{
+  "editor": {
+    "background": {
+      "$type": "color",
+      "$value": "{color.surface}",
+      "$description": "Editor code canvas; pair with editor.text and syntax roles."
+    },
+    "text": {
+      "$type": "color",
+      "$value": "{color.text}",
+      "$description": "Editor default code foreground."
+    },
+    "gutter": {
+      "$type": "color",
+      "$value": "{color.surface.subtle}",
+      "$description": "Line-number gutter surface."
+    },
+    "lineNumber": {
+      "$type": "color",
+      "$value": "{color.text.subtlest}",
+      "$description": "Line numbers on the gutter."
+    },
+    "selection": {
+      "$type": "color",
+      "$value": "{color.background.selected}",
+      "$description": "Selected code range, with native selection/caret cues."
+    },
+    "lineHighlight": {
+      "$type": "color",
+      "$value": "{color.surface.subtle}",
+      "$description": "Current editor line; caret and gutter provide additional cues."
+    },
+    "cursor": {
+      "$type": "color",
+      "$value": "{color.text}",
+      "$description": "Insertion caret."
+    },
+    "border": {
+      "$type": "color",
+      "$value": "{color.border}",
+      "$description": "Editor frame."
+    },
+    "syntax": {
+      "comment": {
+        "$type": "color",
+        "$value": "{color.text.subtlest}",
+        "$description": "Comments: neutral, readable, no dimming."
+      },
+      "string": {
+        "$type": "color",
+        "$value": "{color.text.success}",
+        "$description": "String literals, not success state indicators."
+      },
+      "number": {
+        "$type": "color",
+        "$value": "{color.text.warning}",
+        "$description": "Numeric literals, not warning state indicators."
+      },
+      "keyword": {
+        "$type": "color",
+        "$value": "{color.text.info}",
+        "$description": "Language keywords, not info state indicators."
+      },
+      "type": {
+        "$type": "color",
+        "$value": "{color.text}",
+        "$description": "Types and identifiers."
+      },
+      "delimiter": {
+        "$type": "color",
+        "$value": "{color.text.subtle}",
+        "$description": "Punctuation and delimiters."
+      }
+    },
+    "diff": {
+      "inserted": {
+        "background": {
+          "$type": "color",
+          "$value": "{color.background.success.subtle}",
+          "$description": "Inserted diff text and lines; show + gutter marker."
+        },
+        "text": {
+          "$type": "color",
+          "$value": "{color.text.success}",
+          "$description": "Inserted diff annotation; + or inserted label required."
+        }
+      },
+      "removed": {
+        "background": {
+          "$type": "color",
+          "$value": "{color.background.danger.subtle}",
+          "$description": "Removed diff text and lines; show − gutter marker."
+        },
+        "text": {
+          "$type": "color",
+          "$value": "{color.text.danger}",
+          "$description": "Removed diff annotation; − or removed label required."
+        }
+      }
+    },
+    "font": {
+      "family": {
+        "$type": "fontFamily",
+        "$value": "{font.family.mono}",
+        "$description": "Editor numeric API family from code.default."
+      },
+      "size": {
+        "$type": "dimension",
+        "$value": "{font.size.200}",
+        "$description": "Editor numeric API size from code.default: 14px nominal."
+      },
+      "lineHeight": {
+        "$type": "dimension",
+        "$value": "1.25rem",
+        "$description": "Editor numeric API line height: 20px nominal; Vietnamese 24px.",
+        "$extensions": {
+          "design.beehexa": {
+            "vi": "1.5rem"
+          }
+        }
+      },
+      "weight": {
+        "$type": "fontWeight",
+        "$value": "{font.weight.regular}",
+        "$description": "Editor code weight."
+      }
+    }
+  }
+}

package/dist/dtcg/elevation.json

@@ -4,7 +4,7 @@
       "raised": {
         "$type": "shadow",
         "$value": "0 1px 2px rgb(43 42 40 / 8%), 0 1px 3px rgb(43 42 40 / 6%)",
-        "$description": "Cards that sit on the page.",
+        "$description": "Cards, including cards that only show content, and a card being dragged. Stronger in dark mode.",
         "$extensions": {
           "design.beehexa": {
             "dark": "0 1px 2px rgb(0 0 0 / 40%), 0 1px 3px rgb(0 0 0 / 30%)"
@@ -13,14 +13,24 @@
       },
       "overlay": {
         "$type": "shadow",
-        "$value": "0 24px 80px rgb(43 42 40 / 14%)",
-        "$description": "Dropdowns, popovers and dialogs.",
+        "$value": "0 4px 12px rgb(43 42 40 / 15%)",
+        "$description": "Dropdowns, menus, popovers, select lists and toasts. Pair with color.surface.overlay.",
         "$extensions": {
           "design.beehexa": {
-            "dark": "0 24px 80px rgb(0 0 0 / 50%)"
+            "dark": "0 4px 12px rgb(0 0 0 / 50%)"
+          }
+        }
+      },
+      "modal": {
+        "$type": "shadow",
+        "$value": "0 8px 24px rgb(43 42 40 / 15%)",
+        "$description": "Dialogs, drawers and full sheets that sit on the scrim. Pair with color.surface.overlay.",
+        "$extensions": {
+          "design.beehexa": {
+            "dark": "0 8px 24px rgb(0 0 0 / 50%)"
           }
         }
       }
     }
   }
-}
+}