@kiva/kv-components 8.11.4 → 8.12.0

package/dist/vue/KvSimpleMap2.js

@@ -0,0 +1,529 @@
+import { defineComponent as Ue, useSlots as Ye, computed as l, ref as m, watch as V, onMounted as We, onBeforeUnmount as Xe, openBlock as v, createElementBlock as d, normalizeStyle as $, createElementVNode as g, Fragment as Ge, renderList as qe, unref as C, createVNode as L, createCommentVNode as T, Transition as Ke, withCtx as je, normalizeClass as Je, renderSlot as Qe, toDisplayString as le } from "vue";
+import { mdiPlus as et, mdiMinus as tt, mdiPlay as nt } from "@mdi/js";
+import N from "@kiva/kv-tokens";
+import ot from "../data/simpleMapPaths.js";
+import lt from "../data/simpleMapCountryPaths.js";
+import U from "../data/simpleMapCentroids.js";
+import { ALL_COUNTRIES_ISO_MAP as ae } from "../data/allCountriesISOMap.js";
+import { useMapTourCycle as at } from "../utils/useMapTourCycle.js";
+import Y from "./KvMaterialIcon.js";
+const ut = ["viewBox"], rt = ["d", "fill", "onPointerenter", "onPointerleave"], it = {
+  key: 0,
+  class: "kv-simple-map__zoom-controls tw-absolute tw-top-2 tw-right-2 tw-flex tw-flex-col tw-gap-1"
+}, st = ["disabled"], ct = ["disabled"], pt = { class: "kv-simple-map__popup-layer tw-absolute tw-inset-0 tw-pointer-events-none" }, ft = { class: "kv-simple-map__popup-content" }, mt = { class: "kv-simple-map__default-popup" }, vt = {
+  key: 0,
+  class: "tw-text-label"
+}, dt = {
+  key: 1,
+  class: "tw-text-caption"
+}, R = 1300.02, D = 571.784, yt = "cubic-bezier(0.76, 0, 0.24, 1)", xt = 60, St = /* @__PURE__ */ Ue({
+  __name: "KvSimpleMap",
+  props: {
+    /**
+     * Countries to make interactive: each entry is hover-able and (when autoplay
+     * is true) becomes a stop on the scripted tour. Countries not in this list
+     * still render as background but do not show popups.
+     */
+    countries: {
+      type: Array,
+      default: () => []
+    },
+    /**
+     * Width / height ratio that drives the default container height when no
+     * explicit height is set. Defaults to the source SVG's natural ratio.
+     */
+    aspectRatio: {
+      type: Number,
+      default: R / D
+    },
+    /**
+     * Explicit height override in pixels. Takes precedence over aspectRatio.
+     */
+    height: {
+      type: Number,
+      default: null
+    },
+    /**
+     * Explicit width override in pixels. Defaults to 100% of parent.
+     */
+    width: {
+      type: Number,
+      default: null
+    },
+    /**
+     * When true, the map runs an automatic tour through `countries`, panning
+     * and zooming to each in turn. Drag and zoom controls are suspended.
+     */
+    autoplay: {
+      type: Boolean,
+      default: !1
+    },
+    /**
+     * When true (and autoplay is true), the tour repeats indefinitely.
+     */
+    loop: {
+      type: Boolean,
+      default: !0
+    },
+    /**
+     * Allow click-and-drag to pan the map. Ignored during autoplay.
+     */
+    allowDragging: {
+      type: Boolean,
+      default: !0
+    },
+    /**
+     * Show + / − zoom buttons. Hidden during autoplay.
+     */
+    showZoomControls: {
+      type: Boolean,
+      default: !0
+    },
+    /**
+     * Multiplier applied to the base "fit-to-width" scale when focusing on a
+     * country during the tour. 2.0 ≈ desktop default, 2.4 ≈ more impact on small viewports.
+     */
+    zoomFactor: {
+      type: Number,
+      default: 2
+    },
+    /**
+     * Minimum zoom (1 = full overview).
+     */
+    minZoom: {
+      type: Number,
+      default: 1
+    },
+    /**
+     * Maximum zoom multiplier on top of base scale.
+     */
+    maxZoom: {
+      type: Number,
+      default: 4
+    },
+    /**
+     * Step applied per zoom-button click.
+     */
+    zoomStep: {
+      type: Number,
+      default: 0.5
+    },
+    /** Highlight color for active / hovered countries. Defaults to eco-green DEFAULT. */
+    highlightColor: {
+      type: String,
+      default: N.colors["eco-green"].DEFAULT
+    },
+    /** Base color for countries that aren't in the `countries` list. */
+    baseColor: {
+      type: String,
+      default: N.colors.gray[200]
+    },
+    /**
+     * Loan-count thresholds that bucket each country into one of the four
+     * eco-green tiers. The default mirrors the design spec:
+     *   1–3 → tier 1, 4–8 → tier 2, 9–14 → tier 3, 15+ → tier 4.
+     * Pass an array of four ascending lower-bounds to customize.
+     */
+    loanCountTiers: {
+      type: Array,
+      default: () => [1, 4, 9, 15]
+    },
+    /** Background color of the ocean / unfilled area. */
+    oceanColor: {
+      type: String,
+      default: "#e8f4fa"
+    },
+    /**
+     * Where to place the hover/tour popup relative to the country:
+     *   'top'           — centered above the country (auto-flips below if it
+     *                     would clip the top edge of the container).
+     *   'bottom-right'  — top-left of the popup hugs the country's
+     *                     bottom-right bbox corner.
+     */
+    popupPlacement: {
+      type: String,
+      default: "top",
+      validator: (k) => ["top", "bottom-right"].includes(k)
+    },
+    /**
+     * Pixel gap between the popup and the country edge, applied to whichever
+     * placement is active. Accepts negative values to make the popup overlap
+     * the country (useful for tightly hugging the bbox).
+     */
+    popupOffset: {
+      type: Number,
+      default: 0
+    },
+    /**
+     * On mount (and on resize), fit the camera to the bounding box of the
+     * `countries` list with a small padding buffer. When false, the map opens
+     * on the full world overview. The user's drag/zoom always overrides this
+     * — the fit is only applied until the first interaction.
+     */
+    fitToCountries: {
+      type: Boolean,
+      default: !0
+    },
+    /**
+     * Padding around the fit bbox, expressed as a fraction of the bbox extent
+     * on each side (0.15 = 15% breathing room around all four edges). Only
+     * applies when `fitToCountries` is true.
+     */
+    fitPadding: {
+      type: Number,
+      default: 0.15
+    },
+    /** Tour: ms before the first pan begins. */
+    initialDelay: { type: Number, default: 1e3 },
+    /** Tour: ms per pan animation. */
+    panDuration: { type: Number, default: 1200 },
+    /** Tour: ms to dwell on each country after the pan settles. */
+    holdPerStep: { type: Number, default: 2e3 },
+    /** Tour: ms before the next pan to hide the active popup. */
+    popupHideBefore: { type: Number, default: 350 },
+    /** Tour: ms held on the full overview at the end of a cycle. */
+    holdAll: { type: Number, default: 2e3 },
+    /** Highlight fade duration, in ms. */
+    fadeDuration: { type: Number, default: 500 }
+  },
+  setup(k) {
+    const n = k, ue = Ye(), W = l(() => !!ue.popup), E = m(null), i = m(0), x = m(0);
+    function re() {
+      return n.height != null ? `${n.height}px` : i.value ? `${i.value / n.aspectRatio}px` : `${100 / n.aspectRatio}%`;
+    }
+    const ie = l(() => ({
+      width: n.width != null ? `${n.width}px` : "100%",
+      height: re(),
+      paddingBottom: n.height != null ? void 0 : `${100 / n.aspectRatio}%`
+    }));
+    let P = null;
+    function X() {
+      const e = E.value;
+      if (!e) return;
+      const t = e.getBoundingClientRect();
+      i.value = t.width, x.value = t.height;
+    }
+    const se = l(() => n.countries), ce = l(() => n.loop), A = m(!1), pe = l(() => n.autoplay && !A.value), fe = l(() => ({
+      initialDelay: n.initialDelay,
+      panDuration: n.panDuration,
+      holdPerStep: n.holdPerStep,
+      popupHideBefore: n.popupHideBefore,
+      holdAll: n.holdAll,
+      fadeDuration: n.fadeDuration
+    })), {
+      panIdx: G,
+      highlighted: me,
+      showPopupIdx: q,
+      isRunning: s,
+      start: ve
+    } = at(se, pe, ce, fe.value), c = l(() => i.value ? i.value / R : 1), K = l(() => {
+      const e = c.value, t = D * e;
+      return {
+        x: 0,
+        y: Math.max(0, (x.value - t) / 2),
+        scale: e
+      };
+    });
+    function de(e) {
+      return e.cx != null && e.cy != null ? { cx: e.cx, cy: e.cy } : U[e.id] ?? null;
+    }
+    const ye = l(() => {
+      if (G.value < 0) return null;
+      const e = n.countries[G.value];
+      if (!e) return null;
+      const t = de(e);
+      if (!t) return null;
+      const o = c.value * n.zoomFactor;
+      return {
+        x: i.value / 2 - t.cx * o,
+        y: x.value / 2 - t.cy * o,
+        scale: o
+      };
+    }), u = m({ x: 0, y: 0, scale: 1 }), B = m(!1), j = m(!1), I = m(!1), xe = l(() => {
+      if (!n.fitToCountries || !n.countries.length || !i.value || !x.value) return null;
+      let e = 1 / 0, t = 1 / 0, o = -1 / 0, a = -1 / 0;
+      if (n.countries.forEach((r) => {
+        if (r.cx != null && r.cy != null) {
+          r.cx < e && (e = r.cx), r.cx > o && (o = r.cx), r.cy < t && (t = r.cy), r.cy > a && (a = r.cy);
+          return;
+        }
+        const f = U[r.id];
+        if (!f) return;
+        const ne = 2 * f.cx - f.xMax, oe = 2 * f.cy - f.yMax;
+        ne < e && (e = ne), oe < t && (t = oe), f.xMax > o && (o = f.xMax), f.yMax > a && (a = f.yMax);
+      }), !Number.isFinite(e)) return null;
+      const y = Math.max(0, n.fitPadding), w = Math.max(1, o - e) * (1 + y * 2), M = Math.max(1, a - t) * (1 + y * 2), b = Math.min(i.value / w, x.value / M), He = c.value * n.minZoom, ze = c.value * n.maxZoom, F = Math.max(He, Math.min(ze, b)), Fe = (e + o) / 2, Ve = (t + a) / 2;
+      return {
+        x: i.value / 2 - Fe * F,
+        y: x.value / 2 - Ve * F,
+        scale: F
+      };
+    }), he = l(() => xe.value ?? K.value), O = l(() => s.value ? ye.value ?? K.value : u.value);
+    V(he, (e) => {
+      s.value || I.value || (u.value = e);
+    }, { immediate: !0 }), V(() => n.countries, () => {
+      I.value = !1;
+    }), V(() => n.autoplay, () => {
+      A.value = !1;
+    });
+    const we = l(() => {
+      const { x: e, y: t, scale: o } = O.value, a = !B.value && j.value;
+      return {
+        width: `${R}px`,
+        height: `${D}px`,
+        transformOrigin: "0 0",
+        transform: `translate(${e}px, ${t}px) scale(${o})`,
+        transition: a ? `transform ${n.panDuration}ms ${yt}` : "none",
+        willChange: "transform"
+      };
+    }), _ = m(null), Z = l(() => {
+      const e = /* @__PURE__ */ new Map();
+      return n.countries.forEach((t) => e.set(t.id, t)), e;
+    });
+    function be(e) {
+      return Z.value.has(e) || !!ae[e];
+    }
+    function H(e) {
+      return be(e);
+    }
+    const S = N.colors["eco-green"], ge = [S[1], S[2], S[3], S[4]], J = l(() => n.highlightColor ?? S.DEFAULT), _e = l(() => n.baseColor ?? N.colors.gray[200]), Me = N.colors.gray[300];
+    function Ce(e) {
+      if (e == null || e < n.loanCountTiers[0]) return null;
+      for (let t = n.loanCountTiers.length - 1; t >= 0; t -= 1)
+        if (e >= n.loanCountTiers[t]) return ge[t];
+      return null;
+    }
+    function ke(e) {
+      return {
+        transition: `fill ${n.fadeDuration}ms ease-in-out`,
+        cursor: H(e) && !s.value ? "pointer" : "inherit"
+      };
+    }
+    function Pe(e) {
+      const t = Z.value.get(e), o = t ? Ce(t.loanCount) : null, a = _.value === e && H(e);
+      return me.value.has(e) ? J.value : a ? o ? J.value : Me : o ?? _e.value;
+    }
+    function Se(e) {
+      s.value || H(e) && (_.value = e);
+    }
+    function $e(e) {
+      _.value === e && (_.value = null);
+    }
+    function Te(e) {
+      if (e.cx != null && e.cy != null)
+        return {
+          cx: e.cx,
+          cy: e.cy,
+          xMin: e.cx,
+          xMax: e.cx,
+          yMin: e.cy,
+          yMax: e.cy
+        };
+      const t = U[e.id];
+      return t ? {
+        cx: t.cx,
+        cy: t.cy,
+        xMax: t.xMax,
+        yMax: t.yMax,
+        xMin: 2 * t.cx - t.xMax,
+        yMin: 2 * t.cy - t.yMax
+      } : null;
+    }
+    function Q(e) {
+      const t = Te(e);
+      if (!t) return null;
+      const o = O.value, a = { "--kv-simple-map-popup-offset": `${n.popupOffset}px` };
+      if (n.popupPlacement === "bottom-right")
+        return {
+          placement: "bottom-right",
+          style: {
+            left: `${t.xMax * o.scale + o.x}px`,
+            top: `${t.yMax * o.scale + o.y}px`,
+            ...a
+          }
+        };
+      const y = t.cx * o.scale + o.x, w = t.yMin * o.scale + o.y, M = t.yMax * o.scale + o.y, b = w < xt ? "bottom" : "top";
+      return {
+        placement: b,
+        style: {
+          left: `${y}px`,
+          top: `${b === "top" ? w : M}px`,
+          ...a
+        }
+      };
+    }
+    function ee(e) {
+      return !!e.name || e.loanCount != null;
+    }
+    const p = l(() => {
+      if (s.value && q.value >= 0) {
+        const e = n.countries[q.value];
+        if (!e || !W.value && !ee(e)) return null;
+        const t = Q(e);
+        return t ? { country: e, ...t } : null;
+      }
+      if (!s.value && _.value) {
+        const e = _.value, t = Z.value.get(e) ?? { id: e, name: ae[e] };
+        if (!W.value && !ee(t)) return null;
+        const o = Q(t);
+        return o ? { country: t, ...o } : null;
+      }
+      return null;
+    });
+    function Ne(e) {
+      return e === 1 ? "1 loan" : `${e} loans`;
+    }
+    let h = null;
+    function z(e) {
+      h && (u.value = {
+        ...u.value,
+        x: h.tx + (e.clientX - h.x),
+        y: h.ty + (e.clientY - h.y)
+      });
+    }
+    function Re() {
+      B.value = !1, h = null, window.removeEventListener("pointermove", z);
+    }
+    function De(e) {
+      e.button !== 0 && e.pointerType === "mouse" || (s.value && (u.value = { ...O.value }, A.value = !0), n.allowDragging && (I.value = !0, B.value = !0, h = {
+        x: e.clientX,
+        y: e.clientY,
+        tx: u.value.x,
+        ty: u.value.y
+      }, window.addEventListener("pointermove", z), window.addEventListener("pointerup", Re, { once: !0 })));
+    }
+    const Ee = l(() => n.autoplay && !s.value);
+    function Ae() {
+      A.value = !1, ve();
+    }
+    const Be = l(() => !n.allowDragging || s.value ? "default" : B.value ? "grabbing" : "grab"), Ie = l(() => u.value.scale < c.value * n.maxZoom - 1e-3), Le = l(() => u.value.scale > c.value * n.minZoom + 1e-3);
+    function te(e) {
+      const t = u.value, o = c.value * n.minZoom, a = c.value * n.maxZoom, y = Math.min(a, Math.max(o, t.scale + e * c.value));
+      if (Math.abs(y - t.scale) < 1e-6) return;
+      I.value = !0;
+      const w = i.value, M = x.value, b = y / t.scale;
+      u.value = {
+        x: w / 2 - (w / 2 - t.x) * b,
+        y: M / 2 - (M / 2 - t.y) * b,
+        scale: y
+      };
+    }
+    function Oe() {
+      te(n.zoomStep);
+    }
+    function Ze() {
+      te(-n.zoomStep);
+    }
+    return We(() => {
+      X(), typeof ResizeObserver < "u" && E.value && (P = new ResizeObserver(X), P.observe(E.value)), requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          j.value = !0;
+        });
+      });
+    }), Xe(() => {
+      P == null || P.disconnect(), window.removeEventListener("pointermove", z);
+    }), (e, t) => (v(), d("div", {
+      ref_key: "rootRef",
+      ref: E,
+      class: "kv-simple-map tw-relative tw-block tw-overflow-hidden",
+      style: $(ie.value)
+    }, [
+      g("div", {
+        class: "kv-simple-map__clip tw-absolute tw-inset-0 tw-overflow-hidden",
+        style: $({ backgroundColor: k.oceanColor, cursor: Be.value }),
+        onPointerdown: De
+      }, [
+        g("div", {
+          class: "kv-simple-map__pan-layer tw-absolute tw-top-0 tw-left-0",
+          style: $(we.value)
+        }, [
+          (v(), d("svg", {
+            width: R,
+            height: D,
+            viewBox: `0 0 ${R} ${D}`,
+            fill: "none",
+            "aria-hidden": "true",
+            class: "tw-block"
+          }, [
+            (v(!0), d(Ge, null, qe(C(lt), (o) => (v(), d("path", {
+              key: o.id,
+              d: C(ot)[o.key],
+              fill: Pe(o.id),
+              "fill-rule": "evenodd",
+              "clip-rule": "evenodd",
+              stroke: "white",
+              "stroke-linejoin": "round",
+              style: $(ke(o.id)),
+              onPointerenter: (a) => Se(o.id),
+              onPointerleave: (a) => $e(o.id)
+            }, null, 44, rt))), 128))
+          ], 8, ut))
+        ], 4)
+      ], 36),
+      k.showZoomControls && !C(s) ? (v(), d("div", it, [
+        g("button", {
+          type: "button",
+          class: "kv-simple-map__control-btn",
+          disabled: !Ie.value,
+          "aria-label": "Zoom in",
+          onClick: Oe
+        }, [
+          L(Y, {
+            class: "tw-w-2 tw-h-2",
+            icon: C(et)
+          }, null, 8, ["icon"])
+        ], 8, st),
+        g("button", {
+          type: "button",
+          class: "kv-simple-map__control-btn",
+          disabled: !Le.value,
+          "aria-label": "Zoom out",
+          onClick: Ze
+        }, [
+          L(Y, {
+            class: "tw-w-2 tw-h-2",
+            icon: C(tt)
+          }, null, 8, ["icon"])
+        ], 8, ct)
+      ])) : T("", !0),
+      Ee.value ? (v(), d("button", {
+        key: 1,
+        type: "button",
+        class: "kv-simple-map__control-btn kv-simple-map__play-btn tw-absolute tw-bottom-2 tw-right-2",
+        "aria-label": "Resume tour",
+        onClick: Ae
+      }, [
+        L(Y, {
+          class: "tw-w-2 tw-h-2",
+          icon: C(nt)
+        }, null, 8, ["icon"])
+      ])) : T("", !0),
+      g("div", pt, [
+        L(Ke, { name: "kv-simple-map-popup" }, {
+          default: je(() => [
+            p.value ? (v(), d("div", {
+              key: p.value.country.id,
+              class: Je(["kv-simple-map__popup tw-absolute", `kv-simple-map__popup--${p.value.placement}`]),
+              style: $(p.value.style)
+            }, [
+              g("div", ft, [
+                Qe(e.$slots, "popup", {
+                  country: p.value.country
+                }, () => [
+                  g("div", mt, [
+                    p.value.country.name ? (v(), d("div", vt, le(p.value.country.name), 1)) : T("", !0),
+                    p.value.country.loanCount != null ? (v(), d("div", dt, le(Ne(p.value.country.loanCount)), 1)) : T("", !0)
+                  ])
+                ], !0)
+              ])
+            ], 6)) : T("", !0)
+          ]),
+          _: 3
+        })
+      ])
+    ], 4));
+  }
+});
+export {
+  St as default
+};

