### Install @ant-design/cssinjs with npm

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Use this command to install the library using npm.

```bash
npm install @ant-design/cssinjs
```

--------------------------------

### Install @ant-design/cssinjs with pnpm

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Use this command to install the library using pnpm.

```bash
pnpm add @ant-design/cssinjs
```

--------------------------------

### First Render Example

Source: https://github.com/ant-design/cssinjs/blob/master/docs/demo/first-render.md

This example demonstrates the basic setup for a component's first render using Ant Design's CSS-in-JS. It shows how styles are defined and applied.

```tsx
import React from 'react';
import { createStyles, css } from 'antd-style';

const useStyles = createStyles(({ token }) => ({
  container: {
    display: 'flex',
    flexDirection: 'column',
    alignItems: 'center',
    padding: token.paddingLG,
    border: `1px solid ${token.colorBorder}`,
    borderRadius: token.borderRadiusLG,
  },
  title: {
    fontSize: token.fontSizeHeading1,
    color: token.colorPrimary,
    marginBottom: token.marginLG,
  },
  description: {
    fontSize: token.fontSizeLG,
    color: token.colorTextSecondary,
  },
}));

const FirstRenderDemo = () => {
  const { styles } = useStyles();

  return (
    <div className={styles.container}>
      <h1 className={styles.title}>Welcome to Ant Design CSS-in-JS</h1>
      <p className={styles.description}>
        This is a demonstration of the first render.
      </p>
      <p className={styles.description}>
        Styles are dynamically generated and applied.
      </p>
    </div>
  );
};

export default FirstRenderDemo;
```

--------------------------------

### Diff Salt Example in React

Source: https://github.com/ant-design/cssinjs/blob/master/docs/demo/diff-salt.md

This example demonstrates how to use diff salt with a React component. Ensure you have the necessary CSS-in-JS library and React setup.

```tsx
import React from 'react';
import { useStyle } from '@ant-design/cssinjs';

const App = () => {
  const [token] = useStyle();

  return (
    <div
      style={{
        color: token.colorText,
        padding: token.padding,
        fontSize: token.fontSizeLG,
      }}
    >
      Hello Ant Design CSS-in-JS
    </div>
  );
};

export default App;
```

--------------------------------

### Development Setup

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Commands to set up the development environment for the project.

```bash
npm install
npm start
```

--------------------------------

### Install @ant-design/cssinjs with yarn

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Use this command to install the library using yarn.

```bash
yarn add @ant-design/cssinjs
```

--------------------------------

### Basic Animation Example

Source: https://github.com/ant-design/cssinjs/blob/master/docs/demo/animation.md

A simple example demonstrating how to set up and run a basic animation. Ensure necessary animation libraries are imported.

```tsx
import React from 'react';
import { useSpring, animated } from '@react-spring/web';

const AnimationDemo = () => {
  const props = useSpring({
    from: { opacity: 0, transform: 'translateY(-20px)' },
    to: { opacity: 1, transform: 'translateY(0px)' },
    config: { duration: 500 },
  });

  return (
    <animated.div style={props}>
      Hello, Animation!
    </animated.div>
  );
};

export default AnimationDemo;
```

--------------------------------

### Dynamic Style Example in React

Source: https://github.com/ant-design/cssinjs/blob/master/docs/demo/dynamic.md

This example shows how to dynamically change styles based on component state using the `useStyle` hook. Ensure you have the necessary Ant Design and CSS-in-JS dependencies installed.

```tsx
import React from 'react';
import { useStyle } from '@ant-design/css-in-js';

const DynamicComponent = () => {
  const [styles, token] = useStyle('dynamic-component', (token) => ({
    container: {
      padding: token.padding,
      background: token.colorPrimary,
      color: token.colorTextLightSolid,
      cursor: 'pointer',
    },
    text: {
      fontSize: token.fontSizeHeading1,
    },
  }));

  return (
    <div className={styles.container} onClick={() => alert('Clicked!')}>
      <span className={styles.text}>Click me for dynamic styles</span>
    </div>
  );
};

export default DynamicComponent;
```

--------------------------------

### Define and Use CSS Variables

Source: https://github.com/ant-design/cssinjs/blob/master/docs/demo/css-var.md

This example shows how to define CSS variables using `css` and access them within styles. It's useful for creating themeable components or managing dynamic styles.

```tsx
import React from 'react';
import { css } from '@emotion/react';

const styles = css`
  --primary-color: blue;
  --secondary-color: green;

  h1 {
    color: var(--primary-color);
  }

  p {
    color: var(--secondary-color);
  }
`;

export default () => (
  <div className={styles as any}>
    <h1>Hello World</h1>
    <p>This is a paragraph.</p>
  </div>
);
```

--------------------------------

### Extract Styles with @ant-design/cssinjs

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Example demonstrating how to create a cache, populate it (implicitly through rendering), and then extract styles using `extractStyle`. This is useful for Server-Side Rendering (SSR).

```typescript
import { extractStyle, createCache } from '@ant-design/cssinjs';

// 创建并填充缓存
const cache = createCache();
// 注意：在实际使用中，缓存通常会在渲染组件时自动填充

// 提取样式
const styles = extractStyle(cache, { plain: true, types: ['style', 'token'] });

// 使用提取的样式
const styleElement = document.createElement('style');
styleElement.innerHTML = styles;
document.head.appendChild(styleElement);
```

