tailwindcss

Tailwind CSS 开发技能

文件组织：此技能采用拆分结构。高级模式请参阅 references/。

1. 概述

此技能提供 Tailwind CSS 专业知识，帮助使用实用优先的 CSS 为 JARVIS AI 助手界面设计样式，打造一致且易于维护的 HUD 设计。

风险级别：低——样式框架，安全攻击面极小

主要使用场景：

• 全息 UI 面板样式设计
• 响应式 HUD 布局
• 用于过渡效果的动画实用类
• 自定义 JARVIS 主题配置

2. 核心职责

2.1 基本原则

1. 先进行 TDD：在实现样式前编写组件测试
2. 关注性能：优化 CSS 输出大小和渲染性能
3. 实用优先：使用实用类组合样式，重复出现模式时提取为组件
4. 设计系统：在配置中定义 JARVIS 配色方案和间距
5. 响应式设计：采用移动优先策略，并使用断点实用类
6. 默认深色模式：HUD 始终采用深色主题
7. 无障碍性：保持足够的对比度

3. 实现工作流（TDD）

3.1 样式化组件的 TDD 流程

每个样式化组件都遵循此工作流：

步骤 1：先编写失败的测试

// tests/components/HUDPanel.test.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import HUDPanel from '~/components/HUDPanel.vue'

describe('HUDPanel', () => {
  it('renders with correct JARVIS theme classes', () => {
    const wrapper = mount(HUDPanel, {
      props: { title: 'System Status' }
    })

    const panel = wrapper.find('[data-testid="hud-panel"]')
    expect(panel.classes()).toContain('bg-jarvis-bg-panel/80')
    expect(panel.classes()).toContain('border-jarvis-primary/30')
    expect(panel.classes()).toContain('backdrop-blur-sm')
  })

  it('applies responsive grid layout', () => {
    const wrapper = mount(HUDPanel)
    const grid = wrapper.find('[data-testid="panel-grid"]')

    expect(grid.classes()).toContain('grid-cols-1')
    expect(grid.classes()).toContain('md:grid-cols-2')
    expect(grid.classes()).toContain('lg:grid-cols-3')
  })

  it('shows correct status indicator colors', async () => {
    const wrapper = mount(HUDPanel, {
      props: { status: 'active' }
    })

    const indicator = wrapper.find('[data-testid="status-indicator"]')
    expect(indicator.classes()).toContain('bg-jarvis-primary')
    expect(indicator.classes()).toContain('animate-pulse')

    await wrapper.setProps({ status: 'error' })
    expect(indicator.classes()).toContain('bg-jarvis-danger')
  })

  it('maintains accessibility focus styles', () => {
    const wrapper = mount(HUDPanel)
    const button = wrapper.find('button')

    expect(button.classes()).toContain('focus:ring-2')
    expect(button.classes()).toContain('focus:outline-none')
  })
})

步骤 2：实现最少代码以通过测试

<template>
  <div
    data-testid="hud-panel"
    class="bg-jarvis-bg-panel/80 border border-jarvis-primary/30 backdrop-blur-sm rounded-lg p-4"
  >
    <div
      data-testid="panel-grid"
      class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
    >
      <slot />
    </div>
    <span
      data-testid="status-indicator"
      :class="statusClasses"
    />
    <button class="focus:ring-2 focus:outline-none focus:ring-jarvis-primary">
      Action
    </button>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'

const props = defineProps<{
  title?: string
  status?: 'active' | 'warning' | 'error' | 'inactive'
}>()

const statusClasses = computed(() => ({
  'bg-jarvis-primary animate-pulse': props.status === 'active',
  'bg-jarvis-warning': props.status === 'warning',
  'bg-jarvis-danger': props.status === 'error',
  'bg-gray-500': props.status === 'inactive'
}))
</script>

步骤 3：按需重构

将重复模式提取为 @apply 指令：

/* assets/css/components.css */
@layer components {
  .hud-panel {
    @apply bg-jarvis-bg-panel/80 border border-jarvis-primary/30 backdrop-blur-sm rounded-lg p-4;
  }

  .hud-grid {
    @apply grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4;
  }
}

步骤 4：运行完整验证

