{
  "id": "pixel-density",
  "type": "foundation",
  "status": "published",
  "name": {
    "zh": "像素密度与分辨率",
    "en": "Pixel Density & Resolution"
  },
  "aliases": [
    "像素密度",
    "设备像素比",
    "为什么图在手机上发虚",
    "手机上看图模糊",
    "高清屏",
    "Retina",
    "DPR",
    "pixel density",
    "device pixel ratio"
  ],
  "category": [
    "Foundation",
    "Rendering",
    "Responsive"
  ],
  "description": {
    "zh": "屏幕同时用两套像素计数：真实的设备像素与布局用的 CSS 像素，一个 CSS 像素里塞进几个设备像素就是设备像素比 DPR。手机像素密、CSS 像素少，位图被撑到 CSS 尺寸就发虚。位图按 2x/3x 提供并配 srcset 与矢量即可锐利；文字清晰度取决于字形渲染，与单位无关，rem 只用于相对根字号缩放。",
    "en": "A screen counts pixels two ways: physical device pixels and the CSS pixels used for layout. The device pixel ratio, or DPR, is how many device pixels fill one CSS pixel. Phones pack many device pixels into few CSS pixels, so a bitmap shown at its CSS size looks blurry. Serve 2x/3x assets with srcset and vectors to stay sharp; text sharpness comes from glyph rendering, not units — rem only scales relative to the root font size."
  },
  "use_when": [
    {
      "zh": "位图、图标与截图需要在手机等高密度屏上保持锐利",
      "en": "Bitmaps, icons and screenshots must stay sharp on dense phone screens"
    },
    {
      "zh": "设计稿以 px 标注，开发需要换算到不同 DPR",
      "en": "The design spec is annotated in px and must map onto different DPRs"
    },
    {
      "zh": "排查“为什么图在 Retina 上发虚”或配置响应式图片",
      "en": "Debugging why an image looks soft on Retina, or setting up responsive images"
    }
  ],
  "avoid_when": [
    {
      "zh": "纯文字页面没有位图与图标，密度差异基本无感",
      "en": "A text-only page with no bitmaps or icons, where density barely shows"
    },
    {
      "zh": "只面向固定 1x 的投屏或信息屏，不涉及高密度设备",
      "en": "A fixed 1x signage or projector target with no dense displays"
    },
    {
      "zh": "把所有尺寸都乘 DPR 写死，丢掉 CSS 像素这层抽象",
      "en": "Multiplying every size by DPR and hard-coding it, losing the CSS-pixel abstraction"
    }
  ],
  "tags": [
    "foundation",
    "rendering",
    "responsive-images",
    "device-pixel-ratio",
    "typography"
  ],
  "api": [
    "dppx",
    "devicePixelRatio",
    "srcset",
    "image-set()"
  ],
  "framework_names": [
    {
      "framework": "CSS",
      "name": "resolution media query / dppx",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/resolution",
      "note": {
        "zh": "按屏幕密度切换资源或样式",
        "en": "Switch assets or styles by screen density"
      }
    },
    {
      "framework": "HTML",
      "name": "srcset / sizes",
      "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img",
      "note": {
        "zh": "让浏览器按 DPR 选图",
        "en": "Lets the browser pick the right crop per DPR"
      }
    },
    {
      "framework": "React",
      "name": "window.devicePixelRatio",
      "url": "https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio"
    }
  ],
  "variants": [
    {
      "id": "standard",
      "name": {
        "zh": "标清 1x",
        "en": "Standard 1x"
      },
      "note": {
        "zh": "一个 CSS 像素等于一个设备像素，资源原样显示",
        "en": "One CSS pixel equals one device pixel — assets show as-is"
      }
    },
    {
      "id": "retina",
      "name": {
        "zh": "Retina 2x",
        "en": "Retina 2x"
      },
      "note": {
        "zh": "一个 CSS 像素摊到四个设备像素，位图要出 2x 才不虚",
        "en": "One CSS pixel covers four device pixels — ship 2x bitmaps"
      }
    },
    {
      "id": "dense",
      "name": {
        "zh": "高密度 3x 与矢量",
        "en": "Dense 3x + vectors"
      },
      "note": {
        "zh": "手机常见 2x～3x，位图按此出图；图标与 Logo 用矢量，文字交给系统字体渲染",
        "en": "Phones commonly reach 2x–3x; export bitmaps accordingly, use vectors for icons/logos and let the system render text"
      }
    }
  ],
  "anatomy": [
    "设备像素（Device pixel）",
    "CSS 像素（CSS pixel）",
    "设备像素比（DPR）",
    "位图密度（Image density）",
    "矢量与字体（Vectors & fonts）"
  ],
  "related": [
    {
      "id": "relative-units",
      "relation": "similar_to"
    },
    {
      "id": "type-scale",
      "relation": "used_with"
    },
    {
      "id": "alt-text",
      "relation": "used_with"
    },
    {
      "id": "pixel-art",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "pixel-density",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "MDN — window.devicePixelRatio",
      "url": "https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio"
    },
    {
      "name": "MDN — CSS resolution (dppx)",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/resolution"
    },
    {
      "name": "Apple HIG — Images",
      "url": "https://developer.apple.com/design/human-interface-guidelines/images"
    }
  ],
  "implementation": {
    "css": [
      "image-set(url(logo.png) 1x, url(logo@2x.png) 2x)",
      "@media (min-resolution: 2dppx)",
      "srcset=\"hero@2x.png 2x\"",
      "width: 24px; height: 24px",
      "font-size: 1rem"
    ],
    "notes": {
      "zh": "位图按目标 DPR 出 2x/3x 资源，用 image-set() 或 srcset/sizes 让浏览器自己挑，不要只把 1x 放大。CSS 尺寸一律按 CSS 像素写，映射到设备像素交给浏览器；图标与 Logo 优先 SVG，字号与间距可用 rem 做相对缩放（这是缩放策略，与清晰度无关），发丝线保持 1px。devicePixelRatio 只用于需要精确像素计算的 canvas 或图片预览，不要拿它缩放整个界面。",
      "en": "Export bitmaps at 2x/3x for the target DPR and let image-set() or srcset/sizes choose; never upscale a 1x asset. Always write CSS sizes in CSS pixels and leave the mapping to device pixels to the browser. Prefer SVG for icons and logos; rem may scale font size and spacing relative to the root (a scaling choice, not a sharpness fix), and hairlines stay at 1px. Use devicePixelRatio only for canvas or image previews that need exact pixel math, never to scale the whole UI."
    }
  },
  "prompts": {
    "basic": {
      "zh": "让位图与图标在手机等高密度屏上保持清晰：按 DPR 提供多倍图，并说清 CSS 像素与设备像素的区别。",
      "en": "Keep bitmaps and icons crisp on dense phone screens — serve multiple densities and explain CSS pixels versus device pixels."
    },
    "design": {
      "zh": "像素密度规范：布局与标注统一用 CSS 像素，交付 1x/2x/3x 位图；图标与 Logo 用 SVG；字号与间距可用 rem 相对缩放，发丝线固定 1px；切图命名带 @2x/@3x；说明目标设备的 DPR 区间，不要用设备像素直接标注设计稿。",
      "en": "Pixel density spec: lay out and annotate in CSS pixels, deliver 1x/2x/3x bitmaps, use SVG for icons and logos, scale text and spacing with rem, and keep hairlines at 1px. Name exports with @2x/@3x, state the target DPR range, and never annotate the design in device pixels."
    },
    "implementation": {
      "zh": "用 image-set() 或 srcset/sizes 提供多倍图，例如 img { width: 24px; height: 24px; content: image-set(url(icon.png) 1x, url(icon@2x.png) 2x); }。高密度下再用 @media (min-resolution: 2dppx) 覆盖细节。字号与间距可用 rem 相对缩放，canvas 里乘 window.devicePixelRatio 设置 backing store，并按 CSS 尺寸缩放上下文。",
      "en": "Serve multiple densities with image-set() or srcset/sizes, e.g. img { width: 24px; height: 24px; content: image-set(url(icon.png) 1x, url(icon@2x.png) 2x); } and refine details under @media (min-resolution: 2dppx). Scale text and spacing with rem; in canvas multiply window.devicePixelRatio for the backing store and scale the context back to CSS size."
    },
    "agent": {
      "zh": "在当前项目中实现像素密度适配。\n先检查现有组件体系和 Design Token，优先复用当前组件。\n要求：\n- 布局与尺寸全部按 CSS 像素书写，不乘 DPR\n- 位图提供 1x/2x/3x 并用 image-set() 或 srcset/sizes 选择\n- 图标与 Logo 用 SVG；字号与间距可用 rem（相对缩放，与清晰度无关），发丝线保持 1px\n保持现有项目视觉风格。不要新增不必要依赖。\n尊重 prefers-reduced-motion。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement pixel density handling in the current project.\nInspect the existing component system and design tokens first; reuse what is already there.\nRequirements:\n- Write all layout and sizes in CSS pixels; never multiply by DPR\n- Provide 1x/2x/3x bitmaps and choose with image-set() or srcset/sizes\n- Use SVG for icons and logos; rem may scale text and spacing (a scaling choice, not sharpness); keep hairlines at 1px\nKeep the project's existing visual style. Do not add unnecessary dependencies.\nRespect prefers-reduced-motion.\nRun existing project checks when done and list the modified files."
    }
  }
}