--------------------------------

### Create Theme Instance with Derivatives

Source: https://context7.com/ant-design/cssinjs/llms.txt

Use `createTheme` to generate a Theme instance from derivative functions. Passing the same function reference ensures cache hits. Multiple derivatives can be combined in sequence.

```tsx
import { createTheme } from '@ant-design/cssinjs';
import { TinyColor } from '@ctrl/tinycolor';

interface DesignToken {
  primaryColor: string;
  borderRadius: number;
  fontSize: number;
}

interface DerivativeToken extends DesignToken {
  primaryColorHover: string;
  primaryColorActive: string;
  fontSizeLG: number;
}

// Derivative function: receives base tokens, returns extended tokens
function derivative(token: DesignToken): DerivativeToken {
  return {
    ...token,
    primaryColorHover: new TinyColor(token.primaryColor).lighten(10).toHexString(),
    primaryColorActive: new TinyColor(token.primaryColor).darken(10).toHexString(),
    fontSizeLG: token.fontSize * 1.25,
  };
}

// Same derivative reference → same Theme object (cached)
const theme = createTheme(derivative);

// Multiple derivatives are applied in sequence
const theme2 = createTheme([derivative, anotherDerivative]);
```

--------------------------------

### createTheme

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Creates a theme object. If the same algorithm is provided, it will return the same object, optimizing theme management.

```APIDOC
## createTheme

### Description

Creates a theme object. When same algorithm provided, it will return same object.

### Usage

```typescript
import { createTheme } from '@ant-design/cssinjs';

// Assuming an algorithm is defined elsewhere
// const theme = createTheme(algorithm);
```
```

--------------------------------

### createTheme

Source: https://context7.com/ant-design/cssinjs/llms.txt

Creates a Theme instance from derivative functions. It caches Theme objects based on function references for efficient reuse.

```APIDOC
## createTheme

### Description
Creates (or retrieves from cache) a `Theme` instance from one or more derivative functions. A derivative function accepts your base design tokens and returns an expanded set of derived tokens. Passing the same function reference always returns the same `Theme` object, enabling cache hits in `useCacheToken`.

### Usage
```tsx
import { createTheme } from '@ant-design/cssinjs';
import { TinyColor } from '@ctrl/tinycolor';

interface DesignToken {
  primaryColor: string;
  borderRadius: number;
  fontSize: number;
}

interface DerivativeToken extends DesignToken {
  primaryColorHover: string;
  primaryColorActive: string;
  fontSizeLG: number;
}

// Derivative function: receives base tokens, returns extended tokens
function derivative(token: DesignToken): DerivativeToken {
  return {
    ...token,
    primaryColorHover: new TinyColor(token.primaryColor).lighten(10).toHexString(),
    primaryColorActive: new TinyColor(token.primaryColor).darken(10).toHexString(),
    fontSizeLG: token.fontSize * 1.25,
  };
}

// Same derivative reference → same Theme object (cached)
const theme = createTheme(derivative);

// Multiple derivatives are applied in sequence
const theme2 = createTheme([derivative, anotherDerivative]);
```
```

--------------------------------

### SSR Style Extraction with createCache and extractStyle

Source: https://context7.com/ant-design/cssinjs/llms.txt

Create a CacheEntity instance with createCache for SSR. Pass this cache to StyleProvider in mock="server" mode. Use extractStyle to retrieve all registered styles as <style> tag strings for injection into the SSR document.

```tsx
import { createCache, StyleProvider, extractStyle } from '@ant-design/cssinjs';
import { renderToString } from 'react-dom/server';

// SSR: create a fresh cache per request
const cache = createCache();

const html = renderToString(
  <StyleProvider mock="server" cache={cache}>
    <App />
  </StyleProvider>
);

// Extract all registered styles as <style> tag strings
const styleHTML = extractStyle(cache);
// → '<style data-css-hash="abc123">...css...</style>'

// Inject into the SSR document:
const fullHTML = `
  <!DOCTYPE html>
  <html>
    <head>${styleHTML}</head>
    <body><div id="root">${html}</div></body>
  </html>
`;
```

--------------------------------

### Apply Legacy Logical Properties Transformer

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Demonstrates how to use the `legacyLogicalPropertiesTransformer` within `StyleProvider` to convert logical CSS properties to their legacy equivalents.

```tsx
import {
  legacyLogicalPropertiesTransformer,
  StyleProvider,
} from '@ant-design/cssinjs';

export default () => (
  <StyleProvider transformers={[legacyLogicalPropertiesTransformer]}>
    <MyApp />
  </StyleProvider>
);
```

--------------------------------

### Configure StyleProvider with Transformers and Linters

Source: https://context7.com/ant-design/cssinjs/llms.txt

Use StyleProvider to configure the global cssinjs environment, including cache, hash priority, injection container, SSR mode, transformers, and linters. All cssinjs-powered components must be rendered within a StyleProvider.