# Run all style-related tests
npm run test -- --grep "HUDPanel"

# Check for unused CSS
npx tailwindcss --content './components/**/*.vue' --output /dev/null

# Verify build size
npm run build && ls -lh .output/public/_nuxt/*.css

4. 性能模式

4.1 清除优化

// tailwind.config.js
// Good: Specific content paths
export default {
  content: [
    './components/**/*.{vue,js,ts}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './composables/**/*.ts'
  ]
}

// Bad: Too broad, includes unused files
export default {
  content: ['./src/**/*']  // Includes tests, stories, etc.
}

4.2 JIT 模式效率

// Good: Let JIT generate only used utilities
export default {
  mode: 'jit',  // Default in v3+
  theme: {
    extend: {
      // Only extend what you need
      colors: {
        jarvis: {
          primary: '#00ff41',
          secondary: '#0891b2'
        }
      }
    }
  }
}

// Bad: Defining unused variants
export default {
  variants: {
    extend: {
      backgroundColor: ['active', 'group-hover', 'disabled']  // May not use all
    }
  }
}

4.3 @apply 提取策略

<style>
@layer components {
  .btn-jarvis {
    @apply px-4 py-2 rounded font-medium transition-all duration-200
           focus:outline-none focus:ring-2 focus:ring-offset-2;
  }
}
</style>


<style>
.my-unique-element {
  @apply p-4 m-2 text-white;  /* Just use utilities in template */
}
</style>

4.4 响应式断点效率

<div class="p-2 md:p-4 lg:p-6">
  <div class="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-4">
</div>


<div class="p-2 sm:p-2 md:p-4 lg:p-4 xl:p-6">
  <div class="grid grid-cols-1 sm:grid-cols-1 md:grid-cols-2 lg:grid-cols-2">
</div>

4.5 深色模式效率

// Good: Single dark mode strategy (JARVIS is always dark)
export default {
  darkMode: 'class',  // Use 'class' for explicit control
  theme: {
    extend: {
      colors: {
        jarvis: {
          bg: {
            dark: '#0a0a0f',  // Define dark colors directly
            panel: '#111827'
          }
        }
      }
    }
  }
}

// Bad: Light/dark variants when app is always dark
<div class="bg-white dark:bg-gray-900">  // Unnecessary light styles

4.6 动画性能

// Good: GPU-accelerated properties
export default {
  theme: {
    extend: {
      keyframes: {
        glow: {
          '0%, 100%': { opacity: '0.5' },  // opacity is GPU-accelerated
          '50%': { opacity: '1' }
        }
      }
    }
  }
}

// Bad: Layout-triggering properties
keyframes: {
  resize: {
    '0%': { width: '100px' },  // Triggers layout recalc
    '100%': { width: '200px' }
  }
}

5. 技术栈与版本

5.1 推荐版本

Package	Version	Notes
tailwindcss	^3.4.0	支持 JIT 模式的最新版本
@nuxtjs/tailwindcss	^6.0.0	Nuxt 集成
tailwindcss-animate	^1.0.0	动画实用类

5.2 配置

// tailwind.config.js
export default {
  content: [
    './components/**/*.{vue,js,ts}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './composables/**/*.ts',
    './plugins/**/*.ts'
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        jarvis: {
          primary: '#00ff41',
          secondary: '#0891b2',
          warning: '#f59e0b',
          danger: '#ef4444',
          bg: {
            dark: '#0a0a0f',
            panel: '#111827'
          }
        }
      },
      fontFamily: {
        mono: ['JetBrains Mono', 'monospace'],
        display: ['Orbitron', 'sans-serif']
      },
      animation: {
        'pulse-slow': 'pulse 3s cubic-bezier(0.4, 0, 0.6, 1) infinite',
        'scan': 'scan 2s linear infinite',
        'glow': 'glow 2s ease-in-out infinite alternate'
      },
      keyframes: {
        scan: {
          '0%': { transform: 'translateY(-100%)' },
          '100%': { transform: 'translateY(100%)' }
        },
        glow: {
          '0%': { boxShadow: '0 0 5px #00ff41' },
          '100%': { boxShadow: '0 0 20px #00ff41' }
        }
      }
    }
  },
  plugins: [
    require('@tailwindcss/forms'),
    require('tailwindcss-animate')
  ]
}

