Claude Code से production CSS styling: layers, tokens और visual checks

CSS Claude Code को देने में आसान लगता है, लेकिन production में सिर्फ screen का अच्छा दिखना काफी नहीं है। आपको CSS architecture, reusable tokens, responsive layout, dark mode, accessibility और regression checks भी चाहिए। इस guide में pricing card का छोटा example लेकर दिखाया गया है कि Claude Code को तेज काम करने दें, लेकिन stylesheet को random fixes का ढेर न बनने दें।

Design token का मतलब है रंग, spacing, radius और shadow जैसे decisions को नाम वाली variable में रखना। Cascade layer CSS priority की shelf है। Container query viewport नहीं, बल्कि component के parent container की width देखकर style बदलती है। जब ये सरल भाषा prompt में लिखी जाती है, Claude Code existing project rules को बेहतर follow करता है।

Examples adapt करते समय official docs साथ रखें: MDN @layer, CSS custom properties, container queries, prefers-color-scheme, W3C contrast guidance और Playwright visual comparisons। Claude Code workflow के लिए Claude Code common workflows देखें। Site के अंदर CLAUDE.md best practices और testing strategies भी उपयोगी हैं।

पहले styling harness बनाएं

अगर आप सिर्फ “CSS clean कर दो” लिखते हैं, Claude Code current screen ठीक कर सकता है, लेकिन maintenance मुश्किल हो सकती है। Real project में global CSS, CSS Modules, Tailwind utilities, Markdown content styles, browser defaults और old overrides साथ रहते हैं। Boundary न हो तो assistant अक्सर architecture सुधारने के बजाय stronger selectors जोड़ देता है।

Harness यानी agent के लिए सुरक्षित काम करने का frame। इसमें target files, allowed layers, token naming, commands और forbidden areas लिखें। CSS change जल्दी बड़ा हो जाता है क्योंकि visual result तुरंत दिखता है। Harness diff को reviewable रखता है।

flowchart LR
  P["Claude Code prompt"] --> L["cascade layers"]
  L --> T["design tokens"]
  T --> C["card/button components"]
  C --> R["responsive + container queries"]
  R --> D["dark mode"]
  D --> A["accessibility checks"]
  A --> V["Playwright visual regression"]

Editing से पहले inspection prompt दें:

Read AGENTS.md, CLAUDE.md, package.json, and every file under src/styles.
Do not edit yet.
Report the current CSS architecture, naming conventions, token usage,
dark-mode strategy, responsive breakpoints, and test commands.
Then propose the smallest safe plan for a pricing card and CTA button.

यह prompt Claude Code को existing system छोड़कर नया styling system बनाने से रोकता है। Human boundary तय करता है: कौन सा component बदलेगा, कौन से rules रहेंगे, और कौन से commands result verify करेंगे।

Cascade layers से priority तय करें

Cascade तय करती है कि एक element पर कई CSS rules लगें तो कौन जीतेगा। Teams अक्सर specificity बढ़ाकर, import order बदलकर या !important लगाकर conflict solve करती हैं। यह short term में काम करता है, लेकिन next change मुश्किल बनाता है। @layer priority को explicit बनाता है।

/* src/styles/app.css */
@layer reset, tokens, base, components, utilities, overrides;

@import "./tokens.css" layer(tokens);
@import "./base.css" layer(base);
@import "./components.css" layer(components);
@import "./utilities.css" layer(utilities);

@layer reset {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }

  body,
  h1,
  h2,
  h3,
  p {
    margin: 0;
  }
}

@layer overrides {
  .legacy-markdown :where(table, pre) {
    max-width: 100%;
  }
}

Claude Code से पहले classification करवाएं:

Move existing global CSS into the layer model in src/styles/app.css.
Do not change class names used by templates.
Use reset, tokens, base, components, utilities, and overrides only.
If a rule must go into overrides, explain why in the final response.
Run npm test and the visual check command after editing.

Common pitfall half-migration है। Layer के बाहर normal rules अब भी layer rules से जीत सकते हैं, और @import placement भी important है। पहले एक नया component layer में बनाकर verify करें, फिर old CSS को छोटे steps में migrate करें।

CSS variables में design tokens रखें

Tokens Claude Code को हर task में नया color, shadow और radius invent करने से रोकते हैं। Practical रूप में ये CSS variables हैं जिन्हें team reuse करती है।

