# React 项目
npm install @stitches/react
 
# 框架无关（Vue、Svelte、原生 HTML 等）
npm install @stitches/core

// stitches.config.ts
import { createStitches } from '@stitches/react'
 
export const {
  styled,
  css,
  globalCss,
  keyframes,
  getCssText,
  theme,
  createTheme,
  config,
} = createStitches({
  // 主题前缀
  prefix: '',
 
  // 主题令牌（Design Tokens）
  theme: {
    colors: {
      gray100: '#fcfcfc',
      gray200: '#e8e8e8',
      gray300: '#d6d6d6',
      gray400: '#c4c4c4',
      gray500: '#b2b2b2',
      gray600: '#a0a0a0',
      gray700: '#8e8e8e',
      gray800: '#7c7c7c',
      gray900: '#6a6a6a',
 
      blue100: '#e6f0ff',
      blue500: '#0066ff',
      blue800: '#003d99',
 
      violet100: '#f0e6ff',
      violet500: '#7700ff',
      violet800: '#4d0099',
 
      // 语义化别名
      primary: '$violet500',
      secondary: '$blue500',
      background: '$gray100',
      text: '$gray900',
    },
    space: {
      1: '4px',
      2: '8px',
      3: '12px',
      4: '16px',
      5: '24px',
      6: '32px',
      7: '48px',
      8: '64px',
      9: '80px',
    },
    fontSizes: {
      xs: '12px',
      sm: '14px',
      base: '16px',
      lg: '18px',
      xl: '20px',
      '2xl': '24px',
      '3xl': '30px',
    },
    fonts: {
      sans: 'system-ui, -apple-system, sans-serif',
      mono: 'Menlo, monospace',
    },
    radii: {
      sm: '4px',
      md: '8px',
      lg: '16px',
      round: '9999px',
    },
    shadows: {
      sm: '0 1px 2px rgba(0, 0, 0, 0.05)',
      md: '0 4px 6px rgba(0, 0, 0, 0.1)',
      lg: '0 10px 15px rgba(0, 0, 0, 0.15)',
    },
  },
 
  // 响应式断点
  media: {
    bp1: '(min-width: 480px)',
    bp2: '(min-width: 768px)',
    bp3: '(min-width: 1024px)',
    bp4: '(min-width: 1280px)',
  },
 
  // 自定义工具函数
  utils: {
    // 简写属性
    pt: (value) => ({ paddingTop: value }),
    pb: (value: string) => ({ paddingBottom: value }),
    px: (value: string) => ({ paddingLeft: value, paddingRight: value }),
    py: (value: string) => ({ paddingTop: value, paddingBottom: value }),
    mx: (value: string) => ({ marginLeft: value, marginRight: value }),
    my: (value: string) => ({ marginTop: value, marginBottom: value }),
 
    // 复合工具
    size: (value: string) => ({
      width: value,
      height: value,
    }),
 
    // 省略号
    ellipsis: (value: boolean) =>
      value === true
        ? {
            overflow: 'hidden',
            textOverflow: 'ellipsis',
            whiteSpace: 'nowrap',
          }
        : {},
  },
})

// Button.tsx
import { styled } from './stitches.config'
 
