@nim.zone/ui 0.6.0

package/src/lib/calendars.ts

@@ -0,0 +1,227 @@
+/**
+ * Calendar arithmetic for the two systems the kit draws: Gregorian and
+ * Jalali (Solar Hijri).
+ *
+ * There is no conversion table and no leap-year rule in this file, because the
+ * platform already ships one: `Intl.DateTimeFormat` with `-u-ca-persian` is
+ * ICU's Persian calendar, and it is the same implementation a browser uses to
+ * label a date anywhere else. So the direction that is hard — Gregorian to
+ * Jalali — is asked of `Intl`, and the direction that is easy — Jalali back to
+ * Gregorian — is a close estimate corrected against that same answer until it
+ * round-trips. Every value this module returns has therefore been checked
+ * against the platform's own calendar rather than against a table that has to
+ * be maintained here and goes wrong in 1403 or 2049.
+ *
+ * The kit's value type never changes: an `IsoDate` is always the Gregorian
+ * `YYYY-MM-DD`, in every calendar system. What the viewer reads and what the
+ * API receives are different questions, and only the first one has a calendar.
+ */
+
+/** ISO `YYYY-MM-DD`, Gregorian, always. The kit never invents a date type. */
+export type IsoDate = string
+
+/** The calendar a grid is drawn in — never what a value is stored in. */
+export type CalendarSystem = 'gregory' | 'persian'
+
+export interface CalendarParts {
+  day: number
+  month: number
+  year: number
+}
+
+const DAY_MS = 86_400_000
+
+/** 1 Farvardin 1 — the Solar Hijri epoch, as a Gregorian UTC timestamp. */
+const PERSIAN_EPOCH_MS = Date.UTC(622, 2, 22)
+const PERSIAN_YEAR_DAYS = 365.2422
+
+export const isoOf = (date: Date): IsoDate => date.toISOString().slice(0, 10)
+export const dateOf = (value: IsoDate): Date => new Date(`${value}T00:00:00Z`)
+export const todayIso = (): IsoDate => isoOf(new Date())
+
+/**
+ * Latin digits and the Persian calendar, regardless of the interface locale:
+ * this formatter is read by the code, not by a person. What the viewer sees is
+ * formatted separately, in their own locale.
+ */
+const PERSIAN_PARTS = new Intl.DateTimeFormat('en-u-ca-persian-nu-latn', {
+  day: 'numeric',
+  month: 'numeric',
+  timeZone: 'UTC',
+  year: 'numeric',
+})
+
+/** The calendar fields a viewer of `system` would read off this instant. */
+export function partsOf(value: IsoDate, system: CalendarSystem): CalendarParts {
+  const date = dateOf(value)
+  if (system === 'gregory') {
+    return { day: date.getUTCDate(), month: date.getUTCMonth() + 1, year: date.getUTCFullYear() }
+  }
+
+  const parts = PERSIAN_PARTS.formatToParts(date)
+  const field = (type: string) => Number(parts.find((part) => part.type === type)?.value ?? '0')
+  // `year` comes back as an era year; the Persian calendar has one era in use,
+  // so it is the year. `relatedYear` would be the Gregorian one — not wanted.
+  return { day: field('day'), month: field('month'), year: field('year') }
+}
+
+const rank = (parts: CalendarParts) => parts.year * 10_000 + parts.month * 100 + parts.day
+
+/**
+ * The Gregorian date on which `parts` falls in `system`.
+ *
+ * For Jalali this starts from the mean-year estimate and walks to the answer,
+ * comparing against `partsOf` — which is ICU. The estimate is never more than
+ * a few days out, and the loop is bounded, so a bad input fails by returning
+ * its best effort rather than by spinning.
+ */
+export function fromParts(parts: CalendarParts, system: CalendarSystem): IsoDate {
+  if (system === 'gregory') {
+    return isoOf(new Date(Date.UTC(parts.year, parts.month - 1, parts.day)))
+  }
+
+  const estimateDays =
+    Math.floor((parts.year - 1) * PERSIAN_YEAR_DAYS) +
+    (parts.month <= 7 ? (parts.month - 1) * 31 : 186 + (parts.month - 7) * 30) +
+    parts.day -
+    1
+  let cursor = new Date(PERSIAN_EPOCH_MS + estimateDays * DAY_MS)
+  const target = rank(parts)
+
+  for (let step = 0; step < 40; step += 1) {
+    const current = partsOf(isoOf(cursor), 'persian')
+    const currentRank = rank(current)
+    if (currentRank === target) break
+    // Convert the disagreement into a day count: years and months are worth
+    // roughly what they are worth, and the remainder is walked one day at a
+    // time. In practice this lands on the second pass.
+    const drift =
+      (parts.year - current.year) * 365 +
+      (parts.month - current.month) * 30 +
+      (parts.day - current.day)
+    cursor = new Date(cursor.getTime() + (drift === 0 ? (currentRank < target ? 1 : -1) : drift) * DAY_MS)
+  }
+
+  return isoOf(cursor)
+}
+
+/** The first day of the month `value` falls in, in `system`. */
+export function startOfMonth(value: IsoDate, system: CalendarSystem): IsoDate {
+  const parts = partsOf(value, system)
+  return fromParts({ ...parts, day: 1 }, system)
+}
+
+/** `delta` months on from `value`, clamped into the target month's length. */
+export function addMonths(value: IsoDate, delta: number, system: CalendarSystem): IsoDate {
+  const parts = partsOf(value, system)
+  const zero = parts.year * 12 + (parts.month - 1) + delta
+  const year = Math.floor(zero / 12)
+  const month = (zero % 12) + 1
+  const length = monthLength(year, month, system)
+  return fromParts({ day: Math.min(parts.day, length), month, year }, system)
+}
+
+/**
+ * How many days that month holds — measured, not tabulated. The distance to
+ * the first of the next month is the length, whatever the leap rule says, so
+ * an Esfand of 30 days needs no special case here.
+ */
+export function monthLength(year: number, month: number, system: CalendarSystem): number {
+  const first = dateOf(fromParts({ day: 1, month, year }, system)).getTime()
+  const nextMonth = month === 12 ? 1 : month + 1
+  const nextYear = month === 12 ? year + 1 : year
+  const next = dateOf(fromParts({ day: 1, month: nextMonth, year: nextYear }, system)).getTime()
+  return Math.round((next - first) / DAY_MS)
+}
+
+export const addDays = (value: IsoDate, days: number): IsoDate =>
+  isoOf(new Date(dateOf(value).getTime() + days * DAY_MS))
+
+/** 0 = Sunday. The week's shape is the same fact in every calendar. */
+export const weekdayOf = (value: IsoDate): number => dateOf(value).getUTCDay()
+
+/**
+ * The locale tag that puts `Intl` into `system`. A `-u-ca-` extension already
+ * on the tag wins, so an app asking for `fa-IR-u-ca-gregory` keeps it.
+ */
+export function localeFor(locale: string | undefined, system: CalendarSystem): string {
+  const base = locale ?? 'en'
+  if (base.includes('-u-ca-') || base.includes('-u-')) return base
+  return `${base}-u-ca-${system}`
+}
+
+/**
+ * The calendar an `fa` reader expects. Persian interfaces run on the Jalali
+ * calendar; everything else this kit ships in runs on the Gregorian one.
+ */
+export const defaultSystem = (locale: string | undefined): CalendarSystem =>
+  locale?.startsWith('fa') ? 'persian' : 'gregory'
+
+/** Persian weeks begin on Saturday; the Gregorian ones here on Monday. */
+export const defaultWeekStart = (system: CalendarSystem): number => (system === 'persian' ? 6 : 1)
+
+const DIGIT_CACHE = new Map<string, string[]>()
+
+/** The locale's own ten digits, so `1404` can be written as `۱۴۰۴`. */
+function digitsOf(locale: string | undefined): string[] {
+  const key = locale ?? 'en'
+  const cached = DIGIT_CACHE.get(key)
+  if (cached) return cached
+  const format = new Intl.NumberFormat(key, { useGrouping: false })
+  const digits = Array.from({ length: 10 }, (_, digit) => format.format(digit))
+  DIGIT_CACHE.set(key, digits)
+  return digits
+}
+
+/**
+ * `۱۴۰۴/۰۶/۰۱` — year first, zero-padded, in the locale's digits.
+ *
+ * Deliberately not `Intl`'s numeric pattern, which would give `۰۱/۰۶/۱۴۰۴ ه.ش`
+ * under an English locale on the Jalali calendar: field order and an era
+ * suffix that no Iranian writes and this module's parser cannot read back. A
+ * Jalali date is written biggest-unit-first everywhere it is written at all,
+ * so `formatNumeric` and `parseNumeric` agree by construction.
+ */
+export function formatNumeric(value: IsoDate, locale: string | undefined, system: CalendarSystem): string {
+  const parts = partsOf(value, system)
+  const digits = digitsOf(locale)
+  const write = (number: number, width = 1) =>
+    String(number)
+      .padStart(width, '0')
+      .replace(/\d/g, (digit) => digits[Number(digit)])
+  return `${write(parts.year)}/${write(parts.month, 2)}/${write(parts.day, 2)}`
+}
+
+/**
+ * Reads `1404/06/01`, `۱۴۰۴-۰۶-۰۱`, or anything else with three numbers in
+ * year, month, day order. Returns null rather than guessing at two.
+ */
+export function parseNumeric(input: string, system: CalendarSystem): IsoDate | null {
+  const ascii = toAsciiDigits(input)
+  const numbers = ascii.match(/\d+/g)
+  if (!numbers || numbers.length < 3) return null
+  const [year, month, day] = numbers.map(Number)
+  if (month < 1 || month > 12 || day < 1) return null
+  if (day > monthLength(year, month, system)) return null
+  const value = fromParts({ day, month, year }, system)
+  // The round trip is the validation: anything ICU disagrees with is rejected
+  // rather than silently snapped to a neighbouring day.
+  const back = partsOf(value, system)
+  return back.year === year && back.month === month && back.day === day ? value : null
+}
+
+/**
+ * Persian (۰–۹) and Arabic-Indic (٠–٩) digits to ASCII, separators kept — a
+ * Persian keyboard types ۱۴۰۴/۰۶/۰۱ and the parser above wants 1404/06/01.
+ * `lib/countries.ts` has the digits-only twin, which phone entry needs.
+ */
+function toAsciiDigits(input: string): string {
+  let output = ''
+  for (const character of input) {
+    const code = character.codePointAt(0) ?? 0
+    if (code >= 0x06f0 && code <= 0x06f9) output += String.fromCodePoint(code - 0x06f0 + 0x30)
+    else if (code >= 0x0660 && code <= 0x0669) output += String.fromCodePoint(code - 0x0660 + 0x30)
+    else output += character
+  }
+  return output
+}