/* src/styles/tokens.css */
@layer tokens {
  :root {
    color-scheme: light;
    --color-bg: #f7f7f2;
    --color-surface: #ffffff;
    --color-text: #1f2933;
    --color-muted: #5d6673;
    --color-border: #d9ded7;
    --color-accent: #0f766e;
    --color-accent-strong: #0b4f49;
    --color-focus: #b45309;

    --space-1: 0.25rem;
    --space-2: 0.5rem;
    --space-3: 0.75rem;
    --space-4: 1rem;
    --space-6: 1.5rem;
    --space-8: 2rem;

    --radius-sm: 0.25rem;
    --radius-md: 0.5rem;
    --shadow-card: 0 0.75rem 2rem rgb(31 41 51 / 0.12);
  }

  @media (prefers-color-scheme: dark) {
    :root:not([data-theme="light"]) {
      color-scheme: dark;
      --color-bg: #111827;
      --color-surface: #1f2937;
      --color-text: #f9fafb;
      --color-muted: #cbd5e1;
      --color-border: #475569;
      --color-accent: #2dd4bf;
      --color-accent-strong: #99f6e4;
      --color-focus: #fbbf24;
      --shadow-card: 0 0.75rem 2rem rgb(0 0 0 / 0.32);
    }
  }

  :root[data-theme="dark"] {
    color-scheme: dark;
    --color-bg: #111827;
    --color-surface: #1f2937;
    --color-text: #f9fafb;
    --color-muted: #cbd5e1;
    --color-border: #475569;
    --color-accent: #2dd4bf;
    --color-accent-strong: #99f6e4;
    --color-focus: #fbbf24;
    --shadow-card: 0 0.75rem 2rem rgb(0 0 0 / 0.32);
  }
}

Production CSS में सिर्फ pretty colors न पूछें। Contrast check मांगें। WCAG normal text के लिए आम तौर पर 4.5:1 contrast चाहता है। Body text, muted text, links, buttons और focus ring दोनों themes में पढ़ने लायक होने चाहिए।

Card और button को component layer में रखें

Cards और buttons blog, SaaS dashboard, landing page, settings और checkout में बार-बार आते हैं। अगर Claude Code .title या .button जैसी generic classes जोड़ता है, कोई दूसरी page टूट सकती है। Ownership दिखाने वाले names इस्तेमाल करें।

/* src/styles/components.css */
@layer components {
  .ui-card {
    container: card / inline-size;
    display: grid;
    gap: var(--space-4);
    padding: var(--space-6);
    border: 1px solid var(--color-border);
    border-radius: var(--radius-md);
    background: var(--color-surface);
    color: var(--color-text);
    box-shadow: var(--shadow-card);
  }

  .ui-card__eyebrow {
    color: var(--color-accent);
    font-size: 0.875rem;
    font-weight: 700;
  }

  .ui-card__title {
    max-width: 18ch;
    font-size: clamp(1.5rem, 1rem + 2cqi, 2.25rem);
    line-height: 1.1;
  }

  .ui-card__body {
    color: var(--color-muted);
    font-size: 1rem;
    line-height: 1.7;
  }

  .ui-actions {
    display: flex;
    flex-wrap: wrap;
    gap: var(--space-3);
    align-items: center;
  }

  .ui-button {
    display: inline-flex;
    min-height: 2.75rem;
    align-items: center;
    justify-content: center;
    padding: 0.75rem 1rem;
    border: 1px solid transparent;
    border-radius: var(--radius-sm);
    background: var(--color-accent);
    color: var(--color-surface);
    font: inherit;
    font-weight: 700;
    text-decoration: none;
  }

  .ui-button:hover {
    background: var(--color-accent-strong);
  }

  .ui-button:focus-visible {
    outline: 3px solid var(--color-focus);
    outline-offset: 3px;
  }

  .ui-button[aria-disabled="true"],
  .ui-button:disabled {
    cursor: not-allowed;
    opacity: 0.55;
  }
}

Verification के लिए /style-lab जैसी stable preview route बनाएं। Playwright को fixed content मिलेगा और screenshots reliable रहेंगे।

<main class="style-lab">
  <article class="ui-card" data-testid="pricing-card">
    <p class="ui-card__eyebrow">Team plan</p>
    <h1 class="ui-card__title">Ship production CSS with Claude Code</h1>
    <p class="ui-card__body">
      Layer your CSS, reuse tokens, check dark mode, and catch visual regressions before release.
    </p>
    <div class="ui-actions">
      <a class="ui-button" href="/training/">Start with training</a>
      <a class="ui-button" href="/thanks/">Get the free checklist</a>
    </div>
  </article>
</main>

Responsive और container queries अलग रखें

Media query viewport देखती है। Container query component को मिली जगह देखती है। Same card wide landing page, narrow sidebar और dashboard grid में अलग width पा सकता है।

/* src/styles/responsive.css */
@layer components {
  .style-lab {
    display: grid;
    min-height: 100svh;
    place-items: center;
    padding: clamp(1rem, 4vw, 4rem);
    background: var(--color-bg);
  }

  .pricing-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
    gap: var(--space-6);
    width: min(100%, 72rem);
  }

  @container card (min-width: 36rem) {
    .ui-card {
      grid-template-columns: 1fr auto;
      align-items: center;
    }

    .ui-card__body {
      max-width: 58ch;
    }

    .ui-actions {
      justify-content: end;
    }
  }

  @media (max-width: 40rem) {
    .ui-card {
      padding: var(--space-4);
    }

    .ui-actions,
    .ui-button {
      width: 100%;
    }
  }

  @media (prefers-reduced-motion: reduce) {
    *,
    *::before,
    *::after {
      scroll-behavior: auto !important;
      transition-duration: 0.001ms !important;
      animation-duration: 0.001ms !important;
      animation-iteration-count: 1 !important;
    }
  }
}

