@astryxdesign/core 0.6.1 → 0.6.2-canary.0faf070

package/src/FileInput/FileInput.spec.md

@@ -0,0 +1,199 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:FileInput
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-14
+owners: [cixzhang, imdreamrunner]
+review_triggers: [theming]
+verified_by:
+  [
+    packages/core/src/FileInput/FileInput.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:input-fields]
+design_specs: []
+architecture: [architecture:component-theming-surface]
+contributing: []
+system_specs: []
+---
+
+# FileInput component contract
+
+## Intent
+
+FileInput presents a labelled file-selection field in compact input or dropzone
+form. This contract records its current consumer anatomy and approves separate theme
+ownership for the upload affordance that FileInput paints through Icon.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive public theming target; no existing target,
+  runtime default, DOM, prop, interaction, or accessibility behavior changes
+- Controlled/uncontrolled behavior: unchanged; FileInput remains controlled
+- Migration decision: `component:FileInput/DEC-1`
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The visible file-selection surface and its input/dropzone mode.
+- Whether, where, and at what default size the upload affordance appears.
+- Reflecting FileInput's mode on its locally owned theme targets.
+
+**Does not own / non-goals**
+
+- The upload artwork or Icon's base color, size, and accessibility semantics —
+  owned by `component:Icon`.
+- Label, description, clear-control, and validation-message presentation — owned
+  by `component:Field` and `component:FieldStatus`.
+- Loading-indicator presentation — owned by `component:Spinner`.
+- A new prop, variant, icon slot, or custom property.
+
+## Public concepts
+
+No consumer prop changes. The `file-input-icon` target gives themes a
+same-element seam for the Upload icon and reflects the existing `mode` axis. The
+existing `file-input` target remains on the visible selection surface and keeps
+its `mode` and `status` axes.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                                                                                                                                                  | Basis                                             | Review state                    |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------- |
+| FR1 | The visible selection surface carries `file-input` and reflects the existing `mode` and resolved status.                                                                                                             | Current source, public docs, and focused tests    | Verified current behavior       |
+| FR2 | When not loading, input mode renders an upload affordance at the small Icon size. Dropzone mode renders it at the medium Icon size only while no file is selected.                                                   | Current source and focused tests                  | Verified current behavior       |
+| FR3 | Icon owns the rendered glyph's base size, color, and accessibility semantics; FileInput owns the affordance's mode-dependent placement and default size.                                                             | Current composition and component boundaries      | Verified current composition    |
+| FR4 | The rendered upload affordance MUST carry `file-input-icon` with the existing `mode` reflected, so a theme can restyle the glyph box without structural selectors or changing every Icon that uses the same artwork. | Owner-approved target contract                    | Approved additive contract      |
+| FR5 | Adding the target MUST NOT change the default artwork, computed layout, interaction, file-selection behavior, accessible name, or decorative Icon semantics.                                                         | Compatibility policy and focused regression tests | Required compatibility behavior |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may change standard visual
+  properties such as the upload glyph's size or color through
+  `file-input-icon`; FileInput still owns whether and where the affordance renders.
+- **AV2 — Artwork.** Icon registry and future icon-slot decisions may change the
+  artwork without changing this CSS target's ownership of the painted glyph box.
+
+### Representative states
+
+| State                    | Required invariant                                                       | Allowed variation                       |
+| ------------------------ | ------------------------------------------------------------------------ | --------------------------------------- |
+| Input, empty or selected | Small upload affordance renders on the input surface when not loading.   | Files, placeholder, status, theme paint |
+| Dropzone, empty          | Medium upload affordance renders above the placeholder when not loading. | Drag state, placeholder, theme paint    |
+| Dropzone, selected       | File names replace the upload affordance.                                | File names and status                   |
+| Loading                  | Spinner replaces the upload affordance.                                  | Mode and loading presentation           |
+
+### Transformation and precedence order
+
+- **ORD1 — Content selection.** Resolve loading and selected-file state, choose
+  input or dropzone content, then render the mode-sized upload affordance only in
+  the states recorded by FR2.
+- **ORD2 — Theme composition.** Icon applies its base size and color, then the
+  same-element FileInput target participates in the existing theme layer and
+  standard Icon styling merge order.
+
+### Performance and resources
+
+- **PR1 — No new work.** The additive target performs no measurement, listener,
+  observer, state update, or additional render pass.
+
+## Accessibility contract
+
+The upload affordance remains decorative. The existing focusable file-selection
+trigger, label, description, required/invalid state, disabled explanation, and
+selection announcements remain unchanged.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                  | Representation authority                 | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | ------------------ |
+| Drop zone        | Presents the visible file-selection surface in input or dropzone form.              | Current source and public docs           | Prominent      | FR1                |
+| Upload icon      | Hints at the upload action and changes default size with the selected mode.         | Current source and owner-approved target | Supporting     | FR2, FR3, FR4      |
+| Shared feedback  | Uses Field, FieldStatus, and Spinner for labels, validation, and loading treatment. | Current shared composition               | Supporting     | FR5                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Label": {
+    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
+  },
+  "Description": {
+    "none": {
+      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
+    }
+  },
+  "Drop zone": {"target": "file-input"},
+  "Upload icon": {"target": "file-input-icon"},
+  "Placeholder": {"inherits": "file-input"},
+  "File name display": {"inherits": "file-input"},
+  "Clear button": {
+    "delegatesTo": {
+      "owner": "component:Field",
+      "target": "input-clear-button"
+    }
+  },
+  "Spinner": {
+    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
+  },
+  "Status message": {
+    "delegatesTo": {
+      "owner": "component:FieldStatus",
+      "target": "field-status"
+    }
+  }
+}
+```
+
+The `file-input-icon` disposition records the approved target state. Icon still
+owns the general `icon` target and base glyph semantics; FileInput's narrower
+target owns only this stable upload position and its existing mode distinction.
+
+## Family and system relationships
+
+- `family:input-fields` owns shared labelled-field and validation behavior.
+- `architecture:component-theming-surface` owns target qualification, anatomy
+  mapping, and the requirement that public targets sit on stable painted parts.
+- Field, FieldStatus, Icon, and Spinner retain their existing public target
+  contracts when composed by FileInput.
+
+## Verification map
+
+| Contract            | Verification                                                      | Representative states                              | Mutation or failure expectation                                                                             | Audit section             |
+| ------------------- | ----------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1, FR2            | `FileInput.test.tsx` rendering and target suites                  | Input/dropzone; empty/selected/loading             | Moving the root target or changing when/at what size the affordance renders breaks focused assertions.      | `audit:FileInput/theming` |
+| FR3, FR4, FR5       | `FileInput.test.tsx`, `themingTargets.test.ts`, probe-theme check | Both modes and same-element Icon target            | Missing the target, reflecting the wrong mode, or moving it off the glyph fails source/docs/probe coverage. | `audit:FileInput/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                     | Nine anatomy entries and two locally owned targets | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation.                             | `audit:FileInput/anatomy` |
+
+## Decision log
+
+### DEC-1 — Upload icon is stable FileInput theme anatomy
+
+**Reference:** `component:FileInput/DEC-1`
+**Decider:** cixzhang, 2026-09-14
+
+The upload icon is a stable, consumer-recognizable FileInput affordance whose
+mode-dependent placement and default size belong to FileInput. It receives the
+`file-input-icon` target on the same Icon element that paints the glyph, while
+Icon retains its general target and base glyph semantics.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or shared-component contracts. It links to their owners.