package/src/lib/cn.ts

@@ -0,0 +1,8 @@
+/**
+ * The kit's only class-name helper. nim components compose a small, fixed set
+ * of semantic class names, so a full `clsx`-style dependency would buy nothing
+ * that this does not already do.
+ */
+export type ClassValue = string | false | null | undefined
+
+export const cn = (...values: ClassValue[]) => values.filter(Boolean).join(' ')

package/src/lib/countries.ts

@@ -0,0 +1,110 @@
+/**
+ * Dialling codes for every ISO 3166-1 country and territory.
+ *
+ * The table carries the two things a name cannot be derived from — the ISO
+ * code and the calling code — and nothing else. The display name comes from
+ * `Intl.DisplayNames` in the viewer's own locale, so a Persian interface lists
+ * «آلمان» and an English one lists "Germany" without a second column to keep
+ * in sync, and the flag is derived from the ISO code's regional indicators
+ * rather than shipped as 250 images.
+ */
+
+/** `ISO2:dialling code`, packed so the source stays reviewable in one screen. */
+const TABLE =
+  'AD:376 AE:971 AF:93 AG:1268 AI:1264 AL:355 AM:374 AO:244 AQ:672 AR:54 AS:1684 AT:43 AU:61 ' +
+  'AW:297 AX:358 AZ:994 BA:387 BB:1246 BD:880 BE:32 BF:226 BG:359 BH:973 BI:257 BJ:229 BL:590 ' +
+  'BM:1441 BN:673 BO:591 BQ:599 BR:55 BS:1242 BT:975 BW:267 BY:375 BZ:501 CA:1 CC:61 CD:243 ' +
+  'CF:236 CG:242 CH:41 CI:225 CK:682 CL:56 CM:237 CN:86 CO:57 CR:506 CU:53 CV:238 CW:599 CX:61 ' +
+  'CY:357 CZ:420 DE:49 DJ:253 DK:45 DM:1767 DO:1809 DZ:213 EC:593 EE:372 EG:20 EH:212 ER:291 ' +
+  'ES:34 ET:251 FI:358 FJ:679 FK:500 FM:691 FO:298 FR:33 GA:241 GB:44 GD:1473 GE:995 GF:594 ' +
+  'GG:44 GH:233 GI:350 GL:299 GM:220 GN:224 GP:590 GQ:240 GR:30 GT:502 GU:1671 GW:245 GY:592 ' +
+  'HK:852 HN:504 HR:385 HT:509 HU:36 ID:62 IE:353 IL:972 IM:44 IN:91 IO:246 IQ:964 IR:98 IS:354 ' +
+  'IT:39 JE:44 JM:1876 JO:962 JP:81 KE:254 KG:996 KH:855 KI:686 KM:269 KN:1869 KP:850 KR:82 ' +
+  'KW:965 KY:1345 KZ:7 LA:856 LB:961 LC:1758 LI:423 LK:94 LR:231 LS:266 LT:370 LU:352 LV:371 ' +
+  'LY:218 MA:212 MC:377 MD:373 ME:382 MF:590 MG:261 MH:692 MK:389 ML:223 MM:95 MN:976 MO:853 ' +
+  'MP:1670 MQ:596 MR:222 MS:1664 MT:356 MU:230 MV:960 MW:265 MX:52 MY:60 MZ:258 NA:264 NC:687 ' +
+  'NE:227 NF:672 NG:234 NI:505 NL:31 NO:47 NP:977 NR:674 NU:683 NZ:64 OM:968 PA:507 PE:51 ' +
+  'PF:689 PG:675 PH:63 PK:92 PL:48 PM:508 PR:1787 PS:970 PT:351 PW:680 PY:595 QA:974 RE:262 ' +
+  'RO:40 RS:381 RU:7 RW:250 SA:966 SB:677 SC:248 SD:249 SE:46 SG:65 SH:290 SI:386 SJ:47 SK:421 ' +
+  'SL:232 SM:378 SN:221 SO:252 SR:597 SS:211 ST:239 SV:503 SX:1721 SY:963 SZ:268 TC:1649 ' +
+  'TD:235 TG:228 TH:66 TJ:992 TK:690 TL:670 TM:993 TN:216 TO:676 TR:90 TT:1868 TV:688 TW:886 ' +
+  'TZ:255 UA:380 UG:256 US:1 UY:598 UZ:998 VA:39 VC:1784 VE:58 VG:1284 VI:1340 VN:84 VU:678 ' +
+  'WF:681 WS:685 YE:967 YT:262 ZA:27 ZM:260 ZW:263'
+
+export interface Country {
+  /** Calling code without the plus: `98`, `1`, `44`. */
+  dial: string
+  /** Regional-indicator flag, derived from the ISO code. */
+  flag: string
+  /** ISO 3166-1 alpha-2, uppercase. */
+  iso2: string
+}
+
+/** 🇮🇷 from `IR`: two regional indicator symbols, no image asset involved. */
+function flagOf(iso2: string): string {
+  return String.fromCodePoint(...[...iso2].map((letter) => 0x1f1e6 + letter.charCodeAt(0) - 65))
+}
+
+export const COUNTRIES: Country[] = TABLE.split(' ').map((entry) => {
+  const [iso2, dial] = entry.split(':')
+  return { dial, flag: flagOf(iso2), iso2 }
+})
+
+const BY_ISO2 = new Map(COUNTRIES.map((country) => [country.iso2, country]))
+
+export function countryByIso2(iso2: string): Country | undefined {
+  return BY_ISO2.get(iso2.toUpperCase())
+}
+
+/**
+ * The country a `+…` number belongs to. Longest code wins, so `+1268`
+ * (Antigua) is not read as `+1` (United States).
+ */
+export function countryByDial(e164: string): Country | undefined {
+  const digits = e164.replace(/\D/g, '')
+  let match: Country | undefined
+  for (const country of COUNTRIES) {
+    if (!digits.startsWith(country.dial)) continue
+    if (!match || country.dial.length > match.dial.length) match = country
+  }
+  return match
+}
+
+/**
+ * Country names in `locale`, memoised per locale — building an
+ * `Intl.DisplayNames` is not free and a picker asks for every name on each
+ * keystroke.
+ */
+const NAME_CACHE = new Map<string, (iso2: string) => string>()
+
+export function countryNamer(locale: string): (iso2: string) => string {
+  const cached = NAME_CACHE.get(locale)
+  if (cached) return cached
+
+  let lookup: (iso2: string) => string
+  try {
+    const display = new Intl.DisplayNames([locale], { type: 'region' })
+    lookup = (iso2) => display.of(iso2) ?? iso2
+  } catch {
+    lookup = (iso2) => iso2
+  }
+  NAME_CACHE.set(locale, lookup)
+  return lookup
+}
+
+/**
+ * Persian (۰–۹) and Arabic-Indic (٠–٩) digits to ASCII, everything else
+ * dropped. Every phone and code field in the kit runs input through this: a
+ * Persian keyboard types ۰۹۱۲…, and a number the viewer can read has to reach
+ * the API as `+98912…`.
+ */
+export function toAsciiDigits(input: string): string {
+  let output = ''
+  for (const character of input) {
+    const code = character.codePointAt(0) ?? 0
+    if (code >= 0x06f0 && code <= 0x06f9) output += String.fromCodePoint(code - 0x06f0 + 0x30)
+    else if (code >= 0x0660 && code <= 0x0669) output += String.fromCodePoint(code - 0x0660 + 0x30)
+    else if (character >= '0' && character <= '9') output += character
+  }
+  return output
+}

