Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Link): a hovered label takes the root's hover color, matching its underline and icon (#10142)

Cindy Zhangeaea67de3568
diff --git a/.changeset/link-hover-label-color.md b/.changeset/link-hover-label-color.md
new file mode 100644
index 0000000000..caf9bbb648
--- /dev/null
+++ b/.changeset/link-hover-label-color.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Link: the label now takes the link's own color, at rest and on hover, so on hover a `primary`, `secondary`, or `accent` Link tints its text with its underline and external-link icon. Before, only the underline and the icon took the hover tint. A theme override on the `text` target (for example `text[data-color="accent"]`) no longer reaches Link labels: restyle Link labels through the `link` target. A theme that styles the `text` target's color now also keeps any Text with `color="inherit"` on its parent's color.
+
+@cixzhang
diff --git a/docs/specs/components/Link/Link.spec.md b/docs/specs/components/Link/Link.spec.md
index bd13d455f4..59323fbfb3 100644
--- a/docs/specs/components/Link/Link.spec.md
+++ b/docs/specs/components/Link/Link.spec.md
@@ -15,6 +15,7 @@ verified_by:
packages/core/src/Link/Link.test.tsx,
packages/core/src/Link/__tests__/Link.a11y.test.tsx,
packages/core/src/Link/__tests__/Link.a11y.chromium.spec.ts,
+ packages/core/src/Link/__tests__/Link.hoverColor.a11y.chromium.spec.ts,
packages/core/src/Link/__tests__/Link.navigation.a11y.chromium.spec.ts,
packages/core/src/Link/__tests__/Link.truncation.a11y.chromium.spec.ts,
packages/core/src/Link/__tests__/Link.wrappedLines.a11y.chromium.spec.ts,
@@ -41,7 +42,7 @@ system_specs: [spec:AST-005, spec:AST-085]
| Public contract | None changes. Link takes `href`, `as`, `label`, `onClick`, `isDisabled`, `isExternalLink`, `newTabLabel`, `target`, `rel`, `download`, `referrerPolicy`, `hasUnderline`, `isStandalone`, `tooltip`, Text props, and `children`. |
| Behavior | An enabled Link with `href` is a link rendered by `as`, then `LinkProvider`, then a native anchor. Otherwise it is a link-styled `<button>`, except that an inherited link role renders the link component, and a disabled Link with `href` and no `onClick` renders a plain anchor unless an inherited button role makes it a disabled `<button>` (FR1). A disabled Link stays focusable and inert. |
| End-user impact | People get one link look for navigation and link-styled actions. Keyboard and screen-reader users can reach a disabled Link and hear that it is disabled. External links without `label` announce that they open a new tab. |
-| Builder impact | None. |
+| Builder impact | A theme restyles Link's label color through the `link` target; a `text` target color no longer reaches it. |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A focused link that becomes disabled loses focus, caller attributes can replace Link's disabled exposure and `data-color`, and an ancestor Text line clamp cannot truncate a Link; all are listed under Current-state impact. |
| Review checks | Reject a disabled Link that navigates, runs `onClick`, or leaves the tab order; a `_blank` target without `noopener noreferrer`; an external link with no new-tab text; or a rejected destination that reaches a router. |
| Governing rules | `family:navigation-destinations` FR1–FR7; `spec:AST-005`; `spec:AST-085` FR1, FR2, FR4, FR5; `architecture:interaction-modality` INV1; `design:user-states` DR1, DR2. |
@@ -60,7 +61,8 @@ Consumer usage lives in `Link.doc.mjs`.
- Released default preserved: `yes`; `color="accent"`, `type="body"`,
`display="inline"`, `maxLines={0}`, no underline at rest
- Compatibility class: records shipped behavior; no public prop, default,
- export, or DOM change
+ export, or DOM change; the label inherits the root's color, so a theme restyles
+ Link's color through the `link` target, not the `text` target
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
@@ -109,8 +111,8 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR3 | An external Link that is not rendered as a button shows a trailing extra-small external-link icon that inherits the root's color, followed by visually hidden new-tab text: `newTabLabel`, else the localized default. | Current source and tests |
| FR4 | A destination reaches the link component only through the shared navigation rule; a rejected destination renders an inert anchor and never invokes a router. | `family:navigation-destinations` FR1–FR6; `spec:AST-005` |
| FR5 | A disabled Link stays focusable with `aria-disabled="true"`, never navigates, and never runs `onClick`. The disabled anchor form omits `href`, `target`, and `rel`, takes a Tab stop, and skips the custom link component. In every form, clicks are cancelled and stopped, Enter and Space are suppressed, other keys reach the caller's `onKeyDown`, and the Link paints at half opacity with no pointer events and no press paint. A focused Link that becomes disabled MUST keep focus and expose the change on that element (`spec:AST-085` FR4, FR5), and a caller `aria-disabled`, `role`, or `tabIndex` MUST NOT replace the disabled exposure (`architecture:public-component-api` INV5). Implementation gap: caller props spread after Link's own, so a caller `aria-disabled`, `role`, or `tabIndex` overrides them. Implementation gap: an enabled link renders through the safe link component and a disabled one as a plain anchor (or a `<button>` when it has `onClick`), so a focused link that becomes disabled (or re-enabled) is replaced and focus falls to the page. | `spec:AST-085` FR1, FR2, FR4, FR5; `family:navigation-destinations` FR7; current tests |
-| FR6 | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, line height, and text alignment and lays content out with a small gap; with `maxLines` above 0 it stops at its container, so its Text truncates inside a constrained line; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it. | Current source and tests |
-| FR7 | The root paints the chosen color for the six built-in colors, which the underline and the external icon take; the label's color comes from Text (FR6). On hover-capable pointers an enabled Link underlines on hover, and for `primary`, `secondary`, and `accent` the root color mixes in the hover tint. `hasUnderline` underlines at rest. | Current source and tests |
+| FR6 | Children render inside Text with `type` (default `body`), `size`, `weight`, `color` (default `accent`; for a color the root paints, FR7, the label inherits it), `display` (default `inline`), and `maxLines` (default `0`). The root inherits font family, size, weight, line height, and text alignment and lays content out with a small gap; with `maxLines` above 0 it stops at its container, so its Text truncates inside a constrained line; `isStandalone` sets the body size and leading on the root. A Link inside a Text with `maxLines` MUST truncate with that text. Implementation gap: the root is `inline-flex`, so an ancestor Text clamp does not truncate it. | Current source and tests |
+| FR7 | The root paints the chosen color for the six built-in colors, which the underline and the external icon take. The label inherits the root's color at rest and on hover; a theme styles Link's color through the `link` target. On hover-capable pointers an enabled Link underlines on hover, and for `primary`, `secondary`, and `accent` the root color mixes in the hover tint, so the label, the underline, and the icon keep one color. `hasUnderline` underlines at rest. | Current source and tests |
| FR8 | Press feedback follows `design:user-states` DR1 and DR2 for Link's text surface: an enabled link or button form paints the pressed overlay, and a disabled Link does not. | `design:user-states` DR1, DR2; current tests |
| FR9 | `label`, when non-empty, becomes `aria-label` and replaces the content as the accessible name; a caller `aria-label` overrides it; otherwise the content is the name. | Current tests |
| FR10 | With `tooltip`, Link renders inside a Tooltip that opens above it. | Current source and tests |
@@ -165,13 +167,13 @@ Consumer migration instructions belong in consumer docs and release notes.
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ---------------- | --------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Label | Text-colored label; underline on hover or always. | Current source and tests | Prominent | FR6, FR7 |
+| Label | Takes the root's color; underline on hover or always. | Current source and tests | Prominent | FR6, FR7 |
| External icon | Extra-small trailing icon that inherits the root's color. | Current source and tests | Supporting | FR3 |
| Disabled | Half opacity; no hover, press, or pointer interaction. | Current source and tests | Supporting | FR5 |
`design:user-states` governs Link's pressed overlay (FR8); no other design record
-governs Link. The root carries the `link` target, which paints the underline and the
-external icon; the label is a Text and takes its color from Text's `text` target
+governs Link. The root carries the `link` target, which paints the label, the underline, and
+the external icon; the label is a Text that inherits the root's color
(`architecture:component-theming-surface` INV5). The consumer anatomy names no root part, so this record
carries no anatomy-theming map.
@@ -187,19 +189,19 @@ carries no anatomy-theming map.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, AR1 | `Link.test.tsx` element-form, `as`, and provider cases; `Link.a11y.chromium.spec.ts` | Native, router, button form, disabled | A wrong element form or role fails. Evidence gap: no test renders Link under an inherited interactive role (FR1 (c)). | `audit:Link/anatomy` |
-| FR2, FR3, AR3 | `Link.test.tsx` external, target, rel, and new-tab cases; `Link.a11y.chromium.spec.ts` external state | External; explicit `_blank`; custom label | A missing safety token, icon, or new-tab text fails. Evidence gap: no test checks the accessible name of an external link with `label`. Evidence gap: no test sets `referrerPolicy` or asserts the external icon's size or color. | `audit:Link/accessibility` |
-| FR4 | `Link.navigation.a11y.chromium.spec.ts` | Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails. | `audit:Link/behavior` |
-| FR5, AR2 | `Link.test.tsx` disabled cases | Disabled anchor; disabled button form; with `onClick` | Navigation, a consumer `onClick`, a lost Tab stop, or a custom component on a disabled link fails. Evidence gap: no test disables a focused link or passes a caller `aria-disabled`, `role`, or `tabIndex`. Evidence gap: no test asserts that other keys reach the caller's `onKeyDown`, or the half-opacity, no-pointer-events paint. | `audit:Link/accessibility` |
-| FR6 (type) | `Link.test.tsx` text-type cases; `Link.wrappedLines.a11y.chromium.spec.ts` (wrapped text alignment) | Default `body`; `type="inherit"`; wrapped button and anchor forms in a start-aligned, right-to-left and centred line | A dropped Text `type` fails. `Link.truncation.a11y.chromium.spec.ts`: an anchor and a button Link with `maxLines={1}` in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that `size`, `weight`, `color`, or `display` reach Text, or the `isStandalone` root size. A button form whose wrapped lines line up differently from the anchor form fails. | `audit:Link/visual` |
-| FR6, FR7 (paint) | Evidence gap: the color, underline, and standalone cases assert only that a link renders; hover paint is untested | Each color; `hasUnderline`; `isStandalone` | — | `audit:Link/visual` |
-| FR8 | `Link.test.tsx` pressed-state suite | Link, button form, disabled | No press paint, or press paint on a disabled Link, fails. | `audit:Link/behavior` |
-| FR9, FR11, AR4 | `Link.test.tsx` label, ref, and theme-class cases | With and without `label`; `data-color` | A missing or extra `aria-label`, target, `data-color`, or ref fails. The accessibility suites assert a passed `data-*` attribute and `aria-current` on the root, and the navigation suite asserts `download`. Evidence gap: no test passes both `label` and `aria-label`, or passes `className`, `style`, or `xstyle`. | `audit:Link/theming` |
-| FR10 | Evidence gap: the tooltip case asserts only that the link renders | Tooltip | — | `audit:Link/accessibility` |
-| ORD1–ORD3 | Covered by the FR1–FR3 rows | — | — | `audit:Link/behavior` |
-| PR1, AR5 | Evidence gap: no test asserts the absence of per-link listeners or the focus indicator | — | — | `audit:Link/accessibility` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1, AR1 | `Link.test.tsx` element-form, `as`, and provider cases; `Link.a11y.chromium.spec.ts` | Native, router, button form, disabled | A wrong element form or role fails. Evidence gap: no test renders Link under an inherited interactive role (FR1 (c)). | `audit:Link/anatomy` |
+| FR2, FR3, AR3 | `Link.test.tsx` external, target, rel, and new-tab cases; `Link.a11y.chromium.spec.ts` external state | External; explicit `_blank`; custom label | A missing safety token, icon, or new-tab text fails. Evidence gap: no test checks the accessible name of an external link with `label`. Evidence gap: no test sets `referrerPolicy` or asserts the external icon's size or color. | `audit:Link/accessibility` |
+| FR4 | `Link.navigation.a11y.chromium.spec.ts` | Rejected and ordinary schemes; native, router, downloads | A rejected destination that navigates or reaches a router fails. | `audit:Link/behavior` |
+| FR5, AR2 | `Link.test.tsx` disabled cases | Disabled anchor; disabled button form; with `onClick` | Navigation, a consumer `onClick`, a lost Tab stop, or a custom component on a disabled link fails. Evidence gap: no test disables a focused link or passes a caller `aria-disabled`, `role`, or `tabIndex`. Evidence gap: no test asserts that other keys reach the caller's `onKeyDown`, or the half-opacity, no-pointer-events paint. | `audit:Link/accessibility` |
+| FR6 (type) | `Link.test.tsx` text-type cases; `Link.wrappedLines.a11y.chromium.spec.ts` (wrapped text alignment) | Default `body`; `type="inherit"`; wrapped button and anchor forms in a start-aligned, right-to-left and centred line | A dropped Text `type` fails. `Link.truncation.a11y.chromium.spec.ts`: an anchor and a button Link with `maxLines={1}` in a fixed-width line stop at the line and draw an ellipsis. Evidence gap: no test asserts that `size`, `weight`, `color`, or `display` reach Text, or the `isStandalone` root size. A button form whose wrapped lines line up differently from the anchor form fails. | `audit:Link/visual` |
+| FR6, FR7 (paint) | `Link.hoverColor.a11y.chromium.spec.ts` (the hovered label, root, and icon share one computed color; the resting color returns); evidence gap: the underline and standalone cases assert only that a link renders | Each color; `hasUnderline`; `isStandalone` | — | `audit:Link/visual` |
+| FR8 | `Link.test.tsx` pressed-state suite | Link, button form, disabled | No press paint, or press paint on a disabled Link, fails. | `audit:Link/behavior` |
+| FR9, FR11, AR4 | `Link.test.tsx` label, ref, and theme-class cases | With and without `label`; `data-color` | A missing or extra `aria-label`, target, `data-color`, or ref fails. The accessibility suites assert a passed `data-*` attribute and `aria-current` on the root, and the navigation suite asserts `download`. Evidence gap: no test passes both `label` and `aria-label`, or passes `className`, `style`, or `xstyle`. | `audit:Link/theming` |
+| FR10 | Evidence gap: the tooltip case asserts only that the link renders | Tooltip | — | `audit:Link/accessibility` |
+| ORD1–ORD3 | Covered by the FR1–FR3 rows | — | — | `audit:Link/behavior` |
+| PR1, AR5 | Evidence gap: no test asserts the absence of per-link listeners or the focus indicator | — | — | `audit:Link/accessibility` |
## Current-state impact
diff --git a/packages/core/src/Link/Link.test.tsx b/packages/core/src/Link/Link.test.tsx
index be905397a1..9e9a90a717 100644
--- a/packages/core/src/Link/Link.test.tsx
+++ b/packages/core/src/Link/Link.test.tsx
@@ -484,3 +484,20 @@ describe('pressed state', () => {
expect(hasPressedArm(screen.getByText('Docs').closest('a')!)).toBe(false);
});
});
+
+describe('Link label color', () => {
+ it('lets the label inherit the root color, so a theme styles Link through the link target', () => {
+ for (const color of ['accent', 'primary', 'secondary'] as const) {
+ const {container, unmount} = render(
+ <Link href="/docs" color={color}>
+ Docs
+ </Link>,
+ );
+ const anchor = container.querySelector('a')!;
+ expect(anchor).toHaveAttribute('data-color', color);
+ const label = anchor.querySelector('.astryx-text')!;
+ expect(label).toHaveAttribute('data-color', 'inherit');
+ unmount();
+ }
+ });
+});
diff --git a/packages/core/src/Link/Link.tsx b/packages/core/src/Link/Link.tsx
index 26b521f825..84da814978 100644
--- a/packages/core/src/Link/Link.tsx
+++ b/packages/core/src/Link/Link.tsx
@@ -347,6 +347,10 @@ export function Link({
// The reflected theme attributes win over a caller's same-named `data-*`, so
// theme targeting always sees the real value (public-component-api INV5).
const reflectedAttributes = themeDataAttributes({color});
+ // For a color the root paints, the label inherits it, so the label, the
+ // underline, and the icon keep one color at rest and on hover, whatever a
+ // theme sets on its text targets.
+ const labelColor: TextColor = color in linkColorStyles ? 'inherit' : color;
const sharedContent = (
<>
@@ -354,7 +358,7 @@ export function Link({
type={type}
size={size}
weight={weight}
- color={color}
+ color={labelColor}
display={display}
maxLines={maxLines}>
{children}
diff --git a/packages/core/src/Link/__tests__/Link.hoverColor.a11y.chromium.spec.ts b/packages/core/src/Link/__tests__/Link.hoverColor.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..7d4fe731d7
--- /dev/null
+++ b/packages/core/src/Link/__tests__/Link.hoverColor.a11y.chromium.spec.ts
@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/Link/|packages/core/src/Text/Text\.tsx|apps/storybook/stories/Link\.stories)
+
+/**
+ * @file Link.hoverColor.a11y.chromium.spec.ts
+ * @input Built Link stories and a real Chromium mouse hover
+ * @output Evidence that a hovered Link paints its label in the same color as
+ * its root, which the underline and the external icon take, and that the
+ * resting color does not change
+ * @position Real-engine proof for component:Link FR7; jsdom cannot match
+ * :hover or a (hover: hover) media query
+ */
+
+import {expect, test, type Page} from '@astryxdesign/a11y-spec/playwright';
+import {
+ DEFAULT_STORYBOOK_DIR,
+ serveStorybook,
+ type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+ storybook = await serveStorybook(
+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+ );
+});
+test.afterAll(async () => {
+ await storybook?.close();
+});
+
+async function colors(page: Page) {
+ return page
+ .locator('#storybook-root a')
+ .first()
+ .evaluate(anchor => {
+ const label = anchor.firstElementChild as HTMLElement;
+ const icon = anchor.querySelector('svg');
+ return {
+ root: getComputedStyle(anchor).color,
+ label: getComputedStyle(label).color,
+ icon: icon == null ? null : getComputedStyle(icon).color,
+ };
+ });
+}
+
+for (const story of [
+ 'core-link--default',
+ 'core-link--primary',
+ 'core-link--secondary',
+ 'core-link--external-link',
+]) {
+ test(`${story}: the hovered label matches the root, and the resting color holds`, async ({
+ page,
+ }) => {
+ await page.goto(
+ `${storybook.origin}/iframe.html?id=${story}&viewMode=story`,
+ );
+ const anchor = page.locator('#storybook-root a').first();
+ await expect(anchor).toBeVisible();
+ await page.mouse.move(0, 0);
+ const rest = await colors(page);
+ expect(rest.label).toBe(rest.root);
+
+ await anchor.hover();
+ // Let the root's color transition, if any, settle.
+ await page.waitForTimeout(300);
+ const hovered = await colors(page);
+ expect(hovered.root).not.toBe(rest.root);
+ expect(hovered.label).toBe(hovered.root);
+ if (hovered.icon != null) {
+ expect(hovered.icon).toBe(hovered.root);
+ }
+
+ await page.mouse.move(0, 0);
+ await page.waitForTimeout(300);
+ expect(await colors(page)).toEqual(rest);
+ });
+}
diff --git a/packages/core/src/theme/generateThemeRules.test.ts b/packages/core/src/theme/generateThemeRules.test.ts
index 956dcefd1f..569978af44 100644
--- a/packages/core/src/theme/generateThemeRules.test.ts
+++ b/packages/core/src/theme/generateThemeRules.test.ts
@@ -328,6 +328,15 @@ describe('generateThemeRules', () => {
expect(
rules.some(r => r.includes('.astryx-text[data-color="accent"]')),
).toBe(true);
+ // A Link's label is a Text with color="inherit": a theme that styles the
+ // text target's color must not split it from the link's own color.
+ expect(
+ rules.some(
+ r =>
+ r.includes('.astryx-text[data-color="inherit"]') &&
+ r.includes('color: inherit'),
+ ),
+ ).toBe(true);
});
// --- Size-prop overrides (so `size` beats a themed `type`) ---
diff --git a/packages/core/src/theme/generateThemeRules.ts b/packages/core/src/theme/generateThemeRules.ts
index d6d15499eb..e29c1de708 100644
--- a/packages/core/src/theme/generateThemeRules.ts
+++ b/packages/core/src/theme/generateThemeRules.ts
@@ -1511,6 +1511,9 @@ function generateColorOverrides(
disabled: 'var(--color-text-disabled)',
placeholder: 'var(--color-text-secondary)',
accent: 'var(--color-text-accent)',
+ // A label that follows its owner's color, such as a Link's, keeps doing
+ // so when a theme styles the target's base color.
+ inherit: 'inherit',
};
const touchesText = 'text' in components;