@brunosps00/dev-workflow 0.11.0 → 0.13.0

package/scaffold/skills/dw-ui-discipline/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: dw-ui-discipline
+description: Use BEFORE any UI work — enforces a hard-gate (brand authorities or curated defaults, surface job, state matrix, scene sentence), 14 anti-slop patterns, and WCAG 2.2 AA floor so UI ships with discipline instead of training-data defaults.
+---
+
+# UI Discipline
+
+> **Inspired by** [`pedronauck/skills/ui-craft`](https://github.com/pedronauck/skills/tree/main/skills/mine/ui-craft) (MIT). Hard-gate protocol, anti-slop catalog, state matrix enforcement, and accessibility-floor patterns adapted from Pedro Nauck's work; specifics rewritten for dev-workflow's redesign and review loops.
+
+The fastest path through UI work is the disciplined one. "It's just a small change" is the most common slop excuse. This skill blocks that excuse at four checkpoints before any design decision lands.
+
+## When this skill applies
+
+- Any work invoked from `/dw-redesign-ui`, `/dw-create-techspec` (UI sections), `/dw-functional-doc`, or `/dw-code-review` when the diff touches UI.
+- Adding new screens, components, or surfaces.
+- Reviewing visual changes in a PR.
+- Auditing accessibility on existing surfaces.
+
+If you're tempted to skip the gate "because it's just a tweak" — that's the trigger. Run the gate.
+
+## The hard-gate (4 mandatory items before any UI work)
+
+Before proposing colors, layouts, components, or any visual decision, complete all four:
+
+### 1. Brand authorities OR curated defaults
+
+Locate the project's design source of truth:
+- `.dw/rules/{frontend-module}.md` design system section
+- `DESIGN.md`, `BRAND.md`, or design tokens config (Tailwind, CSS vars, theme file)
+- Component library docs (shadcn/ui, MUI, Chakra, etc.)
+
+If **none exist**, do NOT invent. Read `references/curated-defaults.md` — pick from the 10 neutral palettes + 10 font pairings shipped there. Mark the choice as a finding in the techspec ("no design authority found; used curated default <name>; recommend establishing one").
+
+### 2. Surface job sentence
+
+Write one sentence: "This surface helps the user <do what> so that <outcome>." Vague language ("show data", "manage settings") fails — be specific ("filter overdue invoices so they can chase late payers in <30s").
+
+If you can't write the sentence, the requirements are unclear. Stop and clarify before proceeding.
+
+### 3. Complete state matrix
+
+Enumerate all states the surface can be in. See `references/state-matrix.md` for the full list:
+- `default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success`
+- Plus any domain-specific states (read/unread, online/offline, etc.)
+
+Missing a state at design time = production bug later. The "we'll add empty state later" trap is real.
+
+### 4. Scene sentence
+
+One sentence describing the physical context: **who** is using this, **where** (mobile bus, office desktop, on-call laptop), **what light** (dark room, bright outdoor), **what mood** (rushed, exploring, troubleshooting).
+
+This forcing function prevents category-level defaults from becoming the answer. A "dashboard for an on-call engineer at 3am in a dark room troubleshooting a fire" produces different decisions than "dashboard for a manager during business hours."
+
+## Required Reading Router
+
+| Context | Read |
+|---------|------|
+| Any UI work | `references/hard-gate.md` (full protocol with examples) |
+| Interactive widgets (buttons, forms, modals) | `references/accessibility-floor.md` (WCAG 2.2 AA non-negotiable) |
+| Reviewing a UI diff | `references/anti-slop.md` (14 anti-patterns + 17 anti-defaults) |
+| Designing state coverage | `references/state-matrix.md` (full enumeration + checklist) |
+| No design authority exists in project | `references/curated-defaults.md` (10 palettes + 10 fonts) |
+
+## Anti-slop summary (full list in references/anti-slop.md)
+
+The 14 patterns this skill catches:
+
+1. **Visual sameness** — every section looks like every other section.
+2. **Weak hierarchy** — nothing draws the eye to what matters first.
+3. **Fake interactivity** — hover states that don't change anything functional.
+4. **Emoji spam** — emojis as decoration where icons or restraint would serve.
+5. **Gradient crutch** — gradients used to mask weak composition.
+6. **Glass everything** — frosted glass on every panel.
+7. **Centered all the things** — center-aligned text when left-aligned reads better.
+8. **AI gray washing** — neutral grays everywhere, no character.
+9. **Generic CTAs** — "Get Started", "Learn More", "Click Here" with no specificity.
+10. **Stock illustration** — generic figure-with-laptop hero art.
+11. **Drop shadow soup** — shadows on cards on shadows on borders.
+12. **Loading spinner default** — spinner as the only loading state for everything.
+13. **Empty state void** — empty list with no guidance on what to do next.
+14. **Notification-soup tray** — every UI event becomes a toast.
+
+Plus 17 anti-defaults (specific values to NEVER use without intent — `#3B82F6` blue, `rounded-lg` everywhere, etc.) in `references/anti-slop.md`.
+
+## Accessibility floor — non-negotiable
+
+Before any interactive widget ships:
+
+- [ ] Color contrast meets WCAG 2.2 AA (4.5:1 for body text, 3:1 for large text and UI components).
+- [ ] Focus-visible state exists and is distinct from hover.
+- [ ] Keyboard navigation works (tab order, escape closes modals, enter submits forms).
+- [ ] ARIA labels for icon-only buttons.
+- [ ] Form errors are announced to screen readers.
+- [ ] No keyboard traps.
+
+Full verification recipes in `references/accessibility-floor.md`. This is a hard gate — `/dw-code-review` fails verdict if any interactive widget ships without these.
+
+## When the gate bends
+
+Real-world UI can't always be perfect:
+
+- **Bug fix in existing UI** — gate applies only to the area touched, not the whole surface.
+- **Pure copy change** — gate is just "scene sentence still holds?" — quick check.
+- **Spike / exploration** — gate skipped if the spike is explicitly marked throwaway; production code must run the gate.
+
+In all bend cases, document the bend in the PR description (one line). "I skipped the state matrix because this is a one-line copy fix" is fine. "I skipped because I was in a hurry" is not.
+
+## Integration with dev-workflow commands
+
+- `/dw-redesign-ui` runs the gate end-to-end. Steps 4 (propose design) and 7 (validate WCAG) consult this skill.
+- `/dw-create-techspec` UI sections must list which authorities were consulted (brand vs curated default) and reference the state matrix.
+- `/dw-code-review` checks the diff against `references/anti-slop.md` and the accessibility floor.
+- `/dw-functional-doc` documents the scene sentence in the overview.
+
+## Anti-patterns this skill prevents
+
+- "Just use the same hero as the marketing page" — without verifying the surface job differs.
+- "We'll add empty/error states later" — they're never added later.
+- "It looks fine on my desktop" — without checking mobile + keyboard + screen reader.
+- Designing in isolation from `.dw/rules/` documented patterns.
+- Inventing color values when the design system has tokens that fit.
+- Shipping interactive widgets without WCAG 2.2 AA verification.
+
+## Why this skill exists
+
+The previous bundled skill (`ui-ux-pro-max`) provided 161 color palettes and 57 font pairings — a CATALOG of taste. It had no gates, no anti-patterns, no enforcement. Agents loaded KB of palette data and still produced slop because there was no DISCIPLINE.
+
+This skill inverts that trade-off: 10 curated defaults (enough for 90% of cases) + a strong gate + an anti-slop catalog. Less context bytes, more leverage.

package/scaffold/skills/dw-ui-discipline/references/accessibility-floor.md

@@ -0,0 +1,225 @@
+# Accessibility floor — WCAG 2.2 AA is the minimum, not the goal
+
+This reference is read in full before any interactive widget ships. Skipping any item below is a hard-block in `/dw-code-review`.
+
+## The non-negotiables
+
+### 1. Color contrast
+
+| Element | Minimum ratio (WCAG 2.2 AA) |
+|---------|----------------------------|
+| Body text (under 18pt or under 14pt bold) | 4.5:1 |
+| Large text (18pt+ or 14pt+ bold) | 3:1 |
+| UI components (button borders, icons, focus rings) | 3:1 |
+| Decorative graphics | No requirement |
+
+**Verification:**
+- Use `axe DevTools` browser extension OR `playwright/test` with `@axe-core/playwright`.
+- Manual quick check: `chrome://flags` → Enable "Simulate Vision Deficiencies" + try "Achromatopsia" (no colors). If buttons still legible, contrast is doing its job.
+
+**Common violation:** Light gray text on white. `#9CA3AF` on white = 2.85:1. FAIL.
+
+### 2. Focus-visible state
+
+Every interactive element must have a distinct focus-visible state when keyboard-focused.
+
+**Rules:**
+- `:focus-visible` MUST be distinct from `:hover` — keyboard users need an affordance.
+- Default browser outline is acceptable; replacing with `outline: none` requires alternative (border, ring, shadow).
+- Focus must be visible against any background the element can appear on (dark + light themes).
+
+**Tailwind pattern:**
+```css
+focus-visible:outline-none
+focus-visible:ring-2
+focus-visible:ring-offset-2
+focus-visible:ring-blue-500
+```
+
+**Verification:**
+- Tab through the entire surface with keyboard. Every interactive element must light up visibly.
+- If you can't tell what's focused, the contrast on the focus ring is too low.
+
+### 3. Keyboard navigation
+
+| Capability | Requirement |
+|------------|-------------|
+| Tab order | Logical (left-to-right, top-to-bottom in LTR) |
+| Modals | Tab cycles WITHIN modal; Escape closes; focus returns to trigger |
+| Dropdowns / select | Arrow keys navigate options; Enter selects; Escape closes |
+| Forms | Enter submits; Tab moves to next field; Shift+Tab moves back |
+| Custom widgets | Match the ARIA Authoring Practices Guide patterns |
+
+**Verification:**
+- Unplug mouse. Complete the primary user flow with keyboard only.
+- If you got stuck or couldn't reach an element, keyboard nav is broken.
+
+### 4. ARIA labels for icon-only interactives
+
+Icon-only buttons (e.g., a trash can icon as a delete button) need `aria-label` describing the action.
+
+```html
+<!-- BAD -->
+<button><TrashIcon /></button>
+
+<!-- GOOD -->
+<button aria-label="Delete invoice"><TrashIcon /></button>
+```
+
+Same applies to:
+- Icon-only links
+- Icon-only toggles
+- Tooltips (the trigger needs aria-describedby pointing to the tooltip)
+- Decorative images (`aria-hidden="true"` if purely decorative; `alt=""` not enough)
+
+### 5. Form errors announced to screen readers
+
+When a form field errors:
+
+```html
+<label for="email">Email</label>
+<input
+  id="email"
+  type="email"
+  aria-describedby="email-error"
+  aria-invalid="true"
+/>
+<span id="email-error" role="alert">
+  Email is required
+</span>
+```
+
+Key points:
+- `aria-invalid="true"` on the input.
+- `aria-describedby` links the input to the error message.
+- `role="alert"` on the error message announces it.
+
+**Anti-pattern:** Red border + tooltip on hover. Screen reader users get nothing.
+
+### 6. No keyboard traps
+
+A "keyboard trap" is when focus enters a widget and can't leave with the keyboard. Most common cause: custom-built modals or carousels.
+
+**Rule:** Every modal, drawer, or overlay must let Escape close it and return focus to the trigger element.
+
+**Verification:**
+- Open the widget with keyboard. Press Escape. Does focus return to where it was?
+- Tab through the widget. After last element, does Tab cycle to first (within widget) instead of leaving the page?
+
+### 7. Touch target size (mobile)
+
+Minimum 24x24 CSS pixels (WCAG 2.2 AA minimum). Recommended 44x44 (Apple HIG / Android touch target).
+
+**Pattern:** Even when the visual icon is 16x16, give the button 44x44 hit area:
+
+```css
+button {
+  width: 24px; height: 24px;  /* WCAG 2.2 AA minimum */
+  /* Or */
+  width: 44px; height: 44px;  /* Recommended */
+  padding: 14px;  /* Visual icon inside */
+}
+```
+
+### 8. Heading hierarchy
+
+H1 → H2 → H3 etc. Don't skip levels. Don't use heading tags for visual sizing — use semantic level + CSS for size.
+
+```html
+<!-- BAD -->
+<h2>Section A</h2>
+<h4>Subsection</h4>  <!-- skipped h3 -->
+
+<!-- GOOD -->
+<h2>Section A</h2>
+<h3>Subsection</h3>
+```
+
+Screen readers navigate by heading; broken hierarchy disorients.
+
+### 9. Language attribute
+
+Root `<html lang="en">` (or correct ISO code) for primary language. Sections in other language need `lang` attribute too.
+
+```html
+<html lang="en">
+  <p>Welcome.</p>
+  <p lang="pt-br">Bem-vindo.</p>
+</html>
+```
+
+Screen readers switch pronunciation based on this.
+
+### 10. Reduced motion respect
+
+Honor `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+Or in Tailwind:
+```html
+<div className="transition-all motion-reduce:transition-none">
+```
+
+Vestibular disorders trigger on parallax, large slide-ins, infinite scroll animations.
+
+## Verification recipes
+
+### Automated (CI)
+
+```ts
+// playwright + axe-core
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('homepage a11y', async ({ page }) => {
+  await page.goto('/');
+  const results = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag22a', 'wcag22aa'])
+    .analyze();
+  expect(results.violations).toEqual([]);
+});
+```
+
+Run on every PR. Block merge on violations.
+
+### Manual (PR review)
+
+1. Open the changed page.
+2. Tab through with keyboard only. Verify focus visible at every stop.
+3. Run axe DevTools, fix violations.
+4. Toggle prefers-reduced-motion in DevTools rendering panel. Verify animations stop.
+5. Test with screen reader (VoiceOver on Mac, NVDA on Windows) on at least one critical flow.
+
+### Spot checks
+
+Color contrast: chrome devtools → element inspector → "Contrast" indicator next to text color. Click for actual ratio.
+
+Touch target: Inspect element → check computed width/height. If < 24, flag.
+
+## When the floor bends
+
+- **Iframes you don't control** — your wrapper still has to be accessible, the iframe is best-effort.
+- **Third-party widgets** (analytics dashboards, payment SDKs) — wrap with ARIA landmarks; report violations upstream.
+- **Legacy code being patched** — bring touched components up to floor; leave untouched ones for separate accessibility-debt work.
+
+In all bend cases, file a tracking issue. Don't pretend the floor was met.
+
+## Common AI-generated UI violations
+
+LLM-produced UI commonly fails on:
+- `<div onClick>` instead of `<button>` (not keyboard-accessible).
+- Icon-only buttons with no aria-label.
+- `text-gray-400` on white (contrast 2.8:1 — fail).
+- `outline: none` with no replacement focus state.
+- Modals that trap focus only on success path, not on error.
+- Auto-playing carousels with no pause control.
+
+`/dw-code-review` runs axe-style checks on the diff for these.

package/scaffold/skills/dw-ui-discipline/references/anti-slop.md

@@ -0,0 +1,162 @@
+# Anti-slop catalog — 14 patterns + 17 anti-defaults
+
+Every pattern below is a category of slop that LLMs produce when ungrounded. Detection happens in `/dw-code-review` (UI diffs) and design proposals from `/dw-redesign-ui`.
+
+## The 14 patterns
+
+### 1. Visual sameness
+
+**What it looks like:** Every section of the page uses the same card style, same padding, same text size, same emphasis weight. The eye finds no anchor.
+
+**Why it happens:** LLM defaults to "consistent = good," missing that hierarchy needs deliberate variation.
+
+**Fix:** Establish one primary section per scroll-height. Use size, weight, color saturation, or whitespace differential to anchor the eye. Everything else recedes.
+
+**Example violation:** Dashboard with 6 identical-looking metric cards. **Fix:** One hero metric (largest, brightest, top), 3 supporting metrics, 2 minor metrics in a different visual treatment.
+
+### 2. Weak hierarchy
+
+**What it looks like:** Headings barely larger than body. Important CTAs same color as secondary. The user can't tell what to look at first.
+
+**Why it happens:** Defaults to "elegant restraint" without ensuring guidance still works.
+
+**Fix:** Verify hierarchy by squinting at the design (literally) — what jumps out? If nothing jumps out, hierarchy is failing. Increase contrast in size, weight, or color for the primary element by at least 30%.
+
+### 3. Fake interactivity
+
+**What it looks like:** Hover states that change opacity but the click does nothing meaningful. Buttons that look interactive but don't have a job. Cards with subtle hover but no on-click handler.
+
+**Why it happens:** LLM applies hover styles to anything that looks card-shaped.
+
+**Fix:** Hover state ONLY on elements that have an on-click. If it can't be clicked, don't suggest it can. Use cursor: default explicitly on non-interactive shapes.
+
+### 4. Emoji spam
+
+**What it looks like:** 🎯 Goals · 🚀 Launch · ✨ Features · 📊 Analytics · 🔥 Trending — emojis as decoration in headers, CTAs, and section labels where they add no information.
+
+**Why it happens:** LLM training data has tons of "emoji in headers = engaging" patterns.
+
+**Fix:** Use icons (lucide, heroicons, tabler) for semantic meaning; reserve emojis for genuinely emotive contexts (celebrations, errors that need empathy). If you can remove the emoji and the meaning survives, remove it.
+
+### 5. Gradient crutch
+
+**What it looks like:** Hero with diagonal purple-to-pink gradient. Buttons with subtle gradient. Card backgrounds with mesh gradients. Every empty space gets a gradient.
+
+**Why it happens:** Stable Diffusion / midjourney aesthetics leaked into UI; gradients hide weak composition.
+
+**Fix:** A gradient must earn its place — usually for hero zones with poetic copy, never for utility surfaces. Solid colors + good hierarchy beat gradients 9 times out of 10.
+
+### 6. Glass everything
+
+**What it looks like:** Frosted-glass effect on modals, cards, dropdowns, side panels — anywhere a surface can be layered.
+
+**Why it happens:** Apple's macOS aesthetic. Looks "premium" without effort.
+
+**Fix:** Glass only when there's meaningful content visible behind the surface (a hero image, a busy dashboard). Glass on top of plain backgrounds adds blur for no reason.
+
+### 7. Centered all the things
+
+**What it looks like:** Body paragraphs center-aligned. Headlines centered. Forms with labels centered above inputs. Every text block reads center.
+
+**Why it happens:** Marketing-page training data biases toward center-aligned.
+
+**Fix:** Center-align for hero headlines and small CTA labels only. Body text and forms read better left-aligned (in LTR scripts). Tabular data reads in columns, not centered.
+
+### 8. AI gray washing
+
+**What it looks like:** Neutral gray palette everywhere. `slate-50`, `gray-100`, `zinc-200` for backgrounds, borders, text, accents. Nothing has color personality.
+
+**Why it happens:** "Neutral = safe" default, plus shadcn/ui's neutral start.
+
+**Fix:** Establish ONE accent color from the curated defaults or brand. Use it intentionally — primary CTAs, active states, the one place the user looks first. Gray is the canvas, not the painting.
+
+### 9. Generic CTAs
+
+**What it looks like:** "Get Started" · "Learn More" · "Click Here" · "Submit" · "OK" buttons.
+
+**Why it happens:** Default LLM verb library.
+
+**Fix:** Use the verb the user is actually doing. "Approve refund" not "Submit". "Start free trial" not "Get Started". "Schedule a call" not "Contact us". Generic verbs are tells.
+
+### 10. Stock illustration
+
+**What it looks like:** Figure-with-laptop hero art. Diverse-team-around-table illustration. Abstract floating shapes.
+
+**Why it happens:** "Illustration = friendly" default. Cheap to produce, generic to consume.
+
+**Fix:** Either use product screenshots (real screens, real data — sanitized) or skip illustration entirely. A clean hero with strong typography beats a generic illustration every time.
+
+### 11. Drop shadow soup
+
+**What it looks like:** Cards with shadow. Buttons with shadow. Inputs with shadow. Tooltips with shadow on shadows. Borders AND shadows AND gradients on one element.
+
+**Why it happens:** Material Design leftover; depth as decoration.
+
+**Fix:** Pick ONE depth mechanism per layer. If cards have shadow, buttons inside should not. If you're using elevation systematically (Material 3), enforce the elevation hierarchy.
+
+### 12. Loading spinner default
+
+**What it looks like:** Spinner overlay for every async operation, regardless of duration or context.
+
+**Why it happens:** Default fallback in every UI library.
+
+**Fix:**
+- <300ms: don't show anything. Spinner appearing then disappearing instantly is flicker.
+- 300ms-2s: skeleton loader (shape of incoming content).
+- 2s-10s: spinner + status text ("Loading orders...").
+- 10s+: progress bar or step indicator + cancel button.
+
+### 13. Empty state void
+
+**What it looks like:** "No items found." Centered. Nothing else. User has no idea what to do.
+
+**Why it happens:** Empty state treated as edge case, not a real screen.
+
+**Fix:** Every empty state must answer: WHY is it empty (no data yet vs filter excluded everything vs error). WHAT should the user do next (CTA: "Create your first invoice"). Show example/illustration if it helps onboard.
+
+### 14. Notification-soup tray
+
+**What it looks like:** Every UI event becomes a toast. Save successful → toast. Validation error → toast. Network slow → toast. Now there are 5 stacked toasts and the user can't read any.
+
+**Why it happens:** Toast is the default feedback mechanism in component libraries.
+
+**Fix:** Reserve toasts for actions that need confirmation AWAY from the originating surface (background save completed, deletion can be undone). Inline feedback for form validation. Modal/banner for blocking errors. NEVER stack >2 toasts at once.
+
+## The 17 anti-defaults
+
+Specific values that signal "no thought was put in." Avoid unless you can articulate WHY you picked exactly this:
+
+| Anti-default | Why it's a tell |
+|--------------|-----------------|
+| `#3B82F6` (Tailwind blue-500) | The internet's default blue |
+| `rounded-lg` everywhere | Universal default; no surface character |
+| `shadow-md` on every card | Universal default; no depth hierarchy |
+| `bg-gradient-to-br from-purple-500 to-pink-500` | The "AI startup landing page" gradient |
+| Inter font as the only choice | Default font of 60% of new SaaS |
+| `font-bold` for everything emphasized | Bold is a tool, not the only tool |
+| Lucide icons exclusively | One icon family is fine; signature is none |
+| Stock "happy team" hero illustration | Generic placeholder energy |
+| "Get Started" / "Learn More" CTA copy | Verb-less; says nothing |
+| 4px / 8px / 12px / 16px spacing exclusively | The default 4-step scale; no rhythm |
+| `border-gray-200` for every divider | Visual whisper; no intentionality |
+| Sans-serif headlines + sans-serif body | No typographic contrast |
+| Center-aligned everything | See pattern #7 |
+| Animated CSS confetti on success | Cheesy; never matches the brand |
+| `bg-white dark:bg-gray-900` only | No real dark-mode design pass |
+| Single-column form on a wide screen | Vertical scroll where horizontal fits |
+| Modal-for-everything | Most modals should be inline editing |
+
+## How to use this catalog
+
+In `/dw-redesign-ui` step 4 (propose) — before presenting design directions, self-check against this list. Flag any pattern you're consciously using AND say why (sometimes it's the right call; "gradient crutch" can be intentional for a marketing hero).
+
+In `/dw-code-review` UI section — grep the diff for the anti-defaults table values and the patterns. Each hit becomes a finding with `dw-review-rigor` severity:
+- Pattern violations on a NEW surface → `medium` severity.
+- Pattern violations spreading EXISTING surface's slop further → `low` severity (consistency wins).
+- Pattern violations on a redesign that was supposed to fix slop → `high` severity (regression).
+
+## When the rules bend
+
+- **Marketing pages** can use gradients and emojis with more freedom — different surface job.
+- **Brand-mandated** anti-defaults override this list (if the brand IS `#3B82F6`, use it).
+- **Component libraries** like shadcn ship with neutral defaults — the discipline is to ADD character on top, not remove their neutrality.