@suphark/ui 0.11.2 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.13.0] — 2026-09-25
+
+### Added
+
+- **สเกลตัวอักษรตามบทบาท + ตอบสนองจอ** (ขอจาก Pi Done — บนมือถืออ่านเล็กเกินไป): คลาสใหม่ `text-title-lg` `text-title` `text-subtitle` `text-body` `text-caption` `text-label` ค่าเป็น **mobile-first แล้วแน่นขึ้นบนจอ ≥ 48rem** (body 16→15px, caption 14→13px, subtitle 17→16px) — เหตุผลเดียวกับที่ iOS ใช้ body 17px ส่วน macOS ใช้ 13px: มือถือถือห่างและใช้นิ้ว เดสก์ท็อปอ่านใกล้และชี้ด้วยเมาส์
+  - ทำได้โดย `@theme` ชี้ `--text-*` ไปที่ `--fs-*` แล้วเปลี่ยน `--fs-*` ใน media query — utility ยังเป็นคลาสเดียวและยังใช้ variant ได้ (`md:text-body`); **ไม่แตะ root font-size** ซึ่งจะทับค่าที่ผู้ใช้ตั้งไว้ในเบราว์เซอร์
+  - `text-xs … text-2xl` ยังใช้ได้เหมือนเดิม ไม่ใช่ breaking — แต่ `text-xs` (12px) ไม่ควรเป็นขนาดเนื้อหาอีกต่อไป
+  - `TYPOGRAPHY_ROLES` export จาก `@suphark/ui` เป็นแหล่งความจริงเดียวของตาราง (showcase `/design-system#tokens-typography` render จากค่านี้ ไม่เขียนซ้ำ)
+- **ความสูงขั้นต่ำของรายการเมนูบนอุปกรณ์สัมผัส**: `@media (pointer: coarse)` ตั้ง `min-height: 44px` ให้ `dropdown-menu-item` / `checkbox-item` / `radio-item` / `sub-trigger` / `select-item` / `command-item` — เดิมไม่มีความสูงเลย (`py-1` ≈ 26px) ต่ำกว่าเกณฑ์ Apple 44pt / Material 48dp; ใช้ `pointer: coarse` ไม่ใช่ความกว้างจอ เพราะหน้าต่างแคบบนเดสก์ท็อปยังใช้เมาส์
+- audit: กฎ `raw-text-scale` (warning, opt-in ด้วย `--semantic-text`) จับ `text-xs/text-sm/…` ที่ยังไม่ย้ายไป role class — ให้แอปทยอยย้ายทีละส่วนแล้วเปิดกฎกันถอยหลัง
+
+### Fixed
+
+- **`arbitrary-text` ของ audit ไม่เคยจับ `text-[0.8rem]`**: regex เดิม `\d+` ตามด้วยหน่วยทันที จึงข้ามค่าทศนิยมทั้งหมด (ทั้งใน `audit.mjs` และ `audit-tailwind-typography.mjs`) — แก้เป็น `\d*\.?\d+` แล้วพบของค้าง 15 จุดที่ผ่าน CI เขียวมาตลอด
+- แทนขนาด arbitrary 12 จุดด้วย role class: `text-[0.7rem]`/`text-[0.625rem]`/`text-[0.6rem]` → `text-label` (HeaderCrumb badge, SubNav, TopTabs, IconPicker, Initials, Stepper, SecretReveal, PrimarySecondaryText, showcase site-header) และข้อความ error ของ `FormFieldInput` → `text-caption` (บนมือถือขึ้นเป็น 14px อ่านออกและพ้นเกณฑ์ iOS zoom)
+  - ที่ยังเหลือคือใน `components/ui/**` (`button.tsx` `toggle.tsx` `calendar.tsx` = `text-[0.8rem]`) ซึ่งเป็นไฟล์ที่ shadcn generate — ห้ามแก้มือ รอรอบ regenerate
+
+## [0.12.0] — 2026-09-23
+
+### Added
+
+- **`OrganizationSwitcher` prop `itemAction(org)`** (ขอจาก Pi Auth) — ปุ่มท้ายแถวของแต่ละองค์กรในเมนู เช่น ⚙ "ตั้งค่าองค์กร" แบบ Vercel/Clerk: แอปส่ง element ที่กดได้มาเอง (พร้อม aria-label/title) component ห่อให้และ **หยุด click/keydown ไม่ให้สลับองค์กร**; คืน `null` = แถวนั้นไม่มีปุ่ม; มี `itemAction` แล้วองค์กรเดียวก็ยังมีเมนู (เดิมยุบเป็นป้ายเฉย ๆ เมื่อไม่มี `footer`) — เดิมแอปต้องวาง "ตั้งค่าองค์กร" เป็นรายการแยกใน `footer`
+- **`OrganizationSwitcher` prop `selectableActive`** (ขอจาก Pi Auth) — แถวที่ active กดได้ด้วย เรียก `onSwitch` เหมือนแถวอื่น (ค่าเริ่มต้น false = คงพฤติกรรมเดิม กดแล้วไม่ทำอะไร); สำหรับเมนูที่ "เลือก" = ไปหน้าของสิ่งนั้นไม่ใช่แค่สลับ เช่น crumb บัญชีของ Pi Auth ที่กดชื่อบัญชีแล้วเข้าคอนโซลบัญชีนั้น — ตัดรายการ "คอนโซลบัญชี" ท้ายเมนูที่ซ้ำช่องทางออกได้
+- showcase: หน้า `organization-switcher` ตัวแรกใส่ ⚙ ท้ายแถว; tests 2 กรณี (รวม 130)
+
 ## [0.11.2] — 2026-09-22
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "private": false,
   "type": "module",
   "description": "Design system กลางของ Suphark apps: shadcn/ui (base-nova, Base UI, Tailwind v4) + shared components + token/ฟอนต์ Noto Sans Thai Looped — ส่งเป็น source ให้แอป Next transpile เอง",