```tsx
import {
  StyleProvider,
  createCache,
  legacyLogicalPropertiesTransformer,
  px2remTransformer,
  logicalPropertiesLinter,
  NaNLinter,
} from '@ant-design/cssinjs';

const cache = createCache();

export default function App() {
  return (
    <StyleProvider
      cache={cache}
      hashPriority="low"           // ':where(.css-abc)' selector — low specificity
      container={document.head}   // where to inject <style> tags
      transformers={[
        legacyLogicalPropertiesTransformer,  // marginInlineStart → marginLeft
        px2remTransformer({ rootValue: 16, precision: 5 }),
      ]}
      linters={[logicalPropertiesLinter, NaNLinter]}
      layer                       // wrap styles in @layer to avoid conflicts
    >
      <MyApplication />
    </StyleProvider>
  );
}
// StyleProvider props:
// autoClear?    boolean          – remove <style> when component unmounts (default false)
// cache?        CacheEntity      – custom cache, required for SSR extraction
// hashPriority? 'low' | 'high'  – 'low' uses :where(), reducing selector specificity
// container?    Element|ShadowRoot – injection target (default: document.head)
// ssrInline?    boolean          – render inline <style> for SSR fallback (not recommended)
// transformers? Transformer[]    – CSS transform pipeline (not dynamically updatable)
// linters?      Linter[]         – dev-only CSS linting
// layer?        boolean          – wraps all styles in CSS @layer
```

--------------------------------

### StyleProvider Configuration

Source: https://context7.com/ant-design/cssinjs/llms.txt

StyleProvider is a React context provider that sets up the global cssinjs environment. It allows configuration of cache, hash priority, injection container, SSR mode, transformers, and linters. All components using cssinjs should be rendered within a StyleProvider.

```APIDOC
## StyleProvider

A React context provider that configures the global cssinjs environment — cache entity, hash priority, injection container, SSR mode, transformers, and linters. All cssinjs-powered components must be rendered inside a `StyleProvider` (or rely on the built-in default context).

### Props
- **autoClear?** (boolean) – remove `<style>` when component unmounts (default false)
- **cache?** (CacheEntity) – custom cache, required for SSR extraction
- **hashPriority?** ('low' | 'high') – 'low' uses :where(), reducing selector specificity
- **container?** (Element|ShadowRoot) – injection target (default: document.head)
- **ssrInline?** (boolean) – render inline `<style>` for SSR fallback (not recommended)
- **transformers?** (Transformer[]) – CSS transform pipeline (not dynamically updatable)
- **linters?** (Linter[]) – dev-only CSS linting
- **layer?** (boolean) – wraps all styles in CSS @layer

### Example
```tsx
import {
  StyleProvider,
  createCache,
  legacyLogicalPropertiesTransformer,
  px2remTransformer,
  logicalPropertiesLinter,
  NaNLinter,
} from '@ant-design/cssinjs';

const cache = createCache();

export default function App() {
  return (
    <StyleProvider
      cache={cache}
      hashPriority="low"           // ':where(.css-abc)' selector — low specificity
      container={document.head}   // where to inject <style> tags
      transformers={[
        legacyLogicalPropertiesTransformer,  // marginInlineStart → marginLeft
        px2remTransformer({ rootValue: 16, precision: 5 }),
      ]}
      linters={[logicalPropertiesLinter, NaNLinter]}
      layer                       // wrap styles in @layer to avoid conflicts
    >
      <MyApplication />
    </StyleProvider>
  );
}
```
```

--------------------------------

### extractStyle

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Extracts the styles from the cache and returns them as a string, with options to control the output format and types of styles.

```APIDOC
## extractStyle

### Description

Extracts the styles from the cache and returns them as a string. This is useful for server-side rendering or for manually injecting styles.

### Parameters

- **cache** (Cache) - Required - The cache instance containing the styles.
- **options** (object | boolean, optional) - Options for extracting the styles.
  - **plain** (boolean, optional) - If true, the styles will be returned in plain format. Default is `false`.
  - **types** (string | string[], optional) - The types of styles to extract. Default is `['style', 'token', 'cssVar']`.

### Returns

- (string): The extracted styles as a string.

### Example

```typescript
import { extractStyle, createCache } from '@ant-design/cssinjs';

// Create and populate cache
const cache = createCache();
// Note: In actual usage, the cache is typically populated automatically when rendering components

// Extract styles
const styles = extractStyle(cache, { plain: true, types: ['style', 'token'] });

// Use extracted styles
const styleElement = document.createElement('style');
styleElement.innerHTML = styles;
document.head.appendChild(styleElement);
```
```

--------------------------------

### Generate chainable CSS calculators with `genCalc`

Source: https://context7.com/ant-design/cssinjs/llms.txt

The `genCalc` factory creates a chainable calculator for CSS arithmetic expressions. It supports 'css' mode for `calc(...)` strings and 'js' mode for numerical evaluation, enabling type-safe token math.

```tsx
import { genCalc } from '@ant-design/cssinjs';

// 'css' mode → generates CSS calc() expressions
const calc = genCalc('css', new Set(['lineHeight']));

const c = calc(16);
c.add(8).equal()              // → 'calc(16px + 8px)'
c.mul(1.5).equal()            // → 'calc(16px * 1.5)'
c.add(calc(4).mul(2)).equal() // → 'calc(16px + 4px * 2)'
c.div(2).add(4).equal()       // → 'calc(16px / 2 + 4px)'

// 'js' mode → evaluates immediately (for SSR or non-CSS contexts)
const jsCalc = genCalc('js', new Set());
jsCalc(16).add(8).equal()     // → 24
jsCalc(100).div(4).equal()    // → 25

// Usage in token derivation:
function derivative(token: DesignToken) {
  const calc = genCalc('css', new Set(['lineHeight']));
  return {
    ...token,
    controlHeight: calc(token.fontSize).mul(2.5).add(token.paddingXS * 2).equal(),
    // → 'calc(14px * 2.5 + 8px)'
  };
}
```

