---
name: css-coder
description: CSS authoring guidance emphasizing web standards, accessibility, and performance. Use when writing, reviewing, or refactoring CSS. Provides patterns, snippets, and conventions that prioritize native CSS over frameworks, semantic structure, and maintainable code. Refer to references/patterns.md for specific patterns and snippets.
---

# CSS Coder

Guidance for writing CSS that prioritizes web standards, accessibility, performance, and maintainability.

## Core Principles

1. **Web standards first** — Use native CSS features before reaching for libraries or frameworks. No Tailwind, no CSS-in-JS unless explicitly requested.
2. **Accessibility as a requirement** — Ensure styles support, never hinder, assistive technologies. Respect user preferences (motion, color scheme, contrast).
3. **Performance matters** — Minimize repaints, avoid layout thrashing, use efficient selectors.
4. **Readable over clever** — Future maintainers (including the author) should understand the code at a glance.
5. **Explicit over implicit** — Avoid magic numbers and unexplained values. Use custom properties for shared values.

## Workflow

1. **Check references first** — Before writing CSS, consult `references/patterns.md` for established patterns and snippets.
2. **Validate against specs** — When uncertain, reference MDN Web Docs or CSS specifications.
3. **Suggest alternatives** — Offer ideas beyond the skill's patterns when appropriate, but always aligned with the core principles above.

## Writing Guidelines

### Selectors

- Prefer class selectors over element or ID selectors for styling.
- Keep specificity low and predictable.
- Avoid deep nesting (aim for 2-3 levels maximum).

### Custom Properties

- Use `--` prefixed custom properties for colors, spacing, typography, and other repeated values.
- Define at `:root` or appropriate scope.
- Name descriptively: `--color-primary`, `--spacing-md`, `--font-size-body`.

### Logical Properties

- Always use logical properties (`margin-inline`, `padding-block`, `inset-inline-start`, `block-size`, etc.) instead of physical properties (`margin-left`, `padding-top`, `left`, `height`, etc.).
- Logical properties support internationalization and different writing modes automatically.
- Only fall back to physical properties where logical equivalents do not yet exist.

### Units

- Use `rem` for typography and spacing (respects user font-size preferences).
- Use `em` for component-relative sizing when appropriate.
- Use viewport units (`vw`, `vh`, `dvh`) thoughtfully, with fallbacks where needed.
- Avoid `px` for font sizes; acceptable for borders, shadows, and fine details.

### Colors

- Use modern space-separated syntax for all color functions (`rgb()`, `hsl()`, `oklch()`).
- Recommend `oklch()` for vibrant or wide-gamut colors.
- Use relative color syntax to derive hover states or transparent variants from existing variables.
- See `references/patterns.md` for syntax examples.

### Layout

- Use CSS Grid for two-dimensional layouts, or when vertical flow is needed without extra declarations.
- Use Flexbox for one-dimensional alignment, noting it defaults to `row` direction.
- Avoid floats for layout (legacy use only).

### Media Queries

- Use modern range syntax: `@media (width < 48rem)`, `@media (width >= 48rem)`.
- Prefer **Shared First** over mobile-first: define shared styles outside queries, scope viewport-specific styles with bounded queries.
- Keep breakpoints to a minimum — add more only when there's a clear need.
- See `references/patterns.md` for detailed examples.

### Accessibility

- Never use `display: none` or `visibility: hidden` to hide content that should remain accessible to screen readers. Use appropriate techniques from the references.
- Respect `prefers-reduced-motion`, `prefers-color-scheme`, and `prefers-contrast`.
- Ensure sufficient color contrast (WCAG AA minimum, AAA preferred).
- Maintain visible focus indicators — never remove `:focus` styles without replacement.

### Performance

- Avoid expensive properties in animations (prefer `transform` and `opacity`).
- Use `will-change` sparingly and only when needed.
- Minimize use of `*` selectors.
- Prefer `@layer` for managing cascade when working with larger codebases.

## References

Consult `references/patterns.md` for:

- Visually-hidden utility
- User preference queries (motion, color scheme, contrast)
- Modern color syntax and relative colors
- Shared First responsive patterns
- Any project-specific conventions

This file will grow as patterns are added. If a needed pattern doesn't exist, suggest one aligned with the core principles.