@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/Button/index.tsx

@@ -2,22 +2,30 @@ import {
   createElement,
   isValidElement,
   useCallback,
+  useId,
   useState,
   type ComponentType,
   type ReactNode,
 } from "react";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  MIN_PRESS_TARGET,
+  pressTargetHitSlop,
+  solidButtonIntents,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import { useFormField } from "../shared/utils";
 import {
   Button as TamaguiButton,
   type ButtonProps as TamaguiButtonProps,
   SizableText,
   View,
+  YStack,
   Theme,
-  Spinner,
   styled,
   isWeb,
+  useTheme,
 } from "tamagui";
+import { Spinner } from "../Spinner";
 import type { ThemeName } from "@tamagui/web";
 import type { GestureResponderEvent } from "react-native";
 import type { AnyFormApi } from "../types";
@@ -25,9 +33,33 @@ import { Store, useStore } from "@tanstack/react-store";
 import { getSpace } from "@tamagui/get-token";
 import { themeableVariants } from "@tamagui/stacks";
 import type { SizeTokens, VariantSpreadExtras } from "@tamagui/web";
+import { formatActionLabel } from "../actionLabel";
 import { formButtonColors, formCommonColors } from "../shared/colorRamps";
+import { warnBareDisabled, warnPositiveTabIndex } from "../shared/devWarn";
 import { useControlGrouped } from "../shared/groupContext";
 
+/** Tamagui size-token → px (matches theme elevation comment: $2=28, $4=44). */
+function sizeTokenPx(size: SizeTokens | number | undefined): number {
+  if (typeof size === "number") return size;
+  if (size == null) return MIN_PRESS_TARGET;
+  const map: Record<string, number> = {
+    $1: 20,
+    "$1.5": 24,
+    $2: 28,
+    "$2.5": 32,
+    $3: 36,
+    "$3.5": 40,
+    $4: 44,
+    $true: 44,
+    $5: 52,
+    $6: 64,
+  };
+  return map[String(size)] ?? MIN_PRESS_TARGET;
+}
+
+/** DG-ACT-01 role within an ActionBar / action region. */
+export type ButtonActionRole = "primary" | "secondary" | "chrome";
+
 type IconLike = ReactNode | ComponentType<{ size?: number }>;
 
 /** Many call sites pass Phosphor `Icon` (component) instead of `<Icon />`. */
