web-css（WEB CSS 搜索）

Web CSS Skill

Version: 1.0 Stack: Vanilla CSS with CSS Variables

Clean, maintainable CSS without preprocessors or utility frameworks. Design tokens via CSS variables.

The Problem

AI-generated CSS drifts. Without memory between sessions, similar components end up with slightly different padding, colors, spacing, and border radii — not by design, but by independence. The drift itself isn't the problem. The problem is that every future edit becomes a partial fix: you change .card's background, but .panel uses #fff, .info-box uses white, and .content-block uses rgb(255,255,255) — same color, different formats, so only one gets updated. These standards centralize values into tokens so one edit propagates everywhere.

Consumption

• Builders: Read ## Builder Checklist before writing any CSS. Every value must use a token; every file must follow the 5-file architecture.
• Refactorers: Use ## Enforced Rules to find hardcoded values and structural violations. Read narrative sections for token naming and file organization guidance.
• Both: Narrative sections are the authoritative standard. Checklist and rules table are compressed views of the same content.

Scope and Boundaries

This skill covers:

• Design token implementation (CSS variables in:root)
• Token categories (colors, typography, spacing, borders, shadows, animations, z-index)
• Dark mode implementation with CSS variables
• CSS file organization and import order
• BEM-inspired naming conventions
• Mobile-first responsive breakpoints
• Layout patterns (Grid for structure, Flexbox for flow)
• Component states implementation
• CSS property ordering
• CSS anti-patterns

Defers to other skills:

• design: Design system philosophy, when to use Grid vs Flexbox, premium UI principles
• web-accessibility: Focus indicator patterns, reduced motion media queries, screen reader utilities

Use this skill when: You need CSS architecture, token implementation, or responsive patterns. Use design when: You need design principles, layout philosophy, or component state requirements. Use web-accessibility when: You need WCAG compliance or accessibility-specific CSS patterns.

Core Principles

1. Design Tokens First — All values come from CSS variables.
2. Component-Scoped — CSS lives with its component.
3. Mobile-First — Base styles for mobile, enhance up.
4. No Magic Numbers — Every value has a purpose and comes from the system.
5. Readable Over Clever — Obvious code beats clever code.
6. Consolidate, Don't Duplicate — Check for existing styles before creating new ones.

Before Writing New CSS

This is a gate, not a suggestion. Every new class that duplicates an existing pattern creates a variant. Every variant means future edits only partially propagate — you fix .card but miss .panel and .info-box because they were written independently with different values for the same intent. That's how CSS becomes a whack-a-mole game. Prevention here saves hours of cleanup later.

Before Writing Any Value

1. Check global.css first — Does a token already exist for this value? Use it. Never write a raw 16px, #3b82f6, or 8px when a token like var(--space-4), var(--color-primary), or var(--radius-md) exists.
2. Search for similar styles — Is there already a button, card, or layout pattern that does this? Reuse it.
3. Check for near-matches — Could an existing class work with minor tweaks or a modifier?
4. Extract if repeated — If you're writing the same properties a second time, stop and make it one class.

/* BAD — new class that duplicates existing .btn-primary */
.modal-submit-btn {
  padding: var(--space-2) var(--space-4);
  background: var(--color-primary);
  border-radius: var(--radius-md);
}

/* GOOD — reuse existing class, add modifier only for what's truly different */
.modal-footer .btn-primary {
  /* Only add what's actually different */
}

What Creates Drift

The Rule

If a token exists, use it. If a class exists, extend it. Only create something new when nothing existing fits.

Design Tokens

All design values live in styles/global.css as CSS variables in :root. Token categories:

For full token definitions and values, see assets/token-reference.md.

Dark mode: Override semantic color tokens on [data-theme="dark"]. Components adapt automatically. See assets/token-reference.md for implementation.

File Organization

The 5-File Architecture

All projects use exactly 5 CSS files, loaded in cascade order:

styles/
├── reset.css       # 1. Browser normalization — clean slate
├── global.css      # 2. Design tokens (:root) + element defaults
├── layouts.css     # 3. Page scaffolding, grids, containers
├── components.css  # 4. All component styles (BEM)
└── overrides.css   # 5. Exceptions — one-offs, page-specific, utilities

Enforced by: check.js rules css-file-count (warn >5, error >7) and css-file-names (warn when no canonical names found).

