@hirobius/design-system 0.8.1

package/LICENSE/main.tsx

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Milsap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# Hirobius Design System V2
+
+Hirobius is a portfolio-grade design-system product surface: a React and TypeScript site, a governed component library, a token pipeline, and an autonomous verification loop living in one repository.
+
+## Using the published package
+
+Installing HDS in another project? It ships to the **public npm registry** as
+`@hirobius/design-system` (ESM) — no `.npmrc`, no token, no registry config. Full
+guide: **[docs/CONSUMING.md](docs/CONSUMING.md)**. The short version:
+
+```bash
+npm install @hirobius/design-system react react-dom
+# react-router is an OPTIONAL peer — only if you want HDS links to drive your router
+```
+
+```tsx
+// once at the app root — full bundle: tokens + theme + utilities + embedded fonts
+import '@hirobius/design-system/tokens.css';
+import { Button } from '@hirobius/design-system';
+
+// add data-hds to the root (or any section) so the scoped base styles apply
+export const App = () => (
+  <div data-hds>
+    <Button>Get started</Button>
+  </div>
+);
+```
+
+No router, Tailwind config, or font files needed. With a router, inject it once
+via `<HdsRouterProvider>`. See **[docs/CONSUMING.md](docs/CONSUMING.md)** for the
+router seam, `data-hds` scoping, and MUI coexistence.
+
+## Developing this repo
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Core verification commands:
+
+```bash
+pnpm typecheck
+pnpm run heal
+pnpm test:layout
+pnpm check:size
+```
+
+## HDS V2 architecture
+
+HDS V2 is built around three structural rules:
+
+- Strict semantics: public surfaces prefer system primitives such as `HdsStack`, `HdsGrid`, `HdsSurface`, `HdsTextLockup`, `DocLayout`, and `CaseStudyLayout` instead of raw layout divs or ad hoc CSS.
+- Polymorphism: primitives are expected to preserve semantic HTML while staying composable through governed APIs such as `forwardRef`, `as`, and layout slots.
+- 12-column grid: page structure is organized around a consistent editorial grid, with readable center columns, intentional breakout zones, and explicit `gap` ownership rather than one-off spacing math.
+
+This repo treats the following files as source of truth:
+
+- `hirobius.tokens.json`: token values and alias chain.
+- `public/hds-manifest.json`: machine-readable system inventory, metadata, and docs linkage.
+- `src/app/data/component-api.json`: generated prop tables and reflected component API.
+- `DESIGN.md`: lean visual spec for agents and engineers.
+- `DESIGN-HANDOFF.md`: verbose visual mirror for handoff and review.
+
+## Editorial Enterprise philosophy
+
+The governing visual direction is "Editorial Enterprise": enterprise-grade rigor with editorial pacing and restraint. The system favors sharp hierarchy, open whitespace, disciplined monochrome neutrals, and a single electric-blue accent. Layouts should feel authored rather than templated.
+
+In practice that means:
+
+- documentation reads like a designed publication, not a component dump
+- cards are used sparingly; whitespace, rails, dividers, and bands carry structure first
+- motion teaches or clarifies instead of decorating
+- surfaces, spacing, and type are token-governed so the visual language stays coherent across portfolio pages and HDS docs
+
+## Autonomous agentic workflow
+
+Regression prevention is intentionally layered.
+
+`CLAUDE.md` is the operating contract. It defines the agent execution protocol, permanent UI guardrails, required validation steps, and the self-heal requirement before a task can be marked complete.
+
+`scripts/self-heal.mjs` is the automated repair loop. It runs the local static and smoke checks, captures failures, and gives the agent a consistent path to diagnose and fix type, layout, and runtime drift before reporting completion.
+
+The Playwright guardrails enforce the visual constitution at runtime. The current suite covers accessibility, layout integrity, collision detection, responsiveness, and visual regression so changes that violate containment, overlap, or responsive behavior fail automatically.
+
+Together the workflow is:
+
+1. Change code inside the token and component constraints.
+2. Run `pnpm typecheck` and `pnpm run heal`.
+3. Let Playwright catch runtime and visual regressions.
+4. If a regression is fixed through self-healing, log the root cause and resolution.
+5. Only then update the verification checklist and ship the change.
+
+## Bundle and release hygiene
+
+This repo tracks both runtime quality and size drift:
+
+- `pnpm check:size` builds the library bundle and runs `size-limit`.
+- `pnpm perf:budget` runs Lighthouse CI assertions for page performance budgets.
+- `pnpm check:release` runs the full release gate, including accessibility, responsive, collision, visual, and bundle-size checks.
+
+## Repository shape
+
+```text
+src/
+  app/
+    components/
+    layouts/
+    pages/
+  styles/
+scripts/
+docs/
+public/
+```
+
+## Primary docs
+
+- [`docs/CONSUMING.md`](docs/CONSUMING.md) — installing & using the published package
+- `CLAUDE.md`
+- `DESIGN.md`
+- `DESIGN-HANDOFF.md`
+- `TASKS.md`
+- `TOKEN_GOVERNANCE.md`
+- `SYSTEMS_REGISTRY.md`

