@eifi1/ui-kit 0.31.1 → 0.32.0

package/src/i18n/locales/zh.ts

@@ -20,6 +20,9 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
     seconds < 60 ? `${n(Math.ceil(seconds))} 秒` : `${n(Math.ceil(seconds / 60))} 分钟`;
   const rateLimited = (seconds?: number) =>
     !seconds || seconds <= 0 ? "尝试次数过多，请稍候再试。" : `尝试次数过多，请 ${wait(seconds)}后重试。`;
+  // 0.32.0 — when a trial or a grant ends, as `inDays` in src/billing/billing-labels.ts:
+  // 0 (or less) is today, 1 tomorrow. A numeral brings its own leading space.
+  const inDays = (days: number) => (days <= 0 ? "今天" : days === 1 ? "明天" : ` ${n(days)} 天后`);
 
   return {
     feedbackAttachment: {
@@ -777,6 +780,10 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
           disclaimer: {
             title: "内容与链接的责任",
             body: "这是一个私人的非商业项目，在封闭测试期间提供，不作任何保证。我们所链接的外部网站由其各自的运营者负责；我们无法控制其内容。",
+            // 0.32.0 — the commercial variant (docs/billing-harmonization.md §8). "套餐"
+            // and "订阅" as the `billing` namespace.
+            commercial:
+              "这是一项商业服务。付费套餐由我们的经销商销售，该经销商作为记录商户（Merchant of Record）行事：它以自己的名义销售订阅、收取款项、开具发票并处理增值税，且该笔购买适用其销售条款。我们尽力确保本服务的内容准确，但无法保证其完整或最新。我们所链接的外部网站由其各自的运营者负责；我们无法控制其内容。",
           },
         },
         privacy: {
@@ -1196,6 +1203,7 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       outflow: "支出",
       inflow: "收入",
       direction: (current, next) => `方向：${current}，切换为${next}`,
+      switchTo: (next) => `切换为${next}`,
     },
     columnMapper: {
       paste: "粘贴表格",
@@ -1358,6 +1366,88 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       endedSandbox: "示例数据会定期重置；您在演示中创建的内容会被删除。",
       restart: "开始新的演示",
     },
+    // 0.32.0 — docs/billing-harmonization.md §7, §10 and §12.24: "套餐" is what is bought
+    // (Free, Pro), "订阅" the standing arrangement and the settings group. "您".
+    billing: {
+      group: "订阅",
+      plans: "套餐",
+      interval: "计费周期",
+      yearly: "按年",
+      monthly: "按月",
+      // As `currency.currency`.
+      currency: "货币",
+      perYear: "每年",
+      perMonth: "每月",
+      vatIncluded: "含增值税",
+      free: "免费",
+      notOffered: "此计费周期不提供",
+      // As `progressBar.unlimited`.
+      unlimited: "无限制",
+      limits: "限额",
+      features: "包含内容",
+      current: "当前套餐",
+      choose: (plan) => `选择 ${plan}`,
+      upgrade: (plan) => `升级到 ${plan}`,
+      downgrade: (plan) => `切换到 ${plan}`,
+      isCurrent: "这是您当前的套餐。",
+      pickFirst: "请先选择一个套餐。",
+      status: {
+        trialing: "试用中",
+        active: "有效",
+        past_due: "付款逾期",
+        canceled: "已取消",
+        // As `invitations.status.expired`.
+        expired: "已过期",
+        comped: "免费赠送",
+      },
+      trialEnding: (days) =>
+        `您的试用期将于${inDays(days)}结束。之后您仍可查看所有内容，但需要套餐才能进行修改。`,
+      grantEnding: (days) =>
+        `您的免费使用权将于${inDays(days)}结束。之后您仍可查看所有内容，但需要套餐才能进行修改。`,
+      paymentFailed: "您的上一笔付款未成功。请更新付款方式，以保留您的套餐。",
+      planEnded: "您的套餐已结束。您仍可查看和导出所有内容；选择套餐后即可再次进行修改。",
+      // Never why: the owner's payment status is the owner's personal data (§12.6).
+      guestReadOnly: (item) =>
+        item
+          ? `“${item}”目前为只读；其所有者可以解除此限制。`
+          : "此内容目前为只读；其所有者可以解除此限制。",
+      processing: "您的付款正在处理中。确认后您的套餐即会生效；此页面会自动更新。",
+      choosePlan: "选择套餐",
+      updatePayment: "更新付款方式",
+      checkAgain: "再次检查",
+      lockReason: "您的套餐已结束。选择套餐后即可再次进行修改。",
+      // As `characterCount.limitReached` ("已达到字符数上限").
+      limitReached: "已达到套餐上限",
+      limitUpgrade: "如需添加更多，请选择上限更高的套餐。",
+      limitContact: "如需添加更多，请向我们申请更高的上限。",
+      askForMore: "申请提高上限",
+      // Both figures arrive formatted; written as `characterCount.count` writes them.
+      usage: (used, limit) => `${used}/${limit}`,
+      contactSubject: (dimension) => `套餐上限：${dimension}`,
+      manage: "付款与发票",
+      cancel: "取消订阅",
+      waitingChanges: (count) => `${n(count)} 项修改正在等待套餐`,
+      // "放弃", as `wizard.cancelConfirmLabel`.
+      discardWaiting: "放弃等待中的修改",
+    },
+    // 0.32.0 — docs/text-size-harmonization.md §6: the text-size and contrast settings in
+    // the "外观" group.
+    appearance: {
+      textSize: "文字大小",
+      textSizeHelp: "更大的文字，以及为其留出空间的布局。",
+      textSizes: { normal: "标准", large: "大", xlarge: "特大" },
+      contrast: "对比度",
+      contrastHelp: "增强对比度会加深浅色文字和线条，并加粗焦点框。“跟随系统”沿用此设备的设置。",
+      contrastModes: { system: "跟随系统", standard: "标准", more: "增强" },
+    },
+    rowActions: {
+      actions: "操作",
+      actionsFor: (name) => `${name} 的操作`,
+    },
+    appShellMore: {
+      more: "更多",
+      moreTitle: "更多页面",
+    },
   };
 }
 

