diff --git a/package.json b/package.json
index b50a69a..a4d3cad 100644
--- a/package.json
+++ b/package.json
@@ -28,6 +28,7 @@
"oxlint": "^1.75.0",
"postcss": "^8.5.28",
"prettier": "~3.6.2",
+ "svgo": "^4.1.0",
"tailwindcss": "^4.3.3",
"tslib": "^2.8.1",
"typescript": "^6.0.3",
@@ -41,6 +42,7 @@
"react": "^19.0.0",
"react-dom": "^19.0.0",
"server-only": "^0.0.1",
+ "sonner": "^2.0.8",
"tailwind-merge": "^3.7.0",
"valibot": "^1.5.0"
}
diff --git a/packages/island/package.json b/packages/island/package.json
index 531e012..71af01c 100644
--- a/packages/island/package.json
+++ b/packages/island/package.json
@@ -14,6 +14,7 @@
"./organisms/*": "./src/organisms/*/index.ts",
"./templates/*": "./src/templates/*/index.ts",
"./primitives/*": "./src/primitives/*/index.ts",
+ "./hooks/*": "./src/hooks/*/index.ts",
"./tools/*": "./src/tools/*/index.ts",
"./env": "./src/env/index.ts",
"./styles/*": "./src/styles/*",
@@ -26,7 +27,24 @@
"tags": [
"type:ui",
"scope:shared"
- ]
+ ],
+ "targets": {
+ "icons": {
+ "command": "jiti src/tools/icon-sprite-plugin/run.ts",
+ "options": {
+ "cwd": "{projectRoot}"
+ },
+ "inputs": [
+ "{projectRoot}/src/icons/*.svg",
+ "{projectRoot}/src/tools/icon-sprite-plugin/**/*"
+ ],
+ "outputs": [
+ "{projectRoot}/src/atoms/icon/sprite.svg",
+ "{projectRoot}/src/atoms/icon/icon-names.ts"
+ ],
+ "cache": true
+ }
+ }
},
"dependencies": {
"@lumina/libs": "workspace:*",
diff --git a/packages/island/src/atoms/amount/.gitkeep b/packages/island/src/atoms/amount/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/packages/island/src/atoms/amount/Amount.tsx b/packages/island/src/atoms/amount/Amount.tsx
new file mode 100644
index 0000000..34ef781
--- /dev/null
+++ b/packages/island/src/atoms/amount/Amount.tsx
@@ -0,0 +1,71 @@
+import { number, signed as signedNumber } from '@lumina/tools/format';
+
+import { cn } from '../../tools/cn';
+import { FlexBox } from '../flex-box';
+import { Typography } from '../typography';
+import { amountWeight } from './constants';
+import type { AmountProps } from './types';
+import {
+ amountCurrencyVariants,
+ amountNumberVariants,
+ amountVariants,
+} from './variants';
+
+/**
+ * A Toman amount. The number sits in an LTR isolate, so a sign stays beside the digits in RTL
+ * text and the unit stays outside it. The font draws the digits in Persian. The root sets the
+ * size, so the unit can be 0.8em of it.
+ */
+export function Amount({
+ value,
+ size,
+ tone = size === 'figure' ? 'figure' : 'ink',
+ struck = false,
+ signed = false,
+ decimals = 0,
+ currency,
+ srLabel,
+ className,
+ ...props
+}: AmountProps) {
+ const weight = amountWeight({ size, tone, struck });
+
+ return (
+
+
+ {signed ? signedNumber(value, decimals) : number(value, decimals)}
+
+ {currency != null && (
+
+ {currency}
+
+ )}
+ {srLabel && (
+ // A leading space and brackets, so it reads as an aside after the amount.
+
+ {` (${srLabel})`}
+
+ )}
+
+ );
+}
diff --git a/packages/island/src/atoms/amount/constants.ts b/packages/island/src/atoms/amount/constants.ts
new file mode 100644
index 0000000..3b0ecbb
--- /dev/null
+++ b/packages/island/src/atoms/amount/constants.ts
@@ -0,0 +1,21 @@
+import type { AmountProps } from './types';
+
+type AmountWeight = 'regular' | 'semibold' | 'bold';
+
+/**
+ * The number's weight, in the design system's cascade order (the last matching rule wins):
+ * figure 700, then title 600, mute 400, positive 600, struck 400. So `mute` and `struck` stay
+ * regular even at figure size.
+ */
+export function amountWeight({
+ size,
+ tone,
+ struck,
+}: Pick): AmountWeight {
+ if (struck) return 'regular';
+ if (tone === 'positive') return 'semibold';
+ if (tone === 'mute') return 'regular';
+ if (size === 'title') return 'semibold';
+ if (size === 'figure' || tone === 'figure') return 'bold';
+ return 'semibold';
+}
diff --git a/packages/island/src/atoms/amount/index.ts b/packages/island/src/atoms/amount/index.ts
new file mode 100644
index 0000000..594e30f
--- /dev/null
+++ b/packages/island/src/atoms/amount/index.ts
@@ -0,0 +1,3 @@
+export { Amount } from './Amount';
+export type { AmountProps } from './types';
+export { amountVariants } from './variants';
diff --git a/packages/island/src/atoms/amount/types.ts b/packages/island/src/atoms/amount/types.ts
new file mode 100644
index 0000000..53779a7
--- /dev/null
+++ b/packages/island/src/atoms/amount/types.ts
@@ -0,0 +1,17 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+
+import type { amountVariants } from './variants';
+
+export type AmountProps = Omit, 'children'> &
+ VariantProps & {
+ /** Whole Toman. Never Rial, never rounded or abbreviated. */
+ value: number;
+ /** Always shows `+` or `−` (ledger lines). The colour stays; the sign carries the meaning. */
+ signed?: boolean;
+ decimals?: number;
+ /** The unit after the number, such as «تومان». Omit it where a column header names the unit. */
+ currency?: ReactNode;
+ /** Hidden text that says why, such as «لغو شده» on a struck amount. */
+ srLabel?: string;
+ };
diff --git a/packages/island/src/atoms/amount/variants.ts b/packages/island/src/atoms/amount/variants.ts
new file mode 100644
index 0000000..0075a04
--- /dev/null
+++ b/packages/island/src/atoms/amount/variants.ts
@@ -0,0 +1,52 @@
+import { cva } from 'class-variance-authority';
+
+export const amountVariants = cva('whitespace-nowrap', {
+ variants: {
+ size: {
+ /** The one hero figure on a screen: قابل واریز, the checkout total. */
+ figure: 'text-display',
+ /** Tier totals. */
+ title: 'text-heading-sm',
+ body: 'text-body-md',
+ /** Dense rows. */
+ caption: 'text-caption',
+ },
+ tone: {
+ ink: 'text-text-primary',
+ /** The hero tone: ink with a bold number (600 at title size, as in the DS). Default at figure size. */
+ figure: 'text-text-primary',
+ /** Per-month equivalents. */
+ mute: 'text-text-secondary',
+ /** A negative balance, with its explanation underneath. */
+ negative: 'text-danger-text',
+ /** Money returned to the investor (بازگشت وجه), with `signed`. */
+ positive: 'text-success-text',
+ },
+ /** A cancelled payout, or a standing price beside a promotion. */
+ struck: { true: 'text-text-tertiary', false: '' },
+ },
+ defaultVariants: { size: 'body', tone: 'ink', struck: false },
+});
+
+export const amountNumberVariants = cva('', {
+ variants: {
+ weight: {
+ regular: 'font-normal',
+ semibold: 'font-semibold',
+ bold: 'font-bold',
+ },
+ struck: {
+ true: 'line-through decoration-[1.5px]',
+ false: '',
+ },
+ },
+ defaultVariants: { weight: 'semibold', struck: false },
+});
+
+export const amountCurrencyVariants = cva('text-[0.8em] font-normal', {
+ variants: {
+ /** «تومان» is secondary next to an ink figure, and follows any other tone. */
+ muted: { true: 'text-text-secondary', false: '' },
+ },
+ defaultVariants: { muted: true },
+});
diff --git a/packages/island/src/atoms/avatar/.gitkeep b/packages/island/src/atoms/avatar/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/packages/island/src/atoms/avatar/Avatar.tsx b/packages/island/src/atoms/avatar/Avatar.tsx
new file mode 100644
index 0000000..01f1b85
--- /dev/null
+++ b/packages/island/src/atoms/avatar/Avatar.tsx
@@ -0,0 +1,78 @@
+import { cn } from '../../tools/cn';
+import { Element } from '../../primitives/element';
+import { GridBox } from '../grid-box';
+import { Icon } from '../icon';
+import { Typography } from '../typography';
+import { AVATAR_INITIAL_VARIANT, AVATAR_MARK_PX, AVATAR_PX } from './constants';
+import type { AvatarProps } from './types';
+import { avatarVariants } from './variants';
+
+/**
+ * A circular creator or user picture. The placeholder sits under the image, so it shows while
+ * the image loads and when it fails, without client code.
+ */
+export function Avatar({
+ name,
+ src,
+ size = 'md',
+ verified = false,
+ verifiedLabel,
+ label,
+ className,
+ ...props
+}: AvatarProps) {
+ const px = AVATAR_PX[size];
+
+ return (
+
+
+
+ {Array.from(name)[0] ?? '?'}
+
+ {src && (
+ // A broken image with an empty alt draws nothing, so the letter shows through.
+
+ )}
+
+ {verified && (
+
+
+
+ )}
+
+ );
+}
diff --git a/packages/island/src/atoms/avatar/constants.ts b/packages/island/src/atoms/avatar/constants.ts
new file mode 100644
index 0000000..a4491ec
--- /dev/null
+++ b/packages/island/src/atoms/avatar/constants.ts
@@ -0,0 +1,24 @@
+import type { TypographyVariant } from '../typography';
+import type { AvatarSize } from './types';
+
+/** px, so the image reserves its box before it loads. */
+export const AVATAR_PX: Record = {
+ sm: 32,
+ md: 40,
+ lg: 56,
+ xl: 80,
+};
+
+export const AVATAR_INITIAL_VARIANT: Record = {
+ sm: 'label',
+ md: 'body-md',
+ lg: 'heading-sm',
+ xl: 'heading-lg',
+};
+
+export const AVATAR_MARK_PX: Record = {
+ sm: 12,
+ md: 14,
+ lg: 18,
+ xl: 22,
+};
diff --git a/packages/island/src/atoms/avatar/index.ts b/packages/island/src/atoms/avatar/index.ts
new file mode 100644
index 0000000..6502cc2
--- /dev/null
+++ b/packages/island/src/atoms/avatar/index.ts
@@ -0,0 +1,3 @@
+export { Avatar } from './Avatar';
+export type { AvatarProps, AvatarSize } from './types';
+export { avatarVariants } from './variants';
diff --git a/packages/island/src/atoms/avatar/types.ts b/packages/island/src/atoms/avatar/types.ts
new file mode 100644
index 0000000..e826ac3
--- /dev/null
+++ b/packages/island/src/atoms/avatar/types.ts
@@ -0,0 +1,25 @@
+import type { VariantProps } from 'class-variance-authority';
+import type { ComponentPropsWithRef } from 'react';
+
+import type { avatarVariants } from './variants';
+
+export type AvatarSize = NonNullable<
+ VariantProps['size']
+>;
+
+export type AvatarProps = Omit, 'children'> & {
+ /** The username: its first letter is the placeholder, or `?` while it is empty. */
+ name: string;
+ /** The uploaded image; omit it to show the placeholder. */
+ src?: string | null;
+ size?: AvatarSize;
+ /** The creator's verification mark at the bottom inline end. */
+ verified?: boolean;
+ /** The mark's accessible name, such as «تأییدشده». */
+ verifiedLabel?: string;
+ /**
+ * The avatar's accessible name. Omit it when the username is next to it, as on a post header,
+ * so screen readers don't read the name twice.
+ */
+ label?: string;
+};
diff --git a/packages/island/src/atoms/avatar/variants.ts b/packages/island/src/atoms/avatar/variants.ts
new file mode 100644
index 0000000..09e2ef8
--- /dev/null
+++ b/packages/island/src/atoms/avatar/variants.ts
@@ -0,0 +1,21 @@
+import { cva } from 'class-variance-authority';
+
+/** The placeholder is the username's first letter in white on `action-primary`. */
+export const avatarVariants = cva(
+ 'relative flex-none overflow-hidden rounded-full bg-action-primary text-text-on-action',
+ {
+ variants: {
+ size: {
+ /** Compact rows and the top bar. */
+ sm: 'size-8',
+ /** Post headers, subscription cards, list rows. */
+ md: 'size-10',
+ /** Sheet and checkout headers. */
+ lg: 'size-14',
+ /** The channel profile header. */
+ xl: 'size-20',
+ },
+ },
+ defaultVariants: { size: 'md' },
+ },
+);
diff --git a/packages/island/src/atoms/button/.gitkeep b/packages/island/src/atoms/button/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/packages/island/src/atoms/button/Button.tsx b/packages/island/src/atoms/button/Button.tsx
new file mode 100644
index 0000000..c57bc5b
--- /dev/null
+++ b/packages/island/src/atoms/button/Button.tsx
@@ -0,0 +1,109 @@
+import NextLink from 'next/link';
+import type { MouseEvent } from 'react';
+
+import { cn } from '../../tools/cn';
+import { FlexBox } from '../flex-box';
+import { ButtonContent } from './components/ButtonContent';
+import { FrozenButton } from './components/FrozenButton';
+import { buttonLayout, withoutLinkProps } from './constants';
+import type { ButtonLinkElementProps, ButtonProps } from './types';
+import { buttonVariants } from './variants';
+
+/**
+ * Every tappable action: a full pill (an icon-only button is a circle). No hooks, so a server
+ * component can render it with no JavaScript; only a frozen button with a reason is a client one.
+ */
+export function Button({
+ variant,
+ size,
+ block,
+ icon,
+ iconEnd,
+ label,
+ frozen = false,
+ frozenReason,
+ isLoading = false,
+ className,
+ children,
+ ...props
+}: ButtonProps) {
+ const iconOnly = children == null && icon !== undefined;
+ const classes = cn(
+ buttonVariants({ variant, size, block, iconOnly, frozen }),
+ className,
+ );
+ const content = (
+
+ {children}
+
+ );
+ const ariaLabel = iconOnly ? label : props['aria-label'];
+ const title = iconOnly && !frozen ? label : undefined;
+ const isBlocked = frozen || isLoading;
+
+ // A frozen or loading link renders a `