# css.dev

> Open-source AI skills that stop coding agents from writing CSS slop and make them write modern, accessible CSS instead.

css.dev provides a set of Markdown skill files you install into your AI coding tool (Cursor, Claude Code, GitHub Copilot, Gemini CLI, OpenAI Codex). Once installed, the skills activate automatically whenever the agent touches CSS, enforcing modern patterns and blocking anti-patterns without any per-prompt instruction.

## What it does

AI models default to outdated CSS — floats for layout, hardcoded hex colors, `!important` overrides, `px`-based media queries, layout-thrashing animations — because they are trained on years of legacy public code. css.dev gives the model an explicit modern baseline so it stops defaulting to that output.

## The skills

Nine skills ship in the package. One activates automatically; eight are invoked by slash command.

- **css-expert** — Always-active core skill. Enforces the full css.dev philosophy on every CSS write, review, or debug task. Never needs to be called explicitly.
- **/css-audit** — Read-only quality audit. Scores CSS across six dimensions (Architecture, Specificity, Redundancy, Accessibility, Performance, Modernity) on a 0–10 scale. Produces a structured report with findings and a prioritized fix plan.
- **/css-layout** — Modern layout solutions using CSS Grid, Flexbox, subgrid, and container queries. Replaces floats and absolute-position hacks.
- **/css-animate** — Performant animations using only composited properties (transform, opacity). Includes scroll-driven effects and View Transition API. Always includes `prefers-reduced-motion` handling.
- **/css-responsive** — Container queries, fluid typography with `clamp()`, responsive images. No framework or breakpoint framework required.
- **/css-refactor** — Upgrades legacy CSS. Replaces floats, clearfix, vendor prefixes, and `@import` chains. Introduces cascade layers.
- **/css-theme** — Theming systems built with custom properties, `oklch()` colors, `color-mix()`, and `light-dark()`. Dark mode included by design.
- **/css-a11y** — CSS accessibility: `:focus-visible` styles, `prefers-reduced-motion`, `prefers-contrast`, `forced-colors`, touch target sizing, contrast ratios.
- **/css-debug** — Specificity analysis, inheritance tracing, stacking context maps, layout diagnosis.

## Core philosophy (enforced by every skill)

1. **Modern CSS first.** Container queries over media queries. Grid over float. Native nesting over preprocessors. `oklch()` over hex.
2. **The cascade is a feature.** Use `@layer` to organize specificity. Use `:where()` to zero specificity on reusable code. Never fight the cascade with `!important`.
3. **No frameworks required.** Pure CSS handles layout, theming, responsive design, and animation. Don't reach for Tailwind or Bootstrap unless the project already uses them.
4. **Performance is a constraint.** Animate only `transform` and `opacity`. Use `contain` and `content-visibility`. No layout thrashing.
5. **Accessibility is non-negotiable.** Respect `prefers-reduced-motion`. Provide `:focus-visible`. Support `forced-colors`. Maintain contrast ratios.
6. **Design tokens, not magic numbers.** Every value traces back to a custom property. No hardcoded pixels, hex colors, or arbitrary values.

## Anti-patterns the skills block

Float-based layouts, `!important` abuse, ID selectors for styling, hardcoded hex/px values, `px`-based media queries, media queries for component layout (use container queries), animating layout properties (width/height/top/left), missing `prefers-reduced-motion`, `@import` in stylesheets, outline removal without replacement, deep selector nesting, generic unscoped class names.

Full catalog: https://css.dev/anti-patterns

## Installation

Download the zip from https://css.dev and run the installer:

```bash
./install.sh cursor       # Cursor (project-level)
./install.sh claude       # Claude Code (project-level)
./install.sh copilot      # GitHub Copilot
./install.sh gemini       # Gemini CLI
./install.sh codex        # OpenAI Codex
./install.sh all          # All tools at once
./install.sh cursor --global  # Global install (all projects)
```

The installer copies the `skills/` directory into the correct location for each tool:
- Cursor → `.cursor/skills/`
- Claude Code → `.claude/skills/`
- Copilot / Codex → `.agents/skills/`
- Gemini CLI → `.gemini/skills/`

## License

MIT. The skills are open-source and free to use, modify, and redistribute.

## Links

- Homepage: https://css.dev
- Anti-pattern catalog: https://css.dev/anti-patterns
- Download: https://css.dev/downloads/css-dev-skills.zip