package/src/i18n/review.ts

@@ -267,6 +267,8 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
   "ibanInput.country": [["{{code}}"]],
   "ibanInput.length": [[20, 21]],
   "signChip.direction": [["{{current}}", "{{next}}"]],
+  "signChip.switchTo": [["{{next}}"]],
+  "rowActions.actionsFor": [["{{name}}"]],
   "columnMapper.readError": [["{{name}}"]],
   "columnMapper.summary": [
     [1, 1],
@@ -352,4 +354,16 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
     [3, 12],
   ],
   "demo.minutesLeft": one,
+  // 0.32.0: the subscription parts (docs/billing-harmonization.md §7). A trial or a grant
+  // ending today, tomorrow and in five days; the guest's notice with and without the
+  // item's name.
+  "billing.choose": [["{{plan}}"]],
+  "billing.upgrade": [["{{plan}}"]],
+  "billing.downgrade": [["{{plan}}"]],
+  "billing.trialEnding": [[0], [1], [5]],
+  "billing.grantEnding": [[0], [1], [5]],
+  "billing.guestReadOnly": [["{{item}}"], [undefined]],
+  "billing.usage": [["{{used}}", "{{limit}}"]],
+  "billing.contactSubject": [["{{dimension}}"]],
+  "billing.waitingChanges": one,
 };

package/src/index.ts

@@ -19,11 +19,17 @@ export { useMediaQuery } from "./hooks/use-media-query";
 export { useBodyScrollLock } from "./hooks/use-body-scroll-lock";
 export { useAnchoredRect } from "./hooks/use-anchored-rect";
 export type { AnchorRect } from "./hooks/use-anchored-rect";