const Button = styled('button', {
  // 基础样式
  display: 'inline-flex',
  alignItems: 'center',
  justifyContent: 'center',
  borderRadius: '$md',
  fontFamily: '$sans',
  border: 'none',
  cursor: 'pointer',
  transition: 'all 150ms ease',
 
  // 变体定义
  variants: {
    // 颜色变体
    color: {
      primary: {
        backgroundColor: '$primary',
        color: 'white',
        '&:hover': { backgroundColor: '$violet800' },
      },
      secondary: {
        backgroundColor: '$secondary',
        color: 'white',
        '&:hover': { backgroundColor: '$blue800' },
      },
      ghost: {
        backgroundColor: 'transparent',
        color: '$text',
        '&:hover': { backgroundColor: '$gray200' },
      },
    },
    // 尺寸变体
    size: {
      sm: { px: '$2', py: '$1', fontSize: '$sm' },
      md: { px: '$4', py: '$2', fontSize: '$base' },
      lg: { px: '$6', py: '$3', fontSize: '$lg' },
    },
    // 布尔变体
    outlined: {
      true: {
        backgroundColor: 'transparent',
        border: '2px solid currentColor',
      },
    },
  },
 
  // 默认变体值
  defaultVariants: {
    color: 'primary',
    size: 'md',
  },
 
  // 复合变体
  compoundVariants: [
    {
      color: 'primary',
      outlined: true,
      css: {
        borderColor: '$primary',
        color: '$primary',
      },
    },
    {
      color: 'secondary',
      outlined: true,
      css: {
        borderColor: '$secondary',
        color: '$secondary',
      },
    },
  ],
})
 
// 使用
function App() {
  return (
    <div style={{ display: 'flex', gap: '16px', padding: '32px' }}>
      <Button>主要按钮</Button>
      <Button color="secondary">次要按钮</Button>
      <Button color="ghost">幽灵按钮</Button>
      <Button outlined>轮廓按钮</Button>
      <Button size="lg" color="primary">
        大号按钮
      </Button>
    </div>
  )
}

import { createStitches } from '@stitches/react'
 
export const { styled, css, /* ... */ } = createStitches({
  prefix: string,       // CSS 变量前缀
  theme: ThemeConfig,   // 设计令牌定义
  media: MediaConfig,   // 响应式断点
  utils: UtilsConfig,   // 自定义工具函数
})

// 前缀 $ 引用令牌
backgroundColor: '$primary'
 
// 语义化别名
colors: {
  primary: '$violet500',  // 引用同 scale 上的其他值
}
 
// 局部作用域令牌（双 $$）
css: {
  $$shadowColor: 'rgba(0,0,0,0.1)',
  boxShadow: '0 2px 4px $$shadowColor',
}
 
// Scale 前缀跨类别引用
color: '$colors$purple500'

const Card = styled('div', {
  variants: {
    // 单选变体
    variant: {
      elevated: { boxShadow: '$md' },
      outlined: { border: '1px solid $gray300' },
      ghost: { backgroundColor: 'transparent' },
    },
    // 尺寸变体
    size: {
      sm: { padding: '$2' },
      md: { padding: '$4' },
      lg: { padding: '$6' },
    },
    // 布尔变体
    interactive: {
      true: {
        cursor: 'pointer',
        transition: 'transform 150ms ease',
        '&:hover': { transform: 'translateY(-2px)' },
      },
    },
  },
 
  defaultVariants: {
    variant: 'elevated',
    size: 'md',
  },
 
  // 复合变体：多个变体条件同时满足时生效
  compoundVariants: [
    {
      variant: 'elevated',
      interactive: true,
      css: {
        boxShadow: '$lg',
        '&:hover': { boxShadow: '$lg', transform: 'translateY(-4px)' },
      },
    },
  ],
})
 
// 使用
<Card variant="elevated" size="lg" interactive={true} />

<Card
  size={{
    '@initial': 'sm',   // 默认（最小屏幕）
    '@bp1': 'md',       // 480px+
    '@bp2': 'lg',       // 768px+
  }}
/>

import { CSS, VariantProps } from '@stitches/react'
 
// CSS 类型用于 css prop
type ButtonCSS = CSS
 
// 提取组件的变体类型
type ButtonVariants = VariantProps<typeof Button>

const darkTheme = createTheme({
  colors: {
    background: '#1a1a1a',
    text: '#ffffff',
    primary: '#a78bfa',
  },
})
 
// 应用主题
document.documentElement.classList.add(darkTheme.className)

// Next.js _document.tsx
import { getCssText } from './stitches.config'
 
