Emotion required

Rule

All styled components and CSS-in-JS in this codebase use Emotion:

• styled from @emotion/styled
• css from @emotion/react

Do not use styled-components, even though the package appears in package.json ("styled-components": "5.3.5") as a legacy dependency. New code must not import from styled-components.

Imports

The canonical pair:

import styled from '@emotion/styled';
import { css } from '@emotion/react';

Both are commonly used in the same file: styled.x for components, css template literals for reusable CSS chunks that get composed into styled blocks (see the XxxCSS-suffix convention).

State transforms (hover / active)

For programmatic color manipulation (darken on hover, lighten on active, alpha adjustments), use polished, not chroma-js:

import { darken } from 'polished';

Canonical pattern for state-driven backgrounds:

const getButtonBackground = (background) => {
  const hover = darken(0.03, background);
  const active = darken(0.05, background);

  return css`
    background: ${background};
    &:hover  { background: ${hover}; }
    &:active { background: ${active}; }
  `;
};

Reference: libs/core/src/components/general/Button/Button.component.js.

Theme & global styles

• Theme is provided through the wrapped StylingProviders at @codebase/core/components/providers/StylingProviders — it composes Emotion's ThemeProvider, WebFontProvider, and the project's GlobalStyles.
• Never reach for ThemeProvider from styled-components or instantiate Emotion's ThemeProvider directly. Always go through StylingProviders.

File location

Styled exports live in <Component>.styles.js siblings to the implementation. Reusable CSS chunks shared across multiple styled blocks use the <Name>CSS suffix (e.g. EmptyButtonCSS) — usually colocated with the styled-component file that owns the base style.

Forbidden

Edge cases

• Third-party components with their own theming: components from react-tippy or react-konva may use their own style systems internally — that's fine. The rule applies only to our CSS-in-JS, not to the third-party library's internals.
• SSR: @emotion/server is already wired through the Next.js setup. Don't add custom SSR style extraction for styled-components.
• Generated styled types: Nx generators are pre-configured for Emotion (nx.json → "style": "@emotion/styled"). When creating a new lib/component via nx g, this is automatic — don't override it.

References

• Good examples — canonical patterns from Button, CardGrid, EmptyButtonCSS, and Page.styles.js.
• Bad examples — common wrong shapes the agent will reach for if not told otherwise.
• Rationale — why Emotion, why styled-components stays out, and what would change this rule.