mcpField
T
tailwindcss-responsive-darkmode

tailwindcss-responsive-darkmode

github.com/josiahsiegel设计与 UI59476 次安装19 周前更新
代码仓库

关于 tailwindcss-responsive-darkmode

面向 Tailwind CSS 开发者的响应式设计与深色模式参考技能，涵盖移动优先断点、容器查询及多种主题切换策略。

主要功能

  1. 01移动优先断点与布局
  2. 02自定义及容器查询断点
  3. 03系统、选择器和属性主题策略
  4. 04深色模式颜色与变量
  5. 05无障碍和响应式最佳实践

适用场景

  1. 01为不同视口规划页面布局
  2. 02让可复用组件适配容器尺寸
  3. 03实现手动或系统深色主题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/josiahsiegel/claude-plugin-marketplace --skill tailwindcss-responsive-darkmode

安装后在 Claude Code 中输入/tailwindcss-responsive-darkmode确认已加载。

附带文件references/advanced-responsive-patterns.md

详细介绍

Tailwind CSS 响应式设计与深色模式（2025/2026）

响应式设计

移动优先方法（2025/2026 年的行业标准）

Tailwind 使用移动优先的断点系统。全球网络流量中，超过 60% 来自移动设备，加上 Google 的移动优先索引，因此这种方法至关重要。

关键原则：未添加前缀的工具类适用于所有屏幕尺寸。断点前缀从对应尺寸及以上开始生效。


<div class="text-sm md:text-base lg:text-lg">...</div>


<div class="lg:text-lg md:text-base text-sm">...</div>
默认断点
前缀最小宽度典型设备CSS 媒体查询
（无）0px所有手机所有尺寸
sm:640px (40rem)大屏手机、小型平板电脑@media (min-width: 640px)
md:768px (48rem)平板电脑（纵向）@media (min-width: 768px)
lg:1024px (64rem)平板电脑（横向）、笔记本电脑@media (min-width: 1024px)
xl:1280px (80rem)台式电脑@media (min-width: 1280px)
2xl:1536px (96rem)大型台式电脑@media (min-width: 1536px)
2025/2026 年设备覆盖范围

建议测试的常见设备尺寸：

  • 320px：较旧的 iPhone，支持的最小尺寸
  • 375px：现代基础款 iPhone（约占移动设备的 17%）
  • 390-430px：现代大屏手机（约占移动设备的 35%）
  • 768px：iPad 纵向
  • 1024px：iPad 横向、笔记本电脑
  • 1280px：标准笔记本电脑/台式电脑
  • 1440px：大型台式电脑
  • 1920px：全高清显示屏
自定义断点
@theme {
  /* Add custom breakpoints for specific content needs */
  --breakpoint-xs: 20rem;   /* 320px - very small devices */
  --breakpoint-3xl: 100rem; /* 1600px */
  --breakpoint-4xl: 120rem; /* 1920px - full HD */

  /* Override existing breakpoints based on YOUR content */
  --breakpoint-sm: 36rem;   /* 576px - when content needs space */
  --breakpoint-lg: 62rem;   /* 992px - common content width */
}

用法：

<div class="grid xs:grid-cols-2 3xl:grid-cols-6">
  
</div>
内容驱动的断点（2025 年最佳实践）

不要针对设备设置断点，而是让内容决定断点：

@theme {
  /* Based on content needs, not device specs */
  --breakpoint-prose: 65ch;  /* Optimal reading width */
  --breakpoint-content: 75rem; /* Main content max */
}

在不同宽度下测试设计，并在布局出现问题时添加断点。

响应式示例
响应式网格
<div class="grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4 gap-4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
  <div>Item 4</div>
</div>
响应式排版
<h1 class="text-2xl sm:text-3xl md:text-4xl lg:text-5xl font-bold">
  Responsive Heading
</h1>

<p class="text-sm md:text-base lg:text-lg leading-relaxed">
  Responsive paragraph text
</p>
响应式间距
<section class="py-8 md:py-12 lg:py-16 px-4 md:px-8 lg:px-12">
  <div class="max-w-4xl mx-auto">
    Content with responsive padding
  </div>
</section>
响应式导航
<nav class="flex flex-col md:flex-row items-center justify-between">
  <div class="hidden md:flex gap-4">
    
  </div>
  <button class="md:hidden">
    
  </button>
</nav>
根据屏幕尺寸显示/隐藏

<div class="hidden md:block">Desktop only</div>


<div class="block md:hidden">Mobile only</div>