package/src/FileInput/FileInput.test.tsx

@@ -119,6 +119,20 @@ describe('FileInput', () => {
     expect(screen.getByText('Drop here')).toBeInTheDocument();
   });
 
+  it.each([
+    {mode: 'input' as const, size: 'sm'},
+    {mode: 'dropzone' as const, size: 'md'},
+  ])('exposes the upload icon as a $mode theme target', ({mode, size}) => {
+    render(
+      <FileInput label="Upload" mode={mode} value={null} onChange={() => {}} />,
+    );
+
+    const icon = document.querySelector('.astryx-file-input-icon');
+    expect(icon).toHaveClass('astryx-icon');
+    expect(icon).toHaveAttribute('data-mode', mode);
+    expect(icon).toHaveAttribute('data-size', size);
+  });
+
   it('displays selected file name', () => {
     const file = createFile('report.pdf', 1024, 'application/pdf');
     render(<FileInput label="Document" value={file} onChange={() => {}} />);

package/src/FileInput/FileInput.tsx

@@ -5,7 +5,7 @@
 /**
  * @file FileInput.tsx
  * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
- * @output Exports FileInput component, FileInputProps, FileInputStatus
+ * @output Exports FileInput component, public types, and its root/icon theme targets
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
  * SYNC: When modified, update these files to stay in sync:
@@ -707,7 +707,12 @@ export function FileInput({
     }
     return (
       <>
-        <Icon icon="arrowUp" size="md" color="secondary" />
+        <Icon
+          icon="arrowUp"
+          size="md"
+          color="secondary"
+          {...themeProps('file-input-icon', {mode})}
+        />
         <span {...stylex.props(styles.placeholderText)}>
           {isDragOver ? t('@astryx.fileInput.dropHint') : displayPlaceholder}
         </span>
@@ -728,7 +733,12 @@ export function FileInput({
     }
     return (
       <>
-        <Icon icon="arrowUp" size="sm" color="secondary" />
+        <Icon
+          icon="arrowUp"
+          size="sm"
+          color="secondary"
+          {...themeProps('file-input-icon', {mode})}
+        />
         <span
           {...stylex.props(
             hasFiles ? styles.fileNameText : styles.placeholderText,

package/src/Kbd/Kbd.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
       name: 'keys',
       type: 'string',
       description:
-        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape and return for enter.',
       required: true,
     },
     {
@@ -72,7 +72,7 @@ export const docsZh = {
       name: 'keys',
       type: 'string',
       description:
-        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right。',
+        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right、plus。别名：esc 等同于 escape，return 等同于 enter。',
       required: true,
     },
     {
@@ -122,7 +122,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape, return for enter.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
     className: 'CSS class for root element. Prefer xstyle; className for non-StyleX integration.',
     style: 'Inline styles for root element. Prefer xstyle; inline styles bypass StyleX optimization.',

package/src/Kbd/Kbd.test.tsx

@@ -10,13 +10,14 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect, afterEach} from 'vitest';
+import {describe, it, expect, afterEach, vi} from 'vitest';
 import {Kbd} from './Kbd';
 
 describe('Kbd', () => {
   const originalPlatform = navigator.platform;
 
   afterEach(() => {
+    vi.restoreAllMocks();
     // Restore platform after any test that spoofs it \u2014 ensures no
     // test pollution even if an assertion fails mid-test.
     Object.defineProperty(navigator, 'platform', {
@@ -72,6 +73,61 @@ describe('Kbd', () => {
     expect(screen.getByText('Esc')).toBeInTheDocument();
   });
 
+  it.each([
+    {alias: 'esc', display: 'Esc', label: 'Escape'},
+    {alias: 'return', display: '\u21B5', label: 'Enter'},
+  ])('normalizes the $alias key alias', ({alias, display, label}) => {
+    render(<Kbd keys={alias} />);
+    expect(screen.getByText(display)).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAttribute('aria-label', label);
+  });
+
+  it.each([
+    {alias: 'esc', canonical: 'escape'},
+    {alias: 'return', canonical: 'enter'},
+  ])('$alias renders identically to $canonical', ({alias, canonical}) => {
+    const {container, rerender} = render(<Kbd keys={canonical} />);
+    const text = container.textContent;
+    const label = screen.getByRole('img').getAttribute('aria-label');
+    rerender(<Kbd keys={alias} />);
+    expect(container.textContent).toBe(text);
+    expect(screen.getByRole('img').getAttribute('aria-label')).toBe(label);
+  });
+
+  it.each([
+    {keys: 'ctrl + ESC', display: 'Esc', label: 'Control + Escape'},
+    {keys: 'shift + RETURN', display: '\u21B5', label: 'Shift + Enter'},
+  ])('normalizes aliases inside the $keys combo', ({keys, display, label}) => {
+    render(<Kbd keys={keys} />);
+    expect(screen.getByText(display)).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAttribute('aria-label', label);
+  });
+
+  it('keeps child keys unique after alias normalization', () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+    const {container} = render(
+      <Kbd keys="escape+esc+ESC+enter+return+return" />,
+    );
+    expect(consoleError).not.toHaveBeenCalled();
+    expect(
+      Array.from(container.querySelectorAll('kbd'), key => key.textContent),
+    ).toEqual(['Esc', 'Esc', 'Esc', '↵', '↵', '↵']);
+  });
+
+  it.each(['constructor', '__proto__'])(
+    'renders the unknown %s key without consulting object prototypes',
+    key => {
+      render(<Kbd keys={key} />);
+      expect(screen.getByText(key.toUpperCase())).toBeInTheDocument();
+      expect(screen.getByRole('img')).toHaveAttribute(
+        'aria-label',
+        key.toUpperCase(),
+      );
+    },
+  );
+
   it('exposes a spoken accessible name and hides the glyphs (obs-1)', () => {
     render(<Kbd keys="mod+shift+k" />);
     // The wrapper carries a screen-reader name built from spoken key labels

package/src/Kbd/Kbd.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file Kbd.tsx
- * @input Uses React, StyleX, theme tokens
- * @output Exports Kbd component and KbdProps
+ * @input Uses React, StyleX, theme tokens, shortcut key names and aliases
+ * @output Exports Kbd component and KbdProps with canonical shortcut labels
  * @position Core implementation; renders styled keyboard shortcut indicators
  *
  * SYNC: When modified, update:
@@ -61,20 +61,25 @@ const styles = stylex.create({
  * Note: `mod` is not in this map — it resolves dynamically via platform
  * detection inside the component.
  */
-const KEY_DISPLAY: Record<string, string> = {
-  ctrl: '\u2303', // ⌃
-  alt: '\u2325', // ⌥
-  shift: '\u21E7', // ⇧
-  enter: '\u21B5', // ↵
-  backspace: '\u232B', // ⌫
-  escape: 'Esc',
-  tab: '\u21E5', // ⇥
-  up: '\u2191',
-  down: '\u2193',
-  left: '\u2190',
-  right: '\u2192',
-  plus: '+',
-};
+const KEY_DISPLAY = new Map<string, string>([
+  ['ctrl', '\u2303'], // ⌃
+  ['alt', '\u2325'], // ⌥
+  ['shift', '\u21E7'], // ⇧
+  ['enter', '\u21B5'], // ↵
+  ['backspace', '\u232B'], // ⌫
+  ['escape', 'Esc'],
+  ['tab', '\u21E5'], // ⇥
+  ['up', '\u2191'],
+  ['down', '\u2193'],
+  ['left', '\u2190'],
+  ['right', '\u2192'],
+  ['plus', '+'],
+]);
+
+const KBD_KEY_ALIASES = new Map<string, string>([
+  ['esc', 'escape'],
+  ['return', 'enter'],
+]);
 
 /**
  * Resolves a key name to its display string. Handles the platform-aware
@@ -85,7 +90,7 @@ function getKeyDisplay(key: string, isMac: boolean): string {
   if (key === 'mod') {
     return isMac ? '\u2318' : 'Ctrl';
   }
-  return KEY_DISPLAY[key] ?? key.toUpperCase();
+  return KEY_DISPLAY.get(key) ?? key.toUpperCase();
 }
 
 /**
@@ -93,26 +98,26 @@ function getKeyDisplay(key: string, isMac: boolean): string {
  * (⌘, ⇧, ↵, …) that assistive tech cannot announce meaningfully, so the
  * accessible name for the shortcut is built from these words instead.
  */
-const KEY_LABEL: Record<string, string> = {
-  ctrl: 'Control',
-  alt: 'Alt',
-  shift: 'Shift',
-  enter: 'Enter',
-  backspace: 'Backspace',
-  escape: 'Escape',
-  tab: 'Tab',
-  up: 'Up arrow',
-  down: 'Down arrow',
-  left: 'Left arrow',
-  right: 'Right arrow',
-  plus: 'Plus',
-};
+const KEY_LABEL = new Map<string, string>([
+  ['ctrl', 'Control'],
+  ['alt', 'Alt'],
+  ['shift', 'Shift'],
+  ['enter', 'Enter'],
+  ['backspace', 'Backspace'],
+  ['escape', 'Escape'],
+  ['tab', 'Tab'],
+  ['up', 'Up arrow'],
+  ['down', 'Down arrow'],
+  ['left', 'Left arrow'],
+  ['right', 'Right arrow'],
+  ['plus', 'Plus'],
+]);
 
 function getKeyLabel(key: string, isMac: boolean): string {
   if (key === 'mod') {
     return isMac ? 'Command' : 'Control';
   }
-  return KEY_LABEL[key] ?? key.toUpperCase();
+  return KEY_LABEL.get(key) ?? key.toUpperCase();
 }
 
 function subscribeToPlatformChanges(): () => void {
@@ -127,7 +132,9 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
   ref?: React.Ref<HTMLSpanElement>;
   /**
    * Keyboard shortcut string. Use "+" to separate keys.
-   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.
+   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape,
+   * tab, up, down, left, and right.
+   * Aliases: "esc" for "escape" and "return" for "enter".
    * Use "plus" to render a literal "+" key (e.g. "shift+plus").
    *
    * @example
@@ -163,11 +170,24 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
     getServerPlatformSnapshot,
   );
 
-  const parts = keys.split('+').map(key => key.trim().toLowerCase());
+  const keyOccurrences = new Map<string, number>();
+  const parts = keys
+    .split('+')
+    .map(key => key.trim().toLowerCase())
+    .map(sourceKey => {
+      const occurrence = keyOccurrences.get(sourceKey) ?? 0;
+      keyOccurrences.set(sourceKey, occurrence + 1);
+      return {
+        key: KBD_KEY_ALIASES.get(sourceKey) ?? sourceKey,
+        reactKey: `${sourceKey}:${occurrence}`,
+      };
+    });
 
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
   // the visual glyphs below are announced meaninglessly by assistive tech.
-  const accessibleName = parts.map(key => getKeyLabel(key, isMac)).join(' + ');
+  const accessibleName = parts
+    .map(({key}) => getKeyLabel(key, isMac))
+    .join(' + ');
 
   return (
     <span
@@ -181,8 +201,8 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
         className,
         style,
       )}>
-      {parts.map(key => (
-        <kbd key={key} aria-hidden="true" {...stylex.props(styles.kbd)}>
+      {parts.map(({key, reactKey}) => (
+        <kbd key={reactKey} aria-hidden="true" {...stylex.props(styles.kbd)}>
           {getKeyDisplay(key, isMac)}
         </kbd>
       ))}

package/src/Link/Link.doc.mjs

@@ -164,6 +164,17 @@ export const docs = {
     },
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Link text',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Link text must have at least 4.5:1 contrast with the background behind it. For Pointer down, measure against the pressed overlay the link paints behind its text.',
+      },
+    ],
     description:
       'A styled anchor for inline and standalone text navigation. Supports external links, underline variants, tooltips, and custom link components for router integration. Use it for navigating between pages or to external URLs.',
     bestPractices: [

package/src/Link/Link.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {fireEvent, render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {Link} from './Link';
 import {LinkProvider} from './LinkProvider';
 
@@ -417,3 +418,26 @@ describe('Link', () => {
     expect(link).toHaveAttribute('data-color', 'secondary');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay behind a link while it is pressed', () => {
+    render(<Link href="/docs">Docs</Link>);
+    expect(hasPressedArm(screen.getByRole('link', {name: 'Docs'}))).toBe(true);
+  });
+
+  it('paints it on the button form too', () => {
+    render(<Link onClick={() => {}}>Open</Link>);
+    expect(hasPressedArm(screen.getByRole('button', {name: 'Open'}))).toBe(
+      true,
+    );
+  });
+
+  it('does not press a disabled link', () => {
+    render(
+      <Link href="/docs" isDisabled>
+        Docs
+      </Link>,
+    );
+    expect(hasPressedArm(screen.getByText('Docs').closest('a')!)).toBe(false);
+  });
+});

package/src/Link/Link.tsx

@@ -45,6 +45,7 @@ import {computeTargetAndRel} from './computeTargetAndRel';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -368,6 +369,9 @@ export function Link({
             styles.base,
             styles.buttonReset,
             linkColorStyles[color],
+            // The system's pressed overlay behind the text; the hover stays the
+            // colour change above, so a press is the one background it paints.
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,
@@ -427,6 +431,7 @@ export function Link({
           focusOutlineProps.focusVisible(
             styles.base,
             linkColorStyles[color],
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,