package/dist/chunks/TokenDisplayContext-B3gxyQN7.js

@@ -0,0 +1,95 @@
+import { jsx as r } from "react/jsx-runtime";
+import { useContext as i, createContext as a, forwardRef as w, useState as l, useEffect as L, useCallback as c } from "react";
+const d = a(null);
+function b({ state: t, children: e }) {
+  return /* @__PURE__ */ r(d.Provider, { value: t, children: e });
+}
+function E() {
+  return i(d);
+}
+const x = w(
+  function({ to: e, children: n, ...o }, u) {
+    return /* @__PURE__ */ r("a", { ref: u, href: e, ...o, children: n });
+  }
+), g = a(null);
+function k({ adapter: t, children: e }) {
+  return /* @__PURE__ */ r(g.Provider, { value: t, children: e });
+}
+function y() {
+  const t = i(g);
+  return t || {
+    navigate: (e) => {
+      typeof window < "u" && window.location.assign(e);
+    },
+    currentPath: typeof window < "u" ? window.location.pathname : "/",
+    LinkComponent: x
+  };
+}
+const f = {
+  en: {
+    language: "en",
+    dir: "ltr",
+    label: "English",
+    nativeLabel: "English"
+  }
+}, m = a({
+  language: "en",
+  direction: "ltr",
+  isRtl: !1,
+  setLanguage: () => {
+  },
+  setDirection: () => {
+  },
+  toggleDirection: () => {
+  },
+  options: f
+});
+function D() {
+  try {
+    const t = localStorage.getItem("hds-direction");
+    if (t === "ltr" || t === "rtl") return t;
+  } catch {
+  }
+  return "ltr";
+}
+function A({ children: t }) {
+  const [e, n] = l(D), o = "en", u = e === "rtl";
+  L(() => {
+    try {
+      localStorage.setItem("hds-direction", e);
+    } catch {
+    }
+    document.documentElement.setAttribute("lang", "en"), document.documentElement.setAttribute("data-language", "en"), document.documentElement.setAttribute("dir", e), document.documentElement.setAttribute("data-reading-direction", e);
+  }, [e]);
+  const h = c((s) => {
+  }, []), v = c((s) => {
+    n(s);
+  }, []), p = c(() => {
+    n((s) => s === "ltr" ? "rtl" : "ltr");
+  }, []);
+  return /* @__PURE__ */ r(m.Provider, { value: { language: o, direction: e, isRtl: u, setLanguage: h, setDirection: v, toggleDirection: p, options: f }, children: t });
+}
+function R() {
+  return i(m);
+}
+const C = a(void 0);
+function H({ children: t }) {
+  const [e, n] = l(!1);
+  return /* @__PURE__ */ r(C.Provider, { value: { showCss: e, setShowCss: n, toggleCss: () => n((o) => !o) }, children: t });
+}
+function T() {
+  const t = i(C);
+  return t || { showCss: !1, setShowCss: () => {
+  }, toggleCss: () => {
+  } };
+}
+export {
+  b as F,
+  k as H,
+  A as L,
+  H as T,
+  R as a,
+  E as b,
+  T as c,
+  y as u
+};

package/dist/chunks/form-DnGRy27o.js