package/src/lib/use-anchor.ts

@@ -0,0 +1,92 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import type { RefObject } from 'react'
+
+export interface AnchorPosition {
+  left: number
+  top: number
+}
+
+export interface UseAnchorOptions {
+  /** Called when the viewer asks to dismiss: Escape, or a click outside. */
+  onDismiss: () => void
+  open: boolean
+}
+
+/**
+ * Anchored overlay placement, shared by Menu and Popover.
+ *
+ * Deliberately small: nim does not ship a floating-element engine. It places
+ * the panel under the trigger, flips it above when the space below cannot hold
+ * it, and clamps it inside the viewport. Anything needing collision detection
+ * against scroll containers wants a real positioning library, not this.
+ *
+ * It also owns the two dismissals every overlay must honour and hand-rolled
+ * ones always forget: Escape, and a pointer landing outside both elements.
+ */
+export function useAnchor<T extends HTMLElement, P extends HTMLElement>(
+  triggerRef: RefObject<T | null>,
+  panelRef: RefObject<P | null>,
+  { onDismiss, open }: UseAnchorOptions,
+) {
+  const [position, setPosition] = useState<AnchorPosition>({ left: 0, top: 0 })
+  const restoreRef = useRef<HTMLElement | null>(null)
+
+  const place = useCallback(() => {
+    const trigger = triggerRef.current
+    const panel = panelRef.current
+    if (!trigger || !panel) return
+
+    const anchor = trigger.getBoundingClientRect()
+    const { height, width } = panel.getBoundingClientRect()
+    const gap = 4
+    const margin = 8
+    const rtl = getComputedStyle(trigger).direction === 'rtl'
+
+    const below = anchor.bottom + gap
+    const flip = below + height > window.innerHeight && anchor.top - gap - height > 0
+    const top = flip ? anchor.top - gap - height : below
+
+    const preferred = rtl ? anchor.right - width : anchor.left
+    const left = Math.min(Math.max(preferred, margin), window.innerWidth - width - margin)
+
+    setPosition({ left, top })
+  }, [panelRef, triggerRef])
+
+  useLayoutEffect(() => {
+    if (!open) return
+    place()
+  }, [open, place])
+
+  useEffect(() => {
+    if (!open) return
+
+    restoreRef.current = document.activeElement as HTMLElement | null
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.stopPropagation()
+        onDismiss()
+      }
+    }
+    const onPointerDown = (event: PointerEvent) => {
+      const target = event.target as Node
+      if (panelRef.current?.contains(target) || triggerRef.current?.contains(target)) return
+      onDismiss()
+    }
+
+    window.addEventListener('keydown', onKeyDown)
+    window.addEventListener('pointerdown', onPointerDown)
+    window.addEventListener('resize', place)
+    window.addEventListener('scroll', place, true)
+
+    return () => {
+      window.removeEventListener('keydown', onKeyDown)
+      window.removeEventListener('pointerdown', onPointerDown)
+      window.removeEventListener('resize', place)
+      window.removeEventListener('scroll', place, true)
+      restoreRef.current?.focus?.()
+    }
+  }, [onDismiss, open, panelRef, place, triggerRef])
+
+  return position
+}

