@multiplatform.one/components 7.4.1 → 7.6.0

package/src/Meter/meter.ts

@@ -0,0 +1,111 @@
+/**
+ * Meter math — zone, radius, value label.
+ *
+ * Progress is activity toward completion; Meter is position within bounds.
+ * Full is an incident, not an achievement. Threshold polarity is declared
+ * (`low` / `high` / `optimum`, the HTML <meter> model) and never guessed
+ * (LC-36). The rail is DEFAULT, not BINARY: there is no thumb to square with
+ * (D-meter verdict; RULINGS-2026-08-28.md R2 leftovers apply to Slider).
+ */
+import {
+  formatNumber,
+  formatPercent,
+  resolveRadiusClass,
+  sizeRecipeForToken,
+  type BorderRadius,
+} from "@multiplatform.one/theme";
+
+export type MeterZone = "ok" | "warn" | "critical";
+export type MeterFormat = "number" | "percent";
+export type MeterLayout = "adjacent" | "inline" | "bare";
+
+/** Doctrine class for the thumbless rail and its segments. */
+export const METER_RADIUS_CLASS = "DEFAULT" as const;
+
+/**
+ * Zone paint — theme intent tokens, never raw brand or `$accentBackground`.
+ * ok is the LAW pairing (no verdict under threshold, DG-FB-06). warn/critical
+ * are the same step-9 solid / step-11 ink channel Progress uses (DG-FB-05).
+ */
+export const METER_ZONE_PAINT = {
+  ok: { fill: "$color11", value: "$color11" },
+  warn: { fill: "$orange9", value: "$orange11" },
+  critical: { fill: "$red9", value: "$red11" },
+} as const;
+
+export const METER_TRACK = "$color4";
+export const METER_TICK = "$color8";
+export const UNKNOWN_VALUE = "\u2014";
+
+const SIZE_TOKEN = { small: "$3", medium: "$4", large: "$5" } as const;
+
+export function resolveMeterRailRadius(stop: BorderRadius): number {
+  return resolveRadiusClass(METER_RADIUS_CLASS, stop);
+}
+
+/** Track height = round(0.25 × $size) — the Progress formula, unchanged. */
+export function meterTrackHeightPx(size: "small" | "medium" | "large"): number {
+  return Math.round(sizeRecipeForToken(SIZE_TOKEN[size]).height * 0.25);
+}
+
+export function meterFillRatio(
+  value: number | null | undefined,
+  min: number,
+  max: number,
+): number | null {
+  if (value == null || !Number.isFinite(value) || max === min) return null;
+  return Math.max(0, Math.min(1, (value - min) / (max - min)));
+}
+
+/**
+ * HTML <meter> regions. No `low`/`high`/`optimum` → always ok (undeclared
+ * never wears a verdict). `optimum` names the good end so battery inverts
+ * without new chrome.
+ */
+export function resolveMeterZone(opts: {
+  value: number;
+  min: number;
+  max: number;
+  low?: number;
+  high?: number;
+  optimum?: number;
+}): MeterZone {
+  const { value, min, max, low, high, optimum } = opts;
+  if (low === undefined && high === undefined && optimum === undefined) {
+    return "ok";
+  }
+  const lo = low ?? min;
+  const hi = high ?? max;
+  const opt = optimum ?? (min + max) / 2;
+  if (opt < lo) {
+    if (value <= lo) return "ok";
+    if (value <= hi) return "warn";
+    return "critical";
+  }
+  if (opt > hi) {
+    if (value >= hi) return "ok";
+    if (value >= lo) return "warn";
+    return "critical";
+  }
+  if (value >= lo && value <= hi) return "ok";
+  return "warn";
+}
+
+export function formatMeterValue(opts: {
+  value?: number | null;
+  min: number;
+  max: number;
+  unit?: string;
+  format?: MeterFormat;
+  valueLabel?: string;
+}): string {
+  if (opts.valueLabel !== undefined) return opts.valueLabel;
+  if (opts.value == null || !Number.isFinite(opts.value)) return UNKNOWN_VALUE;
+  if (opts.format === "percent") {
+    const ratio = meterFillRatio(opts.value, opts.min, opts.max);
+    return formatPercent(Math.round((ratio ?? 0) * 100));
+  }
+  const amount = formatNumber(opts.value);
+  const cap = formatNumber(opts.max);
+  return opts.unit ? `${amount} of ${cap} ${opts.unit}` : `${amount} of ${cap}`;
+}