@@ -0,0 +1,63 @@
+import { jsx as m, jsxs as u } from "react/jsx-runtime";
+import * as s from "react";
+import { cn as p } from "../cn.js";
+const g = s.forwardRef(function({ className: e, ...l }, o) {
+  return /* @__PURE__ */ m("form", { ref: o, className: p("flex flex-col gap-4", e), ...l });
+});
+function F({
+  htmlFor: c,
+  childId: e,
+  description: l,
+  error: o
+}) {
+  const i = s.useId(), r = c ?? e ?? i, n = `${r}-description`, d = `${r}-error`, a = [l ? n : null, o ? d : null].filter(Boolean).join(" ") || void 0;
+  return { controlId: r, descriptionId: n, errorId: d, describedBy: a };
+}
+const b = s.forwardRef(
+  function({ controlId: e, label: l, description: o, error: i, required: r = !1, className: n, children: d }, a) {
+    const t = `${e}-description`, f = `${e}-error`;
+    return /* @__PURE__ */ u("div", { ref: a, className: p("flex flex-col gap-2", n), children: [
+      /* @__PURE__ */ u("label", { htmlFor: e, className: "text-sm font-medium text-foreground", children: [
+        l,
+        r ? /* @__PURE__ */ u("span", { "aria-hidden": "true", className: "text-destructive", children: [
+          " ",
+          "*"
+        ] }) : null
+      ] }),
+      d,
+      o && !i ? /* @__PURE__ */ m("p", { id: t, className: "text-xs text-muted-foreground", children: o }) : null,
+      i ? /* @__PURE__ */ m("p", { id: f, role: "alert", className: "text-xs text-destructive", children: i }) : null
+    ] });
+  }
+), N = s.forwardRef(function({ label: e, children: l, htmlFor: o, description: i, error: r, required: n = !1, className: d }, a) {
+  const t = s.Children.only(l), { controlId: f, describedBy: x } = F({
+    htmlFor: o,
+    childId: t.props.id,
+    description: i,
+    error: r
+  }), h = s.cloneElement(t, {
+    id: f,
+    required: t.props.required ?? n,
+    "aria-invalid": r ? !0 : t.props["aria-invalid"],
+    "aria-describedby": [t.props["aria-describedby"], x].filter(Boolean).join(" ") || void 0
+  });
+  return /* @__PURE__ */ m(
+    b,
+    {
+      ref: a,
+      controlId: f,
+      label: e,
+      description: i,
+      error: r,
+      required: n,
+      className: d,
+      children: h
+    }
+  );
+});
+export {
+  g as F,
+  N as a,
+  b,
+  F as u
+};

package/dist/cn.js

@@ -0,0 +1,8 @@
+import { clsx as o } from "clsx";
+import { twMerge as t } from "tailwind-merge";
+function n(...r) {
+  return t(o(r));
+}
+export {
+  n as cn
+};

package/dist/contexts.js

