Button, ButtonLink: Default to neutral ghost in non-legacy themes (#1363

)

.changeset/curly-gorillas-pull.md

@@ -0,0 +1,31 @@
+---
+'braid-design-system': minor
+---
+
+---
+updated:
+  - Button
+  - ButtonLink
+---
+
+**Button, ButtonLink:** Default to neutral ghost in non-legacy themes
+
+By default, a button now has a `neutral` tone and uses the `ghost` variant, allowing the visual prominence to be increased or decreased as required, enabling colour to be applied as accents and with purpose, rather than by default.
+
+```jsx
+<Button />
+// => tone="neutral" & variant="ghost"
+```
+
+To compliment this, when a `tone` is purposefully applied, the default variant becomes `solid` to maximise its impact — allowing the visual prominence to be reduced as needed.
+
+```jsx
+<Button tone="brandAccent" />
+// => tone="brandAccent" & variant="solid"
+```
+
+### No change for `apac` and `seekBusiness` consumers
+
+Given the fundamental change in approach to colour and usage of such a core component, this change has been isolated to newer themes and **does not impact `apac` and `seekBusiness` consumers**.
+
+These themes will continue to have a tone of `formAccent` and a `solid` variant by default, allowing consumers to adopt this new approach as part of the design uplift when migrating to an updated theme, e.g. `seekJobs`.

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

@@ -18,6 +18,101 @@ import {
 } from '../';
 import source from '../../utils/source.macro';
 
+const choosingRightButtonDoc = [
+  {
+    label: 'Choosing the right button',
+    description: (
+      <>
+        <Text>
+          By default, a button has a <Strong>neutral</Strong> tone and uses the{' '}
+          <Strong>ghost</Strong> variant, allowing the visual prominence to be
+          increased or decreased as required.
+        </Text>
+
+        <Text>
+          This enables colour to be applied as accents and with purpose, rather
+          than by default — improving the management of user attention and
+          supporting a more declarative hierarchy of actions.
+        </Text>
+      </>
+    ),
+    background: 'surface',
+    playroom: false,
+    code: false,
+    Example: () =>
+      source(
+        <Stack space="small">
+          <Text size="small" tone="secondary">
+            Default is a <Strong>neutral</Strong> tone and{' '}
+            <Strong>ghost</Strong> variant:
+          </Text>
+          <Inline space="none">
+            <Button variant="ghost" tone="neutral">
+              Button
+            </Button>
+          </Inline>
+        </Stack>,
+      ),
+  },
+  {
+    description: (
+      <>
+        <Text>
+          To compliment this, when a <Strong>tone</Strong> is purposefully
+          applied to a button, the default variant becomes{' '}
+          <Strong>solid</Strong> to maximise its impact — allowing the visual
+          prominence to be reduced as needed.
+        </Text>
+      </>
+    ),
+    background: 'surface',
+    playroom: false,
+    code: false,
+    Example: () =>
+      source(
+        <Stack space="small">
+          <Text size="small" tone="secondary">
+            Default variant becomes <Strong>solid</Strong> when a{' '}
+            <Strong>tone</Strong> is applied:
+          </Text>
+          <Inline space="none">
+            <Button tone="critical">Button</Button>
+          </Inline>
+        </Stack>,
+      ),
+  },
+  {
+    description: (
+      <>
+        <Text>
+          As the approach to colour in our experiences has changed over time, so
+          too has the default visual prominence for buttons. For this reason,
+          older themes such as <Strong>apac</Strong> and{' '}
+          <Strong>seekBusiness</Strong> continue to have the default tone of{' '}
+          <Strong>formAccent</Strong> and a <Strong>solid</Strong> variant.
+        </Text>
+      </>
+    ),
+    background: 'surface',
+    playroom: false,
+    code: false,
+    Example: () =>
+      source(
+        <Stack space="small">
+          <Text size="small" tone="secondary">
+            Historical default was the <Strong>formAccent</Strong> tone and{' '}
+            <Strong>solid</Strong> variant:
+          </Text>
+          <Inline space="none">
+            <Button variant="solid" tone="formAccent">
+              Button
+            </Button>
+          </Inline>
+        </Stack>,
+      ),
+  },
+] as const;
+
 const docs: ComponentDocs = {
   category: 'Content',
   migrationGuide: true,
@@ -140,6 +235,12 @@ const docs: ComponentDocs = {
             For cases where actions need to be emphasized, the{' '}
             <Strong>tone</Strong> can be set to <Strong>formAccent</Strong>.
           </Text>
+          <Notice>
+            <Text>
+              This is the default tone in the <Strong>apac</Strong> and{' '}
+              <Strong>seekBusiness</Strong> themes.
+            </Text>
+          </Notice>
         </>
       ),
       Example: () =>
@@ -176,6 +277,12 @@ const docs: ComponentDocs = {
             </TextLink>{' '}
             to improve contrast.
           </Text>
+          <Notice>
+            <Text>
+              This is the default tone for <Strong>seekJobs</Strong> and other
+              non-legacy themes.
+            </Text>
+          </Notice>
         </>
       ),
       Example: () =>
@@ -242,6 +349,7 @@ const docs: ComponentDocs = {
           </Stack>,
         ),
     },
