Prepared Docs

Quick Reference

Styling decision flowchart:

Box/FlexBox props (preferred) - Use design system props
className + SCSS - When props unavailable
Escalate to UX Guild - When no pattern exists

Never use:

❌ sx prop or sxStyles
❌ styled-components
❌ Inline style={{}} (except rare dynamic values)
❌ CSS modules

BEM naming:

Block: .component-name
Element: .component-name__element
Modifier: .component-name--modifier
Max 2 levels (no .block__element__subelement)

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 &

bem() Utility

Use the bem() utility from @prepared911/ui-core:

Generates:

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 className + SCSS when:

✅ Complex selectors (:hover, :focus, :nth-child)
✅ Pseudo-elements (::before, ::after)
✅ Media queries
✅ Animations and transitions
✅ Design system doesn't cover the pattern

Escalate to UX Guild when:

❌ No design system pattern exists
❌ Component behavior unclear
❌ New visual pattern 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:

Working on features / Writing Hooks

Working on features / Localization (i18n)

Block Element Modifier

When to Use Each Approach

Common Patterns

Hover States

Conditional Classes

Quick Reference

Styling decision flowchart:

Box/FlexBox props (preferred) - Use design system props
className + SCSS - When props unavailable
Escalate to UX Guild - When no pattern exists

Never use:

❌ sx prop or sxStyles
❌ styled-components
❌ Inline style={{}} (except rare dynamic values)
❌ CSS modules

BEM naming:

Block: .component-name
Element: .component-name__element
Modifier: .component-name--modifier
Max 2 levels (no .block__element__subelement)

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 &

bem() Utility

Use the bem() utility from @prepared911/ui-core:

Generates:

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 className + SCSS when:

✅ Complex selectors (:hover, :focus, :nth-child)
✅ Pseudo-elements (::before, ::after)
✅ Media queries
✅ Animations and transitions
✅ Design system doesn't cover the pattern

Escalate to UX Guild when:

❌ No design system pattern exists
❌ Component behavior unclear
❌ New visual pattern 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:

Working on features / Writing Hooks

Working on features / Localization (i18n)

Block Element Modifier

When to Use Each Approach

Common Patterns

Hover States

Conditional Classes

Styling

Quick Reference

Design System First

Co-located SCSS

File Naming

Importing

BEM Naming

Block Element Modifier

With Sass &

bem() Utility

Design Tokens

Max 2 Levels

Responsive Design

When to Use Each Approach

Common Patterns

Hover States

Conditional Classes

Related Documentation

Reference Files

Working on features / Writing Hooks

Working on features / Localization (i18n)

Styling

Quick Reference

Design System First

Co-located SCSS

File Naming

Importing

BEM Naming

Block Element Modifier

With Sass &

bem() Utility

Design Tokens

Max 2 Levels

Responsive Design

When to Use Each Approach

Common Patterns

Hover States

Conditional Classes

Related Documentation

Reference Files

Working on features / Writing Hooks

Working on features / Localization (i18n)