Styling

SCSS, BEM naming, and design tokens.

Quick Reference

Styling decision flowchart:

Box/FlexBox props and shipped parts (preferred) - Use design system props
regionClass with a *.region.module.scss - Token-only paint on a Box or FlexBox host that the props do not cover
Request it through the find-pattern skill - When no prop or part exists

Never use:

❌ sx prop or sxStyles
❌ styled-components
❌ Inline style={{}}
❌ className on a @prepared911/ui part
❌ @layer chroma.* in a product stylesheet

className and regionClass:

Box and FlexBox props for layout and paint
regionClass for token-only host paint the props do not cover, such as a host :hover
className is deprecated outside the design system; pnpm lint:classname rejects it on a published part
Product stylesheets declare no @layer chroma.*; consumer stylelint rejects every chroma layer, chroma.overrides included
bem() is not an export of @prepared911/ui

Design System First

Always check if Box/FlexBox props can handle the styling:

Co-located SCSS

When Box props aren't enough, use className + co-located SCSS:

File Naming

Match component filename convention:

MyComponent.tsx → MyComponent.scss (PascalCase)
filter-bar.tsx → filter-bar.scss (kebab-case)
Single stylesheet in directory → styles.scss

Importing

BEM Naming

Block Element Modifier

With Sass &

regionClass

bem() and prefixClass() are not exports of @prepared911/ui. Layout and paint go through Box and FlexBox props. className is deprecated outside the design system, and pnpm lint:classname rejects it on a published part. For token-only paint the props do not cover, pass regionClass on Box or FlexBox a class from a colocated *.region.module.scss file. The module styles only its host class, optionally with :hover or :focus-visible, and sets colors, borders and opacity; layout stays in props. It declares no @layer chroma.*.

regionClass takes styles.card directly, not a conditional. A region module cannot select descendants, data-* attributes or :has(), so paint that follows product state, such as an active card, comes from a shipped part's state prop, or is requested through the find-pattern skill.

Design Tokens

Always use design tokens instead of hardcoded values:

Max 2 Levels

Only .block and .block__element. Never .block__element__subelement.

Responsive Design

Use media queries with design tokens:

When to Use Each Approach

Use Box/FlexBox props when:

✅ Layout (flex, grid, spacing, alignment)
✅ Typography (font size, weight, color)
✅ Spacing (margin, padding, gap)
✅ Design system values exist

Use regionClass with a *.region.module.scss when:

✅ Token-only host paint the props do not cover: colors, borders, opacity
✅ Host :hover or :focus-visible on that paint

Request it through the find-pattern skill when:

❌ No design system prop or part exists
❌ You need descendant selectors, pseudo-elements, media queries, animations or state-dependent paint
❌ Component behavior is unclear
❌ A new visual pattern is needed

Common Patterns

Hover States

Conditional Classes

Tokens - Design tokens reference
UI Components - @prepared/ui-* package usage
Component Patterns - Component organization

Reference Files

For more detailed technical guidance, see these reference files:

css-best-practices SKILL.md
stylesheets-for-react.md
using-bem-and-sass.md
react-ui-implementation SKILL.md

Working on features / Writing Hooks

Working on features / Localization (i18n)

On this page

Block Element Modifier

When to Use Each Approach

Common Patterns

Hover States

Conditional Classes

Styling

SCSS, BEM naming, and design tokens.

Quick Reference

Styling decision flowchart:

Box/FlexBox props and shipped parts (preferred) - Use design system props
regionClass with a *.region.module.scss - Token-only paint on a Box or FlexBox host that the props do not cover
Request it through the find-pattern skill - When no prop or part exists

Never use:

❌ sx prop or sxStyles
❌ styled-components
❌ Inline style={{}}
❌ className on a @prepared911/ui part
❌ @layer chroma.* in a product stylesheet

className and regionClass:

Box and FlexBox props for layout and paint
regionClass for token-only host paint the props do not cover, such as a host :hover
className is deprecated outside the design system; pnpm lint:classname rejects it on a published part
Product stylesheets declare no @layer chroma.*; consumer stylelint rejects every chroma layer, chroma.overrides included
bem() is not an export of @prepared911/ui

Design System First

Always check if Box/FlexBox props can handle the styling:

Co-located SCSS

When Box props aren't enough, use className + co-located SCSS:

File Naming

Match component filename convention:

MyComponent.tsx → MyComponent.scss (PascalCase)
filter-bar.tsx → filter-bar.scss (kebab-case)
Single stylesheet in directory → styles.scss

Importing

BEM Naming

Block Element Modifier

With Sass &

regionClass

Design Tokens

Always use design tokens instead of hardcoded values:

Max 2 Levels

Only .block and .block__element. Never .block__element__subelement.

Responsive Design

Use media queries with design tokens:

When to Use Each Approach

Use Box/FlexBox props when:

✅ Layout (flex, grid, spacing, alignment)
✅ Typography (font size, weight, color)
✅ Spacing (margin, padding, gap)
✅ Design system values exist

Use regionClass with a *.region.module.scss when:

✅ Token-only host paint the props do not cover: colors, borders, opacity
✅ Host :hover or :focus-visible on that paint

Request it through the find-pattern skill when:

❌ No design system prop or part exists
❌ You need descendant selectors, pseudo-elements, media queries, animations or state-dependent paint
❌ Component behavior is unclear
❌ A new visual pattern is needed

Common Patterns

Hover States

Conditional Classes