From 86ae1acedd4ce37025f87ace0a4ad99b30c2fda2 Mon Sep 17 00:00:00 2001
From: giuliana-gladeye <giuliana.aliotti@gladeye.com>
Date: Tue, 9 Jun 2026 17:37:29 +1200
Subject: [PATCH 1/7] feat: added format date component

---
 .../demo/src/components/demo/format-date.tsx  | 162 ++++++++++++++++++
 .../src/content/components/format-date.mdx    | 106 ++++++++++++
 .../format-date/format-date.module.css        |  10 ++
 .../components/format-date/format-date.tsx    | 162 ++++++++++++++++++
 packages/ui/src/components/index.ts           |   1 +
 5 files changed, 441 insertions(+)
 create mode 100644 packages/demo/src/components/demo/format-date.tsx
 create mode 100644 packages/demo/src/content/components/format-date.mdx
 create mode 100644 packages/ui/src/components/format-date/format-date.module.css
 create mode 100644 packages/ui/src/components/format-date/format-date.tsx

diff --git a/packages/demo/src/components/demo/format-date.tsx b/packages/demo/src/components/demo/format-date.tsx
new file mode 100644
index 0000000..3ee4316
--- /dev/null
+++ b/packages/demo/src/components/demo/format-date.tsx
@@ -0,0 +1,162 @@
+import { PanelLabel, FormatDate, Card, CardContent } from "@eqtylab/equality";
+import { useMemo } from "react";
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+
+export function FormatDateRelativeDemo() {
+  // Compute offsets from "now" once on mount so the examples read naturally.
+  const samples = useMemo(() => {
+    const now = new Date();
+    const time = now.getTime();
+    return [
+      { label: "Seconds ago", date: new Date(time - 10 * 1000) },
+      { label: "Minutes ago", date: new Date(time - 5 * MINUTE) },
+      { label: "Hours ago", date: new Date(time - 3 * HOUR) },
+      { label: "Days ago", date: new Date(time - 2 * DAY) },
+      { label: "Weeks ago", date: new Date(time - 2 * WEEK) },
+      { label: "In the future", date: new Date(time + 4 * DAY) },
+    ];
+  }, []);
+
+  return (
+    <div className="my-4">
+      <Card>
+        <CardContent>
+          {samples.map((sample) => (
+            <div key={sample.label} className="flex items-center gap-3">
+              <PanelLabel label={sample.label} className="w-28" />
+              <FormatDate date={sample.date} displayAs="relative" />
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export function FormatDateTimeZoneDemo() {
+  const date = useMemo(() => new Date("2026-06-09T18:42:03Z"), []);
+
+  return (
+    <div className="my-4">
+      <Card>
+        <CardContent className="divide-border divide-y divide-solid">
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="UTC (default)" className="w-28" />
+            <FormatDate date={date} displayAs="absolute" />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="New York" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="America/New_York"
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="Tokyo" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="Asia/Tokyo"
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="Auckland" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="Pacific/Auckland"
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="Toronto" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="America/Toronto"
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="Los Angeles" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="America/Los_Angeles"
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="Buenos Aires" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="America/Buenos_Aires"
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="London" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              timeZone="Europe/London"
+            />
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export function FormatDateOptionsDemo() {
+  const date = useMemo(() => new Date("2026-06-09T18:42:03Z"), []);
+
+  // Each entry overrides the default Intl.DateTimeFormat options.
+  const samples: {
+    label: string;
+    options: Intl.DateTimeFormatOptions;
+  }[] = [
+    {
+      label: "Date only",
+      options: { year: "numeric", month: "long", day: "numeric" },
+    },
+    {
+      label: "Time only",
+      options: { hour: "2-digit", minute: "2-digit" },
+    },
+    {
+      label: "With weekday",
+      options: {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+      },
+    },
+    {
+      label: "Short numeric",
+      options: { dateStyle: "short", timeStyle: "short" },
+    },
+  ];
+
+  return (
+    <div className="my-4">
+      <Card>
+        <CardContent className="divide-border divide-y divide-solid">
+          {samples.map((sample) => (
+            <div key={sample.label} className="flex items-center gap-3 py-1">
+              <PanelLabel label={sample.label} className="w-28" />
+              <FormatDate
+                date={date}
+                displayAs="absolute"
+                absoluteOptions={sample.options}
+              />
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
diff --git a/packages/demo/src/content/components/format-date.mdx b/packages/demo/src/content/components/format-date.mdx
new file mode 100644
index 0000000..783ad96
--- /dev/null
+++ b/packages/demo/src/content/components/format-date.mdx
@@ -0,0 +1,106 @@
+---
+layout: "@demo/layouts/mdx-layout.astro"
+heading: "Format Date"
+description: "Render a date as relative or absolute time using a semantic <time> element"
+---
+
+import { FormatDate } from "@eqtylab/equality";
+import {
+  FormatDateOptionsDemo,
+  FormatDateRelativeDemo,
+  FormatDateTimeZoneDemo,
+} from "@demo/components/demo/format-date";
+
+## Overview
+
+The <code>FormatDate</code> component renders a date as either **relative** time (e.g. "2 weeks ago", "Just now") or **absolute** time (e.g. "9 Jun 2026, 18:42:03 UTC"). It always renders as a semantic HTML [`<time>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time) element with a `dateTime` attribute, so it's available to browsers, screen readers, and crawlers regardless of how it is displayed.
+
+When showing relative time, a tooltip reveals the absolute time on hover or keyboard focus.
+
+## Time zones
+
+Absolute time is formatted in **UTC by default**. To render in a different zone, pass a `timeZone` (e.g. `"America/New_York"`). Relative time reads the same everywhere.
+
+## Usage
+
+Import the component:
+
+```tsx
+import { FormatDate } from "@eqtylab/equality";
+```
+
+Basic usage with the required `date` property, which accepts an ISO 8601 string, epoch milliseconds, or a `Date`. Each of these renders the same instant:
+
+```tsx
+<FormatDate date="2026-06-09T18:42:03Z" />
+<FormatDate date={1781030523000} />
+<FormatDate date={new Date("2026-06-09T18:42:03Z")} />
+```
+
+## Variants
+
+### Absolute
+
+The default. Renders the full date and time in the configured `timeZone` (UTC unless overridden).
+
+<FormatDateTimeZoneDemo client:only="react" />
+
+```tsx
+<FormatDate date="2026-06-09T18:42:03Z" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="America/New_York" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="Asia/Tokyo" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="Pacific/Auckland" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="America/Toronto" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="America/Los_Angeles" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="America/Buenos_Aires" />
+<FormatDate date="2026-06-09T18:42:03Z" timeZone="Europe/London" />
+```
+
+### Relative
+
+Set `displayAs="relative"` to render distance from now. The value updates automatically on an interval, and hovering or focusing the date reveals the absolute time in a tooltip.
+
+<FormatDateRelativeDemo client:only="react" />
+
+```tsx
+<FormatDate date={data.updatedAt} displayAs="relative" />
+```
+
+Disable the tooltip with `tooltip={false}`, or stop the auto-updating with `live={false}`.
+
+### Custom formatting
+
+Pass `absoluteOptions` to override the [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) options used for absolute time. For example to show a date without a time, a time without a date, or a weekday.
+
+<FormatDateOptionsDemo client:only="react" />
+
+```tsx
+<FormatDate
+  date="2026-06-09T18:42:03Z"
+  absoluteOptions={{ year: "numeric", month: "long", day: "numeric" }}
+/>
+<FormatDate
+  date="2026-06-09T18:42:03Z"
+  absoluteOptions={{ hour: "2-digit", minute: "2-digit" }}
+/>
+<FormatDate
+  date="2026-06-09T18:42:03Z"
+  absoluteOptions={{ weekday: "long", year: "numeric", month: "long", day: "numeric" }}
+/>
+<FormatDate
+  date="2026-06-09T18:42:03Z"
+  absoluteOptions={{ dateStyle: "short", timeStyle: "short" }}
+/>
+```
+
+## Props
+
+| Name              | Description                                                             | Type                         | Default    | Required |
+| ----------------- | ----------------------------------------------------------------------- | ---------------------------- | ---------- | -------- |
+| `date`            | The date to display                                                     | `string`, `number`, `Date`   | —          | ✅       |
+| `displayAs`       | Render relative or absolute time                                        | `relative`, `absolute`       | `absolute` | ❌       |
+| `timeZone`        | Time zone used for absolute formatting                                  | `string`                     | `UTC`      | ❌       |
+| `locale`          | BCP 47 locale used for formatting                                       | `string`                     | runtime    | ❌       |
+| `tooltip`         | When relative, show a tooltip with the absolute time on hover/focus     | `boolean`                    | `true`     | ❌       |
+| `live`            | When relative, re-render on an interval so the value stays current      | `boolean`                    | `true`     | ❌       |
+| `absoluteOptions` | Override the `Intl.DateTimeFormat` options used for absolute formatting | `Intl.DateTimeFormatOptions` | —          | ❌       |
diff --git a/packages/ui/src/components/format-date/format-date.module.css b/packages/ui/src/components/format-date/format-date.module.css
new file mode 100644
index 0000000..b3809de
--- /dev/null
+++ b/packages/ui/src/components/format-date/format-date.module.css
@@ -0,0 +1,10 @@
+@reference '../../theme/theme.module.css';
+
+.format-date {
+  @apply tabular-nums;
+}
+
+.format-date--interactive {
+  @apply focus-ring rounded-sm;
+  @apply cursor-default;
+}
diff --git a/packages/ui/src/components/format-date/format-date.tsx b/packages/ui/src/components/format-date/format-date.tsx
new file mode 100644
index 0000000..aca4264
--- /dev/null
+++ b/packages/ui/src/components/format-date/format-date.tsx
@@ -0,0 +1,162 @@
+import * as React from 'react';
+
+import styles from '@/components/format-date/format-date.module.css';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/tooltip/tooltip';
+import { cn } from '@/lib/utils';
+
+export type FormatDateDisplayMode = 'relative' | 'absolute';
+
+export interface FormatDateProps extends Omit<
+  React.TimeHTMLAttributes<HTMLTimeElement>,
+  'dateTime' | 'children'
+> {
+  /** The date to display. Accepts an ISO 8601 string, epoch milliseconds, or a Date. */
+  date: string | number | Date;
+  /** Render relative ("2 weeks ago") or absolute ("Jun 9 2026, 18:42:03 UTC") time. */
+  displayAs?: FormatDateDisplayMode;
+  /** Time zone used for absolute formatting. Defaults to "UTC". */
+  timeZone?: string;
+  /** BCP 47 locale used for formatting. Defaults to the runtime locale. */
+  locale?: string;
+  /** When relative, show a tooltip with the absolute time on hover/focus. Defaults to true. */
+  tooltip?: boolean;
+  /** When relative, re-render on an interval so the value stays current. Defaults to true. */
+  live?: boolean;
+  /** Override the Intl options used for absolute formatting. */
+  absoluteOptions?: Intl.DateTimeFormatOptions;
+}
+
+const DEFAULT_ABSOLUTE_OPTIONS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: 'short',
+  day: 'numeric',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hour12: false,
+  timeZoneName: 'short',
+};
+
+const RELATIVE_DIVISIONS: { amount: number; unit: Intl.RelativeTimeFormatUnit }[] = [
+  { amount: 60, unit: 'second' },
+  { amount: 60, unit: 'minute' },
+  { amount: 24, unit: 'hour' },
+  { amount: 7, unit: 'day' },
+  { amount: 4.34524, unit: 'week' },
+  { amount: 12, unit: 'month' },
+  { amount: Number.POSITIVE_INFINITY, unit: 'year' },
+];
+
+// Re-render relative time so values like "Just now" stay accurate without busy-looping
+const LIVE_INTERVAL_MS = 30_000;
+
+// Parse any date-like input into a Date, or null if missing/invalid
+function toDate(value: string | number | Date): Date | null {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function formatAbsolute(
+  date: Date,
+  timeZone: string,
+  options: Intl.DateTimeFormatOptions,
+  locale?: string
+): string {
+  return new Intl.DateTimeFormat(locale, { ...options, timeZone }).format(date);
+}
+
+function formatRelative(date: Date, now: Date, locale?: string): string {
+  let duration = (date.getTime() - now.getTime()) / 1000;
+  if (Math.abs(duration) < 45) return 'Just now';
+
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+  for (const division of RELATIVE_DIVISIONS) {
+    if (Math.abs(duration) < division.amount) {
+      return rtf.format(Math.round(duration), division.unit);
+    }
+    duration /= division.amount;
+  }
+  return 'Just now';
+}
+
+function FormatDate({
+  date,
+  displayAs = 'absolute',
+  timeZone = 'UTC',
+  locale,
+  tooltip = true,
+  live = true,
+  absoluteOptions,
+  className,
+  ...props
+}: FormatDateProps) {
+  const parsed = React.useMemo(() => toDate(date), [date]);
+  const [now, setNow] = React.useState(() => new Date());
+
+  const isRelative = displayAs === 'relative';
+
+  React.useEffect(() => {
+    if (!isRelative || !live) return;
+    const id = setInterval(() => setNow(new Date()), LIVE_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, [isRelative, live]);
+
+  if (!parsed) {
+    return (
+      <time className={cn(styles['format-date'], className)} {...props}>
+        Invalid date
+      </time>
+    );
+  }
+
+  const machineValue = parsed.toISOString();
+  const absolute = formatAbsolute(
+    parsed,
+    timeZone,
+    absoluteOptions ?? DEFAULT_ABSOLUTE_OPTIONS,
+    locale
+  );
+
+  if (!isRelative) {
+    return (
+      <time dateTime={machineValue} className={cn(styles['format-date'], className)} {...props}>
+        {absolute}
+      </time>
+    );
+  }
+
+  const relative = formatRelative(parsed, now, locale);
+
+  if (!tooltip) {
+    return (
+      <time dateTime={machineValue} className={cn(styles['format-date'], className)} {...props}>
+        {relative}
+      </time>
+    );
+  }
+
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <time
+            dateTime={machineValue}
+            tabIndex={0}
+            className={cn(styles['format-date'], styles['format-date--interactive'], className)}
+            {...props}
+          >
+            {relative}
+          </time>
+        </TooltipTrigger>
+        <TooltipContent>{absolute}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}
+
+export { FormatDate };
diff --git a/packages/ui/src/components/index.ts b/packages/ui/src/components/index.ts
index 3332d27..8c8f439 100644
--- a/packages/ui/src/components/index.ts
+++ b/packages/ui/src/components/index.ts
@@ -52,6 +52,7 @@ export * from './table/table-components';
 export * from './tabs/tabs-components';
 export * from './tabs/tabs';
 export * from './textarea/textarea';
+export * from './format-date/format-date';
 export * from './toast/toast-components';
 export * from './toast/toast';
 export * from './tooltip/tooltip';

From 7bcde72df72d5ac39c1720a6c8a8d091cb738666 Mon Sep 17 00:00:00 2001
From: giuliana-gladeye <giuliana.aliotti@gladeye.com>
Date: Wed, 10 Jun 2026 09:22:53 +1200
Subject: [PATCH 2/7] feat: added default locale

---
 packages/demo/src/content/components/format-date.mdx   | 2 +-
 packages/ui/src/components/format-date/format-date.tsx | 9 ++++++---
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/demo/src/content/components/format-date.mdx b/packages/demo/src/content/components/format-date.mdx
index 783ad96..66606c5 100644
--- a/packages/demo/src/content/components/format-date.mdx
+++ b/packages/demo/src/content/components/format-date.mdx
@@ -100,7 +100,7 @@ Pass `absoluteOptions` to override the [`Intl.DateTimeFormat`](https://developer
 | `date`            | The date to display                                                     | `string`, `number`, `Date`   | —          | ✅       |
 | `displayAs`       | Render relative or absolute time                                        | `relative`, `absolute`       | `absolute` | ❌       |
 | `timeZone`        | Time zone used for absolute formatting                                  | `string`                     | `UTC`      | ❌       |
-| `locale`          | BCP 47 locale used for formatting                                       | `string`                     | runtime    | ❌       |
+| `locale`          | BCP 47 locale used for formatting                                       | `string`                     | `en-US`    | ❌       |
 | `tooltip`         | When relative, show a tooltip with the absolute time on hover/focus     | `boolean`                    | `true`     | ❌       |
 | `live`            | When relative, re-render on an interval so the value stays current      | `boolean`                    | `true`     | ❌       |
 | `absoluteOptions` | Override the `Intl.DateTimeFormat` options used for absolute formatting | `Intl.DateTimeFormatOptions` | —          | ❌       |
diff --git a/packages/ui/src/components/format-date/format-date.tsx b/packages/ui/src/components/format-date/format-date.tsx
index aca4264..2dcf5fa 100644
--- a/packages/ui/src/components/format-date/format-date.tsx
+++ b/packages/ui/src/components/format-date/format-date.tsx
@@ -31,6 +31,9 @@ export interface FormatDateProps extends Omit<
   absoluteOptions?: Intl.DateTimeFormatOptions;
 }
 
+// BCP 47 locale used for all formatting. Explicit so server and client always agree
+const DEFAULT_LOCALE = 'en-US';
+
 const DEFAULT_ABSOLUTE_OPTIONS: Intl.DateTimeFormatOptions = {
   year: 'numeric',
   month: 'short',
@@ -65,12 +68,12 @@ function formatAbsolute(
   date: Date,
   timeZone: string,
   options: Intl.DateTimeFormatOptions,
-  locale?: string
+  locale: string
 ): string {
   return new Intl.DateTimeFormat(locale, { ...options, timeZone }).format(date);
 }
 
-function formatRelative(date: Date, now: Date, locale?: string): string {
+function formatRelative(date: Date, now: Date, locale: string): string {
   let duration = (date.getTime() - now.getTime()) / 1000;
   if (Math.abs(duration) < 45) return 'Just now';
 
@@ -88,7 +91,7 @@ function FormatDate({
   date,
   displayAs = 'absolute',
   timeZone = 'UTC',
-  locale,
+  locale = DEFAULT_LOCALE,
   tooltip = true,
   live = true,
   absoluteOptions,

From a3e6febaf204380510c81f9e6fc5c36907de7ebf Mon Sep 17 00:00:00 2001
From: giuliana-gladeye <giuliana.aliotti@gladeye.com>
Date: Wed, 10 Jun 2026 09:24:15 +1200
Subject: [PATCH 3/7] fix: update comment

---
 packages/ui/src/components/format-date/format-date.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/src/components/format-date/format-date.tsx b/packages/ui/src/components/format-date/format-date.tsx
index 2dcf5fa..0c74424 100644
--- a/packages/ui/src/components/format-date/format-date.tsx
+++ b/packages/ui/src/components/format-date/format-date.tsx
@@ -21,7 +21,7 @@ export interface FormatDateProps extends Omit<
   displayAs?: FormatDateDisplayMode;
   /** Time zone used for absolute formatting. Defaults to "UTC". */
   timeZone?: string;
-  /** BCP 47 locale used for formatting. Defaults to the runtime locale. */
+  /** BCP 47 locale used for formatting. Defaults to "en-US". */
   locale?: string;
   /** When relative, show a tooltip with the absolute time on hover/focus. Defaults to true. */
   tooltip?: boolean;

From 57d60d85f5b9e8614e24e33994dd004efa7b2064 Mon Sep 17 00:00:00 2001
From: giuliana-gladeye <giuliana.aliotti@gladeye.com>
Date: Wed, 10 Jun 2026 09:36:00 +1200
Subject: [PATCH 4/7] feat: gate relative time

---
 packages/ui/src/components/format-date/format-date.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/ui/src/components/format-date/format-date.tsx b/packages/ui/src/components/format-date/format-date.tsx
index 0c74424..0b286ab 100644
--- a/packages/ui/src/components/format-date/format-date.tsx
+++ b/packages/ui/src/components/format-date/format-date.tsx
@@ -100,9 +100,12 @@ function FormatDate({
 }: FormatDateProps) {
   const parsed = React.useMemo(() => toDate(date), [date]);
   const [now, setNow] = React.useState(() => new Date());
+  const [mounted, setMounted] = React.useState(false);
 
   const isRelative = displayAs === 'relative';
 
+  React.useEffect(() => setMounted(true), []);
+
   React.useEffect(() => {
     if (!isRelative || !live) return;
     const id = setInterval(() => setNow(new Date()), LIVE_INTERVAL_MS);
@@ -133,7 +136,8 @@ function FormatDate({
     );
   }
 
-  const relative = formatRelative(parsed, now, locale);
+  // Until mounted, show the absolute string so SSR and first client render match
+  const relative = mounted ? formatRelative(parsed, now, locale) : absolute;
 
   if (!tooltip) {
     return (

From fc129903cb63de33351c6c7768b9988a2a3c5db3 Mon Sep 17 00:00:00 2001
From: giuliana-gladeye <giuliana.aliotti@gladeye.com>
Date: Wed, 10 Jun 2026 10:45:23 +1200
Subject: [PATCH 5/7] feat: updated format date demo

---
 .../demo/src/components/demo/format-date.tsx  | 39 +++++++++++++++++++
 .../src/content/components/format-date.mdx    | 15 +++++++
 2 files changed, 54 insertions(+)

diff --git a/packages/demo/src/components/demo/format-date.tsx b/packages/demo/src/components/demo/format-date.tsx
index 3ee4316..e64ffeb 100644
--- a/packages/demo/src/components/demo/format-date.tsx
+++ b/packages/demo/src/components/demo/format-date.tsx
@@ -160,3 +160,42 @@ export function FormatDateOptionsDemo() {
     </div>
   );
 }
+
+export function FormatDateIsoDemo() {
+  const date = useMemo(() => new Date("2026-06-09T18:42:03Z"), []);
+
+  // en-CA orders numeric dates as yyyy-mm-dd
+  // en-US would render dd/mm/yyyy
+  const options: Intl.DateTimeFormatOptions = {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  };
+
+  return (
+    <div className="my-4">
+      <Card>
+        <CardContent className="divide-border divide-y divide-solid">
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="en-CA" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              locale="en-CA"
+              absoluteOptions={options}
+            />
+          </div>
+          <div className="flex items-center gap-3 py-1">
+            <PanelLabel label="en-US" className="w-28" />
+            <FormatDate
+              date={date}
+              displayAs="absolute"
+              locale="en-US"
+              absoluteOptions={options}
+            />
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
diff --git a/packages/demo/src/content/components/format-date.mdx b/packages/demo/src/content/components/format-date.mdx
index 66606c5..976f599 100644
--- a/packages/demo/src/content/components/format-date.mdx
+++ b/packages/demo/src/content/components/format-date.mdx
@@ -6,6 +6,7 @@ description: "Render a date as relative or absolute time using a semantic <time>
 
 import { FormatDate } from "@eqtylab/equality";
 import {
+  FormatDateIsoDemo,
   FormatDateOptionsDemo,
   FormatDateRelativeDemo,
   FormatDateTimeZoneDemo,
@@ -93,6 +94,20 @@ Pass `absoluteOptions` to override the [`Intl.DateTimeFormat`](https://developer
 />
 ```
 
+#### ISO 8601 short date
+
+For a short numeric date like `2026-06-09`, use numeric options. Digit _order_ is decided by the `locale`, not the options, so the default `en-US` renders this as `06/09/2026`. Pair the preset with `locale="en-CA"` (which orders numerically as `yyyy-mm-dd`) to get true ISO 8601:
+
+<FormatDateIsoDemo client:only="react" />
+
+```tsx
+<FormatDate
+  date="2026-06-09T18:42:03Z"
+  locale="en-CA"
+  absoluteOptions={{ year: "numeric", month: "2-digit", day: "2-digit" }}
+/>
+```
+
 ## Props
 
 | Name              | Description                                                             | Type                         | Default    | Required |

From 21bd76ce408b3d8b637ef1bc566efa3a12760881 Mon Sep 17 00:00:00 2001
From: Giuliana Aliotti <125221024+giuliana-gladeye@users.noreply.github.com>
Date: Wed, 10 Jun 2026 10:47:14 +1200
Subject: [PATCH 6/7] Update
 packages/demo/src/content/components/format-date.mdx

Co-authored-by: Henry Wilkinson <henry@wilkinson.graphics>
---
 packages/demo/src/content/components/format-date.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/demo/src/content/components/format-date.mdx b/packages/demo/src/content/components/format-date.mdx
index 976f599..f82eb53 100644
--- a/packages/demo/src/content/components/format-date.mdx
+++ b/packages/demo/src/content/components/format-date.mdx
@@ -14,7 +14,7 @@ import {
 
 ## Overview
 
-The <code>FormatDate</code> component renders a date as either **relative** time (e.g. "2 weeks ago", "Just now") or **absolute** time (e.g. "9 Jun 2026, 18:42:03 UTC"). It always renders as a semantic HTML [`<time>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time) element with a `dateTime` attribute, so it's available to browsers, screen readers, and crawlers regardless of how it is displayed.
+The <code>FormatDate</code> component renders a date as either **relative** time (e.g. "2 weeks ago", "Just now") or **absolute** time (e.g. "Jun 9 2026, 18:42:03 UTC"). It always renders as a semantic HTML [`<time>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time) element with a `dateTime` attribute.
 
 When showing relative time, a tooltip reveals the absolute time on hover or keyboard focus.
 

From be6e85eb95f4f952a6f3f366f3a83aadbdb9396d Mon Sep 17 00:00:00 2001
From: Henry Wilkinson <henry@wilkinson.graphics>
Date: Tue, 9 Jun 2026 18:49:41 -0400
Subject: [PATCH 7/7] Update package.json

---
 packages/ui/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/ui/package.json b/packages/ui/package.json
index 93b1b25..abd2394 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -2,7 +2,7 @@
   "name": "@eqtylab/equality",
   "description": "EQTYLab's component and token-based design system",
   "homepage": "https://equality.eqtylab.io/",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "license": "Apache-2.0",
   "keywords": [
     "component library",