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
❌ Native HTML or SVG elements in consumer code (use Box, FlexBox, and shipped parts)
❌ Inline style={{}}
❌ className on a @prepared911/ui part
❌ @layer chroma.* in a product stylesheet (including @layer chroma.overrides to beat Box or component props)
❌ Raw lengths, colors, spacing, radii, shadows, z-index, opacity, or motion literals in product CSS
❌ Utility classes with arbitrary values

Consumer styling (ADR 0002 consumer call-site rules):

Layout and paint through Box/FlexBox props and enum props on shipped components
regionClass for token-only host paint the props do not cover, such as a host :hover
Do not override @prepared911/ui styles with className or chroma layers; request gaps via find-pattern
Product stylesheets declare no @layer chroma.*; consumer stylelint rejects every chroma layer
bem() is not an export of @prepared911/ui

Design System First

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

className and CSS modules

Legacy BEM and plain SCSS in consumer code are out of scope for new work. To migrate existing call sites, follow Migrating to @prepared911/ui. bem() and prefixClass() are not exports of @prepared911/ui. Consumers do not pass className to any @prepared911/ui part. Layout and paint go through Box and FlexBox props and shipped parts; gaps use find-pattern (ADR 0002 consumer call-site rules).

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. When props and shipped parts do not cover a state such as :hover on host paint, use regionClass as above or file a find-pattern request.

Design Tokens

For spacing and paint in consumer screens, use Box and FlexBox props as in the example above. Token names and semantics live on the Tokens page; consumer stylesheets stay token-only and must not repeat layout in CSS modules.

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

When props and shipped parts do not cover other interaction or layout needs, file a find-pattern request. 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

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

Quick Reference

Design System First

className and CSS modules

File Naming

Importing

BEM Naming

Block Element Modifier

With Sass &

regionClass

Design Tokens

When to Use Each Approach

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
❌ Native HTML or SVG elements in consumer code (use Box, FlexBox, and shipped parts)
❌ Inline style={{}}
❌ className on a @prepared911/ui part
❌ @layer chroma.* in a product stylesheet (including @layer chroma.overrides to beat Box or component props)
❌ Raw lengths, colors, spacing, radii, shadows, z-index, opacity, or motion literals in product CSS
❌ Utility classes with arbitrary values

Consumer styling (ADR 0002 consumer call-site rules):

Layout and paint through Box/FlexBox props and enum props on shipped components
regionClass for token-only host paint the props do not cover, such as a host :hover
Do not override @prepared911/ui styles with className or chroma layers; request gaps via find-pattern
Product stylesheets declare no @layer chroma.*; consumer stylelint rejects every chroma layer
bem() is not an export of @prepared911/ui

Design System First

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

className and CSS modules

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

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

When props and shipped parts do not cover other interaction or layout needs, file a find-pattern request. 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