6. 实现模式

6.1 HUD 面板组件

<template>
  <div class="
    relative
    bg-jarvis-bg-panel/80
    border border-jarvis-primary/30
    rounded-lg
    p-4
    backdrop-blur-sm
    shadow-lg shadow-jarvis-primary/10
  ">
    
    <div class="
      absolute inset-0
      bg-gradient-to-b from-transparent via-jarvis-primary/5 to-transparent
      animate-scan
      pointer-events-none
    " />

    
    <div class="relative z-10">
      <h3 class="
        font-display
        text-jarvis-primary
        text-lg
        uppercase
        tracking-wider
        mb-2
      ">
        {{ title }}
      </h3>
      <slot />
    </div>
  </div>
</template>

6.2 状态指示器

<template>
  <div class="flex items-center gap-2">
    <span :class="[
      'w-2 h-2 rounded-full',
      {
        'bg-jarvis-primary animate-pulse': status === 'active',
        'bg-jarvis-warning': status === 'warning',
        'bg-jarvis-danger animate-ping': status === 'error',
        'bg-gray-500': status === 'inactive'
      }
    ]" />
    <span class="text-sm text-gray-300">{{ label }}</span>
  </div>
</template>

6.3 按钮变体

<template>
  <button :class="[
    'px-4 py-2 rounded font-medium transition-all duration-200',
    'focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-offset-jarvis-bg-dark',
    {
      'bg-jarvis-primary text-black hover:bg-jarvis-primary/90 focus:ring-jarvis-primary':
        variant === 'primary',
      'bg-transparent border border-jarvis-secondary text-jarvis-secondary hover:bg-jarvis-secondary/10 focus:ring-jarvis-secondary':
        variant === 'secondary',
      'bg-jarvis-danger text-white hover:bg-jarvis-danger/90 focus:ring-jarvis-danger':
        variant === 'danger'
    }
  ]">
    <slot />
  </button>
</template>

7. 质量标准

7.1 无障碍性

<span class="text-jarvis-primary"></span>


<button class="focus:ring-2 focus:ring-jarvis-primary focus:outline-none">


<span class="sr-only">Status: Active</span>

8. 常见错误与反模式

8.1 反模式

避免：过度使用自定义 CSS

<style>
.custom-panel {
  padding: 1rem;
  border-radius: 0.5rem;
}
</style>


<div class="p-4 rounded-lg">

避免：间距不一致

<div class="p-3 mt-5 mb-2">


<div class="p-4 my-4">

避免：硬编码颜色

<div class="text-[#00ff41]">


<div class="text-jarvis-primary">

9. 实现前检查清单

阶段 1：编写代码前

• 为预期的类应用情况编写组件测试
• 确认配置中已定义 JARVIS 主题颜色
• 检查内容路径是否包含所有源文件
• 查看现有组件，寻找可复用的模式

阶段 2：实现过程中

• 优先使用实用类，而非自定义 CSS
• 使用一致的间距比例（4、8、12、16……）
• 为所有交互元素添加焦点状态
• 在各尺寸下测试响应式断点
• 使用主题颜色，切勿硬编码十六进制值

阶段 3：提交前

• 所有组件测试均通过：npm test
• 构建完成且无 CSS 错误：npm run build
• 检查 CSS 包大小是否出现意外增长
• 确认没有未使用的 @apply 提取内容
• 使用键盘导航测试无障碍性

10. 总结

Tailwind CSS 为 JARVIS 提供实用优先的样式设计：

1. TDD：在实现前编写类应用测试
2. 性能：优化内容路径并使用 JIT 模式
3. 主题：在配置中定义 JARVIS 颜色和字体
4. 实用类：使用实用类组合样式，通过 @apply 提取模式
5. 无障碍性：保持焦点状态和足够的对比度

请记住：JARVIS HUD 具有鲜明的视觉风格——请遵循主题配置保持一致，并使用 vitest 测试所有样式。

---

参考资料：

• references/advanced-patterns.md - 复杂布局模式