package/src/theme/colorways/coral.css

@@ -0,0 +1,62 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   COLOURWAY · CORAL  —  warm cream, coral signal
+
+   Vlora's palette, carried over from `vlora-app/src/theme/tokens.css` so an
+   app on it keeps its exact appearance. Its neutral hierarchy is inverted from
+   the paper set's: the canvas is the tinted warm off-white and surfaces are
+   pure white, which is what makes cards read as raised without a heavy border.
+
+   Selected with `data-nim-colorway="coral"`.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+[data-nim-colorway='coral'] {
+  /* Brand anchors, kept as their own names so the colourway stays readable
+     against the original Vlora token file. */
+  --vlora-coral: #d97757;
+  --vlora-crail: #c15f3c;
+  --vlora-cloudy: #b0aea5;
+  --vlora-slate: #131314;
+
+  --nim-canvas: light-dark(#faf9f6, #1e1d1b);
+  --nim-canvas-sunken: light-dark(#f5f4f0, #131314);
+  --nim-surface: light-dark(#ffffff, #2e2d2b);
+  --nim-surface-raised: light-dark(#ffffff, #43413e);
+  /* Was equal to `surface` in dark, which left a hovered row and a muted card
+     indistinguishable from the card under them. */
+  --nim-surface-muted: light-dark(#f5f4f0, #383634);
+  --nim-scrim: light-dark(rgba(19, 19, 20, 0.52), rgba(19, 19, 20, 0.64));
+
+  --nim-ink: light-dark(#131314, #f4f3ee);
+  --nim-ink-secondary: light-dark(#6b6965, #d4d2ca);
+  --nim-ink-tertiary: light-dark(#b0aea5, #8a8880);
+  --nim-ink-inverse: light-dark(#faf9f5, #131314);
+  --nim-on-accent: light-dark(#ffffff, #ffffff);
+
+  /* Structure here comes from surface and shadow, so borders stay quiet —
+     quieter than the paper set's, by design. */
+  --nim-line: light-dark(rgba(19, 19, 20, 0.1), rgba(255, 255, 255, 0.16));
+  --nim-line-soft: light-dark(rgba(19, 19, 20, 0.06), rgba(255, 255, 255, 0.1));
+  --nim-line-strong: light-dark(rgba(19, 19, 20, 0.18), rgba(255, 255, 255, 0.3));
+
+  --nim-accent: light-dark(#d97757, #e0855f);
+  --nim-accent-hover: light-dark(#cf6a49, #e8906b);
+  --nim-accent-strong: light-dark(#c15f3c, #d97757);
+  --nim-accent-soft: light-dark(rgba(217, 119, 87, 0.12), rgba(224, 133, 95, 0.15));
+  --nim-accent-line: light-dark(rgba(217, 119, 87, 0.24), rgba(224, 133, 95, 0.28));
+
+  --nim-success: light-dark(#2f8f5b, #6cc292);
+  --nim-success-soft: light-dark(rgba(47, 143, 91, 0.12), rgba(108, 194, 146, 0.14));
+  --nim-warning: light-dark(#b07a1f, #d9a94f);
+  --nim-warning-soft: light-dark(rgba(215, 154, 43, 0.14), rgba(217, 169, 79, 0.14));
+  --nim-danger: light-dark(#c0492f, #e0796a);
+  --nim-danger-hover: light-dark(#ab4029, #e88a7c);
+  --nim-danger-soft: light-dark(rgba(216, 92, 69, 0.12), rgba(224, 121, 106, 0.14));
+  --nim-info: light-dark(#4a6b80, #90b2c6);
+  --nim-info-soft: light-dark(rgba(74, 107, 128, 0.1), rgba(144, 178, 198, 0.12));
+
+  /* A soft shadow tinted at 36% of a colour barely darker than the canvas did
+     nothing at all in dark. Dark elevation is true black, and deeper. */
+  --nim-shadow-tint-sm: light-dark(rgba(19, 19, 20, 0.05), rgba(0, 0, 0, 0.44));
+  --nim-shadow-tint-md: light-dark(rgba(19, 19, 20, 0.08), rgba(0, 0, 0, 0.52));
+  --nim-shadow-tint-lg: light-dark(rgba(19, 19, 20, 0.1), rgba(0, 0, 0, 0.6));
+}

package/src/theme/colorways/oxblood.css

@@ -0,0 +1,23 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   COLOURWAY · OXBLOOD  —  the same paper, dressed for law
+
+   Deeper than vermilion and shifted toward wine: the wax-seal red of legal
+   tradition. Darker, cooler and lower in chroma, it reads as institutional
+   permanence rather than editorial urgency, while keeping the same role.
+
+   Six declarations, because that is genuinely all that separates it from
+   `vermilion` — the neutral half comes from `paper.css`. Before 0.2 this was
+   a 220-line theme file that duplicated ninety-eight identical tokens to
+   change these six.
+
+   Selected with `data-nim-colorway="oxblood"`.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+[data-nim-colorway='oxblood'] {
+  --nim-accent: light-dark(#6b1f2a, #d38691);
+  --nim-accent-hover: light-dark(#5e1a25, #d9949e);
+  --nim-accent-strong: light-dark(#551722, #dfa3ac);
+  --nim-accent-soft: light-dark(#f2e4e4, rgba(211, 134, 145, 0.16));
+  --nim-accent-line: light-dark(rgba(107, 31, 42, 0.34), rgba(211, 134, 145, 0.38));
+  --nim-on-accent: light-dark(#fdf7f5, #17130f);
+}

package/src/theme/colorways/paper.css

@@ -0,0 +1,68 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   NEUTRALS · PAPER  —  shared by the `vermilion` and `oxblood` colourways
+
+   A colourway answers the whole colour contract: surfaces, ink, lines, accent,
+   status, and the tint its style's shadows are drawn in. Two of them answer
+   the neutral half identically — warm paper and dense warm ink — and differ
+   only in the signal. Rather than copy ninety-odd values to change six, the
+   shared half is stated once here and each colourway states its accent.
+
+   Every value is a `light-dark()` pair, resolved by the `color-scheme` set in
+   `contract.css`. That is the whole mechanism: no duplicated dark block, no
+   `prefers-color-scheme` query, and no exclusion list to fall behind.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+:where(:root),
+[data-nim-colorway='vermilion'],
+[data-nim-colorway='oxblood'] {
+  /* ─── Surfaces ─────────────────────────────────────────────────────── */
+  --nim-canvas: light-dark(#f7f4ee, #14120e);
+  --nim-canvas-sunken: light-dark(#efeae1, #0e0c09);
+  --nim-surface: light-dark(#fffdf9, #1e1a15);
+  --nim-surface-raised: light-dark(#fffdf9, #262119);
+  /* Muted sits below the canvas in light and above the surface in dark.
+     Inverting the light relationship literally made it equal to `surface`,
+     which left a hovered row invisible. */
+  --nim-surface-muted: light-dark(#efeae1, #272219);
+  --nim-scrim: light-dark(rgba(23, 21, 15, 0.42), rgba(8, 7, 5, 0.66));
+
+  /* ─── Ink ────────────────────────────────────────────────────────────
+     Four levels, each clearing AA (4.5:1) on the canvas at 12px — the labels
+     in this palette are small, and small text is never "large text". */
+  --nim-ink: light-dark(#17150f, #f4f0e8);
+  --nim-ink-secondary: light-dark(#3a352b, rgba(244, 240, 232, 0.79));
+  --nim-ink-tertiary: light-dark(#5b5446, rgba(244, 240, 232, 0.61));
+  --nim-ink-inverse: light-dark(#f7f4ee, #14120e);
+
+  /* ─── Lines ──────────────────────────────────────────────────────────
+     Rules carry the structure under the ledger style, so they are
+     load-bearing rather than incidental: `line` divides, `strong` closes,
+     `soft` groups. The dark ramp is set by what stays visible on ink rather
+     than by symmetry with the light values — a hairline on paper is not a
+     hairline on ink. */
+  --nim-line: light-dark(rgba(23, 21, 15, 0.16), rgba(244, 240, 232, 0.24));
+  --nim-line-soft: light-dark(rgba(23, 21, 15, 0.09), rgba(244, 240, 232, 0.13));
+  --nim-line-strong: light-dark(rgba(23, 21, 15, 0.38), rgba(244, 240, 232, 0.46));
+
+  /* ─── Status ─────────────────────────────────────────────────────────
+     Status colours are not the brand's to choose: green means settled and red
+     means wrong in both of these palettes. */
+  --nim-success: light-dark(#1f6b4a, #5fd39a);
+  --nim-success-soft: light-dark(#e2efe8, rgba(95, 211, 154, 0.14));
+  --nim-warning: light-dark(#8a5a12, #e8b25f);
+  --nim-warning-soft: light-dark(#f4ebda, rgba(232, 178, 95, 0.14));
+  --nim-danger: light-dark(#a32a1c, #ff6f5e);
+  --nim-danger-hover: light-dark(#8c2417, #ff8776);
+  --nim-danger-soft: light-dark(#f6e5e2, rgba(255, 111, 94, 0.14));
+  --nim-info: light-dark(#2c5670, #8ab6d0);
+  --nim-info-soft: light-dark(#e3ecf1, rgba(138, 182, 208, 0.14));
+
+  /* ─── Shadow tint ────────────────────────────────────────────────────
+     The colour the active style's offsets are drawn in. In light this is the
+     rule colour, which is what makes the ledger offset read as a register
+     mark; in dark it must be true black, because a tint lighter than the
+     surface reads as a glow instead of depth. */
+  --nim-shadow-tint-sm: light-dark(rgba(23, 21, 15, 0.16), rgba(0, 0, 0, 0.5));
+  --nim-shadow-tint-md: light-dark(rgba(23, 21, 15, 0.09), rgba(0, 0, 0, 0.5));
+  --nim-shadow-tint-lg: light-dark(rgba(23, 21, 15, 0.09), rgba(0, 0, 0, 0.5));
+}

package/src/theme/colorways/teal.css

@@ -0,0 +1,56 @@
+/* ═══════════════════════════════════════════════════════════════════════════
+   COLOURWAY · TEAL  —  clinical calm
+
+   The Fatemifar appointment platform's palette, carried over from the legacy
+   Angular client's Material ramp so the brand stays recognisable. Same neutral
+   hierarchy as `coral` — tinted canvas, white surfaces — cooled toward the
+   accent instead of warmed away from it.
+
+   The brand face (YekanBakh) is NOT set here: a colourway owns colour. An app
+   with its own typeface overrides `--nim-font-sans` on its provider.
+
+   Selected with `data-nim-colorway="teal"`.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+[data-nim-colorway='teal'] {
+  --fa-teal-500: #00baba;
+  --fa-teal-600: #00a7a7;
+  --fa-teal-700: #008c8c;
+
+  --nim-canvas: light-dark(#f6faf9, #101b1a);
+  --nim-canvas-sunken: light-dark(#eff5f4, #0a1211);
+  --nim-surface: light-dark(#ffffff, #182725);
+  --nim-surface-raised: light-dark(#ffffff, #223634);
+  --nim-surface-muted: light-dark(#eef5f4, #1f302e);
+  --nim-scrim: light-dark(rgba(10, 32, 31, 0.52), rgba(5, 14, 13, 0.64));
+
+  --nim-ink: light-dark(#1d1d1f, #ecf5f4);
+  --nim-ink-secondary: light-dark(#56605f, #c3d2d0);
+  --nim-ink-tertiary: light-dark(#8b9695, #84918f);
+  --nim-ink-inverse: light-dark(#f7fcfb, #0a1211);
+  --nim-on-accent: light-dark(#ffffff, #04211f);
+
+  --nim-line: light-dark(rgba(16, 42, 41, 0.12), rgba(255, 255, 255, 0.16));
+  --nim-line-soft: light-dark(rgba(16, 42, 41, 0.07), rgba(255, 255, 255, 0.1));
+  --nim-line-strong: light-dark(rgba(16, 42, 41, 0.2), rgba(255, 255, 255, 0.3));
+
+  --nim-accent: light-dark(#00baba, #2ad4d4);
+  --nim-accent-hover: light-dark(#00a7a7, #4bdede);
+  --nim-accent-strong: light-dark(#008c8c, #00baba);
+  --nim-accent-soft: light-dark(rgba(0, 186, 186, 0.12), rgba(42, 212, 212, 0.15));
+  --nim-accent-line: light-dark(rgba(0, 186, 186, 0.26), rgba(42, 212, 212, 0.28));
+
+  --nim-success: light-dark(#2f8f5b, #6cc292);
+  --nim-success-soft: light-dark(rgba(47, 143, 91, 0.12), rgba(108, 194, 146, 0.14));
+  --nim-warning: light-dark(#b07a1f, #d9a94f);
+  --nim-warning-soft: light-dark(rgba(215, 154, 43, 0.14), rgba(217, 169, 79, 0.14));
+  --nim-danger: light-dark(#c0492f, #e0796a);
+  --nim-danger-hover: light-dark(#ab4029, #e88a7c);
+  --nim-danger-soft: light-dark(rgba(216, 92, 69, 0.12), rgba(224, 121, 106, 0.14));
+  --nim-info: light-dark(#33698c, #90b2c6);
+  --nim-info-soft: light-dark(rgba(51, 105, 140, 0.1), rgba(144, 178, 198, 0.12));
+
+  --nim-shadow-tint-sm: light-dark(rgba(10, 32, 31, 0.06), rgba(0, 0, 0, 0.44));
+  --nim-shadow-tint-md: light-dark(rgba(10, 32, 31, 0.08), rgba(0, 0, 0, 0.52));
+  --nim-shadow-tint-lg: light-dark(rgba(10, 32, 31, 0.1), rgba(0, 0, 0, 0.6));
+}