package/dist/vue/index.d.ts

@@ -55,6 +55,8 @@ export { default as KvLoadingPlaceholder } from './KvLoadingPlaceholder.vue';
 export { default as KvLoadingSpinner } from './KvLoadingSpinner.vue';
 export { default as KvMap } from './KvMap.vue';
 export { default as KvMaterialIcon } from './KvMaterialIcon.vue';
+export { default as KvSimpleMap } from './KvSimpleMap.vue';
+export type { SimpleMapCountry } from './KvSimpleMap.vue';
 export { default as KvPageContainer } from './KvPageContainer.vue';
 export { default as KvPagination } from './KvPagination.vue';
 export { default as KvPieChart } from './KvPieChart.vue';

package/docs/make-to-vue.md

@@ -90,6 +90,31 @@ Figma Make output is presentational/demo code. Determine what needs to change:
 - **Presentational strings** -> Configurable via props/slots
 - **React animation libraries** -> CSS transitions or Vue composables (prefer no extra deps)
 
+### 1.4 New Sibling Component vs. Extending an Existing One
+
+When the source overlaps an existing kv-component, decide which path to take:
+
+| Situation | Decision |
+|-----------|----------|
+| Same renderer, additional variant or mode | Extend the existing component (new prop, new slot) |
+| Same renderer, breaking change | Create a `V2` (e.g. `KvPieChartV2`) |
+| **Different renderer or fundamentally different runtime cost** | **New sibling component** |
+
+Example: `KvMap` uses MapLibre/Leaflet (WebGL/canvas, tile fetching, ~200KB+ over the wire). A storytelling map driven by inline SVG paths and CSS transforms has none of those costs. Adding a `mode` prop would force every `KvMap` consumer to think about both paths and would bundle code most callers don't use. The right call is a sibling (`KvSimpleMap`) that shares the design vocabulary but not the implementation.
+
+**Stop-and-ask** if the choice isn't obvious — the wrong call is expensive to undo.
+
+### 1.5 External Data Modules
+
+If the source imports a generated or large data module (SVG path dictionaries, GeoJSON, country lists, icon registries, etc.), **copy it into `src/data/` as-is**. Do not translate, reformat, or hand-edit. These files are usually exported from a tool (Figma, Mapshaper, etc.) and should be treated as opaque assets.
+
+- Place the file alongside existing data assets in `src/data/`
+- Rename to a descriptive, kv-style name (e.g. `simpleMapPaths.ts`, not `svg-iw48hjyvei.ts`)
+- Re-export the default export with a typed name where useful
+- Do **not** inline the data into the component file — keeps the component readable and lets the data module be tree-shaken or lazy-imported if needed
+
+Reference: `KvMap.vue` lazy-imports `data/ne_110m_admin_0_countries.json` via dynamic `import()` to keep it out of the main chunk. Do the same when the data is large and only needed when the component actually mounts.
+
 ## Phase 2: Translation Patterns
 
 ### 2.1 React Hooks to Vue Composition API