--------------------------------

### Apply Vendor Prefixes with autoPrefixTransformer

Source: https://context7.com/ant-design/cssinjs/llms.txt

The `autoPrefixTransformer` automatically applies vendor prefixes (e.g., `-webkit-`, `-moz-`) to CSS properties for cross-browser compatibility. It's a special sentinel recognized by `StyleProvider` to enable its internal `autoPrefix` flag.

```tsx
import { StyleProvider, autoPrefixTransformer } from '@ant-design/cssinjs';

// autoPrefixTransformer is a special sentinel — StyleProvider detects its
// presence and sets the internal `autoPrefix` flag (handled differently from
// regular transformers).

export default function App() {
  return (
    <StyleProvider transformers={[autoPrefixTransformer]}>
      <MyApp />
    </StyleProvider>
  );
}

// Without autoPrefixTransformer:
// .box { user-select: none; }

// With autoPrefixTransformer:
// .box { -webkit-user-select: none; -moz-user-select: none; user-select: none; }
```

--------------------------------

### StyleProvider

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

The StyleProvider component allows configuration of the CSS-in-JS injection behavior, including options for clearing styles, custom cache entities, hash priority, injection container, SSR fallback, and style transformers.

```APIDOC
## StyleProvider

### Description

The StyleProvider component allows configuration of the CSS-in-JS injection behavior, including options for clearing styles, custom cache entities, hash priority, injection container, SSR fallback, and style transformers.

### Props

- **autoClear** (boolean) - Optional - Clear inject style element when component remove. Default: `false`
- **cache** (CacheEntity) - Optional - Config cssinjs cache entity. Only set when you need ssr to extract style on you own.
- **hashPriority** ('low' | 'high') - Optional - Use `:where` selector to reduce hashId css selector priority. Default: `'low'`
- **container** (Element | ShadowRoot) - Optional - Tell cssinjs where to inject style in. Default: `document.head`
- **ssrInline** (boolean) - Optional - Component wil render inline `<style />` for fallback in SSR. Not recommend. Default: `false`
- **transformers** (Transformer[]) - Optional - Transform css before inject in document. Please note that `transformers` do not support dynamic update.
```

--------------------------------

### createCache

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

Factory function to create a CacheEntity, which is used by StyleProvider to manage CSS styles.

```APIDOC
## createCache

### Description

Factory function to create a CacheEntity, which is used by StyleProvider to manage CSS styles.

### Usage

```typescript
import { createCache } from '@ant-design/cssinjs';

const cache = createCache();
```
```

--------------------------------

### Convert CSS Logical Properties to Legacy Physical Equivalents

Source: https://context7.com/ant-design/cssinjs/llms.txt

Use `legacyLogicalPropertiesTransformer` to convert modern CSS logical properties to their legacy physical equivalents. This is essential for supporting older browsers that do not understand logical properties. It can be applied globally via `StyleProvider` or manually during build time.

```tsx
import {
  StyleProvider,
  legacyLogicalPropertiesTransformer,
  useStyleRegister,
  createTheme,
} from '@ant-design/cssinjs';

// Input CSSObject before transform:
const inputStyle = {
  '.my-card': {
    marginInline: '16px',          // → marginLeft: 16px; marginRight: 16px
    paddingBlock: '8px 12px',      // → paddingTop: 8px; paddingBottom: 12px
    insetInlineStart: '0',         // → left: 0
    borderInlineStart: '1px solid #ccc',   // → borderLeft: 1px solid #ccc
    borderStartStartRadius: '4px', // → borderTopLeftRadius: 4px
  },
};

// Wrap your app with the transformer active:
export default function App() {
  return (
    <StyleProvider transformers={[legacyLogicalPropertiesTransformer]}>
      <MyApp />
    </StyleProvider>
  );
}

// Or apply it manually at build time:
import { parseStyle } from '@ant-design/cssinjs';
const [cssStr] = parseStyle(inputStyle, {
  transformers: [legacyLogicalPropertiesTransformer],
  hashId: '',
});
// cssStr → '.my-card{margin-left:16px;margin-right:16px;padding-top:8px;...}'
```

--------------------------------

### Derive and Cache Tokens with Overrides

Source: https://context7.com/ant-design/cssinjs/llms.txt

The `useCacheToken` hook derives and caches tokens from a Theme and partial overrides. It returns computed tokens, CSS variable references, and style information. Configure CSS variable generation and token formatting.

```tsx
import { createTheme, useCacheToken } from '@ant-design/cssinjs';
import React from 'react';

const defaultToken: DesignToken = {
  primaryColor: '#1890ff',
  borderRadius: 4,
  fontSize: 14,
};

const theme = createTheme(derivative);

// Typical usage inside a custom useToken hook:
export function useToken() {
  const [overrideToken] = React.useContext(DesignTokenContext);

  const [token, hashId, realToken] = useCacheToken<DerivativeToken, DesignToken>(
    theme,
    // Array of partial tokens merged left-to-right:
    [defaultToken, overrideToken],
    {
      salt: 'my-component-lib',  // differentiate caches across versions
      cssVar: {
        key: 'my-theme-key',     // unique key for CSS variable scope
        prefix: 'my',            // → --my-primary-color
        unitless: { lineHeight: true },   // don't append 'px' to this token
        ignore: { someInternal: true },   // skip this token entirely
        hashed: true,            // scope vars under hash selector
      },
      formatToken: (merged) => ({
        ...merged,
        buttonHeight: merged.fontSize * 2.5,
      }),
    }
  );

  return { token, hashId, realToken };
}

// token.primaryColor === 'var(--my-primary-color)'
// realToken.primaryColor === '#1890ff'
// hashId === 'css-dev-only-do-not-override-abc123' (dev) / 'css-abc123' (prod)
```

