frontend-ui

Files (1)

• SKILL.md

SKILL.md (first lines)

# Frontend UI — Checklist for Web Interface Tasks

Use when task modifies HTML, CSS, templates, or visual components. Catches recurring UI bugs missed by HTTP/syntax checks.

---

## 1. CSS Dark/Light Mode Specificity

**Rule:** Light mode = default. `.dark` class = override. Never use `:not(.dark)` selectors.

### Anti-Pattern (BREAKS dark mode)

```css
.dark .component { background: #0f172a; }
:not(.dark) .component { background: #ffffff; }  /* ← matches <body>, <section>, <div> */
```

`:not(.dark)` matches any ancestor without the class, including `<body>` / `<section>` / `<div>`. Since these are also ancestors of `.component`, the selector ALWAYS matches, overriding `.dark` rules due to cascade order. Result: light colors leak into dark mode.

### Correct Pattern

```css
.component { background: #ffffff; }            /* default = light */
.dark .component { background: #0f172a; }      /* override = dark */
```

Checklist:
- [ ] Tailwind config sets `darkMode: 'class'`
- [ ] `<html class="dark">` initial state from localStorage
- [ ] No `:not(.dark)` selectors in any CSS file
- [ ] Light styles have no class prefix (they ARE the default)
- [ ] Dark overrides use `.dark .component` pattern

---

## 2. Visual Verification

HTTP 200 + valid HTML is insufficient for UI tasks. A page can render with broken visual state and still return 200.

Required checks before marking UI task complete:

- [ ] Screenshot of dark mode (all sections visible, no light leaks)
- [ ] Screenshot of light mode (all sections visible, no dark leaks)
- [ ] Mobile viewport (320px, 375px) — no horizontal scroll, readable text
- [ ] Tablet viewport (768px) — layout adapts
- [ ] Desktop viewport (1280px+) — max-width containers work
- [ ] Theme toggle switches instantly (no flash of wrong theme)
- [ ] For animated drawers/dialogs, wait for the intended settled state and
  verify the relevant content bounds fit the viewport before capturing evidence.
  Visibility alone can pass mid-transition; document scroll-width checks can
  miss fixed overlays clipped outside the window. Do not replace this with an
  arbitrary sleep or silently disable the transition being tested. Inspect the
  resulting screenshots before accepting them; intended scrolling content need
  not fit vertically, but required controls must remain reachable.

If unable to capture screenshots, explicitly ask the user to verify visually before closing.

---

## 3. i18n UI Parity (if applicable)

For bilingual/multilingual sites:

- [ ] All supported language files have identical keys (diff check)
- [ ] Language switcher works from every page
- [ ] URL prefix `/en/`, `/ru/` respected on all internal links (`lang_url()` helper)
- [ ] Cookie persists language choice across requests
- [ ] Date formatting respects current language
- [ ] Text length difference (RU ~20-30% longer than EN) doesn't break layouts
- [ ] Hardcoded strings audit: `grep` in templates for English/Russian leaks on wrong-language pages

---

## 4. Mobile Responsiveness

- [ ] Navigation collapses to hamburger at lg breakpoint
- [ ] Tap targets ≥ 44×44px
- [ ] No content overflows viewport width
- [ ] Images scale down (`max-width: 100%`)
- [ ] Text doesn't get smaller than 14px base

---

## 5. Accessibility Baseline

- [ ] Color contrast ≥ WCAG AA for body text
- [ ] `<button>` has accessible label (`aria-label` if icon-only)
- [ ] Theme toggle has `aria-label` that reflects current state
- [ ] Skip-to-content link (for long navigation)
- [ ] Focus states visible (don't remove outline without replacement)
- [ ] `prefers-reduced-motion` respected for animations

---

## 6. Performance Hygiene

- [ ] No unbounded CSS (`* { animation: ... }`)
- [ ] Images have `loading="lazy"` where below fold
- [ ] Fonts loaded with `font-display: swap`
- [ ] No blocking scripts in `<head>` (use `defer` or `async`)

---

## 7. SEO & Social Preview

- [ ] Unique `<title>` per page
- [ ] `<meta description>` present and relevant
- [ ] Open Graph tags: `og:title`, `og:description`, `og:image`, `og:url`, `og:type`
- [ ] Twitter Card meta
- [ ] `og:image` file actually exists (not just referenced)
- [ ] Canonical URL
- [ ] `hreflang` in sitemap.xml for multilingual sites

---

## When to Apply

- Any `/dr-do` that modifies `.html`, `.php` templates, `.css`, `.vue`, `.tsx` files touching UI
- Any task with type "Website Development" or "Frontend"

From Arcanada-one/datarim, MIT.

More from Arcanada-one/datarim