@@ -119,36 +144,60 @@ Figma Make output is presentational/demo code. Determine what needs to change:
 
 Figma Make outputs raw Tailwind classes. Convert to kv-components patterns:
 
-- **Add `tw-` prefix** to all Tailwind utility classes
-- **Replace hardcoded font families** with design system fonts (`tw-font-sans`, `tw-font-serif`)
-- **Replace hardcoded colors** with token references where possible
-- **Replace pixel values** in Tailwind classes with spacing scale values (8px increments)
-- **Use design tokens** from `@kiva/kv-tokens` for colors, spacing, typography
+- **Always use the project's Tailwind config** (`@kiva/kv-tokens/configs/tailwind.config.js`) as the source of truth for available utilities, the `tw-` prefix, the spacing scale (8px-based, not Tailwind's default 4px), and the colour palette. Don't introduce raw hex values, hardcoded `px`/`rem` literals, or arbitrary class names where a token-backed utility exists.
+- **Apply the `tw-` prefix everywhere.** That includes class attributes in markup *and* `@apply` directives inside `<style lang="postcss" scoped>` blocks. `@apply tw-w-4 tw-h-4 tw-bg-white tw-border tw-border-tertiary tw-rounded-xs;` is the preferred way to assemble shared styles and pseudo-state rules; raw CSS belongs only where no utility exists (e.g. one-off `box-shadow` values, animation keyframes).
+- **Replace hardcoded font families** with design system fonts (`tw-font-sans`, `tw-font-serif`).
+- **Replace hardcoded colors** with token references — semantic Tailwind utilities (`tw-bg-primary`, `tw-text-secondary`, `tw-border-tertiary`) first, then named-palette utilities (`tw-bg-eco-green-2`, `tw-text-gray-300`); reach into `kvTokensPrimitives.colors[...]` from JS only when the colour must reach a non-class consumer (e.g. an SVG `:fill` binding).
+- **Replace pixel values** in Tailwind classes with spacing scale values (8px increments). `tw-w-4` = 32px, not 16px — verify against the token scale, not Tailwind defaults.
+- **Reference the kv-tokens skills** as the canonical guide for any text-styling decision before writing custom CSS. Start with [@kiva/kv-tokens/docs/skills/typography.md](../../kv-tokens/docs/skills/typography.md) for the semantic type scale, heading hierarchy, font pairing, and HTML / Tailwind mappings — always consult it before picking a heading element or text utility.
 
 ### 2.4 Animation Translation
 