<span class="sm:hidden">XS</span>
<span class="hidden sm:inline md:hidden">SM</span>
<span class="hidden md:inline lg:hidden">MD</span>
<span class="hidden lg:inline xl:hidden">LG</span>
<span class="hidden xl:inline 2xl:hidden">XL</span>
<span class="hidden 2xl:inline">2XL</span>
容器查询（v4）——2025 年的重大突破

容器查询支持组件级响应式布局，不受视口尺寸影响。这对于 2025 年的可复用组件至关重要。

@plugin "@tailwindcss/container-queries";


<div class="@container">
  <div class="flex flex-col @md:flex-row @lg:gap-8">
    
  </div>
</div>


<div class="@container/card">
  <div class="@lg/card:grid-cols-2 grid grid-cols-1">
    
  </div>
</div>
容器查询断点
类最小宽度用途
@xs20rem (320px)小型小组件
@sm24rem (384px)紧凑型卡片
@md28rem (448px)标准卡片
@lg32rem (512px)宽卡片
@xl36rem (576px)全宽组件
@2xl42rem (672px)大型容器
@3xl48rem (768px)页面区块
何时使用容器查询与视口查询
容器查询视口查询
可复用组件页面级布局
不同上下文中的卡片导航栏
侧边栏小组件主视觉区块
CMS/嵌入式内容全宽区块
最大宽度断点

针对小于特定尺寸的屏幕：


<div class="md:hidden">Small screens only</div>


<div class="[@media(max-width:600px)]:text-sm">
  Custom max-width
</div>

深色模式

策略：媒体查询（默认）

深色模式通过 prefers-color-scheme 遵循用户的操作系统偏好：

@import "tailwindcss";
/* No additional configuration needed */

<div class="bg-white dark:bg-gray-900">
  <h1 class="text-gray-900 dark:text-white">Title</h1>
  <p class="text-gray-600 dark:text-gray-300">Content</p>
</div>
策略：选择器（手动切换）

通过 CSS 类控制深色模式：

@import "tailwindcss";

@custom-variant dark (&:where(.dark, .dark *));


<html class="dark">
  <body>
    <div class="bg-white dark:bg-gray-900">
      Content
    </div>
  </body>
</html>
JavaScript 切换
// Simple toggle
function toggleDarkMode() {
  document.documentElement.classList.toggle('dark');
}

// With localStorage persistence
function initDarkMode() {
  const isDark = localStorage.getItem('darkMode') === 'true' ||
    (!localStorage.getItem('darkMode') &&
     window.matchMedia('(prefers-color-scheme: dark)').matches);

  document.documentElement.classList.toggle('dark', isDark);
}

function toggleDarkMode() {
  const isDark = document.documentElement.classList.toggle('dark');
  localStorage.setItem('darkMode', isDark);
}

// Initialize on page load
initDarkMode();
三向切换（浅色/深色/系统）
const themes = ['light', 'dark', 'system'];

function setTheme(theme) {
  localStorage.setItem('theme', theme);
  applyTheme();
}

function applyTheme() {
  const theme = localStorage.getItem('theme') || 'system';
  const isDark = theme === 'dark' ||
    (theme === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);

  document.documentElement.classList.toggle('dark', isDark);
}

// Listen for system preference changes
window.matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', () => {
    if (localStorage.getItem('theme') === 'system') {
      applyTheme();
    }
  });

applyTheme();
数据属性策略
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));

<html data-theme="dark">
  <body>
    <div class="bg-white dark:bg-gray-900">Content</div>
  </body>
</html>
使用 Next.js 实现深色模式（next-themes）
npm install next-themes

// app/providers.tsx
'use client';

import { ThemeProvider } from 'next-themes';

export function Providers({ children }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      {children}
    </ThemeProvider>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

// components/ThemeToggle.tsx
'use client';

import { useTheme } from 'next-themes';

export function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
      Toggle Theme
    </button>
  );
}
深色模式调色板

<p class="text-gray-900 dark:text-gray-100">Primary text</p>
<p class="text-gray-600 dark:text-gray-400">Secondary text</p>
<p class="text-gray-400 dark:text-gray-500">Muted text</p>


<div class="bg-white dark:bg-gray-900">Page background</div>
<div class="bg-gray-50 dark:bg-gray-800">Card background</div>
<div class="bg-gray-100 dark:bg-gray-700">Elevated background</div>


<div class="border border-gray-200 dark:border-gray-700">Bordered element</div>


<button class="bg-blue-500 hover:bg-blue-600 dark:bg-blue-600 dark:hover:bg-blue-700">
  Button
