| name | css-modules |
| description | CSS Modules styling, design tokens, variants, responsive layout, and theming. Use when editing styles or visual presentation; use motion for animation. 日本語の依頼例:「スタイルを整えて」「デザイン調整」「ダークモード」「レスポンシブ対応」。 |
CSS Modules
Files & naming
- One module per component, colocated:
UserCard.tsx + UserCard.module.css.
- Class names: camelCase (
primaryButton, not primary-button) — enables styles.primaryButton without bracket access.
- Name by role, not appearance:
.errorMessage not .redText. The module scope already namespaces — no BEM prefixes needed.
- Import as
styles: import styles from './UserCard.module.css'.
Design tokens — single source of truth
- All colors, spacing, radii, shadows, typography, z-index live as CSS custom properties in
src/styles/tokens.css, defined on :root.
- Component modules consume tokens only — the semantic/component tier where tiers exist (see
design-system), never primitives like --blue-600. A raw hex/px value for a themable property in a component module is a bug.
- Spacing on a scale (
--space-1 … --space-8); z-index from a fixed ladder (--z-dropdown, --z-modal, --z-toast) — never z-index: 9999.
- Theming (dark mode) by redefining tokens — components never branch on theme themselves. Default to
prefers-color-scheme; add [data-theme] only when a user-facing toggle is required, set pre-paint by a tiny inline script (CSP nonce applies — see frontend-security) to avoid a wrong-theme flash.
Variants & state
- Variants via data attributes, not class string concatenation:
<button className={styles.button} data-variant={variant} data-size={size}>
.button[data-variant='danger'] { background: var(--color-danger); }
- Boolean UI state the same way (
data-open, aria-expanded) — style off ARIA attributes when one exists: .menu[aria-expanded='true'].
clsx has exactly one job here: merging a consumer-passed className prop with the base class. Enumerated variants and boolean state always go through data attributes, never conditional class lists; a component wanting 3+ conditional classes should be restructured into variants.
Layout & responsive
- Mobile-first: base styles, then
@media (min-width: …) upward. Breakpoints documented once in tokens.css comments (custom properties don't work in media queries — keep the canonical list there).
- Prefer modern layout primitives: flex
gap / grid over margin hacks; aspect-ratio; container queries for components that adapt to their container, media queries only for page-level layout.
- Aspect-preserving media: give the box a defined
aspect-ratio and use object-fit: contain/cover. Never size an image with max-width/max-height inside a flex item — the main-axis shrink sizes width independently of the height cap and stretches the image (a mixed-aspect-ratio thumbnail grid is where this bites).
- Logical properties (
margin-inline, padding-block, inset-inline-start) over physical ones — free RTL support (the foundation the i18n skill builds on).
- No fixed heights on text containers; min-height if needed.
Globals — the only allowed global CSS
Default baseline: src/styles/tokens.css, reset.css, and globals.css (base element styles: body, headings, links). Additional global files need a documented cross-cutting purpose; feature/component styles stay local. No :global() in component modules except to target third-party library DOM you don't control — with a comment saying which library.
Astro components may use a single-file scoped <style> block instead of *.module.css — see astro. Pick one approach per component; the token/naming/variant rules here still apply.
Motion
- Prefer
transform and opacity for movement and fades. Avoid layout-triggering width/height/top/left in continuous motion; when another property is required, keep the affected area small and verify rendering performance instead of assuming every non-transform animation is invalid.
- Every significant animation (anything beyond a subtle hover/focus transition) respects
@media (prefers-reduced-motion: reduce) — same threshold as the a11y skill.
- Durations/easings as tokens (
--duration-fast, --ease-out).
- These are the invariants only — escalation (keyframes / WAAPI / animation libraries), View Transitions, entrance/exit animations, and scroll effects live in the
motion skill.
Enforcement
The token/var() and class-naming rules above are machine-enforced by Stylelint — see tooling for the exact rules and the shipped templates/stylelint.config.mjs.