package/src/Pagination.spec.tsx

@@ -20,6 +20,7 @@ import {
   type IconProps,
 } from "@phosphor-icons/react";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Preset } from "@multiplatform.one/theme";
 import { act, render } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
 import { Pagination } from "./Pagination";
@@ -156,3 +157,35 @@ describe("Pagination summary bidi isolation", () => {
     expect(getByText("\u20680 of 0\u2069")).toBeTruthy();
   });
 });
+
+describe("Pagination design-law (MPO-60)", () => {
+  it("exposes named exports and no default", async () => {
+    const mod = await import("./Pagination");
+    expect(mod.Pagination).toBe(Pagination);
+    expect(mod.getPaginationItems).toBeTypeOf("function");
+    expect(mod.default).toBeUndefined();
+  });
+
+  it("LC-68: animation none publishes data-animation=none (no quick fallback)", () => {
+    const { container } = renderWithProviders(
+      <Preset overrides={{ animation: "none" }}>
+        <Pagination total={5} activeIndex={2} />
+      </Preset>,
+    );
+    const nav = container.querySelector('[role="navigation"]') as HTMLElement;
+    expect(nav.getAttribute("data-animation")).toBe("none");
+  });
+
+  it("LC-68: default animation publishes a named transition, not none", () => {
+    const { container } = renderWithProviders(<Pagination total={5} activeIndex={2} />);
+    const nav = container.querySelector('[role="navigation"]') as HTMLElement;
+    expect(nav.getAttribute("data-animation")).not.toBe("none");
+    expect(nav.getAttribute("data-animation")).toBeTruthy();
+  });
+
+  it("frame publishes data-pad=panel (SP-PAD)", () => {
+    const { container } = renderWithProviders(<Pagination total={5} activeIndex={2} />);
+    const nav = container.querySelector('[role="navigation"]') as HTMLElement;
+    expect(nav.getAttribute("data-pad")).toBe("panel");
+  });
+});

package/src/Pagination.stories.tsx