--------------------------------

### createCache Function

Source: https://context7.com/ant-design/cssinjs/llms.txt

The createCache function generates a CacheEntity instance, which is essential for managing injected style hashes and CSS variable states. This instance is crucial for enabling SSR style extraction when passed to the StyleProvider.

```APIDOC
## createCache

Creates a new `CacheEntity` instance that holds all injected style hashes and CSS variable state. Pass the returned value to `<StyleProvider cache={...}>` to enable SSR style extraction.

### Example
```tsx
import { createCache, StyleProvider, extractStyle } from '@ant-design/cssinjs';
import { renderToString } from 'react-dom/server';

// SSR: create a fresh cache per request
const cache = createCache();

const html = renderToString(
  <StyleProvider mock="server" cache={cache}>
    <App />
  </StyleProvider>
);

// Extract all registered styles as <style> tag strings
const styleHTML = extractStyle(cache);
// → '<style data-css-hash="abc123">...css...</style>'

// Inject into the SSR document:
const fullHTML = `
  <!DOCTYPE html>
  <html>
    <head>${styleHTML}</head>
    <body><div id="root">${html}</div></body>
  </html>
`;
```
```

--------------------------------

### `unit` utility

Source: https://context7.com/ant-design/cssinjs/llms.txt

A utility function that appends 'px' to a number or returns a string value unchanged. It's useful for handling CSS values that might be numeric or already formatted strings within style functions.

```APIDOC
## `unit`

A utility that appends `'px'` to a number, or returns a string value unchanged. Useful inside style functions when a token value may be either a numeric pixel value or an already-formatted CSS string (e.g., `'var(--token)'`).

```tsx
import { unit } from '@ant-design/cssinjs';

unit(16)                        // → '16px'
unit(0)                         // → 0      (zero is returned as-is)
unit('var(--my-spacing)')       // → 'var(--my-spacing)'
unit('1.5rem')                  // → '1.5rem'

// In style functions with CSS variable tokens:
const genButtonStyle = (token: ButtonToken): CSSObject => ({
  '.btn': {
    // token.borderWidth might be 1 (number) or 'var(--btn-border-width)' (cssVar mode)
    border: `${unit(token.borderWidth)} solid ${token.borderColor}`,
    padding: `${unit(token.paddingXS)} ${unit(token.padding)}`,
  },
});
```
```

--------------------------------

### legacyLogicalPropertiesTransformer

Source: https://github.com/ant-design/cssinjs/blob/master/README.md

A transformer that converts logical CSS properties (e.g., marginBlockStart) to their legacy physical equivalents (e.g., marginTop).

```APIDOC
## legacyLogicalPropertiesTransformer

### Description

Convert logical properties to legacy properties. e.g. `marginBlockStart` to `marginTop`.

### Supported Properties

- inset
- margin
- padding
- border

### Usage

```tsx
import {
  legacyLogicalPropertiesTransformer,
  StyleProvider,
} from '@ant-design/cssinjs';

export default () => (
  <StyleProvider transformers={[legacyLogicalPropertiesTransformer]}>
    <MyApp />
  </StyleProvider>
);
```
```

--------------------------------

### Integrate CSS Linters with `StyleProvider`

Source: https://context7.com/ant-design/cssinjs/llms.txt

Development-only CSS validators like `logicalPropertiesLinter`, `NaNLinter`, `legacyNotSelectorLinter`, and `parentSelectorLinter` can be passed to `StyleProvider`'s `linters` prop to detect problematic CSS patterns.

```tsx
import {
  StyleProvider,
  logicalPropertiesLinter,
  NaNLinter,
  legacyNotSelectorLinter,
  parentSelectorLinter,
} from '@ant-design/cssinjs';

export default function App() {
  return (
    <StyleProvider
      linters={[
        logicalPropertiesLinter,   // warns on marginLeft, paddingRight, etc. (use logical props)
        NaNLinter,                  // warns on any property value containing NaN
        legacyNotSelectorLinter,    // warns on :not(.foo.bar) (unsupported in older browsers)
        parentSelectorLinter,       // warns on & used outside root (Sass-style nesting issues)
      ]}>
      <MyApp />
    </StyleProvider>
  );
}

// logicalPropertiesLinter warns for:
//   marginLeft / marginRight / paddingLeft / paddingRight / left / right
//   borderLeft* / borderRight* / borderTopLeftRadius / borderTopRightRadius etc.
//   textAlign: 'left' | 'right'
//   margin: '0 8px 0 16px' (different left/right values)

// NaNLinter warns for:
//   fontSize: NaN  or  width: 'NaNpx'

// Linters implement: type Linter = (key: string, value: any, info: { path, hashId, parentSelectors }) => void
```

--------------------------------

### `genCalc` factory

Source: https://context7.com/ant-design/cssinjs/llms.txt

