Figma UI 稿 100% 还原

/* 使用 Figma 测量的精确值，而非目测 */
.element {
  /* 从 Figma 直接复制样式 */
  width: 320px;
  height: 240px;
  padding: 24px;
  margin: 16px;

  /* 字体属性完整复制，一个都不能少 */
  font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
  font-size: 16px;
  font-weight: 500;
  line-height: 1.5;
  letter-spacing: -0.02em;

  /* 颜色使用设计系统变量，而非硬编码 */
  color: var(--color-text-primary);
  background-color: var(--color-bg-secondary);

  /* 阴影参数精确匹配 */
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);

  /* 圆角 */
  border-radius: 8px;
}

:root {
  /* 颜色令牌 */
  --color-primary: #3b82f6;
  --color-primary-hover: #2563eb;
  --color-text-primary: #111827;
  --color-bg-secondary: #f9fafb;

  /* 间距令牌（8px 网格） */
  --space-xs: 4px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 24px;
  --space-xl: 32px;

  /* 圆角与阴影令牌 */
  --radius-md: 8px;
  --shadow-card: 0 4px 12px rgba(0, 0, 0, 0.08);
}

.card {
  padding: var(--space-lg);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-card);
  background: var(--color-bg-secondary);
}

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          500: '#3b82f6',
          600: '#2563eb',
        }
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
      spacing: {
        // 直接对齐 Figma 的 8px 网格
        '18': '4.5rem',
      },
      borderRadius: {
        card: '8px',
      },
      boxShadow: {
        'figma': '0 4px 12px rgba(0, 0, 0, 0.08)',
      }
    }
  }
}

<!-- 使用注入令牌后的原子类，无需手写魔法数字 -->
<div class="p-6 rounded-card shadow-figma bg-primary-50 font-sans">
  <h2 class="text-primary-600 text-xl font-medium">标题</h2>
</div>

# 使用 Chromatic（配合 Storybook）
npm install -D chromatic
npx chromatic --project-token=YOUR_TOKEN

# 使用 Percy
npm install -D @percy/cli @percy/playwright
npx percy snapshot

// 使用 Playwright 视觉回归：首次生成基准图，之后每次对比像素差异
import { test, expect } from '@playwright/test';

test('visual regression', async ({ page }) => {
  await page.goto('/component');
  // 超过阈值即测试失败，把 UI 走样拦在合并之前
  await expect(page).toHaveScreenshot('component.png', {
    maxDiffPixelRatio: 0.01, // 允许 1% 像素差异
  });
});

// 使用 delta-e 库量化颜色差异，取代"看着差不多"
import deltaE from 'delta-e';

const figmaColor = { L: 50, A: 20, B: 30 };
const implementedColor = { L: 50.5, A: 19.8, B: 30.2 };

const difference = deltaE.getDeltaE00(figmaColor, implementedColor);
console.log(`颜色差异：${difference}`); // 应 < 2 才算合格

// 使用 Playwright 断言元素尺寸严格等于 Figma 标注值
import { test, expect } from '@playwright/test';

test('verify element dimensions', async ({ page }) => {
  await page.goto('/component');
  const element = page.locator('.button');
  const box = await element.boundingBox();

  expect(box.width).toBe(120);  // Figma 中的宽度
  expect(box.height).toBe(40);  // Figma 中的高度
});

// 批量校验一组元素的间距是否符合 8px 网格
import { test, expect } from '@playwright/test';

test('spacing follows 8px grid', async ({ page }) => {
  await page.goto('/list');
  const gaps = await page.evaluate(() => {
    const items = [...document.querySelectorAll('.list-item')];
    return items.slice(1).map((el, i) => {
      const prev = items[i].getBoundingClientRect();
      const curr = el.getBoundingClientRect();
      return curr.top - prev.bottom;
    });
  });
  // 所有间距都应是 8 的整数倍
  gaps.forEach((gap) => expect(gap % 8).toBe(0));
});

/* 1. 使用与设计完全相同的字体文件 */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Regular.woff2') format('woff2');
  font-weight: 400;
  font-display: swap;
}

/* 2. 对齐字体平滑策略（macOS 下 Figma 默认灰度抗锯齿） */
body {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}

/* 3. 确保行高与字间距一致 */
.text {
  line-height: 1.5;       /* 与 Figma 中的 line-height 一致 */
  letter-spacing: -0.01em;/* Figma 常有细微字间距 */
}