@@ -0,0 +1,133 @@
+import { jsx as l, Fragment as A } from "react/jsx-runtime";
+import { useState as i, useCallback as a, useEffect as s, useContext as T, createContext as v } from "react";
+import { F as U, H as z, L as K, T as Y, b as j, u as q, a as B, c as J } from "./chunks/TokenDisplayContext-B3gxyQN7.js";
+const I = ["system", "light", "dark"], m = "hds-theme-mode", w = "hds-theme", S = v({
+  isDark: !0,
+  toggleDark: () => {
+  },
+  mode: "system",
+  setMode: () => {
+  },
+  density: "comfortable",
+  toggleDensity: () => {
+  },
+  setDensity: () => {
+  }
+});
+function y() {
+  try {
+    const t = localStorage.getItem(m);
+    if (t && I.includes(t)) return t;
+  } catch {
+  }
+  return "system";
+}
+function M() {
+  var t;
+  return typeof window > "u" ? !1 : !!((t = window.matchMedia) != null && t.call(window, "(prefers-color-scheme: dark)").matches);
+}
+function E(t) {
+  return t === "dark" ? !0 : t === "light" ? !1 : M();
+}
+function L() {
+  try {
+    const t = localStorage.getItem("hds-density");
+    if (t === "compact" || t === "comfortable") return t;
+  } catch {
+  }
+  return "comfortable";
+}
+function C({ children: t }) {
+  const [n, f] = i(y), [r, u] = i(() => E(y())), [c, g] = i(L), h = a((e) => {
+    const o = e ? "dark" : "light";
+    try {
+      localStorage.setItem(w, o);
+    } catch {
+    }
+    document.documentElement.setAttribute("data-theme", o), document.documentElement.classList.toggle("dark", e);
+  }, []);
+  s(() => {
+    try {
+      localStorage.setItem("hds-density", c);
+    } catch {
+    }
+    document.documentElement.setAttribute("data-density", c);
+  }, [c]), s(() => {
+    h(r);
+  }, [r, h]), s(() => {
+    if (n !== "system" || typeof window > "u" || !window.matchMedia) return;
+    const e = window.matchMedia("(prefers-color-scheme: dark)"), o = () => {
+      u(e.matches);
+    };
+    return e.addEventListener("change", o), () => {
+      e.removeEventListener("change", o);
+    };
+  }, [n]);
+  const _ = a(() => {
+    const e = !r, o = e ? "dark" : "light";
+    f(o), u(e);
+    try {
+      localStorage.setItem(m, o);
+    } catch {
+    }
+  }, [r]), k = a((e) => {
+    f(e), u(E(e));
+    try {
+      localStorage.setItem(m, e);
+    } catch {
+    }
+  }, []), b = a(
+    () => g((e) => e === "comfortable" ? "compact" : "comfortable"),
+    []
+  ), p = a((e) => g(e), []);
+  return /* @__PURE__ */ l(
+    S.Provider,
+    {
+      value: { isDark: r, toggleDark: _, mode: n, setMode: k, density: c, toggleDensity: b, setDensity: p },
+      children: t
+    }
+  );
+}
+function N() {
+  return T(S);
+}
+const d = {}, D = v({ tenantSlug: null });
+function F({ children: t }) {
+  const n = typeof d.VITE_TENANT_SLUG == "string" && d.VITE_TENANT_SLUG.trim().length > 0 ? d.VITE_TENANT_SLUG.trim() : null;
+  return s(() => {
+    if (n)
+      return document.documentElement.setAttribute("data-tenant", n), () => {
+        document.documentElement.removeAttribute("data-tenant");
+      };
+  }, [n]), /* @__PURE__ */ l(D.Provider, { value: { tenantSlug: n }, children: t });
+}
+function G() {
+  return T(D);
+}
+function O(t) {
+  s(() => {
+    const n = document.documentElement.getAttribute("data-tenant");
+    return document.documentElement.setAttribute("data-tenant", t), () => {
+      n !== null ? document.documentElement.setAttribute("data-tenant", n) : document.documentElement.removeAttribute("data-tenant");
+    };
+  }, [t]);
+}
+function H({ children: t }) {
+  return /* @__PURE__ */ l(A, { children: t });
+}
+export {
+  H as FontProvider,
+  U as FreezeState,
+  z as HdsRouterProvider,
+  K as LanguageProvider,
+  F as TenantProvider,
+  C as ThemeProvider,
+  Y as TokenDisplayProvider,
+  j as useFrozenState,
+  q as useHdsRouter,
+  B as useLanguage,
+  G as useTenant,
+  O as useTenantOnDocument,
+  N as useTheme,
+  J as useTokenDisplay
+};

package/dist/form.js

@@ -0,0 +1,62 @@
+import { useForm as f, FormProvider as h, useController as v } from "react-hook-form";
+import { zodResolver as b } from "@hookform/resolvers/zod";
+import { jsx as t } from "react/jsx-runtime";
+import { F as p, u as g, b as S } from "./chunks/form-DnGRy27o.js";
+function y(r, e) {
+  return f({
+    mode: "onTouched",
+    ...e,
+    // @hookform/resolvers v5 + zod v4 model the resolver through separate
+    // input/output generics that don't unify against a single TFieldValues
+    // parameter. The schema parses TO TFieldValues here, so the cast is sound
+    // and keeps the public return type a plain UseFormReturn<TFieldValues>.
+    resolver: b(r)
+  });
+}
+function P({
+  form: r,
+  onSubmit: e,
+  children: i,
+  ...n
+}) {
+  return /* @__PURE__ */ t(h, { ...r, children: /* @__PURE__ */ t(p, { noValidate: !0, onSubmit: r.handleSubmit(e), ...n, children: i }) });
+}
+function j({
+  name: r,
+  label: e,
+  children: i,
+  description: n,
+  required: l,
+  className: a
+}) {
+  var m;
+  const { field: o, fieldState: u } = v({ name: r }), d = (m = u.error) == null ? void 0 : m.message, { controlId: s, describedBy: c } = g({ description: n, error: d }), F = {
+    name: o.name,
+    // Coalesce nullish to '' so a controlled input never flips to uncontrolled.
+    value: o.value ?? "",
+    onChange: o.onChange,
+    onBlur: o.onBlur,
+    ref: o.ref,
+    id: s,
+    required: l,
+    "aria-invalid": d ? !0 : void 0,
+    "aria-describedby": c
+  };
+  return /* @__PURE__ */ t(
+    S,
+    {
+      controlId: s,
+      label: e,
+      description: n,
+      error: d,
+      required: l,
+      className: a,
+      children: i(F)
+    }
+  );
+}
+export {
+  P as HdsForm,
+  j as HdsFormField,
+  y as useHdsForm
+};