Resources scripts/ validate-styling.sh references/ styling-comparison.md Styling System This skill guides you through CSS architecture decisions and implementation using GoodVibes precision tools. Use this workflow when setting up styling infrastructure, creating design systems, or implementing theming and responsive patterns. When to Use This Skill Load this skill when: Setting up a new project's styling infrastructure Choosing between Tailwind, CSS Modules, CSS-in-JS, or vanilla CSS Implementing a design token system Adding dark mode support Creating responsive layouts and breakpoint strategies Migrating between styling approaches Building component variant systems Setting up animation patterns Trigger phrases: "setup styling", "add Tailwind", "implement dark mode", "design tokens", "responsive design", "CSS architecture", "theme system". Core Workflow Phase 1: Discovery Before making styling decisions, understand the project's current state. Step 1.1: Detect Existing Styling Approach Use discover to find styling patterns across the codebase. discover : queries : - id : tailwind_usage type : grep pattern : "(className=|class=).\".\b(flex|grid|text-|bg-|p-|m-)" glob : "/*.{tsx,jsx,vue,svelte}" - id : css_modules type : glob patterns : [ "/.module.css" , "/.module.scss" ] - id : css_in_js type : grep pattern : "(styled\.|styled\(|css`|makeStyles|createStyles)" glob : "/*.{ts,tsx,js,jsx}" - id : design_tokens type : glob patterns : [ "/tokens.{ts,js,json}" , "/design-tokens.{ts,js,json}" , "/theme.{ts,js}" ] - id : dark_mode type : grep pattern : "(dark:|data-theme|ThemeProvider|useTheme|darkMode)" glob : "*/.{ts,tsx,js,jsx,css,scss}" verbosity : count_only What this reveals: Primary styling approach (Tailwind, CSS Modules, CSS-in-JS, vanilla) Whether design tokens exist Dark mode implementation status Consistency across the codebase Step 1.2: Check Configuration Files Read existing config to understand the setup. precision_read : files : - path : "tailwind.config.js" extract : content - path : "tailwind.config.ts" extract : content - path : "postcss.config.js" extract : content - path : "src/styles/globals.css" extract : outline verbosity : minimal Step 1.3: Analyze Component Styling Patterns Read representative components to understand conventions. precision_read : files : - path : "src/components/Button.tsx"
or discovered component
- extract
- :
- content
- -
- path
- :
- "src/components/Card.tsx"
- extract
- :
- content
- output
- :
- max_per_item
- :
- 100
- verbosity
- :
- standard
- Phase 2: Decision Making
- Choose the styling approach that fits your project needs. See
- references/styling-comparison.md
- for the complete decision tree.
- Quick Decision Guide
- Use Tailwind CSS when:
- You want rapid prototyping with utility classes
- Consistency across team is a priority
- You prefer design constraints over complete freedom
- You're building component-based UIs (React, Vue, Svelte)
- Use CSS Modules when:
- You want scoped styles without build complexity
- You prefer writing traditional CSS
- You need coexistence with existing global styles
- Bundle size is a major concern (smaller than Tailwind)
- Use CSS-in-JS when:
- You need runtime dynamic theming
- You want TypeScript types for style props
- Component-scoped styles with JS logic are required
- You're using styled-components or Emotion
- Use Vanilla CSS when:
- You're building simple sites with minimal interactivity
- You want maximum control and minimal dependencies
- Progressive enhancement is critical
- You prefer cascade and inheritance patterns
- For detailed framework-specific patterns, see
- references/styling-comparison.md
- .
- Phase 3: Configuration Setup
- Step 3.1: Install Dependencies
- Based on your chosen approach, install required packages.
- Tailwind CSS:
- precision_exec
- :
- commands
- :
- -
- cmd
- :
- "npm install -D tailwindcss postcss autoprefixer"
- expect
- :
- exit_code
- :
- 0
- -
- cmd
- :
- "npx tailwindcss init -p"
- expect
- :
- exit_code
- :
- 0
- verbosity
- :
- minimal
- CSS-in-JS (styled-components):
- precision_exec
- :
- commands
- :
- -
- cmd
- :
- "npm install styled-components"
- -
- cmd
- :
- "npm install -D @types/styled-components"
- verbosity
- :
- minimal
- Step 3.2: Create Configuration
- Write config files following best practices.
- Tailwind Config Example:
- import
- type
- {
- Config
- }
- from
- 'tailwindcss'
- ;
- const
- config
- :
- Config
- =
- {
- content
- :
- [
- './src/pages/*/.{js,ts,jsx,tsx,mdx}'
- ,
- './src/components/*/.{js,ts,jsx,tsx,mdx}'
- ,
- './src/app/*/.{js,ts,jsx,tsx,mdx}'
- ,
- ]
- ,
- darkMode
- :
- 'class'
- ,
- // or 'media' for system preference
- theme
- :
- {
- extend
- :
- {
- colors
- :
- {
- primary
- :
- {
- 50
- :
- '#f0f9ff'
- ,
- 100
- :
- '#e0f2fe'
- ,
- // ... full scale
- 900
- :
- '#0c4a6e'
- ,
- }
- ,
- }
- ,
- fontFamily
- :
- {
- sans
- :
- [
- 'var(--font-inter)'
- ,
- 'system-ui'
- ,
- 'sans-serif'
- ]
- ,
- }
- ,
- spacing
- :
- {
- '18'
- :
- '4.5rem'
- ,
- }
- ,
- }
- ,
- }
- ,
- plugins
- :
- [
- ]
- ,
- }
- ;
- export
- default
- config
- ;
- Best Practices:
- Use TypeScript for config files (type safety)
- Extend theme, don't replace defaults
- Use CSS variables for dynamic values
- Keep content paths specific to avoid slow builds
- Use the
- class
- strategy for dark mode (more control)
- Step 3.3: Write Configuration Files
- precision_write
- :
- files
- :
- -
- path
- :
- "tailwind.config.ts"
- content
- :
- |
- import type { Config } from 'tailwindcss';
- // ... [full config]
- -
- path
- :
- "src/styles/globals.css"
- content
- :
- |
- @tailwind base;
- @tailwind components;
- @tailwind utilities;
- @layer base
- {
- :
- root
- {
- --background
- :
- 0 0% 100%;
- --foreground
- :
- 222.2 84% 4.9%;
- /*
- ...
- design tokens
- */
- }
- .dark
- {
- --background
- :
- 222.2 84% 4.9%;
- --foreground
- :
- 210 40% 98%;
- }
- }
- verbosity
- :
- count_only
- Phase 4: Design Token System
- Step 4.1: Define Token Structure
- Create a centralized token system for consistency.
- Token Categories:
- Colors
-
- Primary, secondary, neutral, semantic (success, error, warning)
- Typography
-
- Font families, sizes, weights, line heights
- Spacing
-
- Consistent scale (4px base, 8px increments)
- Shadows
-
- Elevation system
- Borders
-
- Radii, widths
- Breakpoints
-
- Responsive design system
- Animation
- Duration, easing functions
Implementation Pattern:
// src/styles/tokens.ts
export
const
tokens
=
{
colors
:
{
primary
:
{
light
:
'#3b82f6'
,
DEFAULT
:
'#2563eb'
,
dark
:
'#1d4ed8'
,
}
,
semantic
:
{
success
:
'#10b981'
,
error
:
'#ef4444'
,
warning
:
'#f59e0b'
,
}
,
}
,
spacing
:
{
xs
:
'0.25rem'
,
// 4px
sm
:
'0.5rem'
,
// 8px
md
:
'1rem'
,
// 16px
lg
:
'1.5rem'
,
// 24px
xl
:
'2rem'
,
// 32px
}
,
typography
:
{
fontFamily
:
{
sans
:
[
'Inter'
,
'system-ui'
,
'sans-serif'
]
,
mono
:
[
'Fira Code'
,
'monospace'
]
,
}
,
fontSize
:
{
xs
:
[
'0.75rem'
,
{
lineHeight
:
'1rem'
}
]
,
sm
:
[
'0.875rem'
,
{
lineHeight
:
'1.25rem'
}
]
,
base
:
[
'1rem'
,
{
lineHeight
:
'1.5rem'
}
]
,
lg
:
[
'1.125rem'
,
{
lineHeight
:
'1.75rem'
}
]
,
xl
:
[
'1.25rem'
,
{
lineHeight
:
'1.75rem'
}
]
,
}
,
}
,
}
as
const
;
export
type
Tokens
=
typeof
tokens
;
// Integration with ThemeProvider (React Context)
type
Theme
=
{
tokens
:
Tokens
;
mode
:
'light'
|
'dark'
;
}
;
// Integration with styled-components
import
'styled-components'
;
declare
module
'styled-components'
{
export
interface
DefaultTheme
extends
Tokens
{
mode
:
'light'
|
'dark'
;
}
}
// Usage in components
import
{
useTheme
}
from
'styled-components'
;
const
Button
=
styled
.
button
background: ${ props => props . theme . colors . primary } ; padding: ${ props => props . theme . spacing [ 4 ] } ;; Step 4.2: Integrate Tokens with Tailwind // tailwind.config.ts import { tokens } from './src/styles/tokens' ; const config : Config = { theme : { extend : { colors : tokens . colors , spacing : tokens . spacing , fontFamily : tokens . typography . fontFamily , fontSize : tokens . typography . fontSize , } , } , } ; Phase 5: Dark Mode Implementation Step 5.1: Choose Dark Mode Strategy Class-based (Recommended): More control over toggle behavior Can persist user preference Works with next-themes or similar libraries Media query-based: Respects system preference only No JS required Less flexibility Step 5.2: Setup next-themes (React/Next.js) // src/components/ThemeProvider.tsx import { ThemeProvider as NextThemesProvider } from 'next-themes' ; import type { ReactNode } from 'react' ; interface ThemeProviderProps { children : ReactNode ; } export function ThemeProvider ( { children } : ThemeProviderProps ) { return ( < NextThemesProvider attribute = "class" defaultTheme = "system" enableSystem disableTransitionOnChange{ children } < / NextThemesProvider
) ; } Step 5.3: Define Dark Mode Color Scales Use CSS variables for seamless theme switching. / globals.css / @layer base { :root { --background : 0 0 % 100 % ; --foreground : 222.2 84 % 4.9 % ; --card : 0 0 % 100 % ; --card-foreground : 222.2 84 % 4.9 % ; --primary : 221.2 83.2 % 53.3 % ; --primary-foreground : 210 40 % 98 % ; } .dark { --background : 222.2 84 % 4.9 % ; --foreground : 210 40 % 98 % ; --card : 222.2 84 % 4.9 % ; --card-foreground : 210 40 % 98 % ; --primary : 217.2 91.2 % 59.8 % ; --primary-foreground : 222.2 47.4 % 11.2 % ; } } Best Practices: Use HSL values for easier manipulation Keep semantic naming (background, foreground, primary) Test contrast ratios for accessibility (WCAG AA: 4.5:1) Avoid pure black (#000) in dark mode (use dark grays) Phase 6: Responsive Design Patterns Step 6.1: Define Breakpoint Strategy Mobile-First Approach (Recommended): / Base styles for mobile / .container { padding : 1 rem ; } / Tablet and up / @media ( min-width : 768 px ) { .container { padding : 2 rem ; } } / Desktop and up / @media ( min-width : 1024 px ) { .container { padding : 3 rem ; } } Tailwind Breakpoints: < div className = " p-4 md:p-8 lg:p-12 "
{ / padding increases with screen size / } </ div
Step 6.2: Container Queries (Modern) Use container queries for component-level responsiveness. .card-container { container-type : inline-size ; } @container ( min-width : 400 px ) { .card { display : grid ; grid-template-columns : 1 fr 2 fr ; } } Tailwind Container Queries: // tailwind.config.ts plugins : [ require ( '@tailwindcss/container-queries' ) ] < div className = " @container "
< div className = " @md:grid @md:grid-cols-2 "
{ / Responsive to container, not viewport / } </ div
</ div
Phase 7: Component Variant Systems Step 7.1: Install class-variance-authority (CVA) precision_exec : commands : - cmd : "npm install class-variance-authority clsx tailwind-merge" verbosity : minimal Step 7.2: Create cn Utility // src/lib/utils.ts import { type ClassValue , clsx } from 'clsx' ; import { twMerge } from 'tailwind-merge' ; export function cn ( ... inputs : ClassValue [ ] ) { return twMerge ( clsx ( inputs ) ) ; } Step 7.3: Build Variant Components // src/components/Button.tsx import { cva , type VariantProps } from 'class-variance-authority' ; import { cn } from '@/lib/utils' ; import type { ButtonHTMLAttributes } from 'react' ; const buttonVariants = cva ( // Base styles 'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50' , { variants : { variant : { default : 'bg-primary text-primary-foreground hover:bg-primary/90' , destructive : 'bg-destructive text-destructive-foreground hover:bg-destructive/90' , outline : 'border border-input bg-background hover:bg-accent' , ghost : 'hover:bg-accent hover:text-accent-foreground' , } , size : { default : 'h-10 px-4 py-2' , sm : 'h-9 rounded-md px-3' , lg : 'h-11 rounded-md px-8' , icon : 'h-10 w-10' , } , } , defaultVariants : { variant : 'default' , size : 'default' , } , } ) ; interface ButtonProps extends ButtonHTMLAttributes < HTMLButtonElement
, VariantProps < typeof buttonVariants
{ asChild ? : boolean ; } export function Button ( { className , variant , size , ... props } : ButtonProps ) { return ( < button className = { cn ( buttonVariants ( { variant , size , className } ) ) } { ... props } /
) ; } Benefits: Type-safe variant props Automatic Tailwind class merging Consistent component API Easy to extend with new variants Phase 8: Error State Styling Step 8.1: Form Validation States // src/components/Input.tsx import { cva } from 'class-variance-authority' ; import { cn } from '@/lib/utils' ; const inputVariants = cva ( 'w-full rounded-md border px-3 py-2 text-sm transition-colors' , { variants : { state : { default : 'border-input focus:border-primary focus:ring-2 focus:ring-primary/20' , error : 'border-destructive focus:border-destructive focus:ring-2 focus:ring-destructive/20' , success : 'border-green-500 focus:border-green-500 focus:ring-2 focus:ring-green-500/20' , } , } , defaultVariants : { state : 'default' , } , } ) ; interface InputProps extends React . InputHTMLAttributes < HTMLInputElement
{ error ? : string ; success ? : boolean ; } export function Input ( { error , success , className , ... props } : InputProps ) { const state = error ? 'error' : success ? 'success' : 'default' ; return ( < div className = "space-y-1"
< input className = { cn ( inputVariants ( { state } ) , className ) } aria - invalid = { ! ! error } aria - describedby = { error ? 'input-error' : undefined } { ... props } /
{ error && ( < p id = "input-error" className = "text-sm text-destructive" role = "alert"
{ error } < / p
) } < / div
) ; } Step 8.2: Toast Notifications // src/components/Toast.tsx import { cva } from 'class-variance-authority' ; const toastVariants = cva ( 'rounded-lg border p-4 shadow-lg' , { variants : { variant : { default : 'bg-background border-border' , success : 'bg-green-50 border-green-200 text-green-900 dark:bg-green-950 dark:border-green-800 dark:text-green-100' , error : 'bg-red-50 border-red-200 text-red-900 dark:bg-red-950 dark:border-red-800 dark:text-red-100' , warning : 'bg-yellow-50 border-yellow-200 text-yellow-900 dark:bg-yellow-950 dark:border-yellow-800 dark:text-yellow-100' , } , } , } ) ; Step 8.3: Loading/Skeleton States / Skeleton pulse animation / @keyframes pulse { 0% , 100% { opacity : 1 ; } 50% { opacity : 0.5 ; } } .skeleton { animation : pulse 2 s cubic-bezier ( 0.4 , 0 , 0.6 , 1 ) infinite ; background-color : hsl ( var ( --muted ) ) ; border-radius : 0.375 rem ; } // src/components/Skeleton.tsx export function Skeleton ( { className , ... props } : React . HTMLAttributes < HTMLDivElement
) { return < div className = { cn ( 'skeleton' , className ) } { ... props } /
; } // Usage in loading states export function CardSkeleton ( ) { return ( < div className = "space-y-3"
< Skeleton className = "h-4 w-full" /
< Skeleton className = "h-4 w-3/4" /
< Skeleton className = "h-20 w-full" /
< / div
) ; } Phase 9: Animation Patterns Step 9.1: CSS Transitions (Lightweight) .button { transition : background-color 200 ms ease-in-out ; } .button :hover { background-color : var ( --primary-hover ) ; } Tailwind: < button className = " transition-colors duration-200 hover:bg-primary-hover "
Click me </ button
Step 9.2: Framer Motion (Advanced) For complex animations and gestures. // src/components/AnimatedCard.tsx import { motion } from 'framer-motion' ; export function AnimatedCard ( ) { return ( < motion . div initial = { { opacity : 0 , y : 20 } } animate = { { opacity : 1 , y : 0 } } exit = { { opacity : 0 , y : - 20 } } transition = { { duration : 0.3 } } whileHover = { { scale : 1.02 } } whileTap = { { scale : 0.98 } }
< div className = "card"
Content < / div
< / motion . div
) ; } Best Practices: Keep animations under 300ms for UI feedback Use easing functions (ease-in-out, ease-out) Respect prefers-reduced-motion Avoid animating layout-triggering properties (width, height) Prefer transform and opacity (GPU-accelerated) Phase 10: Validation Step 10.1: Run Styling Validation Script bash scripts/validate-styling.sh . See scripts/validate-styling.sh for the complete validation suite. Step 10.2: Check Build Output Verify CSS bundle size and ensure no unused styles. precision_exec : commands : - cmd : "npm run build" expect : exit_code : 0 verbosity : standard Check for: CSS bundle size (<50KB gzipped for Tailwind is good) No duplicate utility classes Proper tree-shaking Dark mode classes generated correctly Step 10.3: Accessibility Check Ensure color contrast meets WCAG standards. precision_exec : commands : - cmd : "npx @axe-core/cli http://localhost:3000" verbosity : standard Step 10.4: Visual Regression Testing Catch unintended visual changes with automated screenshot comparison. Playwright with Visual Testing: // tests/visual.spec.ts import { test , expect } from '@playwright/test' ; test ( 'button variants match snapshots' , async ( { page } ) => { await page . goto ( '/components/button' ) ; // Take screenshot and compare await expect ( page ) . toHaveScreenshot ( 'button-variants.png' , { maxDiffPixels : 100 , } ) ; } ) ; test ( 'dark mode toggle' , async ( { page } ) => { await page . goto ( '/' ) ; // Light mode await expect ( page ) . toHaveScreenshot ( 'home-light.png' ) ; // Toggle to dark await page . click ( '[data-testid="theme-toggle"]' ) ; await expect ( page ) . toHaveScreenshot ( 'home-dark.png' ) ; } ) ; Chromatic (for Storybook):
Install and setup
npm install --save-dev chromatic
Run visual tests
npx chromatic --project-token
< token
Percy (cross-browser): import percySnapshot from '@percy/playwright' ; test ( 'responsive layout' , async ( { page } ) => { await page . goto ( '/dashboard' ) ; await percySnapshot ( page , 'Dashboard - Desktop' ) ; await page . setViewportSize ( { width : 375 , height : 667 } ) ; await percySnapshot ( page , 'Dashboard - Mobile' ) ; } ) ; Step 10.5: CSS Purging Configuration Tailwind v3+ with JIT: The content paths in tailwind.config.ts serve as the purge configuration. Tailwind automatically removes unused classes in production builds. // tailwind.config.ts export default { content : [ './src/pages//*.{js,ts,jsx,tsx}' , './src/components//.{js,ts,jsx,tsx}' , './src/app//.{js,ts,jsx,tsx}' , ] , // JIT mode is default in v3+ } ; Production Build Optimization:
Build with minification
npx tailwindcss -i ./src/styles/globals.css -o ./dist/output.css --minify
Check final size
du -h dist/output.css Safelist Dynamic Classes: // tailwind.config.ts export default { content : [ './src//*.{js,ts,jsx,tsx}' ] , safelist : [ // Dynamic classes that can't be detected statically 'bg-red-500' , 'bg-green-500' , 'bg-blue-500' , // Or use patterns { pattern : / bg- ( red | green | blue ) - ( 400 | 500 | 600 ) / , } , ] , } ; Monitor Bundle Size: precision_exec : commands : - cmd : "npm run build" - cmd : "ls -lh dist//*.css" verbosity : standard Target: <50KB gzipped for typical Tailwind projects after purging. Common Anti-Patterns DON'T: Mix styling approaches (Tailwind + CSS-in-JS in same components) Use inline styles for static values Hardcode colors/spacing (use design tokens) Ignore dark mode contrast ratios Use !important to override Tailwind (fix specificity instead) Animate width/height (causes layout thrashing) Skip mobile-first responsive design Use pixel values everywhere (prefer rem for accessibility) DO: Choose one primary styling approach and be consistent Use CSS variables for dynamic values Implement design tokens from the start Test dark mode for contrast and readability Follow Tailwind's utility-first philosophy Animate transform and opacity for performance Design mobile-first, enhance for larger screens Use relative units (rem, em, %) for scalability Security Considerations CSP (Content Security Policy) and Styling: Safe by Default (Build-time): Tailwind CSS - Compiled at build time, no runtime injection CSS Modules - Compiled at build time, CSP-safe Vanilla CSS / SCSS - Served as static files Requires CSP Configuration (Runtime): styled-components - Injects