Style Guide Migration.md

Style Guide Migration

This document provides guidance for consumers looking to migrate from an existing style guide to Braid.

If you have any questions or concerns, or if you need assistance with implementation or migration work, please reach out to us in the #braid-support channel.

Technical Considerations

Before migrating, please be aware of the following:

• Braid requires sku. This is to ensure that consumers have the best possible experience as we continue to evolve our underlying platform.

• Braid is written in TypeScript. We highly recommend consumers also write their applications in TypeScript, or at least the parts of their application that interact with Braid.

Architecture

Since Braid is an entirely new design system, we've taken the opportunity to revisit some of the cross-cutting architectural decisions that were made previously. The most notable changes being:

• Component APIs have been revisited, rather than being straight ports. Across the board, we've taken this as an opportunity to improve APIs with the benefit of hindsight. Whenever migrating a component to Braid, please make sure you reference Braid's API documentation.

• Components don't allow style overrides via className and style props. This is to ensure that gaps in the design system are surfaced, rather than encouraging consumers to constantly apply workarounds.

• Components don't spread props onto DOM elements. We want to ensure that the API for each component is carefully designed, rather than exposing the entire API of the underlying DOM nodes. If there is a gap in a component API, let us know in the #braid-support channel.

• Braid is built from the ground up on primitive components. Our lowest level primitive is Box, which we've exposed to consumers. In a lot of cases, you'll find that you can use Box instead of writing custom CSS. However, since it's a primitive, you shouldn't have to constantly reach for Box. If this is the case, you should let Braid maintainers know in the #braid-support channel so that we can deal with the underlying design issue.

• Braid doesn't provide a global CSS reset. All style resets are applied locally via the Box component mentioned above based on its component prop, e.g. <Box component="h1"> will provide the appropriate reset for an h1 element. When migrating from SEEK Style Guide, you'll need to ensure that you're leveraging Box for all custom low-level elements.

• Braid uses vanilla-extract for styling rather than Less. This lets us author themed styles in TypeScript without incurring a penalty to both bundle size and runtime performance. Theme values are now provided via CSS variables rather than Less variables.

• Text no longer renders white space below it. In our existing style guides, the additional white space below Text components turned out to be a problem for consumers in many cases, forcing them to use the confusingly named raw boolean prop to opt out. In Braid, we've decided to leave Text unopinionated about its surrounding white space. Instead, Braid provides a full suite of layout components.

• Braid no longer provides a Sketch library. For more details, read our design workflow guide.

Component Migration Guides

Note: Links to these migration guides are also available at the bottom of each component page on the Braid documentation site.

• AccordionItem
• Alert
• Alert (tertiary) -> Notice
• AsidedLayout -> Columns
• Autosuggest
• Badge
• BulletList / Bullet-> List
• Button
• ButtonGroup -> Actions
• Card
• Checkbox
• Columns
• Dropdown
• FieldLabel
• FieldMessage
• Icons
• MonthPicker
• PageBlock -> ContentBlock
• Paragraph -> Text
• Pill -> Tag
• Radio
• ScreenReaderOnly -> HiddenVisually
• Secondary
• SlideToggle -> Toggle
• StyleGuideProvider -> BraidProvider
• Strong
• Text
• Text (Headings) -> Heading
• Textarea
• TextField
• TextLink
• ToggleContent -> Disclosure