@@ -45,10 +77,20 @@ function normalizeButtonIcon(icon: IconLike | undefined): ReactNode {
 
 const getButtonSized = (val: SizeTokens | number, { props }: VariantSpreadExtras<any>) => {
   if (!val || props.circular) return;
+  // DG-LAY-04 / SP-FIXED: size knob may shrink chrome ($3=36) but the press
+  // target never drops below 44 — minHeight holds the floor.
   if (typeof val === "number") {
-    return { paddingHorizontal: val * 0.25, height: val };
+    return {
+      paddingHorizontal: val * 0.25,
+      height: Math.max(val, MIN_PRESS_TARGET),
+      minHeight: MIN_PRESS_TARGET,
+    };
   }
-  return { paddingHorizontal: getSpace(val), height: val };
+  return {
+    paddingHorizontal: getSpace(val),
+    height: val,
+    minHeight: MIN_PRESS_TARGET,
+  };
 };
 
 const textAccentLow = {
@@ -68,16 +110,16 @@ const ButtonFrame = styled(View, {
   alignItems: "center",
   flexWrap: "nowrap",
   flexDirection: "row",
-  backgroundColor: formButtonColors.background.base,
-  borderWidth: 1,
-  borderColor: formButtonColors.border.base,
+  backgroundColor: "$background",
+  borderColor: "$borderColor",
   hoverStyle: {
-    backgroundColor: formButtonColors.background.hover,
+    backgroundColor: "$backgroundHover",
   },
   variants: {
     outlined: {
       true: {
         backgroundColor: "transparent",
+        borderWidth: 1,
         hoverStyle: { backgroundColor: "transparent" },
         pressStyle: { backgroundColor: "transparent" },
       },
@@ -111,6 +153,26 @@ export interface ButtonProps extends Omit<TamaguiButtonProps, "form" | "icon" |
   icon?: IconLike;
   iconAfter?: IconLike;
   compact?: boolean;
+  /**
+   * DG-ACT-02 / DG-COPY-03 — structured label. Used when `children` is omitted.
+   * Prefer `{ verb, noun }` over free-form strings for chrome actions.
+   */
+  verb?: string;
+  noun?: string;
+  /**
+   * DG-ACT-01 — marks the button for ActionBar one-primary DEV scans.
+   * Defaults to `"primary"` when `accent` is set.
+   */
+  actionRole?: ButtonActionRole;
+  /**
+   * DG-ST-03 hide / explain / upgrade — explains why the control is disabled.
+   * With `disabled`, the control switches to `aria-disabled` (stays focusable,
+   * presses swallowed) and renders the reason as visible adjacent text wired
+   * via `aria-describedby` — works without hover (Axiom 12; DG-OVL-05 bans
+   * hover-only tooltips on disabled). Required in DEV when passing `disabled`
+   * — bare `disabled` emits `bare-disabled`.
+   */
+  disabledReason?: string;
 }
 
 export function Button({
@@ -127,15 +189,34 @@ export function Button({
   disabled,
   theme,
   onPress,
+  onKeyDown,
   tabIndex,
   icon,
   iconAfter,
   compact,
+  verb,
+  noun,
+  actionRole,
+  disabledReason,
   ...props
 }: ButtonProps) {
   const { resolvedForm: formFromHook } = useFormField({ form: formProp });
   const resolvedForm = action ? formFromHook : undefined;
 
+  warnBareDisabled({
+    component: "Button",
+    id:
+      typeof (props as { id?: string }).id === "string" ? (props as { id?: string }).id : undefined,
+    disabled: Boolean(disabled),
+    disabledReason,
+    // loading / form-invalid are derived — not a bare unexplained disable.
+    skip: Boolean(loading),
+  });
+  warnPositiveTabIndex({
+    component: "Button",
+    value: typeof tabIndex === "number" ? tabIndex : undefined,
+  });
+
   const { isValid } = useStore(
     (resolvedForm?.store ?? dummyStore) as Store<{ isValid: boolean }>,
     (s) => ({ isValid: s.isValid ?? true }),
@@ -147,11 +228,15 @@ export function Button({
     (warning && "warning") ||
     (success && "success") ||
     undefined;
-  const { knobProps, control, text } = useResolvedKnobs({
+  const { knobProps, control, text, disabledState } = useResolvedKnobs({
     intent,
     component: "Button",
     compact,
   });
+  // Ring color resolved OUTSIDE the intent <Theme> wrapper below — the
+  // page-scope `$outlineColor` literal (DG-A11Y-01; see focusVisibleStyle).
+  const parentScopeTheme = useTheme();
+  const pageOutlineColor = parentScopeTheme.outlineColor?.val as string | undefined;
   const grouped = useControlGrouped();
   if (skeleton) {
     return (
@@ -169,17 +254,34 @@ export function Button({
   const isDisabled = disabled || loading || (action === "submit" && resolvedForm && !isValid);
 
   const handlePress = (e: GestureResponderEvent) => {
+    // Explained disable keeps the frame press-able (aria-disabled, focusable)
+    // so the activation guard lives here, not in pointerEvents.
+    if (isDisabled) return;
     if (action === "submit" && resolvedForm) resolvedForm.handleSubmit();
     if (action === "reset" && resolvedForm) resolvedForm.reset();
     onPress?.(e as Parameters<NonNullable<TamaguiButtonProps["onPress"]>>[0]);
   };
 
+  // Axiom 12 LEGIBLE FLOOR: the frame is a div[role=button], which gets no
+  // native Enter/Space activation. Synthesize a real click so activation
+  // bubbles exactly like a pointer press (composed asChild triggers included).
+  const handleKeyDown = (e: KeyboardEvent) => {
+    (onKeyDown as ((e: KeyboardEvent) => void) | undefined)?.(e);
+    if (e.defaultPrevented || e.repeat) return;
+    if (e.key !== "Enter" && e.key !== " ") return;
+    e.preventDefault(); // stop Space scroll / double native synthesis
+    if (isDisabled) return;
+    (e.currentTarget as unknown as HTMLElement | null)?.click?.();
+  };
+
   const activeThemeName = theme ?? intent;
   outlined = outlined ?? knobProps.outlined;
   const isLow = knobProps.textAccent === "low";
   const isMedium = knobProps.textAccent === "medium";
   const baseBorderWidth = knobProps.borderRadius.borderWidth;
-  const resolvedBorderWidth = baseBorderWidth > 0 ? Math.max(baseBorderWidth, 1) : outlined ? 1 : 0;
+  // Filled buttons are theme-driven and borderless unless a knob asks for one;
+  // outlined always keeps at least a 1px hairline.
+  const resolvedBorderWidth = outlined ? Math.max(baseBorderWidth, 1) : baseBorderWidth;
   const [hovering, setHovering] = useState(false);
   const [pressing, setPressing] = useState(false);
   const handlePressIn = useCallback(() => {
@@ -200,9 +302,14 @@ export function Button({
       ? formCommonColors.text
       : undefined;
 
+  const resolvedRole: ButtonActionRole | undefined = actionRole ?? (accent ? "primary" : undefined);
+  const labelFromParts =
+    children == null && verb != null ? formatActionLabel({ verb, noun }) : null;
+  const resolvedChildren = children ?? labelFromParts;
+
   const textContent = loading ? (
     <Spinner size="small" />
-  ) : typeof children === "string" ? (
+  ) : typeof resolvedChildren === "string" ? (
     <SizableText
       userSelect="none"
       flexGrow={0}
@@ -212,12 +319,15 @@ export function Button({
       overflow="hidden"
       {...knobProps.body}
       {...(textColor ? { color: textColor } : undefined)}
+      // LC-40: on the washed disabled chrome the label leaves the on-fill
+      // foreground and pins to the lowest AA tier (keepLabel keeps >=4.5:1).
+      {...(isDisabled ? disabledState.textKnobProps : undefined)}
       transition={knobProps.transition}
     >
-      {children}
+      {resolvedChildren}
     </SizableText>
   ) : (
-    children
+    resolvedChildren
   );
 
   const hasIcon = icon || iconAfter;
@@ -226,10 +336,36 @@ export function Button({
     <View flexShrink={0}>{normalizeButtonIcon(iconAfter)}</View>
   ) : null;
 
+  const explainedDisable = Boolean(disabledReason?.trim()) && Boolean(isDisabled);
+  const generatedId = useId();
+  const reasonId = explainedDisable
+    ? `${(props as { id?: string }).id ?? generatedId}-disabled-reason`
+    : undefined;
+  const isCircular = Boolean((props as { circular?: boolean }).circular);
+  const resolvedSize = (props as { size?: SizeTokens | number }).size ?? knobProps.sizeToken;
+  const visualPx = sizeTokenPx(resolvedSize);
+  // Circular tokens below 44 need an explicit box floor (circular variant also
+  // sets maxWidth/maxHeight to the token). hitSlop covers native/touch leftovers.
+  const circularPressFloor =
+    isCircular && visualPx < MIN_PRESS_TARGET
+      ? {
+          width: MIN_PRESS_TARGET,
+          height: MIN_PRESS_TARGET,
+          minWidth: MIN_PRESS_TARGET,
+          minHeight: MIN_PRESS_TARGET,
+          maxWidth: MIN_PRESS_TARGET,
+          maxHeight: MIN_PRESS_TARGET,
+          hitSlop: pressTargetHitSlop(visualPx),
+        }
+      : isCircular
+        ? { minWidth: MIN_PRESS_TARGET, minHeight: MIN_PRESS_TARGET }
+        : { minHeight: MIN_PRESS_TARGET };
   const buttonElement = (
     <ButtonFrame
-      disabled={isDisabled || false}
-      opacity={isDisabled ? 0.5 : 1}
+      // DG-ST-03: an explained disable is aria-disabled (focusable, press
+      // swallowed in handlePress) instead of a natively disabled dead end.
+      disabled={explainedDisable ? false : isDisabled || false}
+      opacity={1}
       transition={knobProps.transition}
       {...knobProps.borderRadius}
       borderWidth={resolvedBorderWidth}
@@ -237,6 +373,24 @@ export function Button({
       elevation={knobProps.elevation}
       outlined={outlined}
       {...(outlined ? { variant: "outlined" as const } : undefined)}
+      // Solid-intent sub-themes carry the on-fill foreground as `$color`
+      // (LC-05); outlined frames sit on the page, so re-anchor inherited
+      // text/icon color (currentColor) to the hue's readable text tier.
+      {...(outlined && intent && solidButtonIntents.has(intent)
+        ? { color: "$color11" }
+        : undefined)}
+      // LC-40 DISABLED-VISIBLE: keepLabel washes the chrome (muted fill/
+      // border) while label/glyphs re-anchor to the lowest AA text tier
+      // (`color` inherits into currentColor icons); dimWhole dims the
+      // button as its own assembly. Replaces the old hardcoded 0.5
+      // whole-dim that dropped label contrast under AA.
+      {...(isDisabled
+        ? {
+            ...disabledState.surfaceKnobProps,
+            ...disabledState.textKnobProps,
+            ...disabledState.assemblyKnobProps,
+          }
+        : undefined)}
       {...(isLow
         ? {
             onHoverIn: () => setHovering(true),
@@ -246,22 +400,53 @@ export function Button({
           }
         : undefined)}
       hoverStyle={{
-        backgroundColor: outlined ? "transparent" : formButtonColors.background.hover,
-        ...(outlined ? { borderColor: formButtonColors.border.hover } : undefined),
+        backgroundColor: outlined ? "transparent" : "$backgroundHover",
+        ...(outlined ? { borderColor: "$borderColorHover" } : undefined),
         ...control.hoverKnobProps,
         ...text.hoverKnobProps,
       }}
       pressStyle={{
-        backgroundColor: outlined ? "transparent" : formButtonColors.background.active,
-        ...(outlined ? { borderColor: formButtonColors.border.active } : undefined),
+        backgroundColor: outlined ? "transparent" : "$backgroundPress",
+        ...(outlined ? { borderColor: "$borderColorPress" } : undefined),
         ...control.pressKnobProps,
         ...text.pressKnobProps,
       }}
       focusStyle={{}}
-      focusVisibleStyle={{}}
+      // DG-A11Y-01: the house focus-visible ring (recipe-supplied, ≥2px) —
+      // was `{{}}`, which left only the browser default. The color is the
+      // PARENT-scope `$outlineColor` literal: intent buttons re-theme the
+      // frame (<Theme name="accent">…), and those sub-themes derive a ring
+      // for their own inverted surfaces — invisible on the page the ring
+      // actually draws on (measured 1.17:1 on the accent pagination button).
+      focusVisibleStyle={{
+        ...control.focusVisibleKnobProps,
+        ...(pageOutlineColor ? { outlineColor: pageOutlineColor } : undefined),
+      }}
       onPress={handlePress}
+      {...(isWeb ? { onKeyDown: handleKeyDown as unknown as () => void } : undefined)}
       {...(tabIndex != null ? { tabIndex } : undefined)}
       {...props}
+      {...circularPressFloor}
+      {...(explainedDisable
+        ? {
+            // No `title`: hover-only reveals are banned on disabled controls
+            // (DG-OVL-05) — the reason renders as visible adjacent text.
+            "aria-disabled": true,
+            ...(isWeb ? { "aria-describedby": reasonId } : { accessibilityHint: disabledReason }),
+            cursor: "not-allowed",
+            // Hover/press keep the LC-40 washed chrome — an aria-disabled
+            // control must not light up like a pressable one.
+            hoverStyle: {
+              backgroundColor: outlined ? "transparent" : "$background",
+              ...disabledState.surfaceKnobProps,
+            },
+            pressStyle: {
+              backgroundColor: outlined ? "transparent" : "$background",
+              ...disabledState.surfaceKnobProps,
+            },
+            "data-mp-disabled-explained": "true",
+          }
+        : undefined)}
       {...(grouped
         ? {
             borderWidth: 0,
@@ -270,7 +455,8 @@ export function Button({
             height: "100%",
           }
         : undefined)}
-      gap={hasIcon && (children || textContent) ? "$2" : undefined}
+      gap={hasIcon && (resolvedChildren || textContent) ? "$2" : undefined}
+      {...(resolvedRole ? { "data-mp-action-role": resolvedRole } : undefined)}
     >
       {iconElement}
       {textContent}
@@ -278,10 +464,29 @@ export function Button({
     </ButtonFrame>
   );
 
+  // DG-ST-03 explain affordance: visible reason adjacent to the control —
+  // discoverable by pointer, touch, keyboard, and SR (aria-describedby)
+  // without any hover interaction (Axiom 12).
+  const explainedElement = explainedDisable ? (
+    <YStack gap="$1" flexShrink={1} data-mp-disabled-reason-wrapper="true">
+      {buttonElement}
+      <SizableText
+        id={reasonId}
+        size="$1"
+        color={formCommonColors.muted}
+        data-mp-disabled-reason="true"
+      >
+        {disabledReason}
+      </SizableText>
+    </YStack>
+  ) : (
+    buttonElement
+  );
+
   if (activeThemeName) {
-    return <Theme name={activeThemeName as ThemeName}>{buttonElement}</Theme>;
+    return <Theme name={activeThemeName as ThemeName}>{explainedElement}</Theme>;
   }
-  return buttonElement;
+  return explainedElement;
 }
 
 Button.Icon = TamaguiButton.Icon;

package/src/Chip/Chip.spec.tsx

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { Chip } from "./index";
+
+describe("Chip", () => {
+  it("renders its label", () => {
+    const result = renderWithProviders(<Chip>Tag</Chip>);
+    expect(result.findTextElement("Tag")).toBeDefined();
+  });
+
+  // UX-019 / Axiom 6 HONEST STATE: disabled must live in the a11y tree.
+  it("disabled chip exposes aria-disabled on its frame", () => {
+    const result = renderWithProviders(<Chip disabled>Muted</Chip>);
+    expect(result.container.querySelector("[aria-disabled='true']")).not.toBeNull();
+  });
+
+  it("enabled chip carries no aria-disabled", () => {
+    const result = renderWithProviders(<Chip>Live</Chip>);
+    expect(result.container.querySelector("[aria-disabled='true']")).toBeNull();
+  });
+
+  it("disabled chip removes the dismiss affordance", () => {
+    const onDismiss = vi.fn();
+    const result = renderWithProviders(
+      <Chip disabled onDismiss={onDismiss}>
+        Locked
+      </Chip>,
+    );
+    expect(result.container.querySelector("[aria-label='Remove']")).toBeNull();
+  });
+});

package/src/Chip/index.tsx

@@ -1,8 +1,14 @@
 import type { ReactNode } from "react";
 import { XIcon } from "@phosphor-icons/react";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  MIN_PRESS_TARGET,
+  pressTargetHitSlop,
+  pressTargetStyle,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
 import type { ColorTokens, GetProps } from "tamagui";
 import { Text, View, styled } from "tamagui";
+import { t } from "../shared/t";
 
 // ── Types ─────────────────────────────────────────────────────
 
@@ -21,24 +27,36 @@ export interface ChipProps {
 
 // ── Color mappings ────────────────────────────────────────────
 
+// Axiom 12 / WCAG 1.4.3 — chip text is small (12px) and must clear ≥4.5:1 on
+// its own tint. Step-11 text on the step-4 tint measured 3.5–4.1:1 in light
+// for EVERY hue (green 3.93, blue 4.00, red 4.07, orange 3.54, yellow 4.02),
+// so it failed the normal-text floor; step 11 on step 2 still fails green/
+// orange/yellow. Step-12 text is the only pairing that clears AA on the tint
+// in BOTH schemes (9–12:1 light, higher in dark) — DF-04.
 const colorMap: Record<ChipColor, { bg: ColorTokens; text: ColorTokens; border: ColorTokens }> = {
-  gray: { bg: "$color4", text: "$color11", border: "$color7" },
-  red: { bg: "$red4", text: "$red11", border: "$red7" },
-  green: { bg: "$green4", text: "$green11", border: "$green7" },
-  blue: { bg: "$blue4", text: "$blue11", border: "$blue7" },
-  yellow: { bg: "$yellow4", text: "$yellow11", border: "$yellow7" },
-  orange: { bg: "$orange4", text: "$orange11", border: "$orange7" },
-  purple: { bg: "$purple4", text: "$purple11", border: "$purple7" },
+  gray: { bg: "$color4", text: "$color12", border: "$color7" },
+  red: { bg: "$red4", text: "$red12", border: "$red7" },
+  green: { bg: "$green4", text: "$green12", border: "$green7" },
+  blue: { bg: "$blue4", text: "$blue12", border: "$blue7" },
+  yellow: { bg: "$yellow4", text: "$yellow12", border: "$yellow7" },
+  orange: { bg: "$orange4", text: "$orange12", border: "$orange7" },
+  purple: { bg: "$purple4", text: "$purple12", border: "$purple7" },
 };
 
 // ── Styled components ─────────────────────────────────────────
 
-const ChipFrame = styled(View, {
+/**
+ * Exported so chip-scale companions (e.g. the Tags "Add Tag" trigger) share
+ * the exact same size variants — height/padding/font stay in lockstep with
+ * Chip for every size token.
+ */
+export const ChipFrame = styled(View, {
   name: "Chip",
   flexDirection: "row",
   alignItems: "center",
   gap: "$1",
-  borderRadius: "$3",
+  // Radius comes from the knob spread in Chip (knobProps.borderRadius) so the
+  // borderRadius knob wins — no hardcoded base radius (same as Tags chips).
   paddingHorizontal: "$2.5",
   paddingVertical: "$1",
 
@@ -64,7 +82,7 @@ const ChipFrame = styled(View, {
   },
 });
 
-const ChipText = styled(Text, {
+export const ChipText = styled(Text, {
   name: "ChipText",
   fontSize: "$2",
   fontWeight: "500",
@@ -81,13 +99,22 @@ const ChipText = styled(Text, {
   } as const,
 });
 
+/** Icon size that pairs with each chip size (single source, shared with chip-scale triggers). */
+export function chipIconSize(size: ChipSize): number {
+  return size === "$2" ? 10 : size === "$3" ? 12 : 14;
+}
+
 const DismissButton = styled(View, {
   name: "ChipDismiss",
   cursor: "pointer",
   opacity: 0.7,
   borderRadius: "$1",
+  // Visual glyph stays ~icon-sized; DG-LAY-04 floor is applied at the call site
+  // via pressTargetStyle + compensating negative margin + hitSlop.
   padding: "$0.5",
-  marginRight: -4,
+  marginInlineEnd: -4,
+  alignItems: "center",
+  justifyContent: "center",
   hoverStyle: {
     opacity: 1,
     backgroundColor: "$color5",
@@ -96,20 +123,31 @@ const DismissButton = styled(View, {
     opacity: 0.9,
     backgroundColor: "$color6",
   },
+  focusVisibleStyle: {
+    opacity: 1,
+    outlineColor: "$outlineColor",
+    outlineWidth: 2,
+    outlineStyle: "solid",
+  },
 });
 
 // ── Chip Component ────────────────────────────────────────────
 
 export function Chip({
   children,
-  size = "$3",
+  size,
   variant = "subtle",
   color = "gray",
   onDismiss,
   disabled,
 }: ChipProps) {
-  const { knobProps } = useResolvedKnobs();
+  const { knobProps, disabledState } = useResolvedKnobs();
   const colors = colorMap[color];
+  // Chip geometry (padding/font/icon) follows the size knob through the
+  // shared size variants (Tags precedent, LC-18); an explicit size prop
+  // ejects. Control padding is size-derived (SP-PAD), so the space knob
+  // has no separate chip target.
+  const resolvedSize = size ?? (knobProps.sizeToken as ChipSize);
 
   const getBackgroundColor = (): ColorTokens | "transparent" => {
     switch (variant) {
@@ -124,28 +162,67 @@ export function Chip({
 
   const textColor = colors.text;
   const borderColor = variant === "outline" ? colors.border : "transparent";
-  const iconSize = size === "$2" ? 10 : size === "$3" ? 12 : 14;
+  const iconSize = chipIconSize(resolvedSize);
+  // Measured dismiss chrome ~14×14 at $3; expand to 44×44 without growing the pill.
+  const dismissVisual = iconSize + 2;
+  const dismissOutset = Math.max(0, Math.ceil((MIN_PRESS_TARGET - dismissVisual) / 2));
 
   return (
     <ChipFrame
-      size={size}
+      size={resolvedSize}
       variant={variant}
       backgroundColor={getBackgroundColor()}
-      borderColor={borderColor}
-      opacity={disabled ? 0.5 : 1}
       {...knobProps.borderRadius}
+      borderColor={borderColor}
+      // LC-40 DISABLED-VISIBLE: hue tint washes to the muted neutral tiers
+      // while the label pins to the lowest AA step (keepLabel); dimWhole
+      // dims the chip as its own assembly.
+      // Axiom 6 HONEST STATE (UX-019): the disabled state must also live in
+      // the a11y tree, not just the pixels — cross-platform `aria-disabled`
+      // (RN maps it to accessibilityState.disabled; no RN-prop DOM leak).
+      {...(disabled
+        ? {
+            "aria-disabled": true,
+            ...disabledState.surfaceKnobProps,
+            ...disabledState.assemblyKnobProps,
+          }
+        : undefined)}
+      overflow="visible"
     >
-      <ChipText size={size} color={textColor} {...knobProps.body}>
+      <ChipText
+        size={resolvedSize}
+        color={textColor}
+        {...knobProps.body}
+        {...(disabled ? disabledState.textKnobProps : undefined)}
+      >
         {children}
       </ChipText>
       {onDismiss && !disabled && (
         <DismissButton
+          role="button"
+          aria-label={t("Remove")}
+          tabIndex={0}
+          // Dismiss is R-BINARY (spec Chip dismiss): square in the radius
+          // `none` world, a full circle everywhere else — the fixed $1 arc
+          // was knob-dead on both legs (UX-P06 "ChipDismiss br=3").
+          borderRadius={knobProps.pointy ? 0 : 1000}
+          {...pressTargetStyle()}
+          marginVertical={-dismissOutset}
+          marginHorizontal={-dismissOutset}
+          hitSlop={pressTargetHitSlop(dismissVisual)}
           onPress={(e) => {
             e.stopPropagation?.();
             onDismiss();
           }}
-          accessibilityRole="button"
-          accessibilityLabel="Remove"
+          onKeyDown={
+            ((e: KeyboardEvent) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                e.stopPropagation();
+                onDismiss();
+              }
+            }) as unknown as () => void
+          }
         >
           <XIcon size={iconSize} color={textColor as string} />
         </DismissButton>