{
  "id": "breakpoints",
  "type": "foundation",
  "status": "published",
  "name": {
    "zh": "响应式断点",
    "en": "Breakpoints"
  },
  "aliases": [
    "响应式断点",
    "媒体查询断点",
    "断点",
    "手机和电脑的分界",
    "什么时候换布局",
    "大屏小屏切换点",
    "breakpoint",
    "media query breakpoint"
  ],
  "category": [
    "Responsive",
    "Layout",
    "Foundation"
  ],
  "description": {
    "zh": "断点是布局发生切换的视口宽度临界值：窄于此用一套排版，宽于此换另一套。断点应由内容决定——把窗口慢慢拉宽，哪里开始拥挤、哪里变难看，那里就是断点，而不是照搬 iPhone、iPad 的型号宽度。移动优先用 min-width 从小到大叠加，断点越少越容易维护。",
    "en": "Breakpoints are viewport widths where a layout changes. Pick them where content crowds, not device names, then stack mobile-first min-width rules."
  },
  "use_when": [
    {
      "zh": "同一页面在手机和桌面需要不同列数或导航形态",
      "en": "One page needs different column counts or navigation on phone and desktop"
    },
    {
      "zh": "需要在某个宽度切换侧栏、字号或间距密度",
      "en": "A width threshold should switch the sidebar, type scale or density"
    },
    {
      "zh": "从移动端基线出发、逐级增强的响应式布局",
      "en": "Building mobile-first and enhancing upward step by step"
    }
  ],
  "avoid_when": [
    {
      "zh": "只有一种固定宽度、无需适配的嵌入式控件",
      "en": "A fixed-width embedded widget that never adapts"
    },
    {
      "zh": "用设备型号（iPhone 15、iPad Pro）当断点名",
      "en": "Naming breakpoints after device models such as iPhone 15 or iPad Pro"
    },
    {
      "zh": "断点堆到十来个，样式互相打架、难以维护",
      "en": "A dozen breakpoints fighting each other and hard to maintain"
    }
  ],
  "tags": [
    "responsive",
    "foundation",
    "layout",
    "media-query"
  ],
  "api": [
    "@media",
    "min-width",
    "container-type",
    "clamp()"
  ],
  "framework_names": [
    {
      "framework": "CSS",
      "name": "@media (min-width: 48rem)",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries",
      "note": {
        "zh": "移动优先的最小宽度媒体查询",
        "en": "Mobile-first minimum-width media query"
      }
    },
    {
      "framework": "Tailwind CSS",
      "name": "sm: / md: / lg:",
      "url": "https://tailwindcss.com/docs/responsive-design",
      "note": {
        "zh": "前缀即 min-width 断点",
        "en": "Prefixes are min-width breakpoints"
      }
    },
    {
      "framework": "CSS Container Queries",
      "name": "@container (min-width: 30rem)",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries",
      "note": {
        "zh": "按组件容器宽度而非视口切换",
        "en": "Switch on component width, not the viewport"
      }
    }
  ],
  "variants": [
    {
      "id": "mobile-first",
      "name": {
        "zh": "移动优先",
        "en": "Mobile-first"
      },
      "note": {
        "zh": "先写窄屏基线，再用 min-width 逐级叠加",
        "en": "Write the narrow baseline first, then stack min-width rules"
      }
    },
    {
      "id": "content-driven",
      "name": {
        "zh": "内容驱动",
        "en": "Content-driven"
      },
      "note": {
        "zh": "把窗口拉宽，哪里挤了哪里就是断点",
        "en": "Widen the window; wherever it crowds is the breakpoint"
      }
    },
    {
      "id": "token-breakpoints",
      "name": {
        "zh": "断点令牌",
        "en": "Breakpoint tokens"
      },
      "note": {
        "zh": "断点值集中成变量或配置，避免散落魔法数",
        "en": "Centralise breakpoint values as tokens, not scattered magic numbers"
      }
    }
  ],
  "anatomy": [
    "断点值（Breakpoint value）",
    "媒体查询（min-width media query）",
    "布局切换（Layout switch）",
    "移动优先基线（Mobile-first base）"
  ],
  "related": [
    {
      "id": "type-scale",
      "relation": "similar_to"
    },
    {
      "id": "touch-target",
      "relation": "similar_to"
    },
    {
      "id": "navbar",
      "relation": "used_with"
    },
    {
      "id": "sidebar",
      "relation": "used_with"
    }
  ],
  "demo": {
    "component": "breakpoints",
    "modes": [
      "default",
      "dark",
      "variants"
    ]
  },
  "sources": [
    {
      "name": "MDN — Using media queries",
      "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_media_queries/Using_media_queries"
    },
    {
      "name": "web.dev — Learn Responsive Design",
      "url": "https://web.dev/learn/design/"
    },
    {
      "name": "W3C — Media Queries Level 5",
      "url": "https://www.w3.org/TR/mediaqueries-5/"
    }
  ],
  "implementation": {
    "css": [
      "@media (min-width: 48rem)",
      "min-width: 0",
      "grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr))",
      "container-type: inline-size",
      "padding-inline: clamp(1rem, 4vw, 2.5rem)"
    ],
    "notes": {
      "zh": "先写窄屏样式作为基线，再用 @media (min-width: ...) 逐级覆盖，避免 desktop-first 的 max-width 降级写法。断点值用 em/rem（48rem＝768px）而不是 px，用户放大字号时仍按内容切换；断点集中定义成 CSS 变量或 Tailwind screens，组件内不散写魔法数。能靠 flex-wrap、grid auto-fit、clamp() 自适应的地方就别加断点。",
      "en": "Write narrow styles as the base, then override upward with @media (min-width: ...) instead of desktop-first max-width. Express breakpoints in em/rem (48rem = 768px) so they follow zoom; define them once as CSS variables or Tailwind screens and never scatter magic numbers inside components. Where flex-wrap, grid auto-fit or clamp() can adapt, skip the breakpoint entirely."
    }
  },
  "prompts": {
    "basic": {
      "zh": "建立一套响应式断点：按内容需要定义切换宽度，让布局从小屏到大屏平滑变化。",
      "en": "Establish a set of responsive breakpoints — define switch widths from content needs so the layout adapts from small to large screens."
    },
    "design": {
      "zh": "断点规范：移动优先，只用 min-width；断点值用 rem（48rem＝768px、64rem＝1024px）并集中定义；每档写清布局怎么变（列数、导航、间距）；断点数量控制在 3～5 个；优先用 flex-wrap、grid auto-fit、clamp() 做自适应，只有真正需要换结构时才新增断点。",
      "en": "Breakpoint spec: mobile-first, min-width only; values in rem (48rem = 768px, 64rem = 1024px) defined in one place; document what changes at each step (columns, navigation, spacing); keep to three to five breakpoints; prefer flex-wrap, grid auto-fit and clamp() for adaptation, adding a breakpoint only when the structure truly changes."
    },
    "implementation": {
      "zh": "用 min-width 媒体查询从窄到宽覆盖：.grid { display: grid; grid-template-columns: 1fr; } @media (min-width: 48rem) { .grid { grid-template-columns: repeat(2, 1fr); } }。断点值写成 CSS 变量或 Tailwind screens；组件级切换用 container-type: inline-size 配合 @container。避免 max-width 降级写法，也不要逐元素写死断点。",
      "en": "Layer min-width queries from narrow to wide: .grid { display: grid; grid-template-columns: 1fr; } @media (min-width: 48rem) { .grid { grid-template-columns: repeat(2, 1fr); } }. Keep breakpoint values in CSS variables or Tailwind screens; for component-scoped switching add container-type: inline-size and use @container. Avoid desktop-first max-width rewrites and per-element hard-coded thresholds."
    },
    "agent": {
      "zh": "在当前项目中实现响应式断点。\n先检查现有组件体系和 Design Token，优先复用当前组件。\n要求：\n- 移动优先，只用 min-width 媒体查询\n- 断点值集中定义（CSS 变量或 Tailwind screens），组件内不写魔法数\n- 断点数量控制在 3～5 个，优先用自适应布局替代断点\n保持现有项目视觉风格。不要新增不必要依赖。\n尊重 prefers-reduced-motion。\n完成后运行项目现有检查，并列出修改的文件。",
      "en": "Implement responsive breakpoints in the current project.\nInspect the existing component system and design tokens first; reuse what is already there.\nRequirements:\n- Mobile-first, min-width media queries only\n- Breakpoint values defined in one place (CSS variables or Tailwind screens); no magic numbers in components\n- Three to five breakpoints at most; prefer adaptive layout over new breakpoints\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."
    }
  }
}