A factory function that creates a chainable calculator for arithmetic CSS expressions. It supports 'css' mode for generating `calc(...)` strings and 'js' mode for immediate numerical evaluation, enabling type-safe token math.

```APIDOC
## `genCalc`

A factory that creates a chainable calculator for arithmetic CSS expressions. In `'css'` mode it builds `calc(...)` strings; in `'js'` mode it evaluates numerically. Enables type-safe, composable token math without string concatenation.

```tsx
import { genCalc } from '@ant-design/cssinjs';

// 'css' mode → generates CSS calc() expressions
const calc = genCalc('css', new Set(['lineHeight']));

const c = calc(16);
c.add(8).equal()              // → 'calc(16px + 8px)'
c.mul(1.5).equal()            // → 'calc(16px * 1.5)'
c.add(calc(4).mul(2)).equal() // → 'calc(16px + 4px * 2)'
c.div(2).add(4).equal()       // → 'calc(16px / 2 + 4px)'

// 'js' mode → evaluates immediately (for SSR or non-CSS contexts)
const jsCalc = genCalc('js', new Set());
jsCalc(16).add(8).equal()     // → 24
jsCalc(100).div(4).equal()    // → 25

// Usage in token derivation:
function derivative(token: DesignToken) {
  const calc = genCalc('css', new Set(['lineHeight']));
  return {
    ...token,
    controlHeight: calc(token.fontSize).mul(2.5).add(token.paddingXS * 2).equal(),
    // → 'calc(14px * 2.5 + 8px)'
  };
}
```
```

--------------------------------

### Extract Styles for Server-Side Rendering with extractStyle

Source: https://context7.com/ant-design/cssinjs/llms.txt

Use `extractStyle` to serialize styles from a `Cache` instance into `<style>` tags for SSR. Supports filtering by style type and a `once` flag to prevent re-extraction. Use `{ plain: true }` for plain CSS output.

```tsx
import { createCache, extractStyle, StyleProvider } from '@ant-design/cssinjs';
import { renderToString } from 'react-dom/server';

export async function renderPage(req, res) {
  const cache = createCache();

  const html = renderToString(
    <StyleProvider mock="server" cache={cache}>
      <App />
    </StyleProvider>
  );

  // Full extraction — returns <style> tag strings (token vars + component styles)
  const styleHTML = extractStyle(cache);

  // Plain CSS extraction (no wrapping <style> tags) — for injecting via a CSS file
  const plainCSS = extractStyle(cache, { plain: true });

  // Extract only CSS variable token styles (skip component styles)
  const tokenOnlyCSS = extractStyle(cache, { types: ['token', 'cssVar'] });

  // One-shot extraction — subsequent calls skip already-extracted keys
  const firstExtract = extractStyle(cache, { once: true });
  const secondExtract = extractStyle(cache, { once: true }); // → '' (already extracted)

  res.send(
    "\
    <!DOCTYPE html>
    <html>
      <head>${styleHTML}</head>
      <body>
        <div id=\"root\">${html}</div>
        <script>
          // Client-side hydration will reuse server-injected styles via data-css-hash
          hydrateRoot(document.getElementById('root'), <StyleProvider cache={createCache()}><App /></StyleProvider>)
        </script>
      </body>
    </html>
    "
  );
}
```

--------------------------------

### useStyleRegister

Source: https://context7.com/ant-design/cssinjs/llms.txt

A React hook that compiles CSSInterpolation into a scoped CSS string and injects it into the document. It deduplicates styles globally to prevent redundant `<style>` tags.

```APIDOC
## useStyleRegister

### Description
A React hook that compiles a `CSSInterpolation` object into a scoped, hash-isolated CSS string and injects it as a `<style>` tag in the document (or caches it for SSR extraction). Internally deduplicates styles globally — calling this hook in 1000 identical components only injects one `<style>` tag.

### Usage
```tsx
import { useStyleRegister, Keyframes } from '@ant-design/cssinjs';
import type { CSSInterpolation } from '@ant-design/cssinjs';

const spinAnimation = new Keyframes('spin', {
  from: { transform: 'rotate(0deg)' },
  to:   { transform: 'rotate(360deg)' },
});

function useButtonStyle(prefixCls: string, token: DerivativeToken, hashId: string) {
  const { theme } = useThemeContext();

  useStyleRegister(
    {
      theme,
      token,               // used as part of cache key
      path: [prefixCls],   // cache path segments
      hashId,              // scopes all selectors: .btn → :where(.css-abc123).btn
      layer: { name: 'components', dependencies: ['base'] },
      nonce: () => document.querySelector('meta[name=csp-nonce]')?.content ?? '',
      clientOnly: false,   // if true, style is skipped during SSR extraction
      order: 0,            // insertion priority (lower = earlier in <head>)
    },
    (): CSSInterpolation => [
      {
        [`.${prefixCls}`]: {
          display: 'inline-flex',
          alignItems: 'center',
          padding: `${token.paddingXS}px ${token.padding}px`,
          backgroundColor: token.colorPrimary,
          borderRadius: token.borderRadius,
          fontSize: token.fontSize,
          color: '#fff',
          cursor: 'pointer',
          transition: 'opacity 0.2s',

          '&:hover': { opacity: 0.85 },
          '&:disabled': { opacity: 0.4, cursor: 'not-allowed' },

          '@media (max-width: 768px)': {
            [`.${prefixCls}`]: { width: '100%' },
          },
        },
      },
      spinAnimation,  // Keyframes instance auto-registers @keyframes block
    ],
  );
}
```
```