export default class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          <style
            id="stitches"
            dangerouslySetInnerHTML={{ __html: getCssText() }}
          />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

utils: {
  // 简写
  pt: (value) => ({ paddingTop: value }),
  px: (value) => ({ paddingLeft: value, paddingRight: value }),
 
  // 复合工具
  size: (value) => ({ width: value, height: value }),
 
  // 条件工具
  truncate: (lines: number) => ({
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    display: '-webkit-box',
    WebkitLineClamp: lines,
    WebkitBoxOrient: 'vertical',
  }),
}

<Button
  css={{
    backgroundColor: '$blue500',
    borderRadius: '$round',
    '@bp2': {
      padding: '$6',
    },
  }}
/>

// 基础组件
const BaseButton = styled('button', { /* ... */ })
 
// 继承并扩展
const IconButton = styled(BaseButton, {
  size: '$8',
  borderRadius: '$round',
  padding: 0,
})

{
  "compilerOptions": {
    "strict": true,
    "jsx": "react-jsx"
  }
}

// next.config.js
// Stitches 无需特殊 webpack 配置
module.exports = {
  reactStrictMode: true,
}
 
// pages/_document.tsx
import Document, { Html, Head, Main, NextScript } from 'next/document'
import { getCssText } from '../stitches/config'
 
export default class MyDocument extends Document {
  render() {
    return (
      <Html>
        <Head>
          <style
            id="stitches"
            dangerouslySetInnerHTML={{ __html: getCssText() }}
          />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

// jest.setup.ts
// Stitches 组件在测试环境中可直接使用，无需额外 mock
import '@testing-library/jest-dom'
 
// vitest 同样兼容
// Stitches 生成的类名在 jsdom 中正常工作

// ✅ 推荐：使用令牌
const Card = styled('div', {
  backgroundColor: '$background',
  borderRadius: '$md',
  padding: '$4',
  boxShadow: '$sm',
})
 
// ❌ 不推荐：硬编码
const Card = styled('div', {
  backgroundColor: '#fcfcfc',
  borderRadius: '8px',
  padding: '16px',
  boxShadow: '0 1px 2px rgba(0,0,0,0.05)',
})

// ✅ 推荐：合理粒度
const Button = styled('button', {
  variants: {
    color: { primary: {}, secondary: {}, ghost: {} },
    size: { sm: {}, md: {}, lg: {} },
  },
})
 
// ❌ 不推荐：过细粒度（用 css prop 代替）
const Button = styled('button', {
  variants: {
    marginTop: { '4px': {}, '8px': {}, '12px': {} }, // 应使用 css prop
  },
})

// ✅ 推荐：只在真正需要时使用
compoundVariants: [
  {
    color: 'primary',
    disabled: true,
    css: { opacity: 0.5, cursor: 'not-allowed' },
  },
]

utils: {
  // 文本截断
  truncate: (lines: number) => ({
    overflow: 'hidden',
    textOverflow: 'ellipsis',
    display: '-webkit-box',
    WebkitLineClamp: lines,
    WebkitBoxOrient: 'vertical',
  }),
  // Flex 居中
  center: () => ({
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
  }),
}

// tokens/colors.ts
export const lightColors = { /* ... */ }
export const darkColors = { /* ... */ }
 
// themes/dark.ts
import { createTheme } from '../config'
export const darkTheme = createTheme({ colors: darkColors })
 
// components/Button.tsx
import { styled } from '../config'
// 组件只引用令牌名，不关心具体值

// ✅ 推荐：组件组合
const PrimaryButton = styled(Button, {
  color: 'primary',
  size: 'md',
})
 
// ⚠️ 可以但应避免过度使用：css prop 覆盖
<Button color="primary" size="md" css={{ marginTop: '$4' }} />

// Next.js: 在 _document.tsx 中注入 getCssText()
// Remix: 在 root.tsx 的 Links 中注入
// 其他 SSR 框架: 在 <head> 中注入 <style> 标签