Skill: Update Styles

Objective

Update Tailwind CSS styles in components or global CSS with proper dark mode support. This skill handles styling-only changes without modifying component logic.

Non-Goals

• Does NOT modify component logic
• Does NOT add new features
• Does NOT create new components
• Does NOT change layout structure

Tier Classification

Tier: 1 - Light/Cheap

Reasoning: Styling changes are visual-only, follow clear Tailwind patterns, and have low risk. Easy to validate visually.

Inputs

Required Parameters

• $TARGET: File(s) to update (component or global.css)
• $CHANGES: What styling changes are needed

Optional Parameters

• $DARK_MODE: Ensure dark mode support (default: true)

Brand Reference

Always consult Brand Guide for the official color palette, dark mode pairing rules, and typography scale before making styling decisions.

Editorial Design System ("The Broadsheet")

This site uses an editorial newsprint design system. Prefer its semantic tokens over raw grays or generic blues.

• Palette tokens (defined via @theme/.dark in src/styles/global.css): paper #F7F4EC / ink #1B1A17 in light; warm near-black #14140F ground + paper-colored text #ECE7DA in dark. The oxblood accent is mapped to --color-secondary (#7A1F1F light / #C2554D dark) and is reserved for links, kicker rules, and small marks. Use bg-paper text-ink and text-secondary.
• No indigo, no multi-color accents, no radial glows, no prose-slate — and no xergioalex/personal residue.
• Typography: serif is the body + heading default (--font-serif); --font-sans/--font-mono exist as tokens. Use the .font-display utility for serif display headings.
• Width & measure: align page content to the masthead with .main-container; keep a ~66ch reading measure (e.g. max-w-3xl) for long-form prose.
• Editorial primitives live in src/components/editorial/ — Kicker, Rule, Figure, Lead (optional drop cap), Reference. Reuse them instead of hand-rolling eyebrows, hairline rules, captions, or drop caps.

Key Concepts

Tailwind Utility Classes

<!-- Spacing -->
<div class="p-4 m-2 px-6 py-3">

<!-- Colors -->
<div class="bg-white text-gray-900">

<!-- Typography -->
<p class="text-lg font-bold text-center">

<!-- Flexbox/Grid -->
<div class="flex items-center justify-between gap-4">
<div class="grid grid-cols-3 gap-6">

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

Dark Mode Pattern

Always pair light and dark:

<!-- Background -->
<div class="bg-white dark:bg-gray-900">

<!-- Text -->
<p class="text-gray-900 dark:text-gray-100">

<!-- Borders -->
<div class="border-gray-200 dark:border-gray-700">

<!-- Hover states -->
<button class="hover:bg-gray-100 dark:hover:bg-gray-800">

Theme Colors

From src/styles/global.css (editorial "Broadsheet" palette):

@theme {
  --color-paper: #f7f4ec; /* warm newsprint paper — light background */
  --color-ink: #1b1a17; /* warm near-black ink — body text (light) */
  --color-secondary: #7a1f1f; /* oxblood accent (light) */
}
.dark {
  --color-paper: #14140f; /* ink ground — dark background */
  --color-ink: #ece7da; /* paper-colored text (dark) */
  --color-secondary: #c2554d; /* oxblood, lightened for dark surfaces */
}

Usage:

<div class="bg-paper text-ink">
<span class="text-secondary">

Responsive Design Patterns

Mobile-first approach with Tailwind breakpoints:

Always design mobile-first, then progressively enhance:

<!-- Start simple on mobile, enhance at larger sizes -->
<div class="text-sm md:text-base lg:text-lg">
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
<div class="p-4 md:p-6 lg:p-8">

Heading text scaling (common pattern):

<!-- Scale headings across breakpoints for better mobile UX -->
<h1 class="text-3xl sm:text-4xl md:text-5xl lg:text-6xl font-bold">
<h2 class="text-2xl sm:text-3xl md:text-4xl lg:text-5xl font-bold">
<h3 class="text-xl sm:text-2xl md:text-3xl lg:text-4xl font-bold">

Responsive spacing patterns:

<!-- Stack on mobile, side-by-side on larger screens -->
<div class="flex flex-col md:flex-row gap-4 md:gap-8">

<!-- Reduce padding on mobile, increase on desktop -->
<div class="p-4 sm:p-6 md:p-8 lg:p-12">

<!-- Hide on mobile, show on larger screens -->
<div class="hidden md:block">

<!-- Show different content at different sizes -->
<div class="block md:hidden">Mobile content</div>
<div class="hidden md:block">Desktop content</div>

