code-ai-installer 2.5.0 → 4.0.0

package/domains/development/locales/en/.agents/skills/styling-css-stack/SKILL.md

@@ -1,558 +1,195 @@
----
-name: styling-css-stack
-description: CSS practices — custom properties (design tokens), naming (BEM / CSS Modules), responsive, transitions, z-index scale, dark mode, a11y (focus-visible, prefers-reduced-motion, forced-colors). DO/DON'T examples. Activate when writing or reviewing CSS/Less/Sass, when refactoring styles, or for questions "how to properly style X".
----
-
-# Skill: Styling (CSS Stack) Beast Practices
-
-Specific DO/DON'T patterns for CSS — from design tokens to a11y.
-
-**Sections:**
-1. [Design Tokens (CSS Custom Properties)](#1-design-tokens)
-2. [Naming: BEM vs CSS Modules](#2-naming)
-3. [Responsive and Media Queries](#3-responsive)
-4. [Dark Mode](#4-dark-mode)
-5. [Transitions and Animations](#5-transitions-and-animations)
-6. [Z-index Scale](#6-z-index-scale)
-7. [Accessibility (a11y)](#7-accessibility)
-8. [File Organization](#8-file-organization)
-9. [Anti-patterns](#9-anti-patterns)
-
----
-
-## 1. Design Tokens
-
-### ✅ DO: CSS custom properties as a single source of truth
-
-```css
-/* tokens.css — global design tokens */
-:root {
-  /* Colors */
-  --color-primary: hsl(220, 90%, 56%);
-  --color-primary-hover: hsl(220, 90%, 46%);
-  --color-secondary: hsl(280, 70%, 50%);
-  --color-surface: hsl(0, 0%, 100%);
-  --color-surface-elevated: hsl(0, 0%, 98%);
-  --color-text: hsl(220, 20%, 12%);
-  --color-text-muted: hsl(220, 10%, 50%);
-  --color-border: hsl(220, 15%, 88%);
-  --color-error: hsl(0, 80%, 55%);
-  --color-success: hsl(145, 70%, 40%);
-
-  /* Spacing (4px grid) */
-  --space-1: 0.25rem;   /* 4px */
-  --space-2: 0.5rem;    /* 8px */
-  --space-3: 0.75rem;   /* 12px */
-  --space-4: 1rem;      /* 16px */
-  --space-6: 1.5rem;    /* 24px */
-  --space-8: 2rem;      /* 32px */
-  --space-12: 3rem;     /* 48px */
-
-  /* Typography */
-  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
-  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
-  --text-xs: 0.75rem;    /* 12px */
-  --text-sm: 0.875rem;   /* 14px */
-  --text-base: 1rem;     /* 16px */
-  --text-lg: 1.125rem;   /* 18px */
-  --text-xl: 1.25rem;    /* 20px */
-  --text-2xl: 1.5rem;    /* 24px */
-  --line-height-tight: 1.25;
-  --line-height-normal: 1.5;
-
-  /* Borders */
-  --radius-sm: 4px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
-  --radius-full: 9999px;
-
-  /* Shadows */
-  --shadow-sm: 0 1px 2px hsl(0 0% 0% / 0.05);
-  --shadow-md: 0 4px 6px hsl(0 0% 0% / 0.07);
-  --shadow-lg: 0 10px 25px hsl(0 0% 0% / 0.1);
-
-  /* Transitions */
-  --duration-fast: 150ms;
-  --duration-normal: 250ms;
-  --duration-slow: 400ms;
-  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
-  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
-}
-```
-
-### ❌ DON'T: hardwood values in components
-
-```css
-/* ❌ Magic values — impossible to maintain, no dark mode */
-.card {
-  padding: 17px;
-  color: #333;
-  background: white;
-  border-radius: 6px;
-  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
-}
-
-/* ✅ Tokens — uniform, supports theme */
-.card {
-  padding: var(--space-4);
-  color: var(--color-text);
-  background: var(--color-surface);
-  border-radius: var(--radius-md);
-  box-shadow: var(--shadow-md);
-}
-```
-
----
-
-## 2. Naming
-
-### ✅ DO: BEM for vanilla CSS
-
-```css
-/* Block */
-.product-card { }
-
-/* Element */
-.product-card__title { }
-.product-card__price { }
-.product-card__actions { }
-
-/* Modifier */
-.product-card--active { }
-.product-card--sold-out { }
-
-/* State (JS-driven) */
-.product-card.is-selected { }
-.product-card.is-loading { }
-```
-
-```html
-<div class="product-card product-card--active is-selected">
-  <h3 class="product-card__title">Premium Widget</h3>
-  <span class="product-card__price">$29.99</span>
-  <div class="product-card__actions">
-    <button>Add to Cart</button>
-  </div>
-</div>
-```
-
-### ✅ DO: CSS Modules for React (scoped by default)
-
-```css
-/* ProductCard.module.css */
-.card {
-  padding: var(--space-4);
-  border: 1px solid var(--color-border);
-  border-radius: var(--radius-md);
-}
-
-.card.active {
-  border-color: var(--color-primary);
-}
-
-.title {
-  font-size: var(--text-lg);
-  font-weight: 600;
-}
-
-.price {
-  font-family: var(--font-mono);
-  color: var(--color-text-muted);
-}
-```
-
-```jsx
-import styles from './ProductCard.module.css';
-import clsx from 'clsx';
-
-function ProductCard({ product }) {
-  return (
-    <div className={clsx(styles.card, product.active && styles.active)}>
-      <h3 className={styles.title}>{product.name}</h3>
-      <span className={styles.price}>${product.price}</span>
-    </div>
-  );
-}
-```
-
-### When to use what
-
-| Approach | When ✅ | When ❌ |
-|--------|---------|---------|
-| **BEM** | Vanilla CSS/HTML, widgets, legacy | Large SPAs (no scoping) |
-| **CSS Modules** | React/Vue SPA, component architecture | Static sites |
-| **Tailwind** | Rapid prototyping, utility-first teams | Wix widgets, complex animations |
-
----
-
-## 3. Responsive
-
-### ✅ DO: mobile-first with min-width breakpoints
-
-```css
-/* ✅ Mobile-first: base styles for mobile, expand upwards */
-.grid {
-  display: grid;
-  grid-template-columns: 1fr;
-  gap: var(--space-4);
-}
-
-@media (min-width: 640px) {  /* sm */
-  .grid {
-    grid-template-columns: repeat(2, 1fr);
-  }
-}
-
-@media (min-width: 1024px) { /* lg */
-  .grid {
-    grid-template-columns: repeat(3, 1fr);
-  }
-}
-```
-
-### ✅ DO: breakpoint tokens
-
-```css
-/* Breakpoints (not custom properties — media queries do not support var()) */
-/* sm:  640px  — phone landscape / small tablet */
-/* md:  768px  — tablet portrait */
-/* lg:  1024px — tablet landscape / small desktop */
-/* xl:  1280px — desktop */
-/* 2xl: 1536px — wide desktop */
-```
-
-### ✅ DO: container queries for components
-
-```css
-/* ✅ Component adapts to CONTAINER size, not screen */
-.card-container {
-  container-type: inline-size;
-}
-
-.card {
-  display: flex;
-  flex-direction: column;
-}
-
-@container (min-width: 400px) {
-  .card {
-    flex-direction: row; /* Horizontal layout when enough space */
-  }
-}
-```
-
-### ❌ DON'T: fixed width for layout
-
-```css
-/* ❌ Breaks on non-standard screens */
-.container {
-  width: 1200px;
-}
-
-/* ✅ Responsive width */
-.container {
-  width: 100%;
-  max-width: 1200px;
-  margin-inline: auto;
-  padding-inline: var(--space-4);
-}
-```
-
----
-
-## 4. Dark Mode
-
-### ✅ DO: dark mode via overriding tokens
-
-```css
-/* ✅ Automatic dark mode via media query */
-@media (prefers-color-scheme: dark) {
-  :root {
-    --color-surface: hsl(220, 20%, 10%);
-    --color-surface-elevated: hsl(220, 20%, 14%);
-    --color-text: hsl(220, 15%, 90%);
-    --color-text-muted: hsl(220, 10%, 60%);
-    --color-border: hsl(220, 15%, 25%);
-    --color-primary: hsl(220, 90%, 65%);
-    --shadow-md: 0 4px 6px hsl(0 0% 0% / 0.3);
-  }
-}
-
-/* ✅ Or via class toggle (JS-controlled) */
-[data-theme="dark"] {
-  --color-surface: hsl(220, 20%, 10%);
-  --color-text: hsl(220, 15%, 90%);
-  /* ... */
-}
-```
-
-### ❌ DON'T: invert colors or hardcode
-
-```css
-/* ❌ filter — breaks images, icons, video */
-.dark-mode {
-  filter: invert(1);
-}
-
-/* ❌ Duplicating styles instead of overriding tokens */
-.dark-mode .card {
-  background: #1a1a2e;
-  color: #eee;
-  border-color: #333;
-}
-```
-
----
-
-## 5. Transitions and Animations
-
-### ✅ DO: transition on specific properties
-
-```css
-/* ✅ Explicit properties — performant, predictable */
-.button {
-  transition:
-    background-color var(--duration-fast) var(--ease-out),
-    transform var(--duration-fast) var(--ease-out),
-    box-shadow var(--duration-fast) var(--ease-out);
-}
-
-.button:hover {
-  background-color: var(--color-primary-hover);
-  transform: translateY(-1px);
-  box-shadow: var(--shadow-md);
-}
-
-.button:active {
-  transform: translateY(0);
-  box-shadow: var(--shadow-sm);
-}
-
-/* ❌ transition: all — animates everything, including width/height (layout thrashing) */
-.button {
-  transition: all 0.3s ease;  /* ❌ */
-}
-```
-
-### ✅ DO: animate only transform and opacity (GPU-accelerated)
-
-```css
-/* ✅ GPU: transform + opacity — do not trigger layout/paint */
-.fade-in {
-  animation: fadeIn var(--duration-normal) var(--ease-out);
-}
-
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-    transform: translateY(8px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-/* ❌ Animating width/height/top/left — triggers layout recalculation */
-@keyframes bad {
-  from { width: 0; height: 0; }
-  to   { width: 100px; height: 100px; }
-}
-```
-
----
-
-## 6. Z-index Scale
-
-### ✅ DO: predictable fixed scale
-
-```css
-:root {
-  --z-base: 0;
-  --z-dropdown: 100;
-  --z-sticky: 200;
-  --z-overlay: 300;
-  --z-modal: 400;
-  --z-popover: 500;
-  --z-toast: 600;
-  --z-tooltip: 700;
-  --z-max: 9999;      /* only for critical overlays (fullscreen loader) */
-}
-
-/* Usage */
-.dropdown { z-index: var(--z-dropdown); }
-.modal-backdrop { z-index: var(--z-overlay); }
-.modal { z-index: var(--z-modal); }
-.toast { z-index: var(--z-toast); }
-```
-
-### ❌ DON'T: z-index wars
-
-```css
-/* ❌ z-index escalation — impossible to maintain */
-.header   { z-index: 100; }
-.dropdown { z-index: 999; }
-.modal    { z-index: 9999; }
-.toast    { z-index: 99999; }   /* will need 999999 someday */
-```
-
----
-
-## 7. Accessibility
-
-### ✅ DO: focus-visible, not focus
-
-```css
-/* ✅ focus-visible — shows focus only during keyboard navigation */
-.button:focus-visible {
-  outline: 2px solid var(--color-primary);
-  outline-offset: 2px;
-}
-
-/* ❌ focus — shows outline on mouse click (annoys users) */
-.button:focus {
-  outline: 2px solid blue;
-}
-
-/* ❌ Removing outline completely — breaks keyboard navigation */
-*:focus {
-  outline: none;  /* ❌ NEVER */
-}
-```
-
-### ✅ DO: prefers-reduced-motion
-
-```css
-/* ✅ Disable animations when user requests */
-@media (prefers-reduced-motion: reduce) {
-  *,
-  *::before,
-  *::after {
-    animation-duration: 0.01ms !important;
-    animation-iteration-count: 1 !important;
-    transition-duration: 0.01ms !important;
-    scroll-behavior: auto !important;
-  }
-}
-```
-
-### ✅ DO: forced-colors for Windows High Contrast
-
-```css
-/* ✅ Support for Windows High Contrast Mode */
-@media (forced-colors: active) {
-  .button {
-    border: 1px solid ButtonText;         /* System color */
-  }
-  .button:hover {
-    background: Highlight;
-    color: HighlightText;
-  }
-  .icon {
-    forced-color-adjust: auto;            /* Allow system to color */
-  }
-}
-```
-
-### ✅ DO: sufficient contrast
-
-```css
-/* Minimum WCAG 2.1 AA requirements */
-/* Normal text: contrast ≥ 4.5:1 */
-/* Large text (≥ 18px bold or ≥ 24px): contrast ≥ 3:1 */
-/* Interactive elements: contrast ≥ 3:1 */
-
-/* ✅ Check via: https://webaim.org/resources/contrastchecker/ */
-```
-
----
-
-## 8. File Organization
-
-```
-src/
-├── styles/
-│   ├── tokens.css          # Design tokens (custom properties)
-│   ├── reset.css           # CSS reset / normalize
-│   ├── base.css            # Typography, base elements
-│   ├── utilities.css       # Utility classes (.sr-only, .truncate)
-│   └── z-index.css         # Z-index scale
-├── components/
-│   ├── Button/
-│   │   ├── Button.jsx
-│   │   └── Button.module.css
-│   └── ProductCard/
-│       ├── ProductCard.jsx
-│       └── ProductCard.module.css
-└── index.css               # Imports: tokens → reset → base → utilities
-```
-
-### index.css (entry point)
-
-```css
-/* Order is important! */
-@import './styles/tokens.css';
-@import './styles/reset.css';
-@import './styles/base.css';
-@import './styles/utilities.css';
-@import './styles/z-index.css';
-```
-
-### Utility classes
-
-```css
-/* utilities.css — reusable utilities */
-
-/* Screen reader only */
-.sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px;
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
-}
-
-/* Truncate text */
-.truncate {
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-/* Line clamp */
-.line-clamp-2 {
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  -webkit-box-orient: vertical;
-  overflow: hidden;
-}
-```
-
----
-
-## 9. Anti-patterns
-
-| ❌ Anti-pattern | ✅ Solution |
-|----------------|-----------|
-| `!important` for layout | Increase specificity via selectors |
-| `transition: all` | List specific properties |
-| `outline: none` without replacement | `focus-visible` + visible outline |
-| Hardcoded colors (`#333`, `red`) | CSS custom properties |
-| `px` for font-size | `rem` (accessibility: respects user settings) |
-| Global selectors (`div { }`) | Scoped: CSS Modules, BEM, or layer |
-| Nesting > 3 levels (Sass) | Flat selectors, BEM |
-| `@import` in runtime CSS | Bundler (Vite) or `@layer` |
-| Animation of `width`/`height` | `transform: scale()` or `clip-path` |
-| Magic numbers (`margin: 17px`) | Spacing tokens (`var(--space-4)`) |
-
----
-
-## See also
-- `$design-systems` — design systems integration (shadcn/ui, WDS)
-- `$a11y-baseline` — full a11y checklist
-- `$tailwind-beast-practices` — Tailwind-specific patterns
-- `$design-parity-review` — comparing implementation with design
+---
+name: styling-css-stack
+description: 'CSS practices — custom properties (design tokens), naming (BEM / CSS Modules), responsive, transitions, z-index scale, dark mode, a11y (focus-visible, prefers-reduced-motion, forced-colors). DO/DON''T examples. Activate when writing or reviewing CSS/Less/Sass, when refactoring styles, or for questions "how to properly style X".'
+type: discretionary
+domain: development
+owners:
+  - senior_full_stack
+gates:
+  - DEV
+tech:
+  - css
+topic:
+  - general
+triggers:
+  - CSS practices
+  - design tokens
+  - BEM CSS Modules
+  - z-index scale
+  - dark mode CSS
+  - focus-visible
+  - prefers-reduced-motion
+related:
+  - styling-css-stack-reference
+  - design-systems
+  - a11y-baseline
+  - a11y-baseline-reference
+  - tailwind-beast-practices
+  - tailwind-beast-practices-reference
+  - design-parity-review
+  - react-beast-practices
+  - react-beast-practices-reference
+  - typescript-beast-practices
+  - dev-reference-snippets
+budget_lines: 300
+schema_version: 1
+---
+
+
+# Skill: Styling (CSS Stack) Beast Practices
+
+Workflow skill: when to use what in CSS — from design tokens to a11y. Ready-to-copy code templates live in `styling-css-stack-reference`.
+
+**Sections:**
+1. [Design Tokens](#1-design-tokens) — single source of truth
+2. [Naming](#2-naming) — BEM vs CSS Modules vs Tailwind
+3. [Responsive](#3-responsive) — mobile-first + container queries
+4. [Dark Mode](#4-dark-mode) — override tokens
+5. [Transitions/Animations](#5-transitions) — specific properties, GPU
+6. [Z-index Scale](#6-z-index) — fixed scale
+7. [Accessibility](#7-accessibility) — focus-visible + reduced-motion + forced-colors
+8. [File Organization](#8-file-organization)
+9. [Anti-patterns](#9-anti-patterns)
+
+---
+
+## 1. Design Tokens
+
+**Rule:** CSS custom properties are the **single source of truth** for colors / spacing / typography / borders / shadows / transitions / breakpoints.
+
+- Stored in `:root` (global) or scoped to a component.
+- Grouped by type: `--color-*`, `--space-*`, `--text-*`, `--radius-*`, `--shadow-*`, `--duration-*`, `--ease-*`.
+- Spacing on a 4px grid (`--space-1: 0.25rem`).
+- Colors in HSL (easier hover/active variants).
+- **❌ Don't hardcode** values in components (`padding: 17px`, `color: #333`).
+
+➡ Template: `styling-css-stack-reference` § 1 (full `tokens.css`).
+
+---
+
+## 2. Naming
+
+**Choosing the approach:**
+
+| Approach | When ✅ | When ❌ |
+|--------|---------|---------|
+| **BEM** | Vanilla CSS/HTML, widgets, legacy | Large SPAs (no scoping) |
+| **CSS Modules** | React/Vue SPA, component architecture | Static sites |
+| **Tailwind** | Rapid prototyping, utility-first teams | Wix widgets, complex animations |
+
+**BEM**: `block`, `block__element`, `block--modifier`, `block.is-state` (JS-driven). Never `block__element__sub-element` (>2 levels).
+
+**CSS Modules** for React: `import styles from './X.module.css'` + `clsx(styles.a, condition && styles.b)`.
+
+➡ Templates: `styling-css-stack-reference` § 2.
+
+---
+
+## 3. Responsive
+
+- **Mobile-first**: base styles for mobile, expand via `@media (min-width: ...)`.
+- **Breakpoints** in comments (media queries don't support `var()`):
+  `sm: 640px`, `md: 768px`, `lg: 1024px`, `xl: 1280px`, `2xl: 1536px`.
+- **Container queries** for components reacting to container size (not screen): `container-type: inline-size` + `@container (min-width: ...)`.
+- **❌ Fixed width** for layout — breaks on non-standard screens. ✅ `width: 100%; max-width: 1200px; margin-inline: auto`.
+
+➡ Templates: `styling-css-stack-reference` § 3.
+
+---
+
+## 4. Dark Mode
+
+**Rule:** dark mode = **override tokens**, not duplicate styles.
+
+- Automatic: `@media (prefers-color-scheme: dark) { :root { --color-*: ... } }`.
+- Manual (JS-controlled): `[data-theme="dark"] { --color-*: ... }`.
+- **❌ `filter: invert(1)`** — breaks images, icons, video.
+- **❌ Duplicating styles** in components instead of overriding tokens.
+
+➡ Templates: `styling-css-stack-reference` § 4.
+
+---
+
+## 5. Transitions
+
+- **`transition` on specific properties**, not `transition: all` (layout thrashing when animating `width`/`height`).
+- **Animate only `transform` and `opacity`** — GPU-accelerated, no layout/paint.
+- Use `--duration-*` and `--ease-*` tokens for consistency.
+- `@keyframes` with `from { opacity: 0; transform: translateY(8px); } to { ... }`.
+- **❌ Animating `width`/`height`/`top`/`left`** — layout recalc on every frame.
+
+➡ Templates: `styling-css-stack-reference` § 5.
+
+---
+
+## 6. Z-index
+
+**Rule:** fixed scale in tokens, no ad-hoc values.
+
+```
+--z-base: 0; --z-dropdown: 100; --z-sticky: 200; --z-overlay: 300;
+--z-modal: 400; --z-popover: 500; --z-toast: 600; --z-tooltip: 700;
+--z-max: 9999;   /* only for fullscreen critical loaders */
+```
+
+**❌ Z-index wars**: `999 → 9999 → 99999` — impossible to maintain.
+
+➡ Template: `styling-css-stack-reference` § 6.
+
+---
+
+## 7. Accessibility
+
+**Mandatory minimum:**
+- **`:focus-visible`** (not `:focus`) — focus only during keyboard navigation.
+- **❌ `outline: none`** without replacement — breaks keyboard navigation. NEVER.
+- **`@media (prefers-reduced-motion: reduce)`** — globally disable animations (`animation-duration: 0.01ms !important`).
+- **`@media (forced-colors: active)`** — Windows High Contrast support (use system colors `ButtonText`, `Highlight`, `HighlightText`).
+- **WCAG 2.1 AA contrast:**
+  - Normal text: ≥ **4.5:1**
+  - Large text (≥18px bold / ≥24px): ≥ **3:1**
+  - Interactive elements: ≥ **3:1**
+  - Check: https://webaim.org/resources/contrastchecker/
+
+➡ Templates: `styling-css-stack-reference` § 7.
+
+---
+
+## 8. File Organization
+
+Structure `src/styles/`: `tokens.css → reset.css → base.css → utilities.css → z-index.css`. Import order matters — tokens first. Component styles live next to components (`Button.module.css` alongside `Button.jsx`).
+
+Utilities: `.sr-only` (screen reader only), `.truncate`, `.line-clamp-N`.
+
+➡ Templates: `styling-css-stack-reference` § 8.
+
+---
+
+## 9. Anti-patterns
+
+| ❌ Anti-pattern | ✅ Solution |
+|----------------|-----------|
+| `!important` for layout | Increase specificity via selectors |
+| `transition: all` | List specific properties |
+| `outline: none` without replacement | `focus-visible` + visible outline |
+| Hardcoded colors (`#333`, `red`) | CSS custom properties |
+| `px` for font-size | `rem` (accessibility: respects user settings) |
+| Global selectors (`div { }`) | Scoped: CSS Modules, BEM, or layer |
+| Nesting > 3 levels (Sass) | Flat selectors, BEM |
+| `@import` in runtime CSS | Bundler (Vite) or `@layer` |
+| Animation of `width`/`height` | `transform: scale()` or `clip-path` |
+| Magic numbers (`margin: 17px`) | Spacing tokens (`var(--space-4)`) |
+
+---
+
+## See also
+
+- `styling-css-stack-reference` → ready-to-copy code templates for all 9 sections
+- `design-systems` → design systems integration (shadcn/ui, WDS)
+- `a11y-baseline` → full a11y checklist
+- `a11y-baseline-reference` → ready-to-copy a11y snippets
+- `tailwind-beast-practices` → Tailwind-specific patterns
+- `design-parity-review` → comparing implementation with design
+- `react-beast-practices` → CSS-in-JS, styled-components patterns
+- `typescript-beast-practices` → typing styled-components / CSS Modules
+- `dev-reference-snippets` → basic CSS snippets