“Make it responsive” काफी नहीं है। Prompt में 320, 375, 768, 1024 और 1440px पर horizontal overflow, wrapping, focus ring clipping, CTA height और dark mode layout check करने को कहें।

Practical use cases

Use case 1 blog या landing page का monetization card है। Ads, affiliate links, consultation CTA और free download CTA दिखने चाहिए, लेकिन layout shift या visual noise नहीं बढ़ना चाहिए।

Use case 2 SaaS settings screen है। Cards, forms, destructive buttons और saved states एक ही surface share करते हैं। Claude Code से कहें कि existing tokens ही use करे और नया token चाहिए तो पहले proposal दे।

Use case 3 CMS content का legacy CSS है। Markdown और MDX body में h2, table, pre, blockquote पर global rules हो सकते हैं। Change को .legacy-markdown wrapper तक सीमित रखें और published pages की screenshot comparison करें।

Use case 4 design system migration की शुरुआत है। सब कुछ एक साथ migrate न करें। Cards और buttons से शुरू करें क्योंकि diff छोटा रहता है और review आसान होता है।

Review में पकड़ने वाली गलतियां

पहली गलती !important है। अगर Claude Code को यह जरूरी लगता है, तो selector conflict समझाने को कहें। दूसरी गलती contrast check के बिना dark mode है। तीसरी गलती हर problem को viewport breakpoint से solve करना है, जबकि issue container width का हो सकता है। चौथी गलती flaky visual test है, जिसमें fonts, animations, random data या live ads screenshots को unstable बनाते हैं।

Playwright visual regression जोड़ें

CSS को सिर्फ human eye से verify न करें। Playwright card को अलग widths, light mode, dark mode और keyboard focus state में compare कर सकता है।

// tests/visual/style-regression.spec.ts
import { expect, test } from "@playwright/test";

const viewports = [
  { name: "mobile", width: 375, height: 812 },
  { name: "tablet", width: 768, height: 1024 },
  { name: "desktop", width: 1440, height: 900 },
];

for (const viewport of viewports) {
  test(`pricing card visual regression ${viewport.name}`, async ({ page }) => {
    await page.setViewportSize({ width: viewport.width, height: viewport.height });
    await page.emulateMedia({ colorScheme: "light", reducedMotion: "reduce" });
    await page.goto("/style-lab");

    const card = page.getByTestId("pricing-card").first();
    await expect(card).toBeVisible();
    await expect(card).toHaveScreenshot(`pricing-card-${viewport.name}-light.png`, {
      animations: "disabled",
      maxDiffPixelRatio: 0.02,
    });
  });
}

test("dark theme keeps focus states visible", async ({ page }) => {
  await page.emulateMedia({ colorScheme: "dark", reducedMotion: "reduce" });
  await page.goto("/style-lab");
  await page.locator("html").evaluate((element) => {
    element.setAttribute("data-theme", "dark");
  });

  const startButton = page.getByRole("link", { name: /start with training/i });
  await startButton.focus();
  await expect(startButton).toBeFocused();
  await expect(page.getByTestId("pricing-card").first()).toHaveScreenshot(
    "pricing-card-dark-focus.png",
    {
      animations: "disabled",
      maxDiffPixelRatio: 0.02,
    },
  );
});

npx playwright test tests/visual/style-regression.spec.ts --update-snapshots
npx playwright test tests/visual/style-regression.spec.ts

अंत में fixed review prompt दें:

Critically review the CSS diff.
Check cascade layers, token usage, selector specificity, dark mode,
container queries, keyboard focus, color contrast, reduced motion,
and Playwright visual coverage.
Return only concrete issues with file paths and line numbers.

CTA और hands-on result

CSS article का next step साफ होना चाहिए। Individual developers free checklist से अपनी next styling change review कर सकते हैं। Teams Claude Code training and consultation पर जा सकती हैं। Repeatable rules के लिए harness engineering पढ़ें।

मैंने यह workflow छोटे style lab में test किया। सबसे बड़ा फायदा @layer से ज्यादा initial inspection prompt से मिला। जब Claude Code ने पहले existing styles, tokens और validation commands पढ़े, diff card और button तक सीमित रहा। जब मैंने सिर्फ “style बेहतर करो” कहा, hardcoded colors, duplicate spacing और no visual checks दिखे। Claude Code CSS तेजी से लिख सकता है, लेकिन production quality human-owned architecture, token names और regression commands से आती है।