-Prefer CSS transitions over JavaScript animation libraries:
+Prefer CSS-native animations: CSS transitions, Tailwind utility classes, and Vue's built-in `<Transition>` / `<TransitionGroup>` for enter/leave. Reach for a JS-driven composable only when the animation is genuinely numeric (count-up, interpolated values, multi-step choreography that can't be expressed declaratively).
 
 | Figma Make / React | Vue Equivalent |
 |--------------------|----------------|
-| `motion/react` animate prop | CSS `transition` property |
-| `transition={{ duration: 0.5 }}` | `transition: property 500ms ease-in-out` |
+| `motion.div` with `animate={...}` | Bind reactive style/class; let CSS transition handle the tween |
+| `transition={{ duration: 0.5 }}` | `transition: property 500ms ease-in-out` (or `tw-transition tw-duration-500`) |
+| `transition={{ ease: [...] }}` | `transition-timing-function: cubic-bezier(...)` |
 | Staggered animations | Computed `transition-delay` per item index |
-| Spring animations | CSS `cubic-bezier()` or `ease-in-out` |
+| Spring animations | CSS `cubic-bezier()` or `ease-in-out` (springs rarely visibly differ at small distances) |
+| `<AnimatePresence>` + `initial`/`animate`/`exit` | Vue `<Transition>` with `enter-from`/`enter-to`/`leave-from`/`leave-to` classes |
 | `requestAnimationFrame` hooks | Vue composable with `onMounted`/`onUnmounted` lifecycle |
 | Opacity/transform tweens | CSS transitions on those properties |
