alif-ui 2.0.0-alpha.18 → 2.0.0-alpha.19

package/README.md

@@ -134,6 +134,24 @@ If your project requires a brand:
 
 And here's where magic happens - all the components automatically adapt to that brand!
 
+# AI assisted development
+
+This repo also ships **agent skills** for AI assisted development — see `skills/`.
+
+`alif-ui` teaches AI coding assistants how to build UI with this library — setup, every component's props, our patterns and the mistakes to avoid — and adapts to the project it is installed in.
+
+The skill ships inside the package, so once `alif-ui` is installed one command puts it where your assistant looks:
+
+```bash
+npx alif-ui skills install
+```
+
+It installs into every assistant skill directory the project already has — any `.<assistant>/skills` folder, so Claude Code, Cursor, Windsurf and the shared `.agents/skills` are all found without us keeping a list. A project with none of them gets `.claude/skills/`; `--dir <path>` and `--global` override that. Re-run it after upgrading `alif-ui`, and commit the installed folder so your team gets it.
+
+Written in the open [Agent Skills](https://agentskills.io) format, so it works in Claude Code, Cursor, Copilot and other compatible assistants.
+
+A second skill, `alif-ui-contributor`, documents this repository for contributors and needs no installation. See **Guides → AI Assisted Development** in Storybook for details.
+
 # Documentation
 
 Visit [https://ui.alif.tj](https://ui.alif.tj) to view the full documentation.

package/dist/components/Popover/Popover.js

@@ -5,62 +5,63 @@ import { useOutsideClick as r } from "../../hooks/useOutsideClick/useOutsideClic
 import { useFloatingPosition as i } from "./useFloatingPosition/useFloatingPosition.js";
 import { PopoverTrigger as a } from "./PopoverTrigger/PopoverTrigger.js";
 import { PopoverDropdown as o } from "./PopoverDropdown/PopoverDropdown.js";
-import { useRef as s, useState as c } from "react";
-import { jsx as l } from "react/jsx-runtime";
+import { useId as s, useRef as c, useState as l } from "react";
+import { jsx as u } from "react/jsx-runtime";
 //#region src/lib/components/Popover/Popover.tsx
-var u = ({ children: a, offset: o = 4, position: u = "bottom", isOpen: d, onChange: f, onClose: p, withArrow: m = !1, width: h = "max-content", zIndex: g = e("popover"), isFixed: _ = !1, transitionProps: v, triggerType: y = "click", disabled: b = !1 }) => {
-	let [x, S] = c(!1), [C, w] = c(null), [T, E] = c(null), D = s(null), O = s(null), k = n(), { placement: A, arrowPlacement: j } = i(T, C, u, o, m, _), M = () => {
-		if (d !== void 0) {
-			f?.(!d);
+var d = ({ children: a, offset: o = 4, position: d = "bottom", isOpen: f, onChange: p, onClose: m, withArrow: h = !1, width: g = "max-content", zIndex: _ = e("popover"), isFixed: v = !1, transitionProps: y, triggerType: b = "click", disabled: x = !1 }) => {
+	let [S, C] = l(!1), [w, T] = l(null), [E, D] = l(null), O = c(null), k = c(null), A = n(), j = `${A?.popoverPath ?? ""}/${s()}`, { placement: M, arrowPlacement: N } = i(E, w, d, o, h, v), P = () => {
+		if (f !== void 0) {
+			p?.(!f);
 			return;
 		}
-		S((e) => !e);
-	}, N = () => {
-		if (d !== void 0) {
-			f?.(!0);
+		C((e) => !e);
+	}, F = () => {
+		if (f !== void 0) {
+			p?.(!0);
 			return;
 		}
-		S(!0);
-	}, P = () => {
-		!d && !x || (S(!1), f?.(!1), p?.());
+		C(!0);
+	}, I = () => {
+		!f && !S || (C(!1), p?.(!1), m?.());
 	};
-	return r([{ current: C }, { current: T }], P), /* @__PURE__ */ l(t, {
+	return r([{ current: w }, { current: E }], I, (e) => !!e.closest("[data-popover-dropdown]")?.getAttribute("data-popover-dropdown")?.startsWith(`${j}/`)), /* @__PURE__ */ u(t, {
 		value: {
-			closePopover: P,
+			closePopover: I,
 			closeAllPopovers: () => {
-				P(), k?.closeAllPopovers?.();
+				I(), A?.closeAllPopovers?.();
 			},
-			togglePopover: M,
-			openPopover: N,
+			togglePopover: P,
+			openPopover: F,
 			delayedOpen: () => {
-				O.current &&= (window.clearTimeout(O.current), null), !D.current && (D.current = window.setTimeout(() => {
-					N(), D.current = null;
+				k.current &&= (window.clearTimeout(k.current), null), !O.current && (O.current = window.setTimeout(() => {
+					F(), O.current = null;
 				}, 200));
 			},
 			delayedClose: () => {
-				D.current &&= (window.clearTimeout(D.current), null), !O.current && (O.current = window.setTimeout(() => {
-					P(), O.current = null;
+				O.current &&= (window.clearTimeout(O.current), null), !k.current && (k.current = window.setTimeout(() => {
+					I(), k.current = null;
 				}, 200));
 			},
-			triggerRefState: T,
-			setTriggerRefState: E,
-			isOpen: x,
-			isOpenControlled: d,
-			setPopoverRefState: w,
-			popoverRefState: C,
-			placement: A,
-			arrowPlacement: j,
-			width: h,
-			withArrow: m,
-			triggerType: y,
-			disabled: b,
-			zIndex: g,
-			transitionProps: v,
-			isFixed: _
+			popoverPath: j,
+			triggerRefState: E,
+			setTriggerRefState: D,
+			isOpen: S,
+			isOpenControlled: f,
+			setPopoverRefState: T,
+			popoverRefState: w,
+			placement: M,
+			arrowPlacement: N,
+			width: g,
+			withArrow: h,
+			triggerType: b,
+			disabled: x,
+			zIndex: _,
+			transitionProps: y,
+			isFixed: v
 		},
 		children: a
 	});
 };
-u.Trigger = a, u.Dropdown = o;
+d.Trigger = a, d.Dropdown = o;
 //#endregion
-export { u as Popover };
+export { d as Popover };

package/dist/components/Popover/PopoverDropdown/PopoverDropdown.js

@@ -6,13 +6,13 @@ import { PopoverArrow as r } from "./PopoverArrow.js";
 import { jsx as i, jsxs as a } from "react/jsx-runtime";
 //#region src/lib/components/Popover/PopoverDropdown/PopoverDropdown.tsx
 var o = ({ children: o, className: s, style: c, onClick: l, ...u }) => {
-	let { isOpen: d, isOpenControlled: f, placement: p, setPopoverRefState: m, zIndex: h, width: g, withArrow: _, arrowPlacement: v, triggerRefState: y, transitionProps: b, isFixed: x, delayedClose: S, delayedOpen: C, triggerType: w } = n(), T = w === "hover" || w === "click-hover", E = () => {
-		T && C();
-	}, D = (e) => {
-		if (!T) return;
+	let { isOpen: d, isOpenControlled: f, placement: p, setPopoverRefState: m, zIndex: h, width: g, withArrow: _, arrowPlacement: v, triggerRefState: y, transitionProps: b, isFixed: x, delayedClose: S, delayedOpen: C, triggerType: w, popoverPath: T } = n(), E = w === "hover" || w === "click-hover", D = () => {
+		E && C();
+	}, O = (e) => {
+		if (!E) return;
 		let t = e.relatedTarget;
 		t instanceof Node && y?.contains(t) || S();
-	}, O = (e) => {
+	}, k = (e) => {
 		e.stopPropagation(), l?.(e);
 	};
 	return /* @__PURE__ */ i(e, {
@@ -25,7 +25,7 @@ var o = ({ children: o, className: s, style: c, onClick: l, ...u }) => {
 			mounted: f || d,
 			...b,
 			children: (e) => /* @__PURE__ */ a("div", {
-				"data-popover-dropdown": !0,
+				"data-popover-dropdown": T,
 				style: {
 					...e,
 					...c,
@@ -33,9 +33,9 @@ var o = ({ children: o, className: s, style: c, onClick: l, ...u }) => {
 				},
 				className: s,
 				ref: m,
-				onClick: O,
-				onMouseEnter: E,
-				onMouseLeave: D,
+				onClick: k,
+				onMouseEnter: D,
+				onMouseLeave: O,
 				...u,
 				children: [_ && /* @__PURE__ */ i(r, { ...v }), o]
 			})

package/dist/components/Popover/useFloatingPosition/useFloating.util.js

@@ -35,8 +35,7 @@ var e = {
 		`${t}-end`,
 		t
 	].filter((e, t, n) => n.indexOf(e) === t);
-}, i = async (i, a, o, s, c, l) => {
-	await document.fonts.ready;
+}, i = (i, a, o, s, c, l) => {
 	let u = i.getBoundingClientRect(), d = a.getBoundingClientRect(), f = {
 		top: 0,
 		left: 0

package/dist/components/Popover/useFloatingPosition/useFloatingPosition.js

@@ -1,6 +1,6 @@
 import { getPopoverPosition as e } from "./useFloating.util.js";
 import { getScrollableAncestors as t } from "./getScrollableAncestors.js";
-import { useEffect as n, useRef as r, useState as i } from "react";
+import { useLayoutEffect as n, useRef as r, useState as i } from "react";
 //#region src/lib/components/Popover/useFloatingPosition/useFloatingPosition.ts
 var a = (a, o, s = "bottom", c, l = !1, u) => {
 	let [d, f] = i({
@@ -14,21 +14,17 @@ var a = (a, o, s = "bottom", c, l = !1, u) => {
 	return n(() => {
 		if (!a || !o) return;
 		let n = () => {
-			e(a, o, s, c, l, u).then(({ positionProps: e, arrowPosition: t }) => {
-				f(e), m(t);
-			});
+			let { positionProps: t, arrowPosition: n } = e(a, o, s, c, l, u);
+			f(t), m(n);
 		};
-		if (u) {
-			n();
-			return;
-		}
-		let r = t(a);
-		r.forEach((e) => e.addEventListener("scroll", n)), window.addEventListener("resize", n), h.current = new ResizeObserver(n), h.current.observe(a), h.current.observe(o);
-		let i;
-		return document.fonts.ready.then(() => {
-			i = requestAnimationFrame(n);
-		}), () => {
-			r.forEach((e) => e.removeEventListener("scroll", n)), window.removeEventListener("resize", n), h.current?.disconnect(), cancelAnimationFrame(i);
+		n();
+		let r;
+		if (document.fonts.ready.then(() => {
+			r = requestAnimationFrame(n);
+		}), u) return () => cancelAnimationFrame(r);
+		let i = t(a);
+		return i.forEach((e) => e.addEventListener("scroll", n)), window.addEventListener("resize", n), h.current = new ResizeObserver(n), h.current.observe(a), h.current.observe(o), () => {
+			i.forEach((e) => e.removeEventListener("scroll", n)), window.removeEventListener("resize", n), h.current?.disconnect(), cancelAnimationFrame(r);
 		};
 	}, [
 		a,

package/dist/hooks/useOutsideClick/useOutsideClick.js

@@ -1,22 +1,20 @@
 import { useEffect as e, useMemo as t } from "react";
 //#region src/lib/hooks/useOutsideClick/useOutsideClick.ts
-var n = (n, r) => {
-	let i = t(() => Array.isArray(n) ? n : [n], [n]);
+var n = (n, r, i) => {
+	let a = t(() => Array.isArray(n) ? n : [n], [n]);
 	e(() => {
 		let e = (e) => {
 			let t = e.target;
-			if (i.some((e) => e.current?.contains(t))) return;
-			let n = t;
-			for (; n;) {
-				if (n.hasAttribute && n.hasAttribute("data-popover-dropdown")) return;
-				n = n.parentElement;
-			}
-			r(e);
+			a.some((e) => e.current?.contains(t)) || t instanceof Element && i?.(t) || r(e);
 		};
 		return document.addEventListener("mousedown", e), () => {
 			document.removeEventListener("mousedown", e);
 		};
-	}, [i, r]);
+	}, [
+		a,
+		r,
+		i
+	]);
 };
 //#endregion
 export { n as useOutsideClick };

package/dist/src/lib/components/Popover/Popover.context.d.ts

@@ -10,6 +10,7 @@ interface PopoverContext {
     delayedClose: () => void;
     triggerType?: TriggerType;
     disabled?: boolean;
+    popoverPath: string;
     triggerRefState: HTMLDivElement | null;
     setTriggerRefState: (ref: HTMLDivElement | null) => void;
     isOpen: boolean;

package/dist/src/lib/components/Popover/Popover.context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Popover.context.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/Popover/Popover.context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,UAAU,cAAc;IACvB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,kBAAkB,EAAE,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,EAAE,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IACzD,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,SAAS,EAAE,aAAa,CAAC;IACzB,cAAc,EAAE,aAAa,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MACN,sBAAsB;;;+CACtB,iBAAiB,wBACjB,yBAAyB,6BAGzB,CAAC"}
+{"version":3,"file":"Popover.context.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/Popover/Popover.context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,UAAU,cAAc;IACvB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,kBAAkB,EAAE,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,kBAAkB,EAAE,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,KAAK,IAAI,CAAC;IACzD,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IACvC,SAAS,EAAE,aAAa,CAAC;IACzB,cAAc,EAAE,aAAa,CAAC;IAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MACN,sBAAsB;;;+CACtB,iBAAiB,wBACjB,yBAAyB,6BAGzB,CAAC"}

package/dist/src/lib/components/Popover/Popover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Popover.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/Popover/Popover.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAU/C,eAAO,MAAM,OAAO;8JAcjB,YAAY;;;CAgHd,CAAC"}
+{"version":3,"file":"Popover.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/Popover/Popover.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAU/C,eAAO,MAAM,OAAO;8JAcjB,YAAY;;;CA0Hd,CAAC"}

package/dist/src/lib/components/Popover/PopoverDropdown/PopoverDropdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PopoverDropdown.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/components/Popover/PopoverDropdown/PopoverDropdown.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAI/D,eAAO,MAAM,eAAe,GAAI,uDAM7B,oBAAoB,4CAuEtB,CAAC"}
+{"version":3,"file":"PopoverDropdown.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/components/Popover/PopoverDropdown/PopoverDropdown.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAI/D,eAAO,MAAM,eAAe,GAAI,uDAM7B,oBAAoB,4CAwEtB,CAAC"}

package/dist/src/lib/components/Popover/useFloatingPosition/useFloating.util.d.ts

@@ -9,8 +9,8 @@ export declare const ARROW: {
     readonly START_MARGIN: number;
     readonly END_MARGIN: number;
 };
-export declare const getPopoverPosition: (trigger: HTMLDivElement, popover: HTMLDivElement, position: Position, offset: number, withArrow: boolean, isFixed: boolean) => Promise<{
+export declare const getPopoverPosition: (trigger: HTMLDivElement, popover: HTMLDivElement, position: Position, offset: number, withArrow: boolean, isFixed: boolean) => {
     positionProps: PositionProps;
     arrowPosition: ArrowPositionProps;
-}>;
+};
 //# sourceMappingURL=useFloating.util.d.ts.map

package/dist/src/lib/components/Popover/useFloatingPosition/useFloating.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFloating.util.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/components/Popover/useFloatingPosition/useFloating.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,eAAO,MAAM,KAAK;;;;;;;CAgBjB,CAAC;AA+BF,eAAO,MAAM,kBAAkB,GAC9B,SAAS,cAAc,EACvB,SAAS,cAAc,EACvB,UAAU,QAAQ,EAClB,QAAQ,MAAM,EACd,WAAW,OAAO,EAClB,SAAS,OAAO,KACd,OAAO,CAAC;IACV,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,kBAAkB,CAAC;CAClC,CA2IA,CAAC"}
+{"version":3,"file":"useFloating.util.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/components/Popover/useFloatingPosition/useFloating.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,eAAO,MAAM,KAAK;;;;;;;CAgBjB,CAAC;AA+BF,eAAO,MAAM,kBAAkB,GAC9B,SAAS,cAAc,EACvB,SAAS,cAAc,EACvB,UAAU,QAAQ,EAClB,QAAQ,MAAM,EACd,WAAW,OAAO,EAClB,SAAS,OAAO,KACd;IACF,aAAa,EAAE,aAAa,CAAC;IAC7B,aAAa,EAAE,kBAAkB,CAAC;CA0IlC,CAAC"}

package/dist/src/lib/hooks/useOutsideClick/useOutsideClick.d.ts

@@ -1,3 +1,3 @@
 import { RefObject } from 'react';
-export declare const useOutsideClick: (refs: RefObject<HTMLElement> | RefObject<HTMLElement>[], callback: (e?: Event) => void) => void;
+export declare const useOutsideClick: (refs: RefObject<HTMLElement> | RefObject<HTMLElement>[], callback: (e?: Event) => void, shouldIgnore?: (target: Element) => boolean) => void;
 //# sourceMappingURL=useOutsideClick.d.ts.map

package/dist/src/lib/hooks/useOutsideClick/useOutsideClick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOutsideClick.d.ts","sourceRoot":"","sources":["../../../../../src/lib/hooks/useOutsideClick/useOutsideClick.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,OAAO,CAAC;AAEtD,eAAO,MAAM,eAAe,GAC3B,MAAM,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAAE,EACvD,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,SAkC7B,CAAC"}
+{"version":3,"file":"useOutsideClick.d.ts","sourceRoot":"","sources":["../../../../../src/lib/hooks/useOutsideClick/useOutsideClick.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,OAAO,CAAC;AAEtD,eAAO,MAAM,eAAe,GAC3B,MAAM,SAAS,CAAC,WAAW,CAAC,GAAG,SAAS,CAAC,WAAW,CAAC,EAAE,EACvD,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,EAC7B,eAAe,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,SAwB3C,CAAC"}

package/package.json

@@ -21,11 +21,16 @@
 	},
 	"license": "ISC",
 	"private": false,
-	"version": "2.0.0-alpha.18",
+	"version": "2.0.0-alpha.19",
 	"type": "module",
 	"files": [
-		"dist"
+		"dist",
+		"skills",
+		"scripts/installSkills.js"
 	],
+	"bin": {
+		"alif-ui": "./scripts/installSkills.js"
+	},
 	"main": "./dist/main.js",
 	"module": "./dist/main.js",
 	"style": "./dist/alif-ui.css",

package/scripts/installSkills.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const SKILL_NAME = 'alif-ui';
+
+const DEFAULT_DIR = '.claude/skills';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const skillSource = path.join(here, '..', 'skills', SKILL_NAME);
+const packageJsonPath = path.join(here, '..', 'package.json');
+
+const usage = `
+alif-ui — Alif Bank design system
+
+Usage
+  npx alif-ui skills install [--dir <path>] [--global]
+
+Options
+  --dir <path>   install into this directory instead of detecting one
+                 (e.g. --dir .agents/skills for a shared agent directory)
+  --global       install into ~/.claude/skills (available in every project)
+
+With no options the skill is installed into every assistant skill directory the
+project already has — any '.<assistant>/skills' folder, such as .claude/skills,
+.cursor/skills or the shared .agents/skills. A project with none of them gets
+${DEFAULT_DIR}.
+
+Installs the ${SKILL_NAME} skill, which teaches AI coding assistants
+(Claude Code, Cursor, Copilot, ...) how to build UI with alif-ui.
+`;
+
+const getVersion = () => {
+	try {
+		return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version;
+	} catch {
+		return null;
+	}
+};
+
+const getTargets = (args) => {
+	const dirIndex = args.indexOf('--dir');
+
+	if (dirIndex !== -1) {
+		const dir = args[dirIndex + 1];
+
+		if (!dir) {
+			throw new Error('--dir requires a path');
+		}
+
+		return [path.resolve(dir)];
+	}
+
+	if (args.includes('--global')) {
+		const home = process.env.HOME || process.env.USERPROFILE;
+
+		if (!home) {
+			throw new Error('cannot resolve the home directory for --global');
+		}
+
+		return [path.join(home, '.claude', 'skills')];
+	}
+
+	return findAgentDirs();
+};
+
+const findAgentDirs = () => {
+	const root = process.cwd();
+
+	const found = fs
+		.readdirSync(root, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && entry.name.startsWith('.'))
+		.map((entry) => path.join(root, entry.name, 'skills'))
+		.filter((dir) => fs.existsSync(dir));
+
+	if (found.length > 0) {
+		return found;
+	}
+
+	console.log(
+		`no assistant skill directory found — using ${DEFAULT_DIR}\n` +
+			`if your assistant reads somewhere else, re-run with --dir <path>\n`,
+	);
+
+	return [path.resolve(DEFAULT_DIR)];
+};
+
+const installSkill = (args) => {
+	if (!fs.existsSync(skillSource)) {
+		throw new Error(
+			`skill not found at ${skillSource}. Reinstall alif-ui, or run this from a project that depends on it.`,
+		);
+	}
+
+	const version = getVersion();
+
+	for (const target of getTargets(args)) {
+		const destination = path.join(target, SKILL_NAME);
+		const isUpdate = fs.existsSync(destination);
+
+		fs.mkdirSync(target, { recursive: true });
+		fs.cpSync(skillSource, destination, { recursive: true });
+
+		const action = isUpdate ? 'updated' : 'installed';
+		const relative = path.relative(process.cwd(), destination) || destination;
+
+		console.log(
+			`${action} ${SKILL_NAME}${version ? ` (alif-ui ${version})` : ''} → ${relative}`,
+		);
+	}
+
+	console.log(
+		'\nRestart your assistant to pick it up, and commit the folder so your team gets it too.',
+	);
+};
+
+const [command, subcommand, ...rest] = process.argv.slice(2);
+
+try {
+	if (command === 'skills' && (subcommand === 'install' || !subcommand)) {
+		installSkill(rest);
+	} else if (command === 'skills') {
+		throw new Error(`unknown subcommand: skills ${subcommand}`);
+	} else {
+		console.log(usage.trim());
+		process.exit(command === undefined ? 0 : 1);
+	}
+} catch (error) {
+	console.error(`alif-ui: ${error.message}`);
+	process.exit(1);
+}

package/skills/alif-ui/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: alif-ui
+description: How to build application UI with the alif-ui React component library (Alif Bank design system) — setup, the component catalogue and its exact props, composition patterns and the mistakes to avoid. Use whenever writing, reviewing or debugging React/Next.js code that imports from the alif-ui package — screens, forms, tables, modals, layouts, theming, localization or icons. For developing the library itself, use the alif-ui-contributor skill instead.
+---
+
+# Building UI with alif-ui
+
+> This skill is for **application code that imports `alif-ui`**. If you are working inside the library repository itself (`src/lib/**`), use the `alif-ui-contributor` skill instead.
+
+`alif-ui` is Alif Bank's React component library implementing the Alif design system. When a project depends on it, **compose screens out of these components** — do not hand-roll buttons, inputs, modals or spinners, and do not add another UI library (MUI, Ant, shadcn, Chakra) alongside it.
+
+## Step 0 — read this project's setup first
+
+Every app wires the library differently. Before writing UI, establish these facts once per session and follow them instead of the generic examples below:
+
+| What to learn                        | Where to look                                                                                                                                                           |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Installed version                    | `alif-ui` entry in `package.json`, or `node_modules/alif-ui/package.json`                                                                                               |
+| The exact public API of that version | `node_modules/alif-ui/dist/main.d.ts` — the ground truth if anything here disagrees                                                                                     |
+| Whether setup exists, and where      | grep for `AlifProvider` and `alif-ui/styles.css`                                                                                                                        |
+| Brand in use                         | the `brand` prop passed to `AlifProvider`, and which brand CSS is imported next to `alif-ui/styles.css`                                                                 |
+| Theme and locale defaults            | `initialMode` / `initialLocale` on `AlifProvider`                                                                                                                       |
+| Whether the built-in i18n is used    | grep for `localization.init` and `useTranslation`; note where the locale JSONs live                                                                                     |
+| Form library                         | `formik` / `react-hook-form` in `package.json` — picks `Controller` vs `register()` vs plain state                                                                      |
+| Framework                            | `next` in `package.json`, and app router (`app/layout.tsx`) vs pages router (`pages/_app.tsx`) — decides where `'use client'` is needed                                 |
+| House conventions                    | grep existing `from 'alif-ui'` imports: local wrapper components, how errors and loading states are already expressed, whether the app pins sizes or relies on defaults |
+
+Two rules follow from this:
+
+- **Match the app, not the sample.** If the codebase already wraps `Input` in its own `FormField`, use that wrapper; if screens use `size="s"` everywhere, keep it.
+- **When this skill and `main.d.ts` disagree, `main.d.ts` wins** — this skill documents the 2.x API, and an app may sit on a different version. Say so rather than silently writing against the wrong API.
+
+If the setup below is missing entirely, add it — that is the one case where you introduce it yourself.
+
+## Setup (must exist once per app)
+
+```tsx
+import { AlifProvider } from 'alif-ui';
+import 'alif-ui/styles.css'; // library tokens + reset — always first
+import 'styles/alif/alif.css'; // ONE brand css from the design team
+
+<AlifProvider brand="alif" initialMode="light" initialLocale="ru">
+	<App />
+</AlifProvider>;
+```
+
+- `brand`: any string (default `'universal'`). Only `universal` ships inside the package; every other brand is a CSS file the design team hands to the project. The value must equal the brand name in that file's `:root[data-brand='<name>']` selector — otherwise the app silently stays on `universal`.
+- `initialMode`: `'light' | 'dark' | 'system'` (default `'system'`). Persisted in `localStorage`, applied as `<html data-theme>`.
+- `initialLocale`: `'ru' | 'en' | 'tj'` (default: browser locale). Applied as `<html data-locale>`.
+- **Next.js**: `AlifProvider` uses hooks and `localStorage`, so put it in a `'use client'` wrapper component and render that from `app/layout.tsx` (or `pages/_app.tsx`).
+- Components rendered outside `AlifProvider` will not resolve tokens. Wrap the whole tree, including test render helpers.
+
+## Import rules
+
+```tsx
+import { Button, Input, Modal, SolidSystemSettings, useMode } from 'alif-ui';
+```
+
+- Everything — components, hooks, providers, icons, types — is a **named export of the package root**. There are no submodule paths and no default exports.
+- Never import from `alif-ui/dist/...`, `alif-ui/src/...` or a component folder; only `'alif-ui'` and `'alif-ui/styles.css'`.
+- Prop types are exported too (`ButtonProps`, `SelectOption<T>`, `ModalProps`, …) — use them instead of re-declaring shapes.
+
+## Non-negotiable rules
+
+1. **Never restyle with hardcoded values.** No hex colors, no `px` font sizes, no invented spacing. Use the component's own props first; when you must override, set the component's CSS custom properties or use design tokens (`var(--brand-*)`, `var(--mode-*)`). See `references/theming.md`.
+2. **CSS Module class names are hashed** — you cannot target the library's internal classes. Style through `className` / `style` on the component (both are forwarded and merged last) or through its CSS variables.
+3. **Boolean/handler naming is `isOpen` + `onClose` / `onChange`** — not `open`, not `onOpenChange`. Overlays (`Modal`, `Drawer`, `Backdrop`) require both.
+4. **Compound components are used through dot notation** (`Modal.Header`, `Tabs.Panel`, `Table.Td`, `Sidebar.Item`). The sub-parts are not separate imports, and skipping them (e.g. raw `<thead>` inside `Table`) breaks styling.
+5. **Controlled components need `value` + `onChange`.** `Select`, `Tabs`, `Rating`, `InputOtp`, `FileUploader`, `Slider`, `Pagination` and the date pickers have **required** value/handler props; `Accordion`, `Popover`, `Tab.Group`, `Checkbox.Group`, `Radio.Group` accept `defaultValue` for uncontrolled use.
+6. **Size scales differ per component** — `Button` is `xs|s|m|l`, `Input`/`Field`/`Textarea` are `s|m|l`, `List` is `m|l`, `Avatar` is `xxs…xxl`, `Checkbox`/`Radio`/`Switch` are `s|m`. Check `references/components.md` before passing a size.
+7. **Text uses `Typography`** with `variant` + matching `size` (`heading` → `h1…h6`, `body` → `xs|s|m|l`, `description` → `s|m|l`, `display` → `s|m|l`) and `element` for the rendered tag. Don't style bare `<h1>`/`<p>`.
+8. **Inputs are full width by default** (`fullWidth = true` on `Field`/`Input`/`Search`); `Button` is not. Use the `fullWidth` prop rather than wrapper divs with `width: 100%`.
+9. **Icons come from the package** (`SolidSystemSettings`, `OutlineNavigationChevronDown`, `TjFlag`) and inherit `currentColor` — pass them into `leftIcon` / `rightIcon` / `icon` / `leftSection` slots instead of `<img>` or inline SVG.
+10. **User-visible strings are the app's responsibility.** Components ship no copy of their own; feed them through props, and use `useTranslation()` / `localization.t()` if the app uses the built-in i18n.
+
+## Component catalogue (all exports)
+
+Details, exact props and examples: `references/components.md`.
+
+| Area              | Components                                                                                                                                                                                        |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions           | `Button`, `UnstyledButton`                                                                                                                                                                        |
+| Text & media      | `Typography`, `Avatar` (`.Group`), `Badge`, `Indicator`, `Divider`, `Paper`, `Skeleton`, `Loader`, `ProgressBar`                                                                                  |
+| Inputs            | `Input`, `Field`, `Textarea`, `Search`, `InputOtp`, `Checkbox` (`.Group`), `Radio` (`.Group`), `Switch`, `Rating`, `Slider`, `RangeSlider`, `FileUploader`, `FileView`, `SelectorInput`, `Hinter` |
+| Selection         | `Select`, `SelectMultiple`, `List` (`.Group`, `.Item`), `Tab` (`.Group`), `SegmentedControl`                                                                                                      |
+| Dates             | `InputDatePicker`, `InputTimePicker`, `InputMonthPicker`, `InputYearPicker`, `InputMonthYearPicker` (+ bare `DatePicker`, `TimePicker`, `MonthPicker`, `YearPicker`, `MonthYearPicker`)           |
+| Navigation        | `Tabs` (`.Menu`, `.Tab`, `.Panel`), `Breadcrumbs`, `Pagination`, `Navbar`, `Sidebar` (`.Header`, `.Items`, `.Item`, `.Collapse`, `.Group`, `.Element`, `.Profile`, `.Footer`), `AppLayout`        |
+| Overlays          | `Modal` (`.Header`, `.Content`, `.Actions`), `Drawer` (`.Header`, `.Content`, `.Actions`), `Popover` (`.Trigger`, `.Dropdown`), `Menu` (`.Item`, `.Sub`), `Tooltip`, `Backdrop`, `Portal`         |
+| Feedback          | `Snackbar` + `snackbar` API, `Alert`                                                                                                                                                              |
+| Disclosure        | `Accordion` (`.Item`, `.Trigger`, `.Content`), `Collapse`, `Timeline` (`.Item`, `.Content`, `.OppositeContent`)                                                                                   |
+| Data              | `Table` (`.Thead`, `.Tbody`, `.Tfoot`, `.Tr`, `.Th`, `.Td`, `.CollapseRow`)                                                                                                                       |
+| Motion            | `Transition`                                                                                                                                                                                      |
+| Hooks & providers | `AlifProvider`, `useMode`, `useLocale`, `useTranslation`, `localization`, `useMediaQuery`, `useOutsideClick`, `useInfiniteScroll`, `useFloatingPosition`                                          |
+
+## How to work
+
+1. Establish the project's setup (Step 0) if this session hasn't yet.
+2. Find the component in the table above, then read its entry in `references/components.md` — props there are copied from the library's types, so trust them over guesses.
+3. If the task is a whole flow (form, CRUD table, wizard, layout), start from `references/patterns.md`.
+4. Before finishing, check `references/pitfalls.md` — it lists the mistakes that actually break alif-ui code.
+5. Theming, dark mode, brands, localization: `references/theming.md`.
+
+If a component genuinely does not exist for the design at hand, build it from `Paper` + `Typography` + tokens rather than raw styled divs, and say so explicitly in your answer.
+
+## References
+
+- `references/components.md` — every exported component, its props, defaults and a minimal example.
+- `references/patterns.md` — forms (Formik / React Hook Form), overlays, tables with pagination, async selects, snackbars, layout shells, date pickers.
+- `references/theming.md` — tokens, brands, light/dark, overriding component styles, typography, i18n hooks.
+- `references/pitfalls.md` — wrong ↔ right pairs; read before shipping.