--------------------------------

### useCacheToken

Source: https://context7.com/ant-design/cssinjs/llms.txt

A React hook that derives and globally caches the full token set from a Theme and partial token overrides. It returns the computed token, a hash ID, and the real token values.

```APIDOC
## useCacheToken

### Description
A React hook that derives and globally caches the full token set from a `Theme` and one or more partial token overrides. Returns `[token, hashId, realToken, cssVarsStr, cssVarKey]`. The `token` values are replaced with CSS variable references (`var(--prefix-token-name)`) when `cssVar` is configured; `realToken` holds the original computed values.

### Usage
```tsx
import { createTheme, useCacheToken } from '@ant-design/cssinjs';
import React from 'react';

const defaultToken: DesignToken = {
  primaryColor: '#1890ff',
  borderRadius: 4,
  fontSize: 14,
};

const theme = createTheme(derivative);

// Typical usage inside a custom useToken hook:
export function useToken() {
  const [overrideToken] = React.useContext(DesignTokenContext);

  const [token, hashId, realToken] = useCacheToken<DerivativeToken, DesignToken>(
    theme,
    // Array of partial tokens merged left-to-right:
    [defaultToken, overrideToken],
    {
      salt: 'my-component-lib',  // differentiate caches across versions
      cssVar: {
        key: 'my-theme-key',     // unique key for CSS variable scope
        prefix: 'my',            // → --my-primary-color
        unitless: { lineHeight: true },   // don't append 'px' to this token
        ignore: { someInternal: true },   // skip this token entirely
        hashed: true,            // scope vars under hash selector
      },
      formatToken: (merged) => ({
        ...merged,
        buttonHeight: merged.fontSize * 2.5,
      }),
    }
  );

  return { token, hashId, realToken };
}

// token.primaryColor === 'var(--my-primary-color)'
// realToken.primaryColor === '#1890ff'
// hashId === 'css-dev-only-do-not-override-abc123' (dev) / 'css-abc123' (prod)
```
```

--------------------------------

### CSS Linters

Source: https://context7.com/ant-design/cssinjs/llms.txt

Development-only CSS validators (`logicalPropertiesLinter`, `NaNLinter`, `legacyNotSelectorLinter`, `parentSelectorLinter`) that emit console warnings for problematic CSS patterns. They are passed to `StyleProvider`'s `linters` prop and run in non-production environments.

```APIDOC
### Linters: `logicalPropertiesLinter`, `NaNLinter`, `legacyNotSelectorLinter`, `parentSelectorLinter`

Development-only CSS validators that emit console warnings when problematic CSS patterns are detected. Pass them to `StyleProvider`'s `linters` prop. They run after transformers and only in non-production environments.

```tsx
import {
  StyleProvider,
  logicalPropertiesLinter,
  NaNLinter,
  legacyNotSelectorLinter,
  parentSelectorLinter,
} from '@ant-design/cssinjs';

export default function App() {
  return (
    <StyleProvider
      linters={[
        logicalPropertiesLinter,   // warns on marginLeft, paddingRight, etc. (use logical props)
        NaNLinter,                  // warns on any property value containing NaN
        legacyNotSelectorLinter,    // warns on :not(.foo.bar) (unsupported in older browsers)
        parentSelectorLinter,       // warns on & used outside root (Sass-style nesting issues)
      ]}
    >
      <MyApp />
    </StyleProvider>
  );
}

// logicalPropertiesLinter warns for:
//   marginLeft / marginRight / paddingLeft / paddingRight / left / right
//   borderLeft* / borderRight* / borderTopLeftRadius / borderTopRightRadius etc.
//   textAlign: 'left' | 'right'
//   margin: '0 8px 0 16px' (different left/right values)

// NaNLinter warns for:
//   fontSize: NaN  or  width: 'NaNpx'

// Linters implement: type Linter = (key: string, value: any, info: { path, hashId, parentSelectors }) => void
```
```

--------------------------------

### Register Styles with CSS-in-JS

Source: https://context7.com/ant-design/cssinjs/llms.txt

The `useStyleRegister` hook compiles CSS interpolations into scoped, hash-isolated CSS and injects it as a style tag. It handles global deduplication and supports SSR extraction. Configure theme, tokens, path, hashId, layer, and other options.

```tsx
import { useStyleRegister, Keyframes } from '@ant-design/cssinjs';
import type { CSSInterpolation } from '@ant-design/cssinjs';

const spinAnimation = new Keyframes('spin', {
  from: { transform: 'rotate(0deg)' },
  to:   { transform: 'rotate(360deg)' },
});

function useButtonStyle(prefixCls: string, token: DerivativeToken, hashId: string) {
  const { theme } = useThemeContext();

  useStyleRegister(
    {
      theme,
      token,               // used as part of cache key
      path: [prefixCls],   // cache path segments
      hashId,              // scopes all selectors: .btn → :where(.css-abc123).btn
      layer: { name: 'components', dependencies: ['base'] },
      nonce: () => document.querySelector('meta[name=csp-nonce]')?.content ?? '',
      clientOnly: false,   // if true, style is skipped during SSR extraction
      order: 0,            // insertion priority (lower = earlier in <head>)
    },
    (): CSSInterpolation => [
      {
        [`.${prefixCls}`]: {
          display: 'inline-flex',
          alignItems: 'center',
          padding: `${token.paddingXS}px ${token.padding}px`,
          backgroundColor: token.colorPrimary,
          borderRadius: token.borderRadius,
          fontSize: token.fontSize,
          color: '#fff',
          cursor: 'pointer',
          transition: 'opacity 0.2s',

          '&:hover': { opacity: 0.85 },
          '&:disabled': { opacity: 0.4, cursor: 'not-allowed' },

          '@media (max-width: 768px)': {
            [`.${prefixCls}`]: { width: '100%' },
          },
        },
      },
      spinAnimation,  // Keyframes instance auto-registers @keyframes block
    ],
  );
}
```

