braid-design-system

Minor Changes

• Box, atoms: Add borderBrandAccent variants to available boxShadows (#1274)

  Add borderBrandAccent and borderBrandAccentLight to the available boxShadows, combining the brandAccent and brandAccentLight border colours with the standard border width token.
  Previously, brandAccent was only available with the large border width.

  EXAMPLE USAGE:

  <Box boxShadow="borderBrandAccent" />;
  {
    /* or */
  }
  <Box boxShadow="borderBrandAccentLight" />;
  

  import { atoms } from 'braid-design-system/css';
  
  atoms({ boxShadow: 'borderBrandAccent' });
  atoms({ boxShadow: 'borderBrandAccentLight' });
  

• useToast: Design uplift with increased page contrast (#1269)

  As a means to increase constrast against page content, the design has been updated to be presented on inverted backgrounds based on the color mode.
  The design has also be refined to remove the sidebar/keyline (consistent with Alert), while also applying the tone to the provided message.

• Textarea: Add support for disabling built-in spell checker (#1272)

  Provide support for disabling the built-in browser spell checker using the native HTML attribute spellCheck.

  When highlighting ranges you may choose to turn spell check off to prevent colliding highlights. This can be done be setting spellCheck to false.

  EXAMPLE USAGE:

  <Textarea spellCheck={false} />
  

• Add support for caution tone to form fields (#1271)

  Provide support for applying a caution tone to form fields.
  Specifying this tone will show the IconCaution alongside the provided message.

  EXAMPLE USAGE:

  <TextField tone="caution" message="Caution message" />
  

• Textarea: Add support for caution highlightRanges (#1272)

  Providing a tone of caution along with a set of highlightRanges will now apply the caution tone to the text being highlighted.
  To complement this feature, the design has been uplifted to work consistently across both the critical and caution tones.

  EXAMPLE USAGE:

  <Textarea
    tone="caution"
    message="Caution message"
    highlightRanges={...}
  />
  

• Alert: Design uplift (#1269)

  Refine the design to use consistent horizontal container inset, aligning content with elements like Card, as well as simplifying the design by removing the sidebar/keyline (consistent with useToast).

Patch Changes

• Button, ButtonLink: Align ghost border width with field border width (#1274)

  Align the border width of ghost variants with the border width of fields.
  This is the final re-alignment piece to ensure all components use theme scales consistently, improving the ability of Braid themes to deliver cohesive design uplift.

• Stepper: Reduce size of Step indicators (#1275)

  Refine the design of Step indicators by reducing their size.

• TooltipRenderer: Remove custom background (#1268)

  Use the correct semantic token for the background of tooltips.
  While there is no visual change, this is just a clean up to ensure the palette usage remains consistent.

Minor Changes

• Box, atoms, vars: Add small to border radius scale (#1253)

  Extends the border radius scale to include small as a step below standard.
  This addition is to support an upcoming design uplift that requires greater fidelity in the scale.
  Note, the new value is also available as a responsive property.

  EXAMPLE USAGE:

  <Box borderRadius="small" />;
  
  {
    /* Or responsively: */
  }
  <Box borderRadius={{ mobile: 'small', tablet: 'standard' }} />;
  

  import { atoms } from 'braid-design-system/css';
  
  atoms({ borderRadius: 'small' });
  

  import { vars } from 'braid-design-system/css';
  
  const radius = vars.borderRadius.small;
  

• theme: Add support for defining line heights with lineGap (#1267)

  Provide support for themes to define their typographic line heights via lineGap.
  This allows us to reason about the white space between wrapping lines of text in the same way we think about Stack spacing.

  For a visual preview of this mental model head over to the Capsize website.

• Add xxxlarge to the space scale (#1262)

  Extends the range of the space scale to include xxxlarge.
  This addition is to support an upcoming design uplift that requires greater fidelity in the scale.
  Note, the new value is also available as a responsive property.

  EXAMPLE USAGE:

  <Stack space="xxxlarge">...</Stack>;
  
  {
    /* Or responsively: */
  }
  <Stack space={{ mobile: 'large', tablet: 'xxxlarge' }}>...</Stack>;
  

  import { atoms } from 'braid-design-system/css';
  
  atoms({ paddingY: 'xxxlarge' });
  

  import { vars } from 'braid-design-system/css';
  
  const space = vars.space.xxxlarge;
  

Patch Changes

• theme: Add support for webfonts beyond Google Fonts (#1255)

  Previously the webFont on the theme was the familyName and was being used to construct a link tag to a Google Fonts stylesheet and provide to consumers via a runtime token.
  To enable fonts beyond Google Fonts, we are changing webFont to be a URL.

  This does not impact existing themes (as there are no themes currently with a web font), and the contract of the runtime token (a constructed link tag) remains unchanged.

• MenuRenderer: Hide overflow on menu (#1264)

  Fixes a bug where the selection/highlight for a MenuItem could extend outside of the menu itself.

• Badge: Adjust height to support different typographic scales (#1257)

  Adjusts the height of Badge to be driven by the capHeight of xsmall text plus vertical padding, rather than xsmall line height.
  This enables different typographic scales across themes, while ensuring the Badge height is relative.

• RadioItem, Toggle: Use formAccent border when selected (#1251)

  Switch to using the formAccent border colour, rather than the field border color, when in the selected state (e.g. checked for RadioItem, on for Toggle).

• Fix error reading standard of undefined (#1256)

  The use of dynamic property access left some styles exposed to being marked as unused and tree shaken away.

  Refactoring these styles to be explicitly referenced to ensure this will not be the case.

• TooltipRenderer: Refine padding to complement radius scale (#1263)

  Removes the custom padding on tooltips in favour of using the space scale.
  Previously, a custom value was used to complement the over sized radius which has now be reduced.

• Button, ButtonLink: Improve support for different typographic scales (#1259)

  Ensure the height of a small sized Button is not reliant on the text line height.

  This enables different typographic scales across themes, while ensuring the Button height is relative.

• Alert, Card, useToast: Decouple keyline width from space scale (#1266)

  Previously the keyline width on the left determined its width using the space scale.
  Re-aligning this to use the grid unit to enable themes with larger space scales.

• Improve consistency of border radius usage across components (#1253)

  Over time, individual components have reached for a larger radius in the scale, rather than increasing the scale at a theme level. This resulted in inconsistent use across the system, preventing uplift of the scale.

  Re-aligning all components to use the scale consistently enables themes to apply very different radius scales — enabling an upcoming design uplift theme.

• Dialog, Drawer: Reduce space between title and description (#1265)

  Reducing the space between title and description to small to improve association of the header block content

Patch Changes

• Prevent wrong entry point paths from appearing as suggestions in VS Code. (#1247)

  For example, wanting to use Braid's CSS variables (vars) VS Code would suggest braid-design-system/dist/css instead of braid-design-system/css.

Minor Changes

• Disclosure: Add weight support (#1240)

  Provides support for reducing the visual weight of the Disclosure's call to action. Follows the same contextual styling rules as TextLink.

  EXAMPLE USAGE:

  <Disclosure weight="weak">...</Disclosure>
  

• Disclosure: Add inline content support (#1240)

  Provides support for using a Disclosure within a sentence by allowing it to be nested within a typographic component, i.e. Text.

  All size and weight properties will inherit from the parent component.

  EXAMPLE USAGE:

  <Text>
    Preceding text content that is followed by a Disclosure.
    <Disclosure expandLabel="Read more">...</Disclosure>
  </Text>
  

• Button, ButtonLink, TextLink, TextLinkButton: Add support for trailing icons (#1242)

  Provide support for choosing the position of the icon slot within a Button or TextLink.

  By default, the iconPosition will be leading the label, but optionally, can be set to trailing.

  EXAMPLE USAGE:

  <Button icon={<IconArrow direction="right" />} iconPosition="trailing">
    Next
  </Button>
  

Patch Changes

• Show description on form fields when no label provided (#1239)

  Previously, a FieldLabel without a label would return nothing. However, now that form fields can opt for indirect or hidden labels (via aria-label or aria-labelledby), the description should still be shown if provided.

  Note: The secondaryLabel and tertiaryLabel remain conditional based on the presence of a label. This is due to their location in the layout being anchored off the label.

  EXAMPLE USAGE:

  <FieldLabel description="Description now visible without label" />
  

• TextLink, TextLinkButton: Increase text weight of weak links (#1237)

  Increases the text weight of weak links to medium, increasing the affordance against standard text.
  As a result, this makes the weight of all text links consistent.

• Disclosure: Ensure chevron does not wrap alone (#1240)

  Fixes the scenario where based on copy length and container size, the chevron could wrap independently of the rest of the label. By using a zero-width, non-breaking space, the chevron will now wrap together with the last word of the label.

The is a huge enablement release that sees the removal of legacy themes and treat our previous styling solution, as well as a migration to our new build tool Crackle.

By moving to Crackle, Braid will now be published as a pre-compiled artefact, no longer requiring TypeScript to be transpiled by consumers. This should see faster build times and clearer boundaries between Braid and consuming applications.

Outside of the removal of treat and the legacy themes, there is no impact on the public API of Braid. However, if a consuming web app is reaching into Braid internals, this will no longer work and require code changes.

For these cases, to support teams in upgrading we have provided a Compiled Braid Migration Guide based on patterns observed in code bases.

For more detail on the specific changes in this release, please read on.

Major Changes

• Drop support for React 16. (#1229)

  To support the pre-compilation of Braid, it is now a requirement that consumers are on React 17 or later.
  Originally the plan was to drop React 17 as well, however the team has been able to maintain support for a little longer — but there is a catch (see migration guide below).

  MIGRATION GUIDE:

  React 16 consumers

  As this version is no longer supported it is a requirement that consumers upgrade.
  For more information on the differences between v16 and v17, see the React blog.
  We strongly encourage teams to take this opportunity to upgrade to v18 as well.

  React 17 consumers

  The way React 17 exposes the jsx-runtime is not compatible with ESM, which means the bundler will need instructions on how to resolve the import.
  This can be done by adding a fallback module resolve rule to the webpack configuration.

  For sku consumers, this can be done as follows:

  // sku.config.ts
  {
    dangerouslySetWebpackConfig: (config) =>
      webpackMerge(config, {
        resolve: {
          fallback: {
            'react/jsx-runtime': require.resolve('react/jsx-runtime'),
          },
        },
      }),
  }
  

  We recommend using webpack-merge to ensure both configurations are deep merged correctly.

  Note: This rule can be removed after upgrading to React 18, which has ESM support.

  React 18 consumers

  No action required.

• Playroom imports are now formalised entrypoints rather than path imports, and as such no longer require the file path extensions to be provided. (#1229)

  EXAMPLE USAGE:

  // playroom.config.js
  module.exports = {
    frameComponent: require.resolve(
      'braid-design-system/playroom/FrameComponent',
    ),
    components: require.resolve('braid-design-system/playroom/components'),
    snippets: require.resolve('braid-design-system/playroom/snippets'),
    scope: require.resolve('braid-design-system/playroom/scope'),
  };
  

• Remove legacy themes: catho, occ and seekAnz (#1229)

  The seekAnz theme facilitated consumers migrating like-for-like from seek-style-guide, while the catho and occ themes intended to enable a specific use case that never eventuated.

  Removing these themes allows us to move faster with upcoming theme uplift work.

  MIGRATION GUIDE:

  Any remaining consumers of the catho, occ or seekAnz themes should migrate to the apac theme like so:

  -import seekAnz from 'braid-design-system/themes/seekAnz';
  +import apac from 'braid-design-system/themes/apac';
  

• Remove treat support (#1229)

  Treat has been deprecated for nearly 2 years, superseded by vanilla-extract.
  .treat.ts files can no longer be used for styling and should be converted to .css.ts (vanilla-extract) stylesheets.

• Remove experimental color-mode check script (#1229)

  The experimental script for checking which color mode to render has been formalised to an entrypoint specific to the mechanism that is being used — in this case the query parameter.
  In the future we may add other mechanisms, such as local storage for example, but for now all existing consumers should have been migrated to the query-param check.

  MIGRATION GUIDE:

  - import { __experimentalDarkMode__ } from 'braid-design-system/color-mode'
  + import { colorModeQueryParamCheck } from 'braid-design-system/color-mode/query-param'
  

Patch Changes

• Use theme tokens for shape of font metrics (#1214)

  Internally some theme utilities were using Capsize’s FontMetrics as their expected payload, rather than correctly using the shape of the theme tokens.
  This makes Braid compatible with Capsize v3.x.

Patch Changes

• Whitelist only the required FontMetrics for theme tokens (#1212)

  The latest version of FontMetrics type in Capsize adds more properties, and we only populate the properties we require on the theme. Whitelisting the required properties to keep the themes explicit.

Minor Changes

• Accordion, AccordionItem: Add weight support (#1211)

  Add support for customising the weight of AccordionItems.
  This can be either at an Accordion level or on a standalone AccordionItem based on design requirements.

  Note, in order to maintain visual consistency, the weight prop can only be specified on an AccordionItem when outside of an Accordion.

  EXAMPLE USAGE:

  <Accordion weight="strong">
    <AccordionItem />
    ...
  </Accordion>
  

  or

  <AccordionItem weight="strong" />
  

Patch Changes

• CheckboxStandalone: Enable alignment with Text (#1209)

  Enables CheckboxStandalone to be wrapped in a Text component, ensuring it only occupies the same layout as text.
  This is useful for visually aligning checkboxes in a custom layout alongside other text-based components, e.g. AccordionItem.

  EXAMPLE USAGE:

  <Columns>
    <Column>
      <Text>
        <CheckboxStandalone />
      </Text>
    </Column>
    <Column>
      <AccordionItem />
    </Column>
  </Columns>
  

Minor Changes

• color-mode: Add query-param entry (#1205)

  Add new query-param entry, providing a script for resolving the color mode preference from query string, as well as a utility function for retrieving the preference for constructing subsequent links.

Patch Changes

• Tab, Tabs: Updated visual design (#1180)

  The appearance of a Tab has been updated. Changes include:

  • Tab button use regular text weight
  • Hover state of inactive tab toggles neutral tone instead of underline
  • Active tab indicator underlines content only, without the horizontal gutter and animates between tabs
  • The minimal divider under Tabs underlines content only, without the horizontal gutter

• The braid-upgrade command now tries to preserve newlines as best as possible (#1194)

Patch Changes

• Fix type checking for Playroom config (#1192)

Minor Changes

• Expose Playroom config (#1190)

  This allows consuming packages (e.g. Metropolis) to enhance the Playroom experience by leveraging Braid's internal Playroom configuration.

  EXAMPLE USAGE:

  // playroom.config.js
  module.exports = {
    frameComponent: require.resolve(
      'braid-design-system/playroom/FrameComponent.tsx',
    ),
    components: require.resolve('braid-design-system/playroom/components.ts'),
    snippets: require.resolve('braid-design-system/playroom/snippets.ts'),
    scope: require.resolve('braid-design-system/playroom/scope.ts'),
  };
  

Patch Changes

• TextDropdown: Fix a type error affecting consumers on TypeScript versions >=4.9.0 (#1187)

Minor Changes

• TextLink, TextLinkButton: Add icon support (#1184)

  Provides a designed slot for adding an icon to a TextLink or TextLinkButton.
  This solves for the problem of underlining the space between the icon and text.

  EXAMPLE USAGE:

  <Text>
    <TextLink icon={<IconLink />}>...</TextLink>
  </Text>
  

• IconRenderer: Support the sizing and alignment of custom icons (#1185)

  Provides support for sizing and aligning custom icons with Braid’s typographic components. The new IconRenderer component supports being used within Text and Heading components as well as inside icon slots of other components.

  Uses the render prop pattern to provide the required classes to style and align a custom icon.

  EXAMPLE USAGE:

  <Heading level="1">
    <IconRenderer>
      {({ className }) => <svg className={className}>...</svg>}
    </IconRenderer>
  </Heading>
  

Minor Changes

• Link: Support custom data prop format for attributes (#1182)

  While Link already supports the native HTML syntax for data attributes, e.g. data-testid="123", it now supports the data prop too. This allows data attributes to be provided consistently to all components.

  EXAMPLE USAGE:

   <Link
  +  data={{ testId: 'myComponent' }}
   />
  
  

  The above example results in the following HTML attribute being set on the element: data-testId="myComponent".

• Bleed: Add data attribute support (#1182)

  EXAMPLE USAGE:

  <Bleed data={{ testid: 123 }}>...</Bleed>
  

Patch Changes

• Support data attribute boolean values (#1182)

  The data attribute map now supports boolean values. This provides an improvement for the developer experience, no longer having to convert values to strings explicitly.

  EXAMPLE USAGE:

  <Component
    data={{
      'custom-attribute': true,
    }}
  />
  // => <div data-custom-attribute="true" />
  

• TextLink: Allow native data attributes with anchor api (#1182)

  Disables the validation against the use of data attributes on TextLink. Given it exposes the full native anchor tag api, it is not invalid to use the native syntax.

Minor Changes

• TextField: Add inputMode and step support (#1174)

  Provide support for the native inputMode and step attributes.

  The inputMode will also be defaulted based on the specified type. For example: <TextField type="number" /> will default the inputMode to numeric.

  EXAMPLE USAGE:

  <TextField inputMode="numeric" step=".01" />
  

Patch Changes

• Rating: Only fill star for scores .75 and above (#1176)

  A star is only filled when the score is .75 and above. Fixes an issue where all scores .5 or above are shown as half filled stars.

  EXAMPLE USAGE:
  Now when a rating reaches .75 it will round up to a full star.

  <Rating rating={3.75} /> // 4 filled
  

• ButtonLink: Allow native data attributes with anchor api (#1178)

  Disables the validation against the use of data attributes on ButtonLink. Given it exposes the full native anchor tag api, it is not invalid to use the native syntax.

• Box, atoms: Remove native buttons on number input field (#1174)

  Extends the CSS reset behaviour of HTML input fields where type="number" to remove the native increment and decrement buttons.

  EXAMPLE USAGE:
  The following will now render a HTML input of type number without native buttons:

  <Box component="input" type="number" />
  

  Additionally, if using the atoms function to build styles, when resetting an input field, the native buttons will also be removed.

  const customClasses = atoms({
    reset: 'input',
    ...
  });
  

Patch Changes

• Button, ButtonLink: Improve alignment of transparent buttons with icons against Text with icons (#1170)

  To improve optical balance of a Button with an icon, the icon container is bled to the left to balance against the larger horizontal inset of a standard button.
  This alignment correction is now only applied on standard sized buttons that are not using the transparent variant.

  Isolating this alignment correction enables transparent buttons to better align with other components with icon slots, for example:

  <Stack space="small">
    <Text icon={<IconSend />}>Text</Text>
    <Button icon={<IconSend />} variant="transparent" bleed>
      Button
    </Button>
  </Stack>
  

  Icons and text will now be perfectly aligned between Button components and others icon slots with the same text size.

Minor Changes

• Box: Support custom data prop format for attributes (#1168)

  While Box already supports the native HTML syntax for data attributes, e.g. data-testid="123", it now supports the data prop too. This allows data attributes to be provided consistently to all components.

  EXAMPLE USAGE:

   <Box
  +  data={{ testId: 'myComponent' }}
   />
  

  The above example results in the following HTML attribute being set on the element:
  data-testId="myComponent".

• Text, Heading: Add icon slots (#1160)

  Provides a designed slot for adding an icon to Text and Heading components

  EXAMPLE USAGE:

  <Text icon={<IconPromote />}>{...}</Text>
  

  or with a Heading:

  <Heading level="3" icon={<IconPromote />}>{...}</Heading>
  

• useToast: Add data attribute support (#1168)

  Support applying custom data attributes to Toast elements.

  EXAMPLE USAGE:

   export const Component = () => {
     const showToast = useToast();
  
     return (
       <Button onClick={() =>
         showToast({
  +        data: { testId: 'myToastMessage' },
           ...
         })
       }>
         Show
       </Button>
     );
   }
  

  The above example results in the following HTML attribute being set on the toast element:
  data-testId="myToastMessage".

Patch Changes

• Provide dev time validation/warnings when the native data attribute format is provided to components that do not support it. (#1168)
  This is required as TypeScript does not validate kebab cased properties, and Braid components do not spread abritrary props.

  This validation will prevent silent failures where attributes are seemingly provided, but not applied.

  For example:

  <Card data-testid={123} />
  // => Would not be applied and TypeScript would not error.
  

  However, now the following console warning will guide users to use the data prop:

   Braid components do not support the native data attribute format. Use the “data” prop instead.
    <Component
  -    data-testid={123}
  +    data={{
  +      testid: 123,
  +    }}
    />
   For more details, see the “Data Attributes” documentation:
   https://seek-oss.github.io/braid-design-system/components/Box#data-attributes
  

• Pagination: Increase chevron spacing on prev/next links (#1160)

  Increases the space between the "Previous" and "Next" text and their chevron icons to balance with the larger icon size.

• MenuItemCheckbox: Align with increased icon size (#1160)

  Ensure menu item text has uniform spacing to the checkbox of MenuItemCheckbox and the icon slot of MenuItem.

• Text, Heading: Increase icon size inside typographic elements (#1160)

  The size of icons has been increased by 20% when used inside of Text and Heading components. There is no layout impact expected for consumers, with only the visual ratio of icon to text size changing.

  This applies to icons using the new icon slots, as well as inline icons within the text content.

  Icons used outside of typographic elements are not affected by this change.

• ButtonIcon: Increase standard icon size (#1160)

  Adopt the increased standard icon size.

  Note this does not affect overall dimensions of ButtonIcon, or the layout of surrounding components.

• Removes custom icon sizing and layout in favour of new typography icon sizes and layout. (#1162)

Patch Changes

• Update @vanilla-extract/css dependency (#1158)

  This fixes a type error that was occurring with typescript versions >=4.5.0

• Heading: Nested icons inherit text colour (#1153)

  When using icons inside of a Heading, the default tone was always neutral, rather than inheriting the colour of the nearest component.

  For example, when an icon was used inside of a TextLink within a Heading:

  <Heading level="1">
    Title with{' '}
    <TextLink>
      link <IconArrow />
    </TextLink>
  </Heading>
  // => Previously, IconArrow was the heading text colour
  // `neutral`, now inherits the `link` colour.
  

  or equally, when an icon was used inside of a Secondary component within a Heading:

  <Heading level="1">
    Title with{' '}
    <Secondary>
      secondary <IconArrow />
    </Secondary>
  </Heading>
  // => Previously, IconArrow was the heading text colour
  // `neutral`, now inherits the `secondary` colour.
  

Patch Changes

• Fixes an issue with a missing dependency (#1143)