/* 与 Figma 中的 Artboard 宽度严格对应 */
@media (min-width: 1920px) { /* Figma Desktop */ }
@media (min-width: 1440px) { /* Figma Laptop */ }
@media (min-width: 768px)  { /* Figma Tablet */ }
@media (min-width: 375px)  { /* Figma Mobile */ }

/* 对断点之间的过渡区，用 clamp 做流式缩放兜底 */
.title {
  font-size: clamp(1.5rem, 4vw, 2.5rem);
}

/* Figma 阴影参数转换 */
/* Figma: X=0, Y=4, Blur=12, Spread=0, Color=#000000, Opacity=8% */
.element {
  box-shadow: 0 4px 12px 0 rgba(0, 0, 0, 0.08);
}

/* 对于复杂阴影，Figma 里的多个阴影效果需逐层叠加，顺序与 Figma 一致 */
.elevated {
  box-shadow:
    0 1px 2px rgba(0, 0, 0, 0.04),
    0 4px 12px rgba(0, 0, 0, 0.08),
    0 8px 24px rgba(0, 0, 0, 0.12);
}

Variable: color/bg/base
├─ Mode: Light  →  #FFFFFF
├─ Mode: Dark   →  #0F172A
└─ Mode: Brand-A → #FEFEFE

/* 第一层：基础色板（Primitive），只是颜色，无语义 */
:root {
  --blue-500: #3b82f6;
  --blue-600: #2563eb;
  --gray-900: #111827;
  --gray-50: #f9fafb;
}

/* 第二层：语义令牌（Semantic），引用基础色板 */
:root {
  --color-primary: var(--blue-500);
  --color-primary-hover: var(--blue-600);
  --color-text: var(--gray-900);
  --color-bg: var(--gray-50);
}

/* Figma: Auto Layout, Horizontal, Gap=12, Padding=16, Align=Center */
.toolbar {
  display: flex;
  flex-direction: row;
  gap: 12px;
  padding: 16px;
  align-items: center;
}

/* Figma: 某子元素设为 "Fill container" */
.toolbar__search { flex: 1; }

/* Figma: 某子元素设为 "Hug contents" */
.toolbar__button { width: fit-content; flex-shrink: 0; }

/* Figma: Auto Layout, Vertical, Space between, 固定高度 */
.sidebar {
  display: flex;
  flex-direction: column;
  justify-content: space-between;
  height: 100vh;
  padding: 24px 16px;
}

# 1. Figma 导出 SVG 后，用 SVGO 优化（去冗余、压体积）
npx svgo icon.svg -o icon.min.svg

# 2. 批量优化整个图标目录
npx svgo -f ./icons -o ./icons-optimized

// svgo.config.js —— 保留 viewBox、去掉写死的宽高与颜色以便 CSS 控制
module.exports = {
  plugins: [
    { name: 'preset-default', params: { overrides: { removeViewBox: false } } },
    { name: 'removeDimensions' },              // 去掉 width/height，改用 CSS 控制
    { name: 'convertColors', params: { currentColor: true } }, // 填色改 currentColor
  ],
};

/* 优化后的图标可用 CSS 控制尺寸和颜色，一套图标随文字变色 */
.icon {
  width: 1.25em;
  height: 1.25em;
  fill: currentColor;   /* 跟随父级 color，无需为每种颜色导一份 */
}

<!-- 按设备像素比导出 @1x/@2x/@3x，用 srcset 让浏览器择优 -->
<img
  src="hero@1x.webp"
  srcset="hero@1x.webp 1x, hero@2x.webp 2x, hero@3x.webp 3x"
  alt="主视觉"
  width="640" height="360"
  loading="lazy"
  decoding="async"
/>

<!-- 艺术方向不同时用 picture 换图，而非仅缩放 -->
<picture>
  <source media="(min-width: 1024px)" srcset="banner-wide.webp">
  <source media="(min-width: 640px)" srcset="banner-mid.webp">
  <img src="banner-narrow.webp" alt="活动横幅">
</picture>

/* 1. 完整声明各字重，字重值必须与 Figma 一致 */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Regular.subset.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;        /* 先用系统字体兜底，加载完替换 */
  unicode-range: U+0000-00FF; /* 子集化：只加载用到的字符范围 */
}
@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-Medium.subset.woff2') format('woff2');
  font-weight: 500;
  font-display: swap;
}
@font-face {
  font-family: 'Inter';
  src: url('/fonts/Inter-SemiBold.subset.woff2') format('woff2');
  font-weight: 600;
  font-display: swap;
}