Touch target sizing (accessibility requirement):

Minimum 44px touch targets for interactive elements:

<!-- Buttons and interactive elements should be at least 44x44px -->
<button class="px-4 py-2 rounded min-h-[44px] min-w-[44px]">
<a href="/" class="inline-flex items-center justify-center h-12 px-4 rounded">
<div class="w-12 h-12 flex items-center justify-center rounded">

Dark mode + responsive combination:

<!-- Always pair dark mode with responsive changes -->
<h2 class="text-2xl sm:text-3xl md:text-4xl
           text-gray-900 dark:text-gray-100
           font-bold">

<div class="bg-white dark:bg-gray-800
           text-gray-900 dark:text-gray-100
           p-4 md:p-6 lg:p-8">

<button class="bg-blue-500 hover:bg-blue-600 dark:bg-blue-600 dark:hover:bg-blue-700
              px-4 md:px-6 py-2 md:py-3">

Steps

Step 1: Identify Target

• Read the target file(s)
• Understand current styling
• Note what needs to change

Step 2: Apply Changes

• Use Tailwind utilities (not custom CSS when possible)
• Add dark: variants for all color-related classes
• Maintain responsive design (sm:, md:, lg:)
• Keep existing structure

Step 3: Validate

pnpm run biome:check
pnpm run dev  # Visual inspection

Output Format

Success Output

## ✅ Styles Updated

### Target
{What was styled}

### Changes
- `{file}`: {what changed}

### Dark Mode
- Light mode: ✅
- Dark mode: ✅

### Validation
- Biome: ✅
- Visual check: ✅

### Commit Message
style: {description}

Guardrails

Required Patterns

• Dark mode classes included
• Responsive if needed
• Consistent with existing styles
• Uses Tailwind utilities

Scope Limits

• Maximum files: 5
• Maximum LOC: 100 (styling changes)

Stop Conditions

Stop and escalate if:

• Requires new custom CSS classes
• Layout restructuring needed
• Component logic changes required

Definition of Done

• Styling changes applied
• Dark mode supported
• Looks correct in both themes
• pnpm run biome:check passes

Common Patterns

Card Component

<div class="bg-white dark:bg-gray-800 rounded-lg shadow-md p-6 
            hover:shadow-lg transition-shadow">
  <h3 class="text-lg font-bold text-gray-900 dark:text-white">
  <p class="text-gray-600 dark:text-gray-300">
</div>

Button

<button class="px-4 py-2 rounded-lg font-medium
               bg-blue-500 hover:bg-blue-600 text-white
               dark:bg-blue-600 dark:hover:bg-blue-700
               transition-colors">

Link

<a class="text-blue-600 hover:text-blue-800 
          dark:text-blue-400 dark:hover:text-blue-300
          underline transition-colors">

Input

<input class="w-full px-4 py-2 rounded-lg border
              bg-white dark:bg-gray-800
              border-gray-300 dark:border-gray-600
              text-gray-900 dark:text-gray-100
              focus:ring-2 focus:ring-blue-500 focus:outline-none">

Examples

Example 1: Add Dark Mode to Component

Input:

$TARGET: src/components/Footer.astro
$CHANGES: Add dark mode support to footer text

Before:

<footer class="bg-gray-100 text-gray-600">

After:

<footer class="bg-gray-100 dark:bg-gray-900 text-gray-600 dark:text-gray-400">

Example 2: Update Global Container

Input:

$TARGET: src/styles/global.css
$CHANGES: Add new utility class for cards

Add to global.css:

@layer components {
  .card {
    @apply bg-white dark:bg-gray-800 rounded-lg shadow-md p-6;
  }
}

Example 3: Responsive + Dark Mode Fix

Input:

$TARGET: src/components/home/HeroSection.astro
$CHANGES: Scale heading text responsively and ensure dark mode support

Before:

<h1 class="text-6xl font-bold text-gray-900">

After:

<h1 class="text-3xl sm:text-4xl md:text-5xl lg:text-6xl
           font-bold
           text-gray-900 dark:text-gray-100">

Example 4: Responsive Grid Layout

Input:

$TARGET: src/components/ProjectsSection.astro
$CHANGES: Make project grid responsive with dark mode

Before:

<div class="grid grid-cols-4 gap-6 bg-gray-50">

After:

<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-4 md:gap-6
           bg-gray-50 dark:bg-gray-900
           p-4 md:p-8">

Related

• quick-fix - Small fixes
• add-component - Create components
• src/styles/README.md - Styling guide
• tailwind.config.mjs - Tailwind configuration