css-coder

What this skill does

# 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.