# 用 fonttools 做子集化，中文字体尤其必须做（否则动辄几 MB）
pip install fonttools brotli
pyftsubset SourceHanSans.otf \
  --text-file=used-chars.txt \
  --flavor=woff2 \
  --output-file=SourceHanSans.subset.woff2

<!-- 关键字体预加载，减少 FOUT/布局抖动 -->
<link rel="preload" href="/fonts/Inter-Regular.subset.woff2"
      as="font" type="font/woff2" crossorigin>

/* 线性渐变：Figma 角度以"从上到下为 0°顺时针"，CSS 以"从下到上为 0deg"，需换算 */
/* Figma 90°（从左到右） = CSS to right */
.gradient-linear {
  background: linear-gradient(90deg, #3b82f6 0%, #8b5cf6 100%);
}

/* 径向渐变：Figma 的椭圆渐变对应 radial-gradient */
.gradient-radial {
  background: radial-gradient(circle at 30% 30%, #fbbf24 0%, #f59e0b 100%);
}

/* 圆锥渐变（Figma Angular） */
.gradient-conic {
  background: conic-gradient(from 0deg, #f00, #0f0, #00f, #f00);
}

/* 背景模糊（Figma Background Blur → backdrop-filter） */
.glass {
  background: rgba(255, 255, 255, 0.6);
  backdrop-filter: blur(20px) saturate(180%);
  -webkit-backdrop-filter: blur(20px) saturate(180%);
}

/* 图层模糊（Figma Layer Blur → filter） */
.blurred { filter: blur(8px); }

/* 混合模式（Figma Blend Mode → mix-blend-mode / background-blend-mode） */
.overlay-text { mix-blend-mode: difference; color: #fff; }
.duotone {
  background-color: #3b82f6;
  background-image: url('photo.jpg');
  background-blend-mode: multiply;
}

/* Figma: Constraint = Left & Right（横向拉伸填满） */
.stretch-x {
  position: absolute;
  left: 16px;
  right: 16px;
  /* 宽度由 left/right 决定，随父容器变化 */
}

/* Figma: Constraint = Center（始终居中） */
.centered {
  position: absolute;
  left: 50%;
  top: 50%;
  translate: -50% -50%;
}

/* Figma: Constraint = Scale（等比缩放，用百分比） */
.scaled { width: 40%; }

/* 一个输入框的完整状态实现 */
.input {
  padding: 10px 12px;
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  transition: border-color 0.15s, box-shadow 0.15s;
}
.input:hover { border-color: var(--color-border-strong); }
.input:focus-visible {
  outline: none;
  border-color: var(--color-primary);
  box-shadow: 0 0 0 3px var(--color-primary-alpha);
}
.input:disabled {
  background: var(--color-bg-disabled);
  cursor: not-allowed;
  opacity: 0.6;
}
.input[readonly] { background: var(--color-bg-muted); }
.input[aria-invalid="true"] {
  border-color: var(--color-danger);
  box-shadow: 0 0 0 3px var(--color-danger-alpha);
}
.input[data-state="success"] { border-color: var(--color-success); }

/* 按钮加载态：内嵌 spinner，尺寸不跳变 */
.button[data-loading="true"] {
  color: transparent;      /* 隐藏文字但保留宽度 */
  pointer-events: none;
  position: relative;
}
.button[data-loading="true"]::after {
  content: '';
  position: absolute;
  inset: 0;
  margin: auto;
  width: 16px;
  height: 16px;
  border: 2px solid currentColor;
  border-top-color: transparent;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}
@keyframes spin { to { transform: rotate(360deg); } }

/* 列表空态：居中提示 + 插画占位 */
.list:empty::before {
  content: '暂无数据';
  display: block;
  padding: 48px;
  text-align: center;
  color: var(--color-text-muted);
}

# 1. 用 Token Studio 插件把 Figma Variables 导出为 tokens.json
# 2. 用 Style Dictionary 编译成多端产物
npm install -D style-dictionary

// style-dictionary.config.js —— 一份令牌编译到 CSS/SCSS/JS
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'dist/css/',
      files: [{ destination: 'tokens.css', format: 'css/variables' }],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [{ destination: 'tokens.js', format: 'javascript/es6' }],
    },
    tailwind: {
      transformGroup: 'js',
      buildPath: 'dist/',
      files: [{ destination: 'tailwind-tokens.js', format: 'javascript/module' }],
    },
  },
};

// tokens/color.json —— Token Studio 导出的令牌源
{
  "color": {
    "primary": { "value": "#3b82f6", "type": "color" },
    "danger":  { "value": "#dc2626", "type": "color" }
  },
  "space": {
    "md": { "value": "16px", "type": "spacing" }
  }
}

/* Style Dictionary 自动产出（勿手改） */
:root {
  --color-primary: #3b82f6;
  --color-danger: #dc2626;
  --space-md: 16px;
}

// Input.stories.js —— 把每个状态录成一个 story
export default { title: 'Form/Input', component: Input };
export const Default = { args: {} };
export const Focus = { args: {}, parameters: { pseudo: { focusVisible: true } } };
export const Error = { args: { error: '邮箱格式不正确' } };
export const Disabled = { args: { disabled: true } };
export const Loading = { args: { loading: true } };

// playwright.config.js —— 配置像素对比阈值与多视口
export default {
  use: { viewport: { width: 1280, height: 720 } },
  expect: {
    toHaveScreenshot: {
      maxDiffPixelRatio: 0.01,   // 允许 1% 差异
      threshold: 0.2,            // 单像素颜色容差
      animations: 'disabled',    // 关动画避免抖动
    },
  },
  projects: [
    { name: 'desktop', use: { viewport: { width: 1440, height: 900 } } },
    { name: 'mobile', use: { viewport: { width: 375, height: 812 } } },
  ],
};

// 多状态、多视口一次性回归
import { test, expect } from '@playwright/test';

const states = ['default', 'hover', 'focus', 'error', 'disabled'];
for (const state of states) {
  test(`input - ${state}`, async ({ page }) => {
    await page.goto(`/iframe.html?id=form-input--${state}`);
    await expect(page.locator('.input')).toHaveScreenshot(`input-${state}.png`);
  });
}

/* 1. 颜色对比度：正文文字对背景需 ≥ 4.5:1，大字 ≥ 3:1 */
/* 用 Figma 的 Contrast 插件核对，不达标要与设计协商 */

/* 2. 焦点可见：绝不能为了"好看"删掉 outline */
.button:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

/* 3. 尊重减少动效偏好 */
@media (prefers-reduced-motion: reduce) {
  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
}

/* 4. 可点击区域 ≥ 44×44px（移动端） */
.icon-button {
  min-width: 44px;
  min-height: 44px;
}

/* 用流式单位填补断点之间的真空 */
.hero__title {
  /* 从 28px 平滑增长到 56px，中间尺寸不再突变 */
  font-size: clamp(1.75rem, 1rem + 4vw, 3.5rem);
  line-height: 1.15;
  text-wrap: balance;   /* 标题自动平衡换行 */
}
.hero {
  padding-inline: clamp(1rem, 5vw, 6rem);
}
.feature-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 280px), 1fr));
  gap: clamp(1rem, 2vw, 2rem);
}

