TextLink: Underline regular links in non-legacy themes

.changeset/afraid-teachers-jog.md

@@ -0,0 +1,17 @@
+---
+'braid-design-system': patch
+---
+
+---
+updated:
+  - TextLink
+  - TextLinkButton
+---
+
+**TextLink, TextLinkButton:** Underline regular links in non-legacy themes
+
+To improve affordance beyond primarily being colour, a `TextLink` (and `TextLinkButton`) will now always be underlined, in line with [best practice accessibility guidelines].
+
+Given this has not been the case previously, this decision has been applied to non-legacy themes only, as such only affecting consumers of `seekJobs`, `docs` and `wireframe`.
+
+[best practice accessibility guidelines]: https://webaim.org/techniques/hypertext/link_text#appearance

.changeset/empty-rings-itch.md

@@ -0,0 +1,13 @@
+---
+'braid-design-system': patch
+---
+
+---
+updated:
+  - TextLink
+  - TextLinkButton
+---
+
+**TextLink, TextLinkButton:** Apply themed focus outline
+
+Apply a focus outline using the relevant focus attributes from the theme, bringing `TextLink` (and `TextLinkButton`) into line with the focus treatment applied to rest of the system.

.changeset/khaki-maps-push.md

@@ -0,0 +1,13 @@
+---
+'braid-design-system': patch
+---
+
+---
+updated:
+  - TextLink
+  - TextLinkButton
+---
+
+**TextLink, TextLinkButton:** Reduce `weak` links to `regular` font weight
+
+The font weight of a `weak` link is now reduced to `regular` weight, reducing the link's visual prominence in addition to following the neutral text colour.

.changeset/popular-worms-type.md

@@ -0,0 +1,13 @@
+---
+'braid-design-system': patch
+---
+
+---
+updated:
+  - vars
+  - Box
+---
+
+**docs:** Lighten soft background tokens
+
+Lighten the `brandAccentSoft` and `formAccentSoft` background tokens for the `docs` theme.

.changeset/sharp-mangos-dance.md

@@ -0,0 +1,21 @@
+---
+'braid-design-system': minor
+---
+
+---
+updated:
+  - vars
+  - Text
+  - TextLink
+  - TextLinkButton
+---
+
+**seekJobs:** Change link colour to neutral
+
+Changing the `foregroundColor` token for `link` on the `seekJobs` theme to align with neutral text.
+Our different approach to using colour has seen links dialled back to compete less with other messaging and CTAs.
+
+This affects the following usages across the system:
+- `vars.foregroundColor.link`
+- `Text` (using `tone="link"`)
+- `TextLink` and (`TextLinkButton`)

packages/braid-design-system/src/lib/components/TextLink/TextLink.css.ts