-export { useAnchoredPanel, anchoredPanelPlacement, useVisualViewport } from "./hooks/use-anchored-panel";
+export {
+  useAnchoredPanel,
+  anchoredPanelPlacement,
+  useVisualViewport,
+  readKeyboardInset,
+} from "./hooks/use-anchored-panel";
 export type {
   AnchoredPanel,
   AnchoredPanelOptions,
   ViewportBox,
+  KeyboardInsetOptions,
 } from "./hooks/use-anchored-panel";
 export { useEscapeKey, useOutsideClick } from "./hooks/use-dismiss";
 // Focus containment for an overlay, and a live region for a change that moves no focus.
@@ -151,7 +157,7 @@ export * from "./components/icon-picker";
 export * from "./components/choice-card";
 export * from "./components/autocomplete";
 export * from "./components/measured-grid";
-export { useWindowedRows } from "./hooks/use-windowed-rows";
+export { useWindowedRows, WINDOWED_ROW_INDEX } from "./hooks/use-windowed-rows";
 export type { WindowedRows } from "./hooks/use-windowed-rows";
 // Named, not `export *`: file-button.tsx also holds the screening helpers the
 // dropzone shares, which are internal.
@@ -260,7 +266,14 @@ export type {
 // The toast layer over sonner (an OPTIONAL peer, loaded lazily): `toast` mirrors sonner's
 // API so apps migrate by swapping the import; `<Toaster>` carries the placement, theme,
 // tones and z-index both apps had wired by hand.
-export { toast, Toaster, DEFAULT_TOAST_LABELS, TOAST_ACTION_DURATION } from "./components/toast";
+export {
+  toast,
+  Toaster,
+  DEFAULT_TOAST_LABELS,
+  TOAST_ACTION_DURATION,
+  TOASTER_OFFSET_TOP,
+  TOASTER_OFFSET_BOTTOM,
+} from "./components/toast";
 export type {
   ToastId,
   ToastAction,
@@ -485,6 +498,7 @@ export type {
   LegalTextSectionLabels,
   LegalOperatorSectionLabels,
   LegalFramedSectionLabels,
+  LegalDisclaimerSectionLabels,
 } from "./components/legal";
 export { LegalPage, LegalKitSection, LegalAcceptCheckbox, LEGAL_SKELETON } from "./components/legal-page";
 
@@ -507,7 +521,7 @@ export type { RegisterFormProps, RegisterLabels, RegisterValues } from "./auth/r
 export { CompleteNameDialog, DEFAULT_COMPLETE_NAME_LABELS } from "./auth/complete-name-dialog";
 export type { CompleteNameDialogProps, CompleteNameLabels, CompleteNameValues } from "./auth/complete-name-dialog";
 export { taggedEmail } from "./auth/email-tag";
-export { isAuthError, authErrorCode } from "./auth/auth-errors";
+export { isAuthError, authErrorCode, isBillingError } from "./auth/auth-errors";
 export type { AuthErrorCode } from "./auth/auth-errors";
 export { ForgotPasswordForm, DEFAULT_FORGOT_PASSWORD_LABELS } from "./auth/forgot-password-form";
 export type { ForgotPasswordFormProps, ForgotPasswordLabels } from "./auth/forgot-password-form";
@@ -545,7 +559,7 @@ export type { CompanySwitcherProps, CompanySwitcherLabels, CompanySwitcherCompan
 // invitations panel, and the account's own settings — email change, sessions, deletion,
 // export. Callbacks only; the confirmation level is the server's.
 export { isRateLimited, retryAfterSeconds } from "./auth/auth-errors";
-export type { AccountErrorCode, DemoErrorCode, KitErrorCode } from "./auth/auth-errors";
+export type { AccountErrorCode, BillingErrorCode, DemoErrorCode, KitErrorCode } from "./auth/auth-errors";
 export { EmailChangeSetting, DEFAULT_EMAIL_CHANGE_LABELS } from "./account/email-change-setting";
 export type {
   EmailChangeSettingProps,
@@ -669,7 +683,8 @@ export {
 export type { SettingsGroup, SettingsEntry, SettingsSearchEntriesOptions } from "./settings/settings-catalogue";
 export { DEFAULT_SETTINGS_LABELS, useSettingsLabels } from "./settings/settings-labels";
 export type { SettingsLabels, SettingsGroupLabels, SettingsCoreGroup } from "./settings/settings-labels";
-// Only the language follows the account (§6.2).
+// The language follows the account (§6.2); since 0.32 so do the text size and the
+// contrast (useAccountAppearance below, docs/text-size-harmonization.md §6).
 export { useAccountLanguage, resolveAccountLanguage, matchOfferedLanguage } from "./settings/use-account-language";
 export type {
   UseAccountLanguageOptions,
@@ -738,8 +753,61 @@ export type {
   LegalSkeletonEntry,
   LegalSkeletonPage,
   LegalSectionOwner,
+  LegalDisclaimerVariant,
 } from "./components/legal-page";
 
+// ── 0.32.0: text size and contrast (docs/text-size-harmonization.md) ──
+export * from "./theme/text-size";
+export * from "./theme/contrast";
+export { useBreakpoint, usePhoneLayout, breakpointQuery, BREAKPOINT_REM } from "./hooks/use-breakpoint";
+export type { Breakpoint, BreakpointVariant } from "./hooks/use-breakpoint";
+export { useAccountAppearance, resolveAccountAppearance } from "./settings/use-account-appearance";
+export type {
+  AppearanceSource,
+  AccountAppearanceFields,
+  DeviceAppearance,
+  AccountAppearancePatch,
+  ResolvedAccountAppearance,
+  UseAccountAppearanceOptions,
+  AccountAppearance,
+} from "./settings/use-account-appearance";
+export { DEFAULT_APPEARANCE_LABELS, useAppearanceLabels } from "./components/appearance-labels";
+// The behaviours at Large (§4, §10.7–10.9): a row's actions, the hooks components read.
+export { RowActions, rowActionsColumn, DEFAULT_ROW_ACTIONS_LABELS } from "./components/row-actions";
+export type {
+  RowAction,
+  RowActionList,
+  RowActionsLabels,
+  RowActionsProps,
+  RowActionsCollapse,
+  RowActionsSize,
+  RowActionsColumnOptions,
+} from "./components/row-actions";
+export { useLargeText, useCoarsePointer, useInlineFacts } from "./hooks/use-large-text";
+export type { AppearanceLabels } from "./components/appearance-labels";
+
+// ── 0.32.0: billing — plans, standing, banners, the limit notice (docs/billing-harmonization.md §7) ──
+export { DEFAULT_BILLING_LABELS, useBillingLabels, SUBSCRIPTION_STATUSES } from "./billing/billing-labels";
+export type { BillingLabels, SubscriptionStatus } from "./billing/billing-labels";
+export { BILLING_INTERVALS, planPrice, minorToMajor, formatPlanPrice, billingCurrencyFor } from "./billing/plan-price";
+export type { BillingInterval, BillingCurrency, PlanIntervalPrices, PlanPrices, PlanPriceAnswer } from "./billing/plan-price";
+export { PlanCard, PlanPicker, planRelation } from "./billing/plan-card";
+export type { BillingPlan, PlanRelation, PlanCardProps, PlanPickerProps, PlanChoice } from "./billing/plan-card";
+export { SubscriptionStatusChip, SUBSCRIPTION_STATUS_TONES } from "./billing/subscription-status-chip";
+export type { SubscriptionStatusChipProps } from "./billing/subscription-status-chip";
+export { BillingBanner } from "./billing/billing-banner";
+export type { BillingBannerProps, BillingBannerKind } from "./billing/billing-banner";
+export { PlanLimitNotice, planLimitMailto } from "./billing/plan-limit-notice";
+export type { PlanLimitNoticeProps } from "./billing/plan-limit-notice";
+export { isPlanLimit } from "./billing/plan-limit";
+export type { PlanLimitRefusal } from "./billing/plan-limit";
+export { combineWriteLocks, useBillingLockReason } from "./billing/billing-lock";
+export type { WriteLockSource, CombinedWriteLock, BillingLockReasonOptions } from "./billing/billing-lock";
+export { billingLockAt, isBillingReadOnly, billingDaysLeft } from "./billing/billing-standing";
+export type { BillingStanding } from "./billing/billing-standing";
+export { SubscriptionActions } from "./billing/subscription-actions";
+export type { SubscriptionActionsProps } from "./billing/subscription-actions";
+
 // ── 0.22.0: the inputs round (kastlan's, keksdose's and Kurvenschmiede's audits) ──
 export * from "./components/checkbox-group";
 export * from "./components/one-time-code-input";

package/src/landing/public-header.tsx

@@ -1,7 +1,7 @@
 import type { ReactNode } from "react";
 
-import { Button, PHONE_QUERY } from "../components/ui";
-import { useMediaQuery } from "../hooks/use-media-query";
+import { Button } from "../components/ui";
+import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { TopBar } from "../shell/top-bar";
 import type { TopBarProps } from "../shell/top-bar";
 import { TopBarBrand } from "../shell/top-bar-brand";
@@ -55,7 +55,7 @@ export interface PublicHeaderProps extends Omit<TopBarProps, "brand" | "actions"
  * | user | **Open app** (primary) |
  *
  * A demo session is not "signed in" here: it is still offered access, which is the point
- * of the demo (§5.6). On a phone (`PHONE_QUERY`) the actions take the kit's `sm` size, so
+ * of the demo (§5.6). In the phone layout (`usePhoneLayout()`) the actions take the kit's `sm` size, so
  * the brand mark, the two controls and two actions fit 390px; "Sign in" gives way below
  * `sm` as in keksdose — the sign-in page is one tap away from "Request access" anyway.
  */
@@ -75,7 +75,7 @@ export function PublicHeader({
 }: PublicHeaderProps) {
   const labels = useLandingLabels(labelsProp);
   const accessLink = useAccessAction(access, labelsProp);
-  const phone = useMediaQuery(PHONE_QUERY, false);
+  const phone = usePhoneLayout();
   const size = phone ? "sm" : "md";
   const home = homeHref ?? (session === "none" ? "/" : "/welcome");
 

package/src/lib/cn.ts

@@ -1,5 +1,16 @@
 import { clsx } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * tailwind-merge, told about the kit's own font sizes (docs/text-size-harmonization.md
+ * §3.2): `text-micro` and `text-caption` are `@theme` sizes in tokens.css, which
+ * tailwind-merge cannot see. Unknown, a `text-<word>` is taken for a COLOUR, so
+ * `cn("text-caption text-[var(--text-muted)]")` dropped the size — the later colour
+ * "won" over it — and `cn("text-xs", "text-caption")` kept both sizes. Registered as
+ * sizes, they merge like `text-xs`: a later size replaces an earlier one, a colour sits
+ * beside them.
+ */
+const merge = extendTailwindMerge({ extend: { theme: { text: ["micro", "caption"] } } });
 
 /** Merge class lists with Tailwind conflict resolution (later wins). */
-export const cn = (...inputs: Parameters<typeof clsx>) => twMerge(clsx(inputs));
+export const cn = (...inputs: Parameters<typeof clsx>) => merge(clsx(inputs));

package/src/rhf/fields.tsx

@@ -1003,7 +1003,7 @@ function RangeBody({
           key={message}
           id={messageIds[i]}
           data-slot="form-message"
-          className="text-[11px] leading-tight text-[var(--danger)]"
+          className="text-caption leading-tight text-[var(--danger)]"
         >
           {message}
         </p>

package/src/rhf/form.tsx

@@ -287,7 +287,7 @@ export function FormDescription({ className, ...rest }: FormDescriptionProps) {
       data-slot="form-description"
       {...rest}
       id={formDescriptionId}
-      className={cn("text-[11px] leading-tight text-[var(--text-muted)]", className)}
+      className={cn("text-caption leading-tight text-[var(--text-muted)]", className)}
     />
   );
 }
@@ -315,7 +315,7 @@ export function FormMessage({ className, children, ...rest }: FormMessageProps)
       data-slot="form-message"
       {...rest}
       id={formMessageId}
-      className={cn("text-[11px] leading-tight text-[var(--danger)]", className)}
+      className={cn("text-caption leading-tight text-[var(--danger)]", className)}
     >
       {body}
     </p>

package/src/search/command-palette.tsx

@@ -3,8 +3,8 @@ import type { ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { CornerDownLeft, Search, X } from "lucide-react";
 import { cn } from "../lib/cn";
-import { PHONE_QUERY } from "../components/ui";
-import { useMediaQuery } from "../hooks/use-media-query";
+import { FIELD_TOUCH_TEXT } from "../components/ui";
+import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
@@ -191,7 +191,7 @@ interface CommandPaletteProps {
    *  which overrides it per row). Off by default. */
   redactLabels?: boolean;
   /**
-   * Below the phone breakpoint ({@link PHONE_QUERY}) the palette fills the screen:
+   * In the phone layout (`usePhoneLayout()`) the palette fills the screen:
    * no inset, no rounded panel, the field pinned at the top inside the safe areas and
    * the list scrolling under it, with a close button since there is no backdrop to tap.
    * On by default — a top-centred card at 70vh leaves little room once the keyboard is
@@ -267,7 +267,7 @@ export function CommandPalette({
     setQuery(next);
   };
   const dirty = submitMode && draft !== query;
-  const isPhone = useMediaQuery(PHONE_QUERY, false) && fullScreenOnPhone;
+  const isPhone = usePhoneLayout() && fullScreenOnPhone;
   const [results, setResults] = useState<CommandItem[]>([]);
   const [loading, setLoading] = useState(false);
   const [failed, setFailed] = useState(false);
@@ -471,11 +471,12 @@ export function CommandPalette({
             enterKeyHint={submitMode ? "search" : undefined}
             className={cn(
               "w-full bg-transparent py-3 outline-none placeholder:text-[var(--text-placeholder)] text-[var(--text-primary)]",
-              // 16px on a phone, or iOS zooms the page in on focus.
-              isPhone ? "text-base" : "text-sm",
+              // 16px on a phone, or iOS zooms the page in on focus — and on any other
+              // touch screen too (a tablet's popover), FIELD_TOUCH_TEXT (§10.1).
+              isPhone ? "text-base" : cn("text-sm", FIELD_TOUCH_TEXT),
             )}
           />
-          {loading && <span className="shrink-0 text-[11px] text-[var(--text-placeholder)]">{l.loading}</span>}
+          {loading && <span className="shrink-0 text-caption text-[var(--text-placeholder)]">{l.loading}</span>}
           {fieldText !== "" && (
             <button
               type="button"
@@ -536,7 +537,7 @@ export function CommandPalette({
               <div
                 id={groupId(groupIndex)}
                 role="presentation"
-                className="px-3 pb-0.5 pt-2 text-[10px] font-semibold uppercase tracking-wide text-[var(--text-placeholder)]"
+                className="px-3 pb-0.5 pt-2 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]"
               >
                 {group}
               </div>
@@ -635,7 +636,7 @@ export function CommandPalette({
         </ul>
 
         {l.hint && (
-          <div className="border-t border-[var(--border)] px-3 py-1.5 text-[11px] text-[var(--text-placeholder)]">
+          <div className="border-t border-[var(--border)] px-3 py-1.5 text-caption text-[var(--text-placeholder)]">
             {l.hint}
           </div>
         )}

package/src/settings/settings-layout.tsx

@@ -3,6 +3,7 @@ import type { ReactElement, ReactNode } from "react";
 import { Link, useHref, useLocation } from "react-router";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 import { Button, Card, EmptyState, Tabs } from "../components/ui";
+import { FOCUS_RING } from "../components/focus-ring";
 import { Chip } from "../components/chip";
 import { List, ListItem } from "../components/list";
 import type { ListItemLinkProps } from "../components/list";
@@ -266,7 +267,7 @@ export function SettingsLayout<G extends string>({
                 e.preventDefault();
                 route.back();
               }}
-              className="-ms-1 inline-flex items-center gap-0.5 self-start rounded-md pe-1 text-sm font-medium text-[var(--text-muted)] hover:text-[var(--text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]"
+              className={cn("-ms-1 inline-flex items-center gap-0.5 self-start rounded-md pe-1 text-sm font-medium text-[var(--text-muted)] hover:text-[var(--text-primary)]", FOCUS_RING)}
             >
               <ChevronLeft aria-hidden className="size-4 rtl:-scale-x-100" />
               {pageTitle}

package/src/settings/use-account-appearance.ts

@@ -0,0 +1,148 @@
+import { useCallback, useMemo } from "react";
+import { isTextSize, resolveTextSize } from "../theme/text-size";
+import type { TextSize } from "../theme/text-size";
+import { isContrastMode, resolveContrastMode } from "../theme/contrast";
+import type { ContrastMode } from "../theme/contrast";
+
+/**
+ * The text size and contrast follow the account like the language does
+ * (docs/text-size-harmonization.md §2.2, §2.6, §6; settings contract §6.2) — the same
+ * rule as {@link useAccountLanguage}, for two values at once.
+ */
+
+/** Where a value in force came from, in the order they are asked. */
+export type AppearanceSource = "device" | "account" | "default";
+
+/** The two fields of an `/auth/me` answer this reads — server-kit 0.6's `UserResponse`,
+ *  both nullable (null = never chosen). */
+export interface AccountAppearanceFields {
+  text_size?: string | null;
+  contrast?: string | null;
+}
+
+/** This device's own choices — the text-size and contrast stores' values, `null` where
+ *  this device never chose. */
+export interface DeviceAppearance {
+  textSize?: string | null;
+  contrast?: string | null;
+}
+
+/** The body of `PATCH /auth/me` for a pick: one field, as server-kit's `ProfileUpdate`
+ *  spells it. */
+export type AccountAppearancePatch = { text_size: TextSize } | { contrast: ContrastMode };
+
+export interface ResolvedAccountAppearance {
+  textSize: TextSize;
+  /** The stored MODE — "system" included — not whether more contrast is on now. */
+  contrast: ContrastMode;
+  sources: { textSize: AppearanceSource; contrast: AppearanceSource };
+}
+
+function source(device: boolean, account: boolean): AppearanceSource {
+  return device ? "device" : account ? "account" : "default";
+}
+
+/**
+ * The values on a device (§2.6): **its own choice → the account's → the default**
+ * (Normal; "system" for contrast), each taken only when it is a known value. Pure.
+ */
+export function resolveAccountAppearance(
+  device: DeviceAppearance,
+  account: AccountAppearanceFields | null | undefined,
+): ResolvedAccountAppearance {
+  return {
+    textSize: resolveTextSize(device.textSize, account?.text_size),
+    contrast: resolveContrastMode(device.contrast, account?.contrast),
+    sources: {
+      textSize: source(isTextSize(device.textSize), isTextSize(account?.text_size)),
+      contrast: source(isContrastMode(device.contrast), isContrastMode(account?.contrast)),
+    },
+  };
+}
+
+export interface UseAccountAppearanceOptions {
+  /** The signed-in account (`/auth/me`), or `null` / `undefined` while signed out or not
+   *  loaded yet — then nothing is saved to it. */
+  account: AccountAppearanceFields | null | undefined;
+  /** This device's own choices: `useTextSizeStore((s) => s.size)` and
+   *  `useContrastStore((s) => s.contrast)`. */
+  device: DeviceAppearance;
+  /** Store a device choice: `(patch) => { if (patch.textSize) setSize(patch.textSize);
+   *  if (patch.contrast) setContrast(patch.contrast); }`. */
+  setDevice: (patch: { textSize?: TextSize; contrast?: ContrastMode }) => void;
+  /** Write the account: `PATCH /auth/me` with the patch as its body. Return its promise. */
+  save: (patch: AccountAppearancePatch) => unknown;
+  /** A demo session: a pick stays on the device, the account is never written (§6). */
+  isDemo?: boolean;
+}
+
+export interface AccountAppearance extends ResolvedAccountAppearance {
+  /** The user picked a size: it becomes the device's choice and — signed in, and not a
+   *  demo — the account's. The promise is `save`'s; the device keeps the pick if it
+   *  fails, and the app says so. */
+  pickTextSize: (size: TextSize) => Promise<unknown>;
+  /** As {@link pickTextSize}, for the contrast mode. */
+  pickContrast: (mode: ContrastMode) => Promise<unknown>;
+}
+
+/**
+ * The account's text size and contrast on this device (§6): the order of
+ * {@link resolveAccountAppearance}, and the writes.
+ *
+ * - **Nothing writes the account on its own.** Rendering, signing in and adopting the
+ *   account's values call neither `save` nor `setDevice`, so a new device adopts the
+ *   account instead of overwriting it.
+ * - **A pick** writes the device's choice, then `save` — except in a demo session or
+ *   signed out.
+ *
+ * The hook only answers. The values are put in force by the stores' apply hooks, which
+ * resolve the same order from the same inputs:
+ *
+ * ```tsx
+ * useApplyTextSize({ account: me?.text_size });
+ * useApplyContrast({ account: me?.contrast });
+ * ```
+ */
+export function useAccountAppearance(options: UseAccountAppearanceOptions): AccountAppearance {
+  const { account, device, setDevice, save, isDemo = false } = options;
+  const deviceTextSize = device.textSize;
+  const deviceContrast = device.contrast;
+  const accountTextSize = account?.text_size;
+  const accountContrast = account?.contrast;
+  const signedIn = account !== null && account !== undefined;
+  // By value, so a fresh `/auth/me` object with the same two fields changes nothing.
+  const resolved = useMemo(
+    () =>
+      resolveAccountAppearance(
+        { textSize: deviceTextSize, contrast: deviceContrast },
+        signedIn ? { text_size: accountTextSize, contrast: accountContrast } : undefined,
+      ),
+    [deviceTextSize, deviceContrast, signedIn, accountTextSize, accountContrast],
+  );
+  const write = useCallback(
+    (patch: AccountAppearancePatch) => {
+      if (isDemo || !signedIn) return Promise.resolve();
+      try {
+        return Promise.resolve(save(patch));
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    [save, isDemo, signedIn],
+  );
+  const pickTextSize = useCallback(
+    (size: TextSize) => {
+      setDevice({ textSize: size });
+      return write({ text_size: size });
+    },
+    [setDevice, write],
+  );
+  const pickContrast = useCallback(
+    (mode: ContrastMode) => {
+      setDevice({ contrast: mode });
+      return write({ contrast: mode });
+    },
+    [setDevice, write],
+  );
+  return { ...resolved, pickTextSize, pickContrast };
+}

package/src/settings/use-settings-route.ts

@@ -1,12 +1,11 @@
 import { useCallback, useEffect, useMemo } from "react";
 import { useLocation, useNavigate } from "react-router";
-import { useMediaQuery } from "../hooks/use-media-query";
-import { PHONE_QUERY } from "../components/ui";
+import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { normalizeSettingsBase, visibleSettingsGroups } from "./settings-catalogue";
 import type { SettingsEntry, SettingsGroup } from "./settings-catalogue";
 
 /**
- * Which layout the settings page is in. `"auto"` follows the screen ({@link PHONE_QUERY},
+ * Which layout the settings page is in. `"auto"` follows the screen (`usePhoneLayout()`,
  * as `Tabs` does); `"desktop"` / `"phone"` pin one — for a preview of both side by side,
  * where the window is one width.
  */
@@ -187,7 +186,7 @@ export function useSettingsRoute<G extends string>(options: UseSettingsRouteOpti
   const { groups, entries, basePath, defaultGroup, aliases, layout = "auto" } = options;
   const location = useLocation();
   const navigate = useNavigate();
-  const narrow = useMediaQuery(PHONE_QUERY, false);
+  const narrow = usePhoneLayout();
   const phone = layout === "phone" || (layout === "auto" && narrow);
   const base = normalizeSettingsBase(basePath);