@@ -213,15 +213,15 @@ export const AllStates: Story = {
   render: () => (
     <YStack gap="$6" alignItems="center">
       <YStack gap="$2" alignItems="center">
-        <Text fontWeight="600">Dots (default)</Text>
+        <Text fontWeight="400">Dots (default)</Text>
         <ControlledPagination total={5} />
       </YStack>
       <YStack gap="$2" alignItems="center">
-        <Text fontWeight="600">Bars</Text>
+        <Text fontWeight="400">Bars</Text>
         <ControlledPagination total={5} variant="bars" />
       </YStack>
       <YStack gap="$2" alignItems="center">
-        <Text fontWeight="600">With completed steps</Text>
+        <Text fontWeight="400">With completed steps</Text>
         <Pagination
           total={5}
           activeIndex={3}
@@ -230,7 +230,7 @@ export const AllStates: Story = {
         />
       </YStack>
       <YStack gap="$2" alignItems="center">
-        <Text fontWeight="600">Disabled</Text>
+        <Text fontWeight="400">Disabled</Text>
         <ControlledPagination total={5} disabled />
       </YStack>
     </YStack>

package/src/Pagination.tsx

@@ -156,8 +156,10 @@ export function Pagination({
 }: PaginationProps) {
   const { t } = useTranslation();
   const { knobProps } = useResolvedKnobs();
-  // LC-25: discrete page jumps tween indicator geometry/color; no continuous drag here.
-  const motionTransition = (knobProps.transition as string | undefined) || "quick";
+  // LC-68: undefined at animation "none" / PRM — a `|| "quick"` fallback
+  // re-enables the tween and is the violation. DotIndicator also drops
+  // host transition when the knob is off.
+  const motionTransition = knobProps.transition as string | undefined;
   if (isWeb) ensureKeyboardModalityTracking();
   // LC-71: ring rides the focused page control only, keyboard-origin, never
   // mouse. Selected is fill (below), not this outline channel.
@@ -276,6 +278,9 @@ export function Pagination({
       justifyContent="center"
       role="navigation"
       aria-label={t("Pagination")}
+      data-animation={motionTransition ?? "none"}
+      data-pad="panel"
+      {...knobProps.panelPadding}
       {...knobProps.gap}
       {...stackProps}
     >
@@ -307,7 +312,7 @@ export function Pagination({
       />
 
       {isNumbered ? (
-        <XStack alignItems="center" gap="$1">
+        <XStack alignItems="center" {...knobProps.gap}>
           {items.map((item) => {
             if (typeof item !== "number") {
               return (
@@ -330,7 +335,6 @@ export function Pagination({
               <Button
                 key={item}
                 size={knobProps.sizeToken}
-                paddingHorizontal="$2"
                 accent={isCurrent}
                 chromeless={!isCurrent}
                 disabled={disabled}

package/src/PopoverContent.stories.tsx

@@ -27,7 +27,7 @@ function PopoverHarness({
         </Popover.Trigger>
         <PopoverContent maxWidth={300}>
           <YStack {...knobProps.gap} {...knobProps.panelPadding}>
-            <SizableText fontWeight="600">Popover title</SizableText>
+            <SizableText fontWeight="400">Popover title</SizableText>
             <Paragraph>
               Elevated overlay surface driven by the elevatedSurface knob recipe.
             </Paragraph>

package/src/ProgressSteps/ProgressSteps.spec.tsx

@@ -88,6 +88,19 @@ describe("ProgressSteps", () => {
     expect(container.querySelector('[aria-label="Go to step 2: Two"]')).toBeFalsy();
   });
 
+  it("publishes density without pinning compact (LC-76 / R7 labels at 400)", () => {
+    const { container } = renderWithProviders(<ProgressSteps steps={steps} current={1} />);
+    const root = container.querySelector('[role="list"]') as HTMLElement;
+    expect(root.getAttribute("data-density")).toBeTruthy();
+    const labels = Array.from(container.querySelectorAll('[role="list"] *')).filter(
+      (el) => el.textContent === "Two" && (el as HTMLElement).style?.fontWeight,
+    );
+    for (const el of labels) {
+      const weight = (el as HTMLElement).style.fontWeight || getComputedStyle(el).fontWeight;
+      expect(["400", "normal", ""]).toContain(String(weight));
+    }
+  });
+
   it("paints markers at nestedControl size, not the 44px press floor", () => {
     const { container } = renderWithProviders(<ProgressSteps steps={steps} current={1} />);
     const marker = container.querySelector("[data-nested-px]") as HTMLElement;
@@ -103,6 +116,16 @@ describe("ProgressSteps", () => {
     expect(marker.getAttribute("data-nested-px")).toBe("28");
   });
 
+  it("hides visible step labels when labels is hidden", () => {
+    const { container } = renderWithProviders(
+      <ProgressSteps steps={steps} current={1} labels="hidden" />,
+    );
+    expect(container.querySelector("[data-labels='hidden']")).toBeTruthy();
+    expect(container.textContent).not.toContain("One");
+    expect(container.textContent).not.toContain("Two");
+    expect(container.querySelector('[aria-current="step"]')).toBeTruthy();
+  });
+
   it("flags an error step on the marker", () => {
     const { container } = renderWithProviders(
       <ProgressSteps

package/src/ProgressSteps/ProgressSteps.stories.tsx

@@ -22,6 +22,7 @@ const meta: Meta<typeof ProgressSteps> = {
     compact: { control: "boolean" },
     allowJump: { control: "boolean" },
     linear: { control: "boolean" },
+    labels: { control: "select", options: ["visible", "hidden"] },
   },
 };
 export default meta;
@@ -83,6 +84,15 @@ export const Vertical: Story = {
   },
 };
 
+export const HiddenLabels: Story = {
+  name: "Labels hidden",
+  args: {
+    steps: demoSteps,
+    current: 1,
+    labels: "hidden",
+  },
+};
+
 export const Compact: Story = {
   args: {
     steps: demoSteps.map(({ id, label }) => ({ id, label })),

package/src/ProgressSteps/index.tsx

@@ -53,6 +53,13 @@ export interface ProgressStepsProps extends Omit<GetProps<typeof StepsRoot>, "ch
   linear?: boolean;
   /** Compact markers + type (density compact override). */
   compact?: boolean;
+  /**
+   * Rail label treatment. `"hidden"` keeps markers (and a11y names) and
+   * drops the visible per-step label — the 390 wizard treatment; the
+   * current step's name rides the wizard legend as "Step n of m — X".
+   * @default "visible"
+   */
+  labels?: "visible" | "hidden";
 }
 
 type StepState = "completed" | "current" | "upcoming";
@@ -129,14 +136,16 @@ export function ProgressSteps({
   orientation = "horizontal",
   allowJump = true,
   linear = true,
-  compact = false,
+  compact,
+  labels = "visible",
   ...props
 }: ProgressStepsProps) {
   const { t } = useTranslation();
-  const { knobProps, control, disabledState } = useResolvedKnobs({
-    component: "ProgressSteps",
-    compact,
-  });
+  const { knobProps, control, disabledState } = useResolvedKnobs(
+    compact === undefined
+      ? { component: "ProgressSteps" }
+      : { component: "ProgressSteps", compact },
+  );
   if (isWeb) ensureKeyboardModalityTracking();
   const [kbFocusIndex, setKbFocusIndex] = useState<number | null>(null);
   // LC-05: current marker rides the accent fill; completed/error fills pick
@@ -154,7 +163,13 @@ export function ProgressSteps({
   const gapToken = knobProps.gap.gap;
 
   return (
-    <StepsRoot role="list" aria-label={t("Progress")} data-density={knobProps.density} {...props}>
+    <StepsRoot
+      role="list"
+      aria-label={t("Progress")}
+      data-density={knobProps.density}
+      data-labels={labels}
+      {...props}
+    >
       <XStack
         flexDirection={horizontal ? "row" : "column"}
         alignItems={horizontal ? "flex-start" : "stretch"}
@@ -222,7 +237,7 @@ export function ProgressSteps({
               ) : (
                 <SizableText
                   {...knobProps.label}
-                  fontWeight="600"
+                  fontWeight="400"
                   color={kind === "current" ? (onSelected ?? "$color1") : markerFg}
                 >
                   {index + 1}
@@ -259,7 +274,7 @@ export function ProgressSteps({
               <SizableText
                 {...knobProps.body}
                 {...knobProps.label}
-                fontWeight={state === "current" ? "600" : knobProps.body.fontWeight}
+                fontWeight="400"
                 color={
                   kind === "error"
                     ? "$red11"
@@ -309,10 +324,11 @@ export function ProgressSteps({
             />
           ) : null;
 
+          const showLabels = labels !== "hidden";
           const body = horizontal ? (
             <YStack alignItems="center" flexShrink={0}>
               {markerTarget}
-              {labelBlock}
+              {showLabels ? labelBlock : null}
             </YStack>
           ) : (
             <XStack alignItems="stretch" gap={gapToken} minHeight={MIN_PRESS_TARGET}>
@@ -320,7 +336,7 @@ export function ProgressSteps({
                 {markerTarget}
                 {verticalConnector}
               </YStack>
-              {labelBlock}
+              {showLabels ? labelBlock : null}
             </XStack>
           );
 

package/src/Quote/Quote.spec.tsx

@@ -9,6 +9,14 @@ describe("Quote", () => {
     expect(container.textContent).toContain("Invent the future.");
   });
 
+  it("does not pin compact, so the density knob restyles the frame", () => {
+    const { container } = renderWithProviders(<Quote>Invent the future.</Quote>);
+    const figure = container.querySelector("figure") as HTMLElement;
+    expect(figure).toBeTruthy();
+    expect(figure.getAttribute("data-density")).toBeTruthy();
+    expect(figure.getAttribute("data-density")).not.toBe("");
+  });
+
   it("renders cite attribution outside the quotation", () => {
     const { container } = renderWithProviders(<Quote cite="Alan Kay">Invent the future.</Quote>);
     expect(container.textContent).toContain("Alan Kay");

package/src/Quote/index.tsx

@@ -61,8 +61,10 @@ function quoteRailWidth(borderWidth: number): number {
  * (attribution lives outside the quotation per the spec). Chrome: flush
  * logical-start rail (XStack reverses in RTL) + SF-CARD frame.
  */
-export function Quote({ children, cite, compact = false, ...props }: QuoteProps) {
-  const { knobProps } = useResolvedKnobs({ component: "Quote", compact });
+export function Quote({ children, cite, compact, ...props }: QuoteProps) {
+  const { knobProps } = useResolvedKnobs(
+    compact === undefined ? { component: "Quote" } : { component: "Quote", compact },
+  );
   const railWidth = quoteRailWidth(knobProps.borderRadius.borderWidth);
   const citeColor =
     knobProps.textAccentColor === "$color" ? componentColors.text.muted : knobProps.textAccentColor;
@@ -70,6 +72,7 @@ export function Quote({ children, cite, compact = false, ...props }: QuoteProps)
   return (
     <QuoteFrame
       render="figure"
+      data-density={knobProps.density}
       backgroundColor={componentColors.surface.background}
       overflow="hidden"
       // R-SCALE quote frame (Axiom 1 child-clip cap). Padding lives on the

package/src/Separator/Separator.spec.tsx

@@ -0,0 +1,168 @@
+/**
+ * @vitest-environment jsdom
+ *
+ * MPO-47 — Separator paints a line.
+ *
+ * What this locks: the house rule paints, at 1 CSS px, in $borderColor, in
+ * both schemes, and cannot flex-grow (DG-OVF-07 — the raw primitive it
+ * replaced declares `flex: 1`). Asserting a separator's height and never its
+ * colour is how a transparent rule ships, so this spec asserts the painted
+ * colour first.
+ *
+ * (The ticket's "96 of 96 paint nothing" reading was a probe artefact — it
+ * read borderTopWidth on a primitive that paints borderBottomWidth. See the
+ * component header. The assertions below are unaffected: they are about what
+ * the HOUSE rule paints, not about what the raw one did.)
+ *
+ * jsdom cannot CASCADE Tamagui's class-based CSS, so `getComputedStyle` on the
+ * element reads nothing — but Tamagui does INJECT its atomic rules into
+ * `document.styleSheets`, so the declaration behind each of the element's own
+ * atoms is readable and is what this spec asserts. That is deliberate: the
+ * first version of this file matched atom NAMES (`/_o-0d0t5/`), the encoder
+ * emits `_o-0--5`, and the quiet test was red from the day it merged without
+ * anyone seeing it — CI runs `turbo run build` only (MPO-78). A declaration is
+ * the law; an atom name is an implementation detail of the encoder.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { Theme, getConfig } from "tamagui";
+import { afterEach, describe, expect, it } from "vitest";
+import { Separator } from "./index";
+
+afterEach(cleanup);
+
+function getSeparator(container: HTMLElement): HTMLElement {
+  const el = container.querySelector('[role="separator"]');
+  expect(el, "a Separator must render role='separator'").toBeTruthy();
+  return el as HTMLElement;
+}
+
+const escapeForRegExp = (value: string) => value.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+
+/**
+ * Every value Tamagui declared for `property` through one of THIS element's
+ * atomic classes. Empty means the element does not carry that property at all.
+ */
+function declared(el: HTMLElement, property: string): string[] {
+  const atoms = el.className.split(/\s+/).filter(Boolean);
+  const values: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList | undefined;
+    try {
+      rules = sheet.cssRules;
+    } catch {
+      continue; // cross-origin sheet; nothing of ours lives there
+    }
+    for (const rule of Array.from(rules ?? [])) {
+      const parsed = (rule.cssText ?? "").match(/^([^{]+)\{([^}]*)\}$/);
+      if (!parsed) continue;
+      const [, selector, body] = parsed;
+      const mine = atoms.some((atom) =>
+        new RegExp(`\\.${escapeForRegExp(atom)}(?![\\w-])`).test(selector),
+      );
+      if (!mine) continue;
+      const decl = body.match(
+        new RegExp(`(?:^|[;\\s])${escapeForRegExp(property)}\\s*:\\s*([^;]+)`),
+      );
+      if (decl) values.push(decl[1].trim());
+    }
+  }
+  return values;
+}
+
+/** Resolve a theme colour Variable to its raw value string. */
+function themeColorVal(scheme: "light" | "dark", key: string): string {
+  const themes = getConfig().themes as Record<string, Record<string, { val?: unknown }>>;
+  const variable = themes[scheme]?.[key];
+  return String(variable?.val ?? "");
+}
+
+function isVisibleColor(value: string): boolean {
+  if (!value) return false;
+  if (value === "transparent") return false;
+  // rgba/hsla with a 0 alpha channel paints nothing.
+  return !/(?:rgba|hsla)\([^)]*,\s*0(?:\.0+)?\s*\)/.test(value);
+}
+
+describe("Separator — painted colour (the regression this component exists for)", () => {
+  it("paints its 1px box with the $borderColor token, not a transparent box", () => {
+    const { container } = renderWithProviders(<Separator />);
+    const separator = getSeparator(container);
+    // PAINT: the declared background is the borderColor token, not transparent.
+    expect(declared(separator, "background-color")).toEqual(["var(--borderColor)"]);
+    // GEOMETRY: exactly 1 CSS px tall — never 0.5 (§7.3: "1px is the value").
+    expect(declared(separator, "height")).toEqual(["1px"]);
+  });
+
+  it("carries a visible $borderColor in BOTH schemes (token values are real colours)", () => {
+    // The component paints one token; the scheme resolves it. Prove the token
+    // itself is a visible colour on both sides so the indirection cannot hide
+    // a transparent value in either scheme.
+    renderWithProviders(<Separator />);
+    for (const scheme of ["light", "dark"] as const) {
+      const value = themeColorVal(scheme, "borderColor");
+      expect(value, `${scheme} theme must define borderColor`).not.toBe("");
+      expect(isVisibleColor(value), `${scheme} borderColor "${value}" must be visible`).toBe(true);
+    }
+  });
+
+  it("paints the same token under an explicit dark theme subtree", () => {
+    const { container } = renderWithProviders(
+      <Theme name="dark">
+        <Separator />
+      </Theme>,
+    );
+    const separator = getSeparator(container);
+    expect(declared(separator, "background-color")).toEqual(["var(--borderColor)"]);
+    expect(declared(separator, "height")).toEqual(["1px"]);
+  });
+});
+
+describe("Separator — quiet variant (§7.3: opacity 0.5, never a lighter colour)", () => {
+  it("dims with opacity 0.5 and keeps the exact same paint token", () => {
+    const { container } = renderWithProviders(<Separator quiet />);
+    const separator = getSeparator(container);
+    expect(declared(separator, "opacity")).toEqual(["0.5"]);
+    // Never a lighter colour: the paint token is unchanged from the default.
+    expect(declared(separator, "background-color")).toEqual(["var(--borderColor)"]);
+  });
+
+  it("default separator carries no opacity dim", () => {
+    const { container } = renderWithProviders(<Separator />);
+    expect(declared(getSeparator(container), "opacity")).toEqual([]);
+  });
+});
+
+describe("Separator — vertical (§7.3: vertical separators are 1px wide)", () => {
+  it("is 1px wide, releases the horizontal height, and declares its orientation", () => {
+    const { container } = renderWithProviders(<Separator vertical />);
+    const separator = getSeparator(container);
+    expect(declared(separator, "width")).toEqual(["1px"]);
+    expect(declared(separator, "height")).toEqual(["auto"]);
+    expect(separator.getAttribute("aria-orientation")).toBe("vertical");
+  });
+
+  it("horizontal default does not claim a vertical orientation", () => {
+    const { container } = renderWithProviders(<Separator />);
+    expect(getSeparator(container).getAttribute("aria-orientation")).toBeNull();
+  });
+});
+
+describe("Separator — DG-OVF-07: never leftover space", () => {
+  it("cannot grow or shrink (flex: none discipline on the painting edge)", () => {
+    const { container } = renderWithProviders(<Separator />);
+    const separator = getSeparator(container);
+    // The raw primitive it replaced declares `flex: 1` — the defect DG-OVF-07
+    // measures — so both ends of the flex story are pinned here.
+    expect(declared(separator, "flex-grow")).toEqual(["0"]);
+    expect(declared(separator, "flex-shrink")).toEqual(["0"]);
+  });
+});
+
+describe("Separator — consumer eject stays the last word (STD-EJECT-LAST)", () => {
+  it("an explicit backgroundColor prop wins over the house paint", () => {
+    const { container } = renderWithProviders(<Separator backgroundColor="$red9" />);
+    const separator = getSeparator(container);
+    expect(declared(separator, "background-color")).toEqual(["var(--red9)"]);
+  });
+});

package/src/Separator/Separator.stories.tsx

@@ -0,0 +1,61 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Text, XStack, YStack } from "tamagui";
+import { sectionHeading } from "../componentColors";
+import { Separator } from "./index";
+
+const meta: Meta<typeof Separator> = {
+  title: "Components/Separator",
+  component: Separator,
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "House rule between content groups: a painted 1px line in $borderColor " +
+          "(tamagui-rendered-reference §7.3 — 1px, never 0.5px). The quiet variant dims " +
+          "with opacity 0.5 rather than a lighter colour; vertical rules are 1px wide.",
+      },
+    },
+  },
+  argTypes: {
+    vertical: { control: "boolean", description: "1px-wide vertical rule" },
+    quiet: { control: "boolean", description: "Half-opacity rule (never a lighter colour)" },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Separator>;
+
+export const Default: Story = {
+  name: "Main",
+  render: (args) => (
+    <YStack width={420} gap="$3">
+      <Text {...sectionHeading}>Group title</Text>
+      <Separator {...args} />
+      <Text>Content under the rule — the separator paints, it is not a 1px gap.</Text>
+    </YStack>
+  ),
+};
+
+export const Quiet: Story = {
+  args: { quiet: true },
+  render: (args) => (
+    <YStack width={420} gap="$3">
+      <Separator />
+      <Text>Between a default rule…</Text>
+      <Separator {...args} />
+      <Text>…and a quiet one: same colour, half the opacity.</Text>
+    </YStack>
+  ),
+};
+
+export const Vertical: Story = {
+  args: { vertical: true },
+  render: (args) => (
+    <XStack height={44} alignItems="center" gap="$3">
+      <Text>Start</Text>
+      <Separator {...args} />
+      <Text>End</Text>
+    </XStack>
+  ),
+};