.pill { border-radius: 9999px; }   /* 高度变化时始终保持胶囊形 */

.button {
  display: inline-flex;
  align-items: center;   /* 用 flex 居中，摆脱 line-height 干扰 */
  justify-content: center;
  height: 40px;
  padding-inline: 16px;
}

/* 把缓动曲线也令牌化，全站动效统一质感 */
:root {
  --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);   /* 标准（进出） */
  --ease-decelerate: cubic-bezier(0, 0, 0.2, 1);    /* 入场（减速） */
  --ease-accelerate: cubic-bezier(0.4, 0, 1, 1);    /* 出场（加速） */
  --duration-fast: 150ms;
  --duration-base: 250ms;
  --duration-slow: 400ms;
}

/* 卡片悬浮：用令牌化的曲线和时长 */
.card {
  transition: transform var(--duration-base) var(--ease-standard),
              box-shadow var(--duration-base) var(--ease-standard);
}
.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.12);
}

/* 弹窗入场：减速曲线，从下方滑入 */
@keyframes modal-in {
  from { opacity: 0; transform: translateY(20px) scale(0.98); }
  to   { opacity: 1; transform: translateY(0) scale(1); }
}
.modal {
  animation: modal-in var(--duration-slow) var(--ease-decelerate) both;
}

/* 1. 刘海屏安全区：内容避开挖孔与圆角 */
.app-bar {
  padding-top: env(safe-area-inset-top);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}
