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.