--------------------------------

### Use Logical Properties Transformer

Source: https://github.com/ant-design/cssinjs/blob/master/docs/demo/transformer.md

Applies logical properties for better internationalization support. Ensure the transformer is correctly configured in your build process.

```tsx
import React from 'react';
import { useStyle } from '@ant-design/cssinjs';

const App = () => {
  const [token] = useStyle(styles);

  return (
    <div
      className={token.container}
      style={{
        // Use logical properties
        paddingBlockStart: token.padding,
        paddingInlineEnd: token.padding,
        paddingBlockEnd: token.padding,
        paddingInlineStart: token.padding,
      }}
    >
      Hello World
    </div>
  );
};

export default App;

const styles = {
  container: {
    // Use logical properties
    padding: '16px',
  },
};
```

--------------------------------

### Append 'px' to numbers with `unit` utility

Source: https://context7.com/ant-design/cssinjs/llms.txt

Use the `unit` utility to append 'px' to numeric values, or return string values as-is. This is useful for CSS properties where values can be numbers or CSS variables.

```tsx
import { unit } from '@ant-design/cssinjs';

unit(16)                        // → '16px'
unit(0)                         // → 0      (zero is returned as-is)
unit('var(--my-spacing)')       // → 'var(--my-spacing)'
unit('1.5rem')                  // → '1.5rem'

// In style functions with CSS variable tokens:
const genButtonStyle = (token: ButtonToken): CSSObject => ({
  '.btn': {
    // token.borderWidth might be 1 (number) or 'var(--btn-border-width)' (cssVar mode)
    border: `${unit(token.borderWidth)} solid ${token.borderColor}`,
    padding: `${unit(token.paddingXS)} ${unit(token.padding)}`,
  },
});
```

--------------------------------

### Compute tokens with `getComputedToken` utility

Source: https://context7.com/ant-design/cssinjs/llms.txt

The `getComputedToken` utility runs a base token through a theme's derivative function and merges override tokens. It's useful for computing final token sets outside React components, such as in unit tests or style precompilation scripts.

```tsx
import { createTheme, getComputedToken } from '@ant-design/cssinjs';

const theme = createTheme(derivative);

const baseToken: DesignToken = {
  primaryColor: '#1890ff',
  borderRadius: 4,
  fontSize: 14,
};

const override = { primaryColor: '#ff4d4f' };

// Returns derivativeToken merged with override, then optionally reformatted:
const computed = getComputedToken(
  baseToken,
  override,
  theme,
  (merged) => ({
    ...merged,
    buttonHeight: merged.fontSize * 2.5,
  })
);

console.log(computed.primaryColor);         // '#ff4d4f' (override wins)
console.log(computed.primaryColorDisabled); // 'rgba(255,77,79,0.5)' (derived)
console.log(computed.buttonHeight);         // 35 (from formatToken)
```

--------------------------------

### Register Component-Level CSS Variables with useCSSVarRegister

Source: https://context7.com/ant-design/cssinjs/llms.txt

Use `useCSSVarRegister` to transform token maps into CSS custom properties and inject them as scoped blocks. Pass `realToken` to `token` for raw values to become CSS variable declarations. Ensure `key` matches `useCacheToken`'s key.

```tsx
import { useCSSVarRegister } from '@ant-design/cssinjs';

const Button = ({ type = 'default' }) => {
  const { theme, token, hashId, cssVarKey, realToken } = useToken();

  // Register component-level CSS variables scoped to 'ant-btn'
  const [cssVarToken] = useCSSVarRegister(
    {
      path: ['ant-btn'],
      key: cssVarKey,         // must match the key used in useCacheToken
      prefix: 'btn',         // → --btn-padding, --btn-border-radius
      token: realToken,       // raw values, NOT var() references
      hashId,
      unitless: { lineHeight: true },
      ignore: { someFlag: true },
      scope: 'ant-btn',      // scopes to .ant-btn elements
      nonce: undefined,
    },
    () => ({
      // Extra component-specific tokens to expose as CSS vars:
      buttonPadding: '4px 16px',
      buttonBorderWidth: `${realToken.borderWidth * 2}px`,
    }),
  );

  // Merge CSS-var token references back into style functions:
  const mergedToken = { ...token, ...cssVarToken };
  // mergedToken.buttonPadding === 'var(--btn-button-padding)'

  useStyleRegister({ theme, token, hashId, path: ['ant-btn'] }, () => ({
    '.ant-btn': { padding: mergedToken.buttonPadding }
  }));

  return <button className={`ant-btn ${hashId} ${cssVarKey}`}>{...}</button>;
};
```