.bottom-nav {
  padding-bottom: env(safe-area-inset-bottom);
}

/* 2. 移动端视口高度：用 dvh 避免地址栏收放导致的抖动 */
.fullscreen {
  height: 100dvh;   /* 动态视口高度，优于 100vh */
}

/* 3. 去掉移动端点击高亮，改用自定义反馈 */
.tappable {
  -webkit-tap-highlight-color: transparent;
  touch-action: manipulation;   /* 去掉 300ms 点击延迟 */
}
.tappable:active { opacity: 0.7; }

/* 4. 禁止 iOS 输入框缩放：字号 ≥16px */
input, textarea { font-size: 16px; }

<!-- viewport 配置：viewport-fit=cover 才能用 safe-area -->
<meta name="viewport"
      content="width=device-width, initial-scale=1, viewport-fit=cover">

/* 自制差值叠加：把设计稿固定叠在页面上做 diff */
.pixel-overlay {
  position: fixed;
  inset: 0;
  z-index: 99999;
  pointer-events: none;
  background: url('/design-export@2x.png') top left / contain no-repeat;
  mix-blend-mode: difference;   /* 差值模式：一致处全黑，偏差处发亮 */
  opacity: 1;
}

/* 1. 给动画元素提示合成层，但别滥用（过多 will-change 反而耗内存） */
.animated { will-change: transform; }

/* 2. 优先用 transform/opacity 做动画（走合成线程，不触发重排重绘） */
.slide { transition: transform 0.3s; }   /* 好 */
/* .slide { transition: left 0.3s; }      坏：触发重排 */

/* 3. backdrop-filter 很耗性能，大面积慎用，可加降级 */
@supports not (backdrop-filter: blur(1px)) {
  .glass { background: rgba(255, 255, 255, 0.95); }
}

/* 4. content-visibility 让屏外内容跳过渲染，长页面提速明显 */
.long-section {
  content-visibility: auto;
  contain-intrinsic-size: auto 500px;   /* 预留高度避免滚动条跳 */
}

# 建立 Figma → 代码的令牌 CI：设计改令牌，自动开 PR 更新代码
# .github/workflows/sync-tokens.yml 触发 Token Studio 导出 + Style Dictionary 编译

// 每个代码组件用 story 与 Figma 组件建立映射，视觉回归双向校验
export default {
  title: 'Components/Dropdown',
  parameters: {
    design: {
      type: 'figma',
      url: 'https://figma.com/file/xxx?node-id=123',  // 直连 Figma 源
    },
  },
};

/* 1. 令牌层（来自 Figma Variables，自动同步） */
:root {
  --notice-radius: 8px;
  --notice-padding: 16px;
  --notice-gap: 12px;
  --color-info-bg: #eff6ff;
  --color-info-border: #3b82f6;
  --color-info-text: #1e40af;
}

/* 2. 组件层（只消费令牌，无魔法数字） */
.notice {
  display: flex;
  gap: var(--notice-gap);
  padding: var(--notice-padding);
  border-radius: var(--notice-radius);
  border-inline-start: 4px solid var(--color-info-border);
  background: var(--color-info-bg);
  color: var(--color-info-text);
}
.notice__icon { flex-shrink: 0; width: 20px; height: 20px; fill: currentColor; }
.notice__body { flex: 1; }
.notice__close {
  flex-shrink: 0;
  min-width: 44px; min-height: 44px;   /* 无障碍点击区 */
  background: none; border: none; cursor: pointer;
}
.notice__close:focus-visible { outline: 2px solid var(--color-info-border); }

/* 3. 变体（对应 Figma 的组件 Variants） */
.notice[data-variant="success"] {
  --color-info-bg: #f0fdf4;
  --color-info-border: #22c55e;
  --color-info-text: #15803d;
}
.notice[data-variant="danger"] {
  --color-info-bg: #fef2f2;
  --color-info-border: #ef4444;
  --color-info-text: #b91c1c;
}

/* 4. 入场动效（缓动令牌化） */
@keyframes notice-in {
  from { opacity: 0; transform: translateY(-8px); }
  to   { opacity: 1; transform: translateY(0); }
}
.notice { animation: notice-in 250ms cubic-bezier(0, 0, 0.2, 1) both; }

@media (prefers-reduced-motion: reduce) {
  .notice { animation: none; }
}