For detailed descriptions of each file (what goes in, what doesn't, internal organization), see references/file-architecture.md.

Templates

Pre-built template files define the canonical section structure for each CSS file. Projects override values, not structure.

templates/
├── reset.css       # Full reset (deterministic, same for every project)
├── global.css      # Token skeleton (:root with 9 categories) + element defaults
├── layouts.css     # Section headers only (project-specific content)
├── components.css  # Pattern template (Base → Variants → States per component)
└── overrides.css   # Section headers + accessibility utilities

Scaffold command: node scaffold-css.js <target-directory> copies all 5 templates. Never overwrites existing files.

Enforced by: check.js rules css-section-order (warn — major sections out of canonical order) and token-category-order (warn — token sub-categories out of order in global.css :root).

Where Does This Go?

Naming Conventions

BEM-Inspired (Simplified)

.product-card { }          /* Block */
.product-card__image { }   /* Element (child of block) */
.product-card--featured { } /* Modifier (variation) */
.product-card.is-loading { } /* State (JS-toggled) */

Naming Rules

Responsive Design

• Mobile-first only: Use min-width breakpoints. Never max-width.
• Standard breakpoints: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
• Grid for structure, Flexbox for flow.
• All interactive elements need 5 states: default, hover, active, focus-visible, disabled.

For code examples (breakpoints, container pattern, grid/flexbox layouts, component states, accessibility patterns), see assets/css-patterns.md.

Anti-Patterns

Property Order

Organize properties by group. 5 groups, always in this order:

.component {
  /* 1. Positioning */
  position: relative;
  top: 0;
  z-index: var(--z-dropdown);

  /* 2. Box Model */
  display: flex;
  grid-template-columns: 1fr 1fr;
  width: 100%;
  padding: var(--space-4);
  margin: 0;

  /* 3. Typography */
  font-family: var(--font-sans);
  font-size: var(--font-size-base);
  color: var(--color-text);

  /* 4. Visual */
  background-color: var(--color-surface);
  border: 1px solid var(--color-border);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
  transform: translateY(0);

  /* 5. Animation */
  transition: box-shadow var(--duration-fast);
}

Enforced by: check.js rule css-property-order (warn).

Builder Checklist

Before writing CSS governed by this skill, verify your plan against these constraints. Builders read this section before writing code; refactorers use the Enforced Rules table and full narrative instead.

Design Tokens

• All colors use CSS variables
• All spacing uses CSS variables
• All font sizes use CSS variables
• All shadows use CSS variables
• No hardcoded hex colors in component CSS
• No hardcoded pixel values (except borders)

Organization

• Tokens defined in central file
• CSS colocated with components
• BEM-style naming used
• No ID selectors for styling

Responsive

• Mobile-first (min-width queries only)
• Standard breakpoints used
• Tested at all breakpoints

Accessibility

• Focus indicators visible
• Reduced motion respected
• Color contrast meets WCAG AA
• No reliance on color alone

No Tailwind. No PostCSS.

This design system uses vanilla CSS with design tokens. No build tools, no utility-class frameworks, no preprocessors.

Why not Tailwind? It moves styling decisions into HTML, producing class bloat (class="flex items-center gap-4 p-6 rounded-lg bg-white shadow-md") that's hard to scan, hard to search, and impossible to update from one place. Our design system solves the same problem — consistency — by putting it where it belongs: in CSS variables and semantic class names.

Why not PostCSS? Modern CSS supports variables, nesting, @layer, color-mix(), and container queries natively. PostCSS adds a build step and tooling complexity for features browsers already handle.

If a project already uses Tailwind or PostCSS:

1. Don't add more Tailwind utilities or PostCSS plugins
2. New CSS goes in vanilla .css files using the 5-file architecture and design tokens
3. When touching existing Tailwind components, extract the utility chains into semantic classes in components.css that reference tokens
4. Migrate incrementally — don't rewrite everything at once, but don't extend the old pattern either

Enforced Rules

These rules are deterministically checked by check.js (clean-team). When updating these standards, update the corresponding check.js rules to match — and vice versa.

References

• references/file-architecture.md — Detailed descriptions of each CSS file
• assets/token-reference.md — Full token definitions, usage examples, dark mode
• assets/css-patterns.md — Responsive, layout, state, and accessibility code examples