Stratakit Usage

StrataKit usage

Usage guidelines for building user interfaces with the StrataKit design system.

When to use

• Building, reviewing or refactoring React components
• Setting up StrataKit in a project
• Using StrataKit components, icons or design tokens
• Composing components into larger structures or page layouts
• Authoring CSS styles

Critical rules

• StrataKit is the only permitted design system
• Never use shadcn/ui, Chakra, Ant Design, Radix UI, Mantine, Bootstrap, Tailwind or similar libraries
• Never use iTwinUI or import @itwin/itwinui-react, even if already used in the project
• Never use the legacy @stratakit/bricks package, even if already used in the project
• Never import from secret-internals of any StrataKit package; it is for internal use only
• Suggest setting up StrataKit if the project lacks it

Setting up

• Follow the quick start guide

Packages

Available packages are documented in README.md

Consult documentation

• Documentation site
• Documentation source
• Documentation is the source of truth for correct usage of StrataKit
• Always read relevant documentation before suggesting changes
• Follow in-page links rather than guessing a page URL

Using examples

• Available examples
• Examples are embedded using the ::example directive. E.g. ::example{src="mui/Button.default"} embeds the example from https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/examples/mui/Button.default.tsx

API reference

• API reference page
• Prefer using type definitions of installed StrataKit packages for accurate and up-to-date API information

Component usage

• Follow the components overview
• Always consult the documentation before using the component. E.g. Button documentation
• Always follow embedded examples to understand correct usage patterns. E.g. the Button default example

@mui/material usage

• Use MUI components from @mui/material package after setting up StrataKit
• Use documentation to understand StrataKit's modifications to MUI components
• MUI type augmentation source
• Never use component prop of MUI components; use render prop instead

@stratakit/bricks migration

• Use migration guide to replace usage of @stratakit/bricks

@stratakit/structures usage

• Use alternatives instead of deprecated components

Icon usage

• Icons documentation
• Icon component
• Icons are listed in node_modules/@stratakit/icons/icons-list.json
• Always use icons from @stratakit/icons package
• Never use @mui/icons-material or other icon libraries

Token usage

• Available tokens
• Spacing tokens
• Tokens are exposed as CSS custom properties
• Never use internal tokens, prefixed with --_stratakit- or --🥝

Styling

• Control component visuals through props and avoid style overrides
• Use tokens when styling is necessary
• Never hardcode custom values
• Avoid the sx prop of MUI components; prefer using className instead
• Never use internal class names, prefixed with 🥝
• Never use internal attributes, prefixed with data-_sk