Braid Design System

Braid relies on several technologies for styling and validation that may require specific bundler configurations:

Styling with Vanilla Extract

Braid uses Vanilla Extract for styling. This allows CSS to be authored in TypeScript and statically extracted at build time into atomic CSS classes. You will need a bundler plugin (like the one provided by Vanilla Extract) to collect these styles and inject them into your document or a separate stylesheet.

Runtime Assertions

Braid uses the assert library to perform precondition and invariant checking at runtime to ensure components are used correctly.

• Recommendation: To avoid performance overhead in production, use unassert at build time (e.g., via babel-plugin-unassert) to strip these calls from your production bundle.

Dev-time Warnings

Braid provides warnings for deprecations and other communications based on process.env.NODE_ENV.

• Recommendation: Ensure your bundler (e.g., Webpack) replaces process.env.NODE_ENV with a hardcoded string during the build process so that minifiers can perform dead-code elimination and remove these checks from production bundles.

When creating custom components that wrap or forward props to Braid components, do not import types from internal paths. Instead, use React's ComponentProps utility to derive them from the component itself.

Standard Components

import { Text } from 'braid-design-system';
import type { ComponentProps } from 'react';

type TextProps = ComponentProps<typeof Text>;

interface MyComponentProps {
  tone: TextProps['tone'];
}

Generic Components (e.g., Autosuggest)

Because components like Autosuggest are generic, using ComponentProps<typeof Autosuggest> will result in unknown types. To maintain type safety, use TypeScript 4.7+ instantiation expressions to specialize the component first.

Note: Requires TypeScript 4.7+ and sku@11.6.0 or higher.

import type { ComponentProps } from 'react';
import { Autosuggest } from 'braid-design-system';

// A specialized Autosuggest component that only accepts `string`s
const StringAutosuggest = Autosuggest<string>;
type AutosuggestProps = ComponentProps<typeof StringAutosuggest>;

type Value = AutosuggestProps['value'];

const autosuggestValue: Value = {
  text: 'myValue',
  value: 'foo', // Correctly typed as string
};

Icon Slot Prop Types

To derive the type for an icon slot, use an existing Braid icon component as a reference.

import type { IconAdd } from 'braid-design-system';
import type { ComponentProps, ReactElement } from 'react';

type IconProps = ComponentProps<typeof IconAdd>;

interface MyComponentProps {
  icon?: ReactElement<IconProps>;
}

If your project uses automatic IDE imports, you may have accidentally imported from private internal paths. These must be updated to use public entrypoints.

Public Components

Import components from the main entrypoint instead of their file paths.

-import { Text } from 'braid-design-system/lib/components/Text/Text';
+import { Text } from 'braid-design-system';

Themes

Import themes via the braid-design-system/themes entrypoint.

-import { apac } from 'braid-design-system/lib/themes';
-import apac from 'braid-design-system/lib/themes/apac';
+import apac from 'braid-design-system/themes/apac';

Styling APIs

Import vars, atoms, and responsiveStyle via the braid-design-system/css entrypoint.

-import { vars } from 'braid-design-system/lib/themes/vars.css';
-import { atoms } from 'braid-design-system/lib/css/atoms/atoms';
-import { responsiveStyle } from 'braid-design-system/lib/css/responsiveStyle';
+import { vars, atoms, responsiveStyle } from 'braid-design-system/css';