package/scripts/audit-tailwind-typography.mjs

@@ -3,7 +3,7 @@ import path from "node:path";
 
 /** โฟลเดอร์ที่จะตรวจ: argument แรก (ค่าเริ่มต้น `src`) — แอปปลายทางรันจาก node_modules ได้ */
 const SRC_DIR = path.resolve(process.cwd(), process.argv[2] ?? "src");
-const ARBITRARY_TEXT_REGEX = /text-\[\d+(?:px|rem|em)\]/g;
+const ARBITRARY_TEXT_REGEX = /text-\[\d*\.?\d+(?:px|rem|em)\]/g;
 
 /**
  * Recursively find all .ts and .tsx files in directory

package/scripts/audit.mjs

@@ -33,6 +33,8 @@ const STRICT = flags.has("--strict");
 const PALETTE = !flags.has("--no-palette");
 const SKIP_BASE_UI = flags.has("--no-base-ui");
 const IMPORTANT = flags.has("--important");
+// opt-in ระหว่างทยอยย้ายไป role class (text-body/text-caption/…) ทีละส่วนของแอป
+const SEMANTIC_TEXT = flags.has("--semantic-text");
 
 const SKIP_DIRS = new Set([
   "node_modules",
@@ -67,8 +69,9 @@ const RULES = [
   {
     id: "arbitrary-text",
     level: "error",
-    regex: /\btext-\[\d+(?:px|rem|em)\]/g,
-    message: "ห้าม text-[Npx] — ใช้ typography scale (text-xs … text-3xl) ตาม docs/design-system.md",
+    regex: /\btext-\[\d*\.?\d+(?:px|rem|em)\]/g,
+    message:
+      "ห้าม text-[Npx] — ใช้ role class (text-body, text-caption, text-label …) ตาม docs/design-system.md",
   },
   {
     id: "important",
@@ -77,6 +80,13 @@ const RULES = [
     message:
       "utility ที่ลงท้าย ! — แอปที่ scan แพ็กเกจผ่าน @source อาจไม่ generate class นี้ ปรับ specificity แทน",
   },
+  {
+    id: "raw-text-scale",
+    level: "warning",
+    regex: /(?<![\w-])(?:[a-z-]+:)*text-(?:xs|sm|base|lg|xl|[2-9]xl)(?![\w-])/g,
+    message:
+      "t-shirt size ไม่บอกบทบาทและตอบสนองจอไม่ได้ — ใช้ text-body / text-caption / text-label / text-subtitle / text-title",
+  },
   {
     id: "raw-palette",
     level: "warning",
@@ -134,6 +144,7 @@ for (const file of files) {
   for (const rule of RULES) {
     if (rule.id === "raw-palette" && !PALETTE) continue;
     if (rule.id === "important" && !IMPORTANT) continue;
+    if (rule.id === "raw-text-scale" && !SEMANTIC_TEXT) continue;
     for (let i = 0; i < masked.length; i++) {
       const line = masked[i] ?? "";
       rule.regex.lastIndex = 0;
@@ -202,6 +213,7 @@ for (const rule of RULES) {
   const n = byRule.get(rule.id) ?? 0;
   if (rule.id === "raw-palette" && !PALETTE) continue;
   if (rule.id === "important" && !IMPORTANT) continue;
+  if (rule.id === "raw-text-scale" && !SEMANTIC_TEXT) continue;
   console.log(
     `  ${n === 0 ? "✓" : rule.level === "error" || STRICT ? "✗" : "△"} ${rule.id.padEnd(15)} ${n}${n ? `  — ${rule.message}` : ""}`,
   );

package/src/components/app-shell/header-crumb.tsx

@@ -48,7 +48,7 @@ export function HeaderCrumb({
       {hint && <span className="hidden truncate text-muted-foreground md:inline">{hint}</span>}
       {/* badge ซ่อนบนจอแคบ (ที่เหลือให้ชื่อ) — เห็นได้ในเมนู/popover */}
       {badge && (
-        <span className="hidden shrink-0 rounded-md border bg-muted px-1.5 py-px font-medium text-[0.7rem] text-muted-foreground leading-4 sm:inline">
+        <span className="hidden shrink-0 rounded-md border bg-muted px-1.5 py-px font-medium text-label text-muted-foreground leading-4 sm:inline">
           {badge}
         </span>
       )}