+| `setTimeout`-driven cycles | Vue composable that owns the timer set + cleanup (see 2.5) |
 
-For complex numeric animations (count-up, interpolation), create a composable in `src/utils/`:
+Guidelines:
 
-```ts
-// src/utils/useCountUp.ts
-import { ref, watch, onUnmounted } from 'vue';
+- **Default to declarative.** If the animation can be expressed as "this style depends on this state, transition between them," it belongs in CSS — not in a JS animation loop.
+- **One key per remountable element.** When porting `AnimatePresence` keyed children, preserve the `:key` on the Vue side so `<Transition>` treats each instance as a fresh mount/unmount.
+- **Match perceived timing, not the exact curve.** Spring → ease-in-out and motion's default cubic → a similar `cubic-bezier` are acceptable substitutions unless the user says otherwise. **Stop-and-ask** if the source uses a noticeably distinct easing (overshoot, bounce).
+- **Tailwind first, scoped CSS second.** Prefer `tw-transition`, `tw-duration-*`, `tw-ease-*` utilities; fall back to `<style scoped>` only when a utility doesn't exist for the property or curve.
+- **Don't add a JS animation library.** No `framer-motion` Vue equivalent, no `gsap`, no `motion-vue`. If a component genuinely needs orchestrated numeric animation, write a small composable.
 
-export function useCountUp(target: Ref<number>, active: Ref<boolean>, duration = 500) {
-  // requestAnimationFrame-based tween with easing
-  // Returns reactive ref with current display value
-}
-```
+### 2.5 Timer-Driven Cycles → Composables
+
+`setTimeout`/`setInterval` choreography inside a React `useEffect` should become a composable that owns its timer set and cleans up on unmount. Component files stay declarative; the cycle becomes independently testable.
+
+Guidelines:
+
+- **One owner for timers.** The composable creates timers, holds the references, and clears them on unmount or `stop()`. The component doesn't manage timers directly.
+- **Cancellation is non-negotiable.** Always provide a teardown path and call it from `onBeforeUnmount`. Stale timers firing after unmount are a common source of port bugs.
+- **Expose state, not timers.** Return reactive refs (current step, active flag, etc.) and `start`/`stop` controls — never raw timer IDs.
+- **Test with fake timers.** Use `jest.useFakeTimers()` to assert state transitions at each step boundary without rendering the component.
+- **Make timings injectable.** Pass durations/delays as options with sensible defaults so the cycle can be tuned per consumer (and sped up in tests).
+
+### 2.6 Container-Responsive Sizing
+
+Figma Make outputs **fixed pixel dimensions**. kv-components must be responsive by default, with optional explicit overrides.
+
+Guidelines:
+
+- **Default to 100% width.** Never hardcode a container width into the component.
+- **Mirror existing sizing props.** When a kv-component already implements responsive sizing (e.g. `KvMap` with `aspectRatio` / `height` / `width` props and a `mapDimensions` computed), follow that prop shape so consumers have one mental model.
+- **Decouple internal coordinates from rendered size.** SVG `viewBox`, math keyed off the source's `CONT_W`/`CONT_H` constants, etc. should remain at their natural values; the *container* is what scales. If the source's pan/zoom math is keyed off fixed pixel dimensions, derive those from `getBoundingClientRect()` at runtime.
+- **Use `ResizeObserver` if the container can resize after mount.** Fall back gracefully where it isn't supported.
+- **Aspect-ratio prop, not fixed height.** A numeric `aspectRatio` (width / height) lets the component scale fluidly; explicit `height`/`width` props are escape hatches, not the default path.
 
 ## Phase 3: Component Structure
 
