alif-ui 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/utils/typography.js

@@ -1,104 +1,104 @@
-const t = {
-  display: {
-    l: {
-      fontSize: "var(--brand-font-size-display-l)",
-      lineHeight: "var(--brand-font-line-height-display-l)",
-      letterSpacing: "var(--brand-font-letter-spacing-display-l)"
-    },
-    m: {
-      fontSize: "var(--brand-font-size-display-m)",
-      lineHeight: "var(--brand-font-line-height-display-m)",
-      letterSpacing: "var(--brand-font-letter-spacing-display-m)"
-    },
-    s: {
-      fontSize: "var(--brand-font-size-display-s)",
-      lineHeight: "var(--brand-font-line-height-display-s)",
-      letterSpacing: "var(--brand-font-letter-spacing-display-s)"
-    }
-  },
-  heading: {
-    h1: {
-      fontSize: "var(--brand-font-size-heading-h1)",
-      lineHeight: "var(--brand-font-line-height-heading-h1)",
-      letterSpacing: "var(--brand-font-letter-spacing-heading-h1)"
-    },
-    h2: {
-      fontSize: "var(--brand-font-size-heading-h2)",
-      lineHeight: "var(--brand-font-line-height-heading-h2)",
-      letterSpacing: "var(--brand-font-letter-spacing-heading-h2)"
-    },
-    h3: {
-      fontSize: "var(--brand-font-size-heading-h3)",
-      lineHeight: "var(--brand-font-line-height-heading-h3)",
-      letterSpacing: "var(--brand-font-letter-spacing-heading-h3)"
-    },
-    h4: {
-      fontSize: "var(--brand-font-size-heading-h4)",
-      lineHeight: "var(--brand-font-line-height-heading-h4)",
-      letterSpacing: "var(--brand-font-letter-spacing-heading-h4)"
-    },
-    h5: {
-      fontSize: "var(--brand-font-size-heading-h5)",
-      lineHeight: "var(--brand-font-line-height-heading-h5)",
-      letterSpacing: "var(--brand-font-letter-spacing-heading-h5)"
-    },
-    h6: {
-      fontSize: "var(--brand-font-size-heading-h6)",
-      lineHeight: "var(--brand-font-line-height-heading-h6)",
-      letterSpacing: "var(--brand-font-letter-spacing-heading-h6)"
-    }
-  },
-  description: {
-    l: {
-      fontSize: "var(--brand-font-size-description-l)",
-      lineHeight: "var(--brand-font-line-height-description-l)",
-      letterSpacing: "var(--brand-font-letter-spacing-description-l)"
-    },
-    m: {
-      fontSize: "var(--brand-font-size-description-m)",
-      lineHeight: "var(--brand-font-line-height-description-m)",
-      letterSpacing: "var(--brand-font-letter-spacing-description-m)"
-    },
-    s: {
-      fontSize: "var(--brand-font-size-description-s)",
-      lineHeight: "var(--brand-font-line-height-description-s)",
-      letterSpacing: "var(--brand-font-letter-spacing-description-s)"
-    }
-  },
-  body: {
-    l: {
-      fontSize: "var(--brand-font-size-body-l)",
-      lineHeight: "var(--brand-font-line-height-body-l)",
-      letterSpacing: "var(--brand-font-letter-spacing-body-l)"
-    },
-    m: {
-      fontSize: "var(--brand-font-size-body-m)",
-      lineHeight: "var(--brand-font-line-height-body-m)",
-      letterSpacing: "var(--brand-font-letter-spacing-body-m)"
-    },
-    s: {
-      fontSize: "var(--brand-font-size-body-s)",
-      lineHeight: "var(--brand-font-line-height-body-s)",
-      letterSpacing: "var(--brand-font-letter-spacing-body-s)"
-    },
-    xs: {
-      fontSize: "var(--brand-font-size-body-xs)",
-      lineHeight: "var(--brand-font-line-height-body-xs)",
-      letterSpacing: "var(--brand-font-letter-spacing-body-xs)"
-    }
-  }
-}, a = {
-  description: "var(--brand-font-family-description)",
-  body: "var(--brand-font-family-body)",
-  display: "var(--brand-font-family-display)",
-  heading: "var(--brand-font-family-heading)"
-}, r = (n, e, i = "regular") => ({
-  "--typography-font-family": a[n],
-  "--typography-font-size": t[n][e].fontSize,
-  "--typography-line-height": t[n][e].lineHeight,
-  "--typography-letter-spacing": t[n][e].letterSpacing,
-  "--typography-font-weight": `var(--brand-font-weight-${i})`
+//#region src/lib/utils/typography.ts
+var e = {
+	display: {
+		l: {
+			fontSize: "var(--brand-font-size-display-l)",
+			lineHeight: "var(--brand-font-line-height-display-l)",
+			letterSpacing: "var(--brand-font-letter-spacing-display-l)"
+		},
+		m: {
+			fontSize: "var(--brand-font-size-display-m)",
+			lineHeight: "var(--brand-font-line-height-display-m)",
+			letterSpacing: "var(--brand-font-letter-spacing-display-m)"
+		},
+		s: {
+			fontSize: "var(--brand-font-size-display-s)",
+			lineHeight: "var(--brand-font-line-height-display-s)",
+			letterSpacing: "var(--brand-font-letter-spacing-display-s)"
+		}
+	},
+	heading: {
+		h1: {
+			fontSize: "var(--brand-font-size-heading-h1)",
+			lineHeight: "var(--brand-font-line-height-heading-h1)",
+			letterSpacing: "var(--brand-font-letter-spacing-heading-h1)"
+		},
+		h2: {
+			fontSize: "var(--brand-font-size-heading-h2)",
+			lineHeight: "var(--brand-font-line-height-heading-h2)",
+			letterSpacing: "var(--brand-font-letter-spacing-heading-h2)"
+		},
+		h3: {
+			fontSize: "var(--brand-font-size-heading-h3)",
+			lineHeight: "var(--brand-font-line-height-heading-h3)",
+			letterSpacing: "var(--brand-font-letter-spacing-heading-h3)"
+		},
+		h4: {
+			fontSize: "var(--brand-font-size-heading-h4)",
+			lineHeight: "var(--brand-font-line-height-heading-h4)",
+			letterSpacing: "var(--brand-font-letter-spacing-heading-h4)"
+		},
+		h5: {
+			fontSize: "var(--brand-font-size-heading-h5)",
+			lineHeight: "var(--brand-font-line-height-heading-h5)",
+			letterSpacing: "var(--brand-font-letter-spacing-heading-h5)"
+		},
+		h6: {
+			fontSize: "var(--brand-font-size-heading-h6)",
+			lineHeight: "var(--brand-font-line-height-heading-h6)",
+			letterSpacing: "var(--brand-font-letter-spacing-heading-h6)"
+		}
+	},
+	description: {
+		l: {
+			fontSize: "var(--brand-font-size-description-l)",
+			lineHeight: "var(--brand-font-line-height-description-l)",
+			letterSpacing: "var(--brand-font-letter-spacing-description-l)"
+		},
+		m: {
+			fontSize: "var(--brand-font-size-description-m)",
+			lineHeight: "var(--brand-font-line-height-description-m)",
+			letterSpacing: "var(--brand-font-letter-spacing-description-m)"
+		},
+		s: {
+			fontSize: "var(--brand-font-size-description-s)",
+			lineHeight: "var(--brand-font-line-height-description-s)",
+			letterSpacing: "var(--brand-font-letter-spacing-description-s)"
+		}
+	},
+	body: {
+		l: {
+			fontSize: "var(--brand-font-size-body-l)",
+			lineHeight: "var(--brand-font-line-height-body-l)",
+			letterSpacing: "var(--brand-font-letter-spacing-body-l)"
+		},
+		m: {
+			fontSize: "var(--brand-font-size-body-m)",
+			lineHeight: "var(--brand-font-line-height-body-m)",
+			letterSpacing: "var(--brand-font-letter-spacing-body-m)"
+		},
+		s: {
+			fontSize: "var(--brand-font-size-body-s)",
+			lineHeight: "var(--brand-font-line-height-body-s)",
+			letterSpacing: "var(--brand-font-letter-spacing-body-s)"
+		},
+		xs: {
+			fontSize: "var(--brand-font-size-body-xs)",
+			lineHeight: "var(--brand-font-line-height-body-xs)",
+			letterSpacing: "var(--brand-font-letter-spacing-body-xs)"
+		}
+	}
+}, t = {
+	description: "var(--brand-font-family-description)",
+	body: "var(--brand-font-family-body)",
+	display: "var(--brand-font-family-display)",
+	heading: "var(--brand-font-family-heading)"
+}, n = (n, r, i = "regular") => ({
+	"--typography-font-family": t[n],
+	"--typography-font-size": e[n][r].fontSize,
+	"--typography-line-height": e[n][r].lineHeight,
+	"--typography-letter-spacing": e[n][r].letterSpacing,
+	"--typography-font-weight": `var(--brand-font-weight-${i})`
 });
-export {
-  r as resolveTypography
-};
+//#endregion
+export { n as resolveTypography };

package/dist/utils/unit-resolver.js

@@ -1,4 +1,4 @@
-const e = (r, t = "px") => typeof r == "number" ? `${r}${t}` : r;
-export {
-  e as resolveUnit
-};
+//#region src/lib/utils/unit-resolver.ts
+var e = (e, t = "px") => typeof e == "number" ? `${e}${t}` : e;
+//#endregion
+export { e as resolveUnit };

package/package.json

@@ -21,11 +21,16 @@
 	},
 	"license": "ISC",
 	"private": false,
-	"version": "2.0.0-alpha.2",
+	"version": "2.0.0-alpha.21",
 	"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",
@@ -45,43 +50,37 @@
 		"build": "tsc && vite build",
 		"preview": "vite preview",
 		"lint:fix": "eslint --fix --no-error-on-unmatched-pattern '**/*.{jsx,ts,tsx}'",
-		"lint": "npm run eslint && npm run stylelint",
-		"stylelint": "stylelint \"**/*.css\" --fix",
-		"eslint": "eslint --ext .ts,.tsx --fix",
+		"lint": "yarn eslint && yarn stylelint",
+		"stylelint": "stylelint \"**/*.css\"",
+		"stylelint:fix": "stylelint \"**/*.css\" --fix",
+		"eslint": "eslint --fix",
 		"format": "prettier --no-error-on-unmatched-pattern --write **/*.{jsx,ts,tsx}",
-		"prepare": "husky",
 		"test": "jest --config config/jest/jestconfig.json",
 		"storybook": "storybook dev -p 6006",
 		"build-storybook": "storybook build"
 	},
 	"devDependencies": {
-		"@chromatic-com/storybook": "^3.2.4",
-		"@storybook/addon-essentials": "^8.5.3",
-		"@storybook/addon-interactions": "^8.5.3",
-		"@storybook/addon-links": "^8.5.3",
-		"@storybook/addon-onboarding": "^8.5.3",
-		"@storybook/blocks": "^8.5.3",
-		"@storybook/react": "^8.5.3",
-		"@storybook/react-vite": "^8.5.3",
-		"@storybook/test": "^8.5.3",
-		"@testing-library/jest-dom": "^6.4.6",
-		"@testing-library/react": "^16.0.0",
+		"@eslint/js": "^10.0.1",
+		"@storybook/addon-docs": "10.2.10",
+		"@storybook/react-vite": "10.2.10",
+		"@testing-library/dom": "^10.4.1",
+		"@testing-library/jest-dom": "^6.9.1",
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
 		"@types/css-modules": "^1.0.5",
 		"@types/jest": "^29.5.12",
-		"@types/node": "^20.11.24",
+		"@types/node": "^25.9.1",
 		"@types/react": "^19.2.7",
 		"@types/react-dom": "^19.2.3",
-		"@typescript-eslint/eslint-plugin": "^7.0.2",
-		"@typescript-eslint/parser": "^7.0.2",
-		"@vitejs/plugin-react": "^4.3.4",
-		"eslint": "^8.57.0",
-		"eslint-config-prettier": "^9.1.0",
-		"eslint-plugin-import": "^2.29.1",
-		"eslint-plugin-jsx-a11y": "^6.8.0",
-		"eslint-plugin-prettier": "^5.1.3",
-		"eslint-plugin-react-hooks": "^4.6.2",
+		"@typescript-eslint/eslint-plugin": "^8.59.4",
+		"@typescript-eslint/parser": "^8.59.4",
+		"@vitejs/plugin-react": "^6.0.2",
+		"eslint": "^10.4.0",
+		"eslint-plugin-import": "^2.32.0",
+		"eslint-plugin-prettier": "^5.5.5",
+		"eslint-plugin-react-hooks": "^7.1.1",
 		"eslint-plugin-storybook": "^0.11.2",
-		"eslint-plugin-unused-imports": "^3.1.0",
+		"eslint-plugin-unused-imports": "^4.4.1",
 		"formik": "^2.4.9",
 		"husky": "^9.0.11",
 		"identity-obj-proxy": "^3.0.0",
@@ -91,22 +90,18 @@
 		"prettier": "^3.2.5",
 		"react": "^19.2.3",
 		"react-dom": "^19.2.3",
-		"react-hook-form": "^7.71.1",
+		"react-hook-form": "^7.76.0",
 		"react-router-dom": "^7.1.5",
 		"sass": "^1.76.0",
-		"storybook": "^8.5.3",
+		"storybook": "10.2.10",
 		"style-dictionary": "^3.9.2",
 		"stylelint": "^16.7.0",
 		"stylelint-config-standard": "^36.0.1",
 		"ts-jest": "^29.2.3",
-		"typescript": "^5.2.2",
-		"vite": "6.0.9",
-		"vite-plugin-dts": "^3.7.3",
-		"vite-plugin-libcss": "^1.1.1",
+		"typescript": "^6.0.3",
+		"vite": "^8.0.14",
+		"vite-plugin-dts": "^5.0.1",
 		"vite-plugin-linter": "^2.1.1",
-		"vite-tsconfig-paths": "^4.3.1"
-	},
-	"dependencies": {
-		"emoji-picker-react": "^4.14.1"
+		"vite-tsconfig-paths": "^6.1.1"
 	}
 }

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.