# Stratakit Usage

> Ensures correct StrataKit usage. Use when building, reviewing or refactoring frontend code - React components (jsx/tsx), CSS styling, web pages, MUI usage, icons, design tokens, and page layouts. StrataKit is the design system to use, even in repos that don't have it yet (it should be set up). Apply even when the user doesn't mention StrataKit by name, e.g. "add a button", "build a settings page", or "style this form". Not for backend or other non-UI code.

- Skill: `itwin/stratakit-usage` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add itwin/stratakit-usage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/itwin/stratakit-usage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: itwin (https://skillmd.com/u/itwin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/itwin/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](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/getting-started/develop.mdx)

## Packages

Available packages are documented in [README.md](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/README.md)

## Consult documentation

- [Documentation site](https://stratakit.bentley.com/docs/)
- [Documentation source](https://api.github.com/repos/iTwin/stratakit/contents/apps/website/src/content/docs)
- 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](https://api.github.com/repos/iTwin/stratakit/contents/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](https://stratakit.bentley.com/docs/reference/)
- Prefer using type definitions of installed StrataKit packages for accurate and up-to-date API information

## Component usage

- Follow the [components overview](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/components/overview.md)
- Always consult the documentation before using the component. E.g. [`Button` documentation](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/components/mui/Button.md)
- Always follow embedded examples to understand correct usage patterns. E.g. the [`Button` default example](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/examples/mui/Button.default.tsx)

## `@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](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/packages/mui/src/types.ts)
- Never use `component` prop of MUI components; use `render` prop instead

## `@stratakit/bricks` migration

- Use [migration guide](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/getting-started/migration-from-legacy-stratakit.mdx) to replace usage of `@stratakit/bricks`

## `@stratakit/structures` usage

- Use [alternatives](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/getting-started/migration-from-legacy-stratakit.mdx) instead of deprecated components

## Icon usage

- [Icons documentation](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/icons.mdx)
- [`Icon` component](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/apps/website/src/content/docs/components/stratakit/Icon.md)
- 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](https://stratakit.bentley.com/tokens/)
- [Spacing tokens](https://raw.githubusercontent.com/iTwin/stratakit/refs/heads/main/packages/foundations/src/%7Espace.css)
- Tokens are exposed as [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_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`