+    ...choosingRightButtonDoc,
     {
       label: 'Icons',
       background: 'surface',

packages/braid-design-system/src/lib/components/Button/Button.screenshots.tsx

@@ -333,10 +333,18 @@ export const screenshots: ComponentScreenshot = {
       Example: () => (
         <BackgroundContrastTest>
           <Inline space="small">
-            <Button variant="solid">Solid</Button>
-            <Button variant="ghost">Ghost</Button>
-            <Button variant="soft">Soft</Button>
-            <Button variant="transparent">Transparent</Button>
+            <Button tone="formAccent" variant="solid">
+              Solid
+            </Button>
+            <Button tone="formAccent" variant="ghost">
+              Ghost
+            </Button>
+            <Button tone="formAccent" variant="soft">
+              Soft
+            </Button>
+            <Button tone="formAccent" variant="transparent">
+              Transparent
+            </Button>
           </Inline>
         </BackgroundContrastTest>
       ),

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

@@ -224,9 +224,29 @@ const ButtonLoader = () => (
 const transparentPaddingX = 'small';
 const buttonRadius = 'standard';
 
+const resolveToneAndVariant = ({
+  variant: variantProp,
+  tone: toneProp,
+  legacy,
+}: Pick<ButtonProps, 'variant' | 'tone'> & { legacy: boolean }) => {
+  if (legacy) {
+    return {
+      variant: variantProp ?? 'solid',
+      tone: toneProp ?? 'formAccent',
+    };
+  }
+
+  const fallbackVariant = toneProp ? 'solid' : 'ghost';
+
+  return {
+    variant: variantProp ?? fallbackVariant,
+    tone: toneProp ?? 'neutral',
+  };
+};
+
 export const ButtonOverlays = ({
-  variant = 'solid',
-  tone,
+  variant: variantProp,
+  tone: toneProp,
   keyboardFocusable = true,
   forceActive = false,
   radius = buttonRadius,
@@ -235,7 +255,13 @@ export const ButtonOverlays = ({
   radius?: 'full' | typeof buttonRadius;
   forceActive?: boolean;
 }) => {
-  const stylesForVariant = variants[variant][tone ?? 'formAccent'];
+  const { variant, tone } = resolveToneAndVariant({
+    variant: variantProp,
+    tone: toneProp,
+    legacy: useBraidTheme().legacy,
+  });
+
+  const stylesForVariant = variants[variant][tone];
   const colorContrast = useColorContrast();
   const lightness = useBackgroundLightness();
 
@@ -306,15 +332,21 @@ export const ButtonText = ({
   size: sizeProp,
   icon,
   iconPosition = 'leading',
-  variant = 'solid',
-  tone,
+  variant: variantProp,
+  tone: toneProp,
   bleed,
 }: ButtonProps) => {
+  const { variant, tone } = resolveToneAndVariant({
+    variant: variantProp,
+    tone: toneProp,
+    legacy: useBraidTheme().legacy,
+  });
+
   const lightness = useBackgroundLightness();
   const actionsContext = useContext(ActionsContext);
   const isLegacyTheme = useBraidTheme().legacy;
   const size = sizeProp ?? actionsContext?.size ?? 'standard';
-  const stylesForVariant = variants[variant][tone ?? 'formAccent'];
+  const stylesForVariant = variants[variant][tone];
   const shouldReducePaddingX = size === 'small' || variant === 'transparent';
   const labelPaddingXForTheme = isLegacyTheme ? 'medium' : 'gutter';
   const labelPaddingX = shouldReducePaddingX
@@ -388,18 +420,24 @@ export const ButtonText = ({
 };
 
 export const useButtonStyles = ({
-  variant = 'solid',
+  variant: variantProp,
   size: sizeProp,
-  tone,
+  tone: toneProp,
   loading,
   radius = buttonRadius,
   bleed,
 }: ButtonProps & {
   radius?: 'full' | typeof buttonRadius;
 }): BoxProps => {
+  const { variant, tone } = resolveToneAndVariant({
+    variant: variantProp,
+    tone: toneProp,
+    legacy: useBraidTheme().legacy,
+  });
+
   const actionsContext = useContext(ActionsContext);
   const size = sizeProp ?? actionsContext?.size ?? 'standard';
-  const stylesForVariant = variants[variant][tone ?? 'formAccent'];
+  const stylesForVariant = variants[variant][tone];
   const colorConstrast = useColorContrast();
   const lightness = useBackgroundLightness();