@@ -194,10 +243,13 @@ const { colors } = kvTokensPrimitives;
 
 ### 4.2 Typography
 
-Map Figma Make font references:
-- `Kiva Post Grot:Book` -> `font-weight: 300` (light/book)
-- `Kiva Post Grot:Medium` -> `font-weight: 500` (medium)
-- Font family -> `tw-font-sans` (PostGrotesk)
+The canonical reference for type styling is the [kv-tokens typography skill](../../kv-tokens/docs/skills/typography.md). Consult it before picking a heading element or a text utility; it covers the semantic type scale (`tw-text-display`, `tw-text-headline`, `tw-text-title`, `tw-text-base`, `tw-text-caption`, etc.), heading hierarchy, font pairing, and the HTML / Tailwind mappings.
+
+Quick guidance for a port:
+- **Map Figma Make font references** by intent, not by raw weight: pick the semantic utility (e.g. `tw-text-headline`, `tw-text-title`, `tw-text-label`) that matches the role the text plays. Don't translate `font-weight: 500` into a hand-set numeric weight — pick the utility that the design system says owns "medium" emphasis.
+- **Font family** → `tw-font-sans` (PostGrotesk) by default; only switch when the typography skill calls for `tw-font-serif`.
+- **Heading elements** → follow the heading hierarchy described in the typography skill so any new `<h1>`–`<h6>` usage you introduce uses the correct semantic level for its role.
+- If no existing element default or utility class fits the design, that's a signal to stop and confirm with the design system team — not to author bespoke CSS.
 
 ### 4.3 Spacing