@@ -10,39 +10,31 @@ import { vars } from '../../themes/vars.css';
 const textLinkVars = createThemeContract({
   color: null,
   colorHover: null,
-  textDecoration: null,
-  textDecorationHover: null,
 });
 
 const lightModeRegularLinkVars = assignVars(textLinkVars, {
   color: vars.foregroundColor.link,
   colorHover: vars.foregroundColor.linkHover,
-  textDecoration: 'none',
-  textDecorationHover: 'underline',
 });
 
 const darkModeRegularLinkVars = assignVars(textLinkVars, {
   color: vars.foregroundColor.linkLight,
   colorHover: vars.foregroundColor.linkLight,
-  textDecoration: 'none',
-  textDecorationHover: 'underline',
 });
 
 const weakLinkVars = assignVars(textLinkVars, {
   color: 'inherit',
   colorHover: 'inherit',
-  textDecoration: 'underline',
-  textDecorationHover: 'underline',
 });
 
 export const base = style({
   color: textLinkVars.color,
-  textDecoration: textLinkVars.textDecoration,
-  textDecorationThickness: '0.1em',
+  textDecoration: vars.linkDecoration,
+  textDecorationThickness: '0.08em',
   textUnderlineOffset: 3,
   ':hover': {
     color: textLinkVars.colorHover,
-    textDecoration: textLinkVars.textDecorationHover,
+    textDecoration: 'underline',
     /*
       Duplicating the thickness rule due to inconsistent support
       for shorthand properties of `text-decoration`. Without this,
@@ -52,15 +44,19 @@ export const base = style({
       We also cannot use the long-form `text-decoration-line` due
       to browser support policy of Edge 16+.
     */
-    textDecorationThickness: '0.1em',
+    textDecorationThickness: '0.08em',
   },
-  ':focus': {
+  ':focus-visible': {
     color: textLinkVars.colorHover,
+    outline: `${vars.focusRingSize} solid ${vars.borderColor.focus}`,
+    outlineOffset: '0.2em',
+    borderRadius: vars.borderRadius.small,
   },
 });
 
 export const weakLink = style({
   vars: weakLinkVars,
+  textDecoration: 'underline',
 });
 
 export const regularLinkLightMode = styleVariants({

packages/braid-design-system/src/lib/components/TextLink/TextLink.docs.tsx

@@ -103,11 +103,18 @@ const docs: ComponentDocs = {
     {
       label: 'Design considerations',
       description: (
-        <Text>
-          By default, a TextLink uses colour and underline on hover to create
-          affordance. Optionally you can decrease their visual weight by setting{' '}
-          <Strong>weight</Strong> to <Strong>weak</Strong>.
-        </Text>
+        <>
+          <Text>
+            By default, a TextLink will follow the link colour of the theme and
+            use a <Strong>medium</Strong> font weight to create affordance
+            against surrounding text.
+          </Text>
+          <Text>
+            Optionally, you can decrease the visual weight by setting{' '}
+            <Strong>weight</Strong> to <Strong>weak</Strong> — with the link now
+            following the default text colour and weight.
+          </Text>
+        </>
       ),
       Example: () =>
         source(
@@ -137,7 +144,8 @@ const docs: ComponentDocs = {
         <>
           <Text>
             To avoid clashing colours, when on a background other than{' '}
-            <Strong>surface</Strong>, TextLink will default its{' '}
+            <Strong>surface</Strong>, <Strong>body</Strong> or{' '}
+            <Strong>neutralLight</Strong>, TextLink will default its{' '}
             <Strong>weight</Strong> to <Strong>weak</Strong>. In addition, when
             placed on a dark background, it may be inverted based on the{' '}
             <TextLink href="/components/Text#contrast">

packages/braid-design-system/src/lib/components/TextLink/TextLink.tsx

@@ -85,7 +85,7 @@ export const useLinkStyles = ({
   return clsx(
     styles.base,
     linkStyles,
-    typographyStyles.fontWeight.medium,
+    weight !== 'weak' ? typographyStyles.fontWeight.medium : undefined,
     showVisited
       ? [
           styles.visitedLightMode[backgroundLightness.lightMode],

packages/braid-design-system/src/lib/themes/docs/tokens.ts

@@ -219,9 +219,9 @@ const tokens: BraidTokens = {
       brandAccent,
       brandAccentActive: brandAccent,
       brandAccentHover: palette.grey['700'],
-      brandAccentSoft: palette.grey['200'],
-      brandAccentSoftActive: darken(0.025, palette.grey['200']),
-      brandAccentSoftHover: darken(0.05, palette.grey['200']),
+      brandAccentSoft: palette.grey['100'],
+      brandAccentSoftActive: darken(0.025, palette.grey['100']),
+      brandAccentSoftHover: darken(0.05, palette.grey['100']),
       caution: palette.yellow['500'],
       cautionLight: palette.yellow['100'],
       critical: palette.red['600'],
@@ -234,9 +234,9 @@ const tokens: BraidTokens = {
       formAccent,
       formAccentActive: palette.indigo['700'],
       formAccentHover: darken(0.05, palette.indigo['600']),
-      formAccentSoft: palette.indigo['100'],
-      formAccentSoftActive: darken(0.05, palette.indigo['100']),
-      formAccentSoftHover: darken(0.025, palette.indigo['100']),
+      formAccentSoft: palette.indigo['50'],
+      formAccentSoftActive: darken(0.05, palette.indigo['50']),
+      formAccentSoftHover: darken(0.025, palette.indigo['50']),
       info: palette.blue['600'],
       infoLight: palette.blue['100'],
       neutral: palette.grey['800'],

packages/braid-design-system/src/lib/themes/makeVanillaTheme.ts

@@ -83,7 +83,7 @@ const fontSizeToCapHeight = (
 };
 
 export const makeVanillaTheme = (braidTokens: BraidTokens) => {
-  const { name, displayName, ...tokens } = braidTokens;
+  const { name, displayName, legacy, ...tokens } = braidTokens;
   const { webFont, ...typography } = tokens.typography;
   const { foreground, background } = tokens.color;
   const textSize = mapValues(tokens.typography.text, (definition) =>
@@ -121,6 +121,12 @@ export const makeVanillaTheme = (braidTokens: BraidTokens) => {
         tokens.typography.fontWeight[tokens.typography.heading.weight.regular],
       ),
     },
+    /*
+      Going forward, all links variants should be underlined as an accessibility
+      best practice. However, to maintain existing behaviour we are sunsetting
+      the old style based on the `legacy` theme flag, e.g. `apac`.
+    */
+    linkDecoration: legacy ? 'none' : 'underline',
     inlineFieldSize: {
       standard: getInlineFieldSize('standard'),
       small: getInlineFieldSize('small'),

packages/braid-design-system/src/lib/themes/seekJobs/tokens.ts

@@ -161,9 +161,9 @@ export default makeTokens({
       foreground: {
         formAccent: palette.violet['500'],
         formAccentLight: palette.violet['300'],
-        link: palette.violet['500'],
-        linkHover: palette.violet['500'],
-        linkLight: palette.violet['300'],
+        link: palette.grey['700'],
+        linkHover: palette.grey['700'],
+        linkLight: '#fff',
         linkVisited: palette.purple['800'],
         linkLightVisited: palette.purple['200'],
         promote: palette.purple['700'],