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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/docs/specs/components/Link/Link.spec.md b/docs/specs/components/Link/Link.spec.mdindex 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 recordcarries 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 impactdiff --git a/packages/core/src/Link/Link.test.tsx b/packages/core/src/Link/Link.test.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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;