</button>
使用 CSS 变量实现深色模式
@theme {
  /* Light mode colors (default) */
  --color-bg-primary: oklch(1 0 0);
  --color-bg-secondary: oklch(0.98 0 0);
  --color-text-primary: oklch(0.15 0 0);
  --color-text-secondary: oklch(0.4 0 0);
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg-primary: oklch(0.15 0 0);
    --color-bg-secondary: oklch(0.2 0 0);
    --color-text-primary: oklch(0.95 0 0);
    --color-text-secondary: oklch(0.7 0 0);
  }
}

<div class="bg-[var(--color-bg-primary)] text-[var(--color-text-primary)]">
  Semantic colors
</div>
Typography 插件的深色模式
<article class="prose dark:prose-invert">
  
</article>

结合响应式设计与深色模式


<div class="
  grid grid-cols-1 md:grid-cols-2
  bg-white dark:bg-gray-900
  p-4 md:p-8
  text-gray-900 dark:text-white
">
  <div class="hidden dark:md:block">
    Only visible on md+ screens in dark mode
  </div>
</div>

最佳实践（2025/2026）

1. 从移动端开始，再逐步增强

<div class="text-sm md:text-base lg:text-lg">


<div class="lg:text-lg md:text-base text-sm">
2. 触控友好的交互元素

WCAG 2.2 要求最小尺寸为 24x24px，但建议使用 44x44px：


<button class="min-h-11 min-w-11 px-4 py-2.5">
  Click me
</button>


<a href="#" class="block py-3 px-4 min-h-11">
  Navigation Item
</a>


<div class="flex gap-3">
  <button class="min-h-11 px-4 py-2">Button 1</button>
  <button class="min-h-11 px-4 py-2">Button 2</button>
</div>
3. 流体排版（消除断点跳变）
@theme {
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);
  --text-fluid-lg: clamp(1.25rem, 1rem + 1.25vw, 2rem);
  --text-fluid-xl: clamp(1.5rem, 1rem + 2.5vw, 3rem);
}

<h1 class="text-fluid-xl font-bold">Smoothly Scaling Heading</h1>
<p class="text-fluid-base leading-relaxed">Smoothly scaling body text.</p>
2. 使用语义化的深色模式颜色
@theme {
  /* Instead of raw colors, use semantic names */
  --color-surface: oklch(1 0 0);
  --color-surface-dark: oklch(0.15 0 0);
  --color-on-surface: oklch(0.1 0 0);
  --color-on-surface-dark: oklch(0.95 0 0);
}
3. 测试所有断点

在开发过程中使用 debug-screens 插件：

npm install -D @tailwindcss/debug-screens

@plugin "@tailwindcss/debug-screens";
4. 使用组件减少重复
/* components.css */
@layer components {
  .card {
    @apply bg-white dark:bg-gray-800 rounded-lg p-6 shadow-sm;
  }

  .section {
    @apply py-12 md:py-16 lg:py-24;
  }
}
5. 考虑色彩对比度

确保浅色和深色模式下都有足够的对比度（WCAG 2.2）：

  • 普通文本：对比度至少为 4.5:1
  • 大号文本（18pt+）：对比度至少为 3:1
  • 交互元素：与相邻颜色的对比度至少为 3:1

<button class="
  bg-blue-600 text-white
  dark:bg-blue-500 dark:text-white
  hover:bg-blue-700 dark:hover:bg-blue-400
  /* Focus ring for accessibility */
  focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2
">
  Action
</button>
6. 尊重减少动态效果偏好

尊重偏好减少动态效果的用户：

<div class="
  transition-transform duration-300
  hover:scale-105
  motion-reduce:transition-none
  motion-reduce:hover:scale-100
">
  Respects motion preferences
</div>
7. 优化性能的响应式图像

<img
  src="image.jpg"
  alt="Description"
  loading="lazy"
  class="w-full h-auto"
/>


<img
  src="medium.jpg"
  srcset="small.jpg 400w, medium.jpg 800w, large.jpg 1200w"
  sizes="(min-width: 1024px) 50vw, 100vw"
  alt="Responsive image"
  loading="lazy"
  class="w-full h-auto"
/>
8. 安全区域处理（带刘海的设备）
@utility safe-area-pb {
  padding-bottom: env(safe-area-inset-bottom);
}


<nav class="fixed bottom-0 inset-x-0 safe-area-pb bg-white border-t">
  Navigation
</nav>

评论

支持 Markdown