package/src/components/app-shell/organization-switcher.tsx

@@ -40,6 +40,16 @@ export interface OrganizationSwitcherProps {
   hint?: (org: OrganizationOption) => ReactNode;
   /** slot ท้ายเมนู เช่น "สร้างองค์กร…", "จัดการองค์กร" */
   footer?: ReactNode;
+  /**
+   * ปุ่มท้ายแถวของแต่ละองค์กร เช่น ⚙ "ตั้งค่าองค์กร" (แบบ Vercel/Clerk) — คืน `null` เพื่อไม่แสดงในแถวนั้น
+   * คลิกแล้ว **ไม่สลับองค์กร** (component หยุด event ให้); ส่ง element ที่กดได้เองและใส่ aria-label/title ด้วย
+   */
+  itemAction?: (org: OrganizationOption) => ReactNode;
+  /**
+   * แถวที่ active กดได้ด้วย (เรียก `onSwitch` เหมือนแถวอื่น) — ค่าเริ่มต้น false = กดแล้วไม่ทำอะไร
+   * ใช้เมื่อ "เลือก" = ไปหน้าของสิ่งนั้น ไม่ใช่แค่สลับ (เช่น crumb บัญชี: กดชื่อบัญชี = เข้าคอนโซลบัญชีนั้น)
+   */
+  selectableActive?: boolean;
   /** `header` = HeaderCrumb ใน header (layout top); `sidebar` = ปุ่มเต็มกว้างใน `sidebarHeader` ของ AppShell */
   placement?: "header" | "sidebar";
   className?: string;
@@ -64,6 +74,8 @@ export function OrganizationSwitcher({
   heading,
   hint = (o) => (o.slug ? `/${o.slug}` : undefined),
   footer,
+  itemAction,
+  selectableActive = false,
   placement = "header",
   className,
 }: OrganizationSwitcherProps) {
@@ -72,7 +84,7 @@ export function OrganizationSwitcher({
   const [pending, start] = useTransition();
   const active = organizations.find((o) => o.id === activeId);
   const label = active ? active.name : (fallbackLabel ?? text.switcher?.choose ?? "เลือกองค์กร");
-  const single = organizations.length <= 1 && !footer;
+  const single = organizations.length <= 1 && !footer && !itemAction;
 
   const trigger =
     placement === "sidebar" ? (
@@ -102,7 +114,7 @@ export function OrganizationSwitcher({
   if (single) return trigger;
 
   function pick(id: string) {
-    if (id === activeId) return;
+    if (id === activeId && !selectableActive) return;
     start(async () => {
       await onSwitch(id);
       if (refresh) router.refresh();
@@ -119,6 +131,7 @@ export function OrganizationSwitcher({
           </DropdownMenuLabel>
           {organizations.map((o) => {
             const isActive = o.id === activeId;
+            const action = itemAction?.(o);
             return (
               <DropdownMenuItem
                 key={o.id}
@@ -134,6 +147,17 @@ export function OrganizationSwitcher({
                   )}
                 </span>
                 {isActive && <Check className="size-4 shrink-0" aria-hidden="true" />}
+                {action && (
+                  // ปุ่มท้ายแถว (⚙) — กดแล้วต้องไม่สลับองค์กร จึงหยุด event ไม่ให้ถึง onClick ของแถว
+                  // biome-ignore lint/a11y/noStaticElementInteractions: ตัวห่อไม่ใช่ปุ่ม — แอปส่ง element ที่กดได้มาเอง
+                  <span
+                    className="-my-1 -mr-1 flex shrink-0 items-center"
+                    onClick={(e) => e.stopPropagation()}
+                    onKeyDown={(e) => e.stopPropagation()}
+                  >
+                    {action}
+                  </span>
+                )}
               </DropdownMenuItem>
             );
           })}

package/src/components/app-shell/sub-nav.tsx

@@ -111,7 +111,7 @@ export function SubNav({
           >
             {/* หัวกลุ่มแบบ Clerk/Linear — ตัวเล็ก uppercase จางกว่ารายการ ให้แยกจากรายการได้ชัด (ขอจาก Pi Auth) */}
             {s.title && (
-              <p className="px-2 pt-1 pb-1 font-semibold text-[0.7rem] text-muted-foreground/70 uppercase tracking-wider">
+              <p className="px-2 pt-1 pb-1 font-semibold text-label text-muted-foreground/70 uppercase tracking-wider">
                 {s.title}
               </p>
             )}
@@ -132,7 +132,7 @@ export function SubNav({
                   {i.icon}
                   <span className="truncate">{i.title}</span>
                   {i.badge !== undefined && (
-                    <span className="ml-auto rounded-full bg-muted px-1.5 text-[0.7rem] text-muted-foreground">
+                    <span className="ml-auto rounded-full bg-muted px-1.5 text-label text-muted-foreground">
                       {i.badge}
                     </span>
                   )}

package/src/components/app-shell/top-tabs.tsx

@@ -56,7 +56,7 @@ export function TopTabs({ nav, className }: { nav: AppNavGroup[]; className?: st
             {tab.icon}
             <span className="truncate">{tab.title}</span>
             {tab.badge !== undefined && (
-              <span className="rounded-full bg-muted px-1.5 py-px font-medium text-[0.7rem] text-muted-foreground leading-4">
+              <span className="rounded-full bg-muted px-1.5 py-px font-medium text-label text-muted-foreground leading-4">
                 {tab.badge}
               </span>
             )}

package/src/components/design-system/sections/showcase-foundations.tsx

@@ -9,6 +9,7 @@ import {
   CardTitle,
 } from "@suphark/ui/components/ui/card";
 import { Kbd, KbdGroup } from "@suphark/ui/components/ui/kbd";
+import { TYPOGRAPHY_ROLES } from "@suphark/ui/lib/typography";
 import { AlignLeft, Check, Copy, Info, Palette, Type } from "lucide-react";
 import * as React from "react";
 
@@ -111,44 +112,16 @@ export function ShowcaseFoundations() {
     { name: "Chart 5 (Red/Rose)", class: "bg-chart-5 text-white", token: "var(--chart-5)" },
   ];
 
-  const typeScale = [
-    {
-      role: "Page Title",
-      className: "text-2xl font-bold tracking-tight",
-      sample: "Bidding Package Review & Award",
-      usage: "ชื่อหน้าหลักของแต่ละ Module ใน PageShell",
-    },
-    {
-      role: "Section Title",
-      className: "text-lg font-semibold tracking-normal",
-      sample: "Vendor Qualification & Price Breakdown",
-      usage: "หัวข้อหลักของ Card, Dialog, Sheet, หรือ Tabs panel",
-    },
-    {
-      role: "Subsection Title",
-      className: "text-base font-semibold",
-      sample: "Material Specification & BOQ Rates",
-      usage: "หัวข้อย่อยใน Form sections หรือ Card sub-blocks",
-    },
-    {
-      role: "Base Body",
-      className: "text-sm leading-normal",
-      sample: "All bids submitted before the deadline are subject to procurement committee review.",
-      usage: "เนื้อหาหลัก, Table row data, Description, Input labels",
-    },
-    {
-      role: "Caption / Metadata",
-      className: "text-xs text-muted-foreground",
-      sample: "Last modified by procurement.manager@company.com • 15 mins ago",
-      usage: "Helper text, timestamp, audit metadata, table header captions",
-    },
-    {
-      role: "Monospace / Numbers",
-      className: "font-mono text-xs text-foreground",
-      sample: "PO-2026-08-9941 / THB 14,850,200.00 / SHA-256",
-      usage: "Code identifiers, Document numbers, Financial decimals, Hashes",
-    },
-  ];
+  // ตัวอย่างข้อความของแต่ละบทบาท — ขนาด/ชื่อบทบาทมาจาก TYPOGRAPHY_ROLES (แหล่งเดียวกับ styles.css)
+  const samples: Record<string, string> = {
+    "text-title-lg": "Bidding Package Review & Award",
+    "text-title": "Vendor Qualification & Price Breakdown",
+    "text-subtitle": "Material Specification & BOQ Rates",
+    "text-body":
+      "All bids submitted before the deadline are subject to procurement committee review.",
+    "text-caption": "Last modified by procurement.manager@company.com • 15 mins ago",
+    "text-label": "PROCUREMENT STATUS",
+  };
 
   const spatialRules = [
     {
@@ -290,24 +263,28 @@ export function ShowcaseFoundations() {
 
         <Card>
           <CardContent className="p-0 divide-y divide-border">
-            {typeScale.map((item) => (
+            {TYPOGRAPHY_ROLES.map((item) => (
               <div
-                key={item.role}
+                key={item.className}
                 className="flex flex-col gap-2 p-4 transition-colors hover:bg-muted/30 lg:flex-row lg:items-center lg:justify-between"
               >
                 <div className="flex flex-col gap-1 w-full lg:w-1/3">
                   <div className="flex items-center gap-2">
-                    <span className="font-semibold text-xs text-foreground">{item.role}</span>
+                    <span className="font-semibold text-xs text-foreground">{item.name}</span>
                     <Badge variant="outline" className="text-xs font-mono py-0">
-                      {item.className.split(" ")[0]}
+                      {item.className}
                     </Badge>
                   </div>
-                  <code className="text-xs text-muted-foreground font-mono">{item.className}</code>
+                  <code className="text-xs text-muted-foreground font-mono">
+                    {item.mobile === item.desktop
+                      ? item.mobile
+                      : `${item.mobile} → ${item.desktop} (≥ 48rem)`}
+                  </code>
                   <p className="text-xs text-muted-foreground">{item.usage}</p>
                 </div>
                 <div className="w-full lg:w-2/3 pt-1 lg:pt-0">
                   <div className={`rounded-md bg-muted/40 p-3 border ${item.className}`}>
-                    {item.sample}
+                    {samples[item.className]}
                   </div>
                 </div>
               </div>

package/src/components/shared/form/form-field-input.tsx

@@ -205,7 +205,7 @@ function UniqueCheckInput<T extends FieldValues>({
         )}
       </InputGroup>
       {isDuplicate && (
-        <p className="mt-1 font-medium text-[0.8rem] text-destructive">{uniqueErrorMessage}</p>
+        <p className="mt-1 font-medium text-caption text-destructive">{uniqueErrorMessage}</p>
       )}
     </div>
   );
@@ -368,7 +368,7 @@ export function FormFieldInput<T extends FieldValues>({
             })()}
           </FormControl>
           {props.description && (
-            <p className="text-[0.8rem] text-muted-foreground">{props.description}</p>
+            <p className="text-caption text-muted-foreground">{props.description}</p>
           )}
           <FormMessage />
         </FormItem>

package/src/components/shared/icon-picker.tsx

@@ -116,7 +116,7 @@ export function IconPicker<T extends string = string>({
             <selected.icon className="size-5" aria-hidden="true" />
           </span>
           <div className="min-w-0">
-            <p className="font-semibold text-[0.625rem] text-muted-foreground/70 uppercase tracking-wider">
+            <p className="font-semibold text-label text-muted-foreground/70 uppercase tracking-wider">
               {text.preview}
             </p>
             <p className="truncate font-bold text-foreground text-xs">{labelOf(selected)}</p>

package/src/components/shared/initials.tsx

@@ -23,7 +23,7 @@ export function Initials({
     <Avatar className={cn("shrink-0", className)} {...props}>
       {src && <AvatarImage src={src} alt="" />}
       <AvatarFallback
-        className="text-[0.7rem] font-medium"
+        className="text-label font-medium"
         style={{ backgroundColor: `oklch(0.93 0.04 ${hue})`, color: `oklch(0.4 0.08 ${hue})` }}
       >
         {initialsOf(name)}

package/src/components/shared/navigation/stepper.tsx

@@ -58,7 +58,7 @@ export function Stepper({
                   {step.statusLabel && (
                     <StatusBadge
                       tone={TONE[step.status]}
-                      className="w-fit px-1.5 py-0 font-normal text-[0.7rem] leading-4"
+                      className="w-fit px-1.5 py-0 font-normal text-label leading-4"
                     >
                       {step.statusLabel}
                     </StatusBadge>

package/src/components/shared/secret-reveal.tsx

@@ -28,7 +28,7 @@ export function SecretReveal({
       <dl className="flex flex-col gap-2">
         {Object.entries(values).map(([k, v]) => (
           <div key={k} className="flex flex-col gap-1">
-            <dt className="font-mono text-[0.7rem] text-muted-foreground">{k}</dt>
+            <dt className="font-mono text-label text-muted-foreground">{k}</dt>
             <dd className="flex items-center gap-2">
               <code className="min-w-0 flex-1 break-all rounded-md bg-background/70 px-2 py-1 font-mono text-xs">
                 {v}

package/src/components/shared/text/primary-secondary-text.tsx

@@ -157,7 +157,7 @@ export function PrimarySecondaryText({
     if (listStyle === "bullet") {
       return (
         <div key={idx} className="flex items-start gap-2">
-          <span className="mt-1.5 text-[0.6rem] text-muted-foreground leading-none">•</span>
+          <span className="mt-1.5 text-label text-muted-foreground leading-none">•</span>
           {content}
         </div>
       );

package/src/index.ts

@@ -240,4 +240,8 @@ export {
   statusColorThemes,
   TAILWIND_COLORS,
 } from "./lib/status-colors";
+export {
+  TYPOGRAPHY_ROLES,
+  type TypographyRole,
+} from "./lib/typography";
 export { cn } from "./lib/utils";

package/src/lib/typography.ts

@@ -0,0 +1,64 @@
+/**
+ * สเกลตัวอักษร "ตามบทบาท" — แหล่งความจริงเดียวของ type scale
+ *
+ * ค่าจริงอยู่ใน `styles.css` (@theme → `--text-*` ชี้ไปที่ `--fs-*` เพื่อให้เปลี่ยนตาม
+ * breakpoint ได้) ไฟล์นี้คือรายการบทบาทสำหรับเอกสาร/showcase จะได้ไม่เขียนสเกลซ้ำสองที่
+ * แล้วคลาดกันภายหลัง — เพิ่มบทบาทใหม่ต้องแก้ทั้งสองไฟล์คู่กันเสมอ
+ */
+export type TypographyRole = {
+  /** ชื่อคลาสที่ใช้จริง เช่น `text-body` */
+  className: string;
+  /** ชื่อบทบาทสำหรับเอกสาร */
+  name: string;
+  /** ขนาดบนมือถือ (< 48rem) */
+  mobile: string;
+  /** ขนาดบนจอกว้าง (≥ 48rem) — ว่าง = เท่ากับมือถือ */
+  desktop: string;
+  /** ใช้กับอะไร */
+  usage: string;
+};
+
+export const TYPOGRAPHY_ROLES: readonly TypographyRole[] = [
+  {
+    className: "text-title-lg",
+    name: "Page Title",
+    mobile: "24px",
+    desktop: "24px",
+    usage: "ชื่อหน้าหลักของแต่ละ Module ใน PageShell",
+  },
+  {
+    className: "text-title",
+    name: "Section Title",
+    mobile: "18px",
+    desktop: "18px",
+    usage: "หัวข้อหลักของ Card, Dialog, Sheet, Tabs panel",
+  },
+  {
+    className: "text-subtitle",
+    name: "Subsection Title",
+    mobile: "17px",
+    desktop: "16px",
+    usage: "หัวข้อย่อยใน Form section หรือ Card sub-block",
+  },
+  {
+    className: "text-body",
+    name: "Body",
+    mobile: "16px",
+    desktop: "15px",
+    usage: "เนื้อหาหลัก, ชื่อรายการ, Table row, ข้อความใน Dialog",
+  },
+  {
+    className: "text-caption",
+    name: "Caption / Metadata",
+    mobile: "14px",
+    desktop: "13px",
+    usage: "คำอธิบายรอง, timestamp, metadata chip, ตัวนับ",
+  },
+  {
+    className: "text-label",
+    name: "Field Label",
+    mobile: "12px",
+    desktop: "12px",
+    usage: "ป้ายชื่อฟิลด์ (มักคู่กับ uppercase/font-bold), overline",
+  },
+] as const;

package/src/styles.css

@@ -68,6 +68,58 @@
   --radius-xl: calc(var(--radius) + 4px);
 }
 
+/*
+ * Typography by role, not by t-shirt size.
+ *
+ * Each token points at a `--fs-*` variable rather than a literal, so the value
+ * can change per breakpoint while the generated utility stays one class
+ * (`text-body`, and its variants such as `md:text-body`, keep working).
+ * Values below are mobile-first and get *denser* on wide screens: a phone is
+ * held further away and tapped, a desktop is read up close with a mouse — the
+ * same reason iOS uses a 17px body where macOS uses 13px.
+ *
+ * Apps should reach for these roles instead of `text-xs`/`text-sm`, which
+ * carry no meaning and cannot respond to the viewport.
+ */
+@theme {
+  --text-title-lg: var(--fs-title-lg);
+  --text-title-lg--line-height: var(--lh-title-lg);
+  --text-title: var(--fs-title);
+  --text-title--line-height: var(--lh-title);
+  --text-subtitle: var(--fs-subtitle);
+  --text-subtitle--line-height: var(--lh-subtitle);
+  --text-body: var(--fs-body);
+  --text-body--line-height: var(--lh-body);
+  --text-caption: var(--fs-caption);
+  --text-caption--line-height: var(--lh-caption);
+  --text-label: var(--fs-label);
+  --text-label--line-height: var(--lh-label);
+}
+
+:root {
+  /* Phones and small tablets. */
+  --fs-title-lg: 1.5rem; /* 24px */
+  --lh-title-lg: 1.25;
+  --fs-title: 1.125rem; /* 18px */
+  --lh-title: 1.3;
+  --fs-subtitle: 1.0625rem; /* 17px */
+  --lh-subtitle: 1.4;
+  --fs-body: 1rem; /* 16px */
+  --lh-body: 1.45;
+  --fs-caption: 0.875rem; /* 14px */
+  --lh-caption: 1.4;
+  --fs-label: 0.75rem; /* 12px */
+  --lh-label: 1.35;
+}
+
+@media (width >= 48rem) {
+  :root {
+    --fs-subtitle: 1rem; /* 16px */
+    --fs-body: 0.9375rem; /* 15px */
+    --fs-caption: 0.8125rem; /* 13px */
+  }
+}
+
 :root {
   --radius: 0.625rem;
   --background: oklch(1 0 0);
@@ -230,6 +282,23 @@ body,
   background-color: color-mix(in oklch, var(--muted), var(--foreground) 14%);
 }
 
+/*
+ * นิ้วไม่ใช่เมาส์: รายการในเมนู/ดรอปดาวน์ไม่ได้ตั้งความสูงไว้เลย (`py-1` ≈ 26px) ซึ่งต่ำกว่าเกณฑ์
+ * Apple 44pt / Material 48dp มาก บนอุปกรณ์สัมผัสจึงยกพื้นความสูงให้ — ใช้ `pointer: coarse`
+ * (คือ "นิ้ว") ไม่ใช่ความกว้างจอ เพราะหน้าต่างแคบบนเดสก์ท็อปยังชี้ด้วยเมาส์อยู่
+ * override ที่นี่แบบไม่อยู่ใน layer จึงชนะ utility โดยไม่แก้ component ของ shadcn
+ */
+@media (pointer: coarse) {
+  [data-slot="dropdown-menu-item"],
+  [data-slot="dropdown-menu-checkbox-item"],
+  [data-slot="dropdown-menu-radio-item"],
+  [data-slot="dropdown-menu-sub-trigger"],
+  [data-slot="select-item"],
+  [data-slot="command-item"] {
+    min-height: 2.75rem; /* 44px */
+  }
+}
+
 /* ผู้ใช้ตั้ง "ลดการเคลื่อนไหว" → ตัด animation/transition ของทุก component (tw-animate, animate-spin, dialog zoom …) */
 @media (prefers-reduced-motion: reduce) {
   *,