@brunosps00/dev-workflow 0.10.0 → 0.13.0

package/scaffold/skills/dw-testing-discipline/references/positive-patterns.md

@@ -0,0 +1,241 @@
+# Twelve positive patterns — pseudo-code that survives refactors
+
+Each pattern survives across testing frameworks (Jest, Vitest, Playwright, Cypress, pytest, JUnit). Pseudo-code in JavaScript-flavored examples; translate to your stack.
+
+## 1. Query by behavior and accessible role, not CSS selectors
+
+**Pattern:**
+
+```javascript
+// GOOD — describes what the user does
+const submitBtn = await page.getByRole('button', { name: 'Submit order' });
+await submitBtn.click();
+expect(await page.getByText(/order #\d+ confirmed/i)).toBeVisible();
+```
+
+**Anti-pattern:**
+
+```javascript
+// BAD — describes implementation
+await page.click('.btn-primary.submit-btn');
+expect(page.querySelector('.confirmation-toast')).toBeTruthy();
+```
+
+The good version survives a CSS refactor, a className rename, a Tailwind migration. The bad version breaks on each.
+
+## 2. Selector hierarchy
+
+When the role isn't enough, climb DOWN this ladder. Stop at the highest rung that disambiguates:
+
+1. **Role + name** — `getByRole('button', { name: 'Submit' })`
+2. **Label / form association** — `getByLabel('Email')`
+3. **Text content** — `getByText('Welcome back')`
+4. **Test-id** — `getByTestId('user-menu')` (escape hatch; do not start here)
+5. **Structural / CSS** — `querySelector('article:nth-child(3)')` (last resort; flags)
+
+Test-id is fine. Test-id as your default is a sign you're not designing accessible UI.
+
+## 3. Wait on observable conditions, never wall-clock
+
+**Pattern:**
+
+```javascript
+// GOOD — waits for the actual condition
+await expect(page.getByText('Order confirmed')).toBeVisible({ timeout: 5000 });
+```
+
+**Anti-pattern:**
+
+```javascript
+// BAD — wall-clock hopes
+await page.waitForTimeout(3000);
+expect(page.getByText('Order confirmed')).toBeVisible();
+```
+
+`waitForTimeout` is the #1 source of flakiness. It races with the network, with rendering, with the event loop. Always wait on what you actually need to see.
+
+## 4. Each test independent and order-free
+
+Every test runs cleanly when invoked in isolation (with `.only`) or in a randomized order.
+
+**Pattern:**
+
+```javascript
+beforeEach(async () => {
+  // Set up state THIS test needs
+  await db.users.create({ id: 'test-1', email: 'a@b.c' });
+});
+
+afterEach(async () => {
+  // Clean up — but if tests are independent, you may not need this
+  await db.users.deleteAll();
+});
+```
+
+**Anti-pattern:** Shared state in `beforeAll`. Tests passing only when run in suite order. Brittle CI runs.
+
+**Healthier:** prefer setup in `beforeEach` over teardown in `afterEach`. A test that sets up its own state from a clean baseline never wonders "did the previous test corrupt me?"
+
+## 5. One behavior per test, as many assertions as that behavior needs
+
+**Pattern:**
+
+```javascript
+test('successful login redirects to dashboard and shows user name', async () => {
+  await login('user@example.com', 'password');
+
+  expect(await page.url()).toContain('/dashboard');
+  expect(await page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  expect(await page.getByText('user@example.com')).toBeVisible();
+});
+```
+
+ONE behavior ("successful login leads to dashboard with user info"). THREE assertions because that behavior has three observable parts.
+
+**Anti-pattern:** Two unrelated behaviors crammed into one test ("login + then-also-test-search-works"). When it fails, you don't know which broke.
+
+## 6. Names read as specifications
+
+**Pattern:**
+
+```
+should reject invalid email when registering given no prior account
+should approve refund within SLA given amount under threshold
+should sync calendar events when user reconnects given offline edits
+```
+
+Form: `should <expected outcome> when <triggering condition> [given <starting state>]`
+
+**Anti-pattern:**
+
+```
+test_login
+test_email_1
+testHappy
+```
+
+These tell you nothing on failure. A spec-style name doubles as documentation when failure messages get noisy.
+
+## 7. Table-driven / parameterized when inputs vary
+
+**Pattern:**
+
+```javascript
+describe.each([
+  { input: '',           expected: 'required' },
+  { input: 'a',          expected: 'too short' },
+  { input: 'a'.repeat(100), expected: 'too long' },
+  { input: 'a@b.c',      expected: 'valid' },
+])('validateEmail($input)', ({ input, expected }) => {
+  test(`returns ${expected}`, () => {
+    expect(validateEmail(input)).toBe(expected);
+  });
+});
+```
+
+Easy to add cases; impossible to forget one input class.
+
+**Anti-pattern:** Five copy-pasted tests with one variable changed. Drift between them; one gets updated, others don't.
+
+## 8. Build test data via factories
+
+**Pattern:**
+
+```javascript
+const buildUser = (overrides = {}) => ({
+  id: 'u-' + Math.random().toString(36).slice(2),
+  email: 'test@example.com',
+  role: 'member',
+  createdAt: new Date(),
+  ...overrides,
+});
+
+test('admin can delete users', () => {
+  const admin = buildUser({ role: 'admin' });
+  const target = buildUser();
+  expect(canDelete(admin, target)).toBe(true);
+});
+```
+
+Tests focus on the FIELDS that matter to the behavior. Default everything else.
+
+**Anti-pattern:** Literal 50-field JSON blobs copy-pasted across tests. When the schema changes, you update them all — or worse, miss some.
+
+## 9. Mock at boundaries you don't control
+
+**Pattern:**
+
+| Boundary | Test treatment |
+|----------|---------------|
+| Your own modules | Real (don't mock) |
+| Your own DB (with testcontainers) | Real |
+| Third-party HTTP API | Mock at fetch/axios level |
+| Cloud SDK (AWS, GCP, Stripe) | Mock at SDK level OR sandbox account |
+| System clock | Mock when test depends on time |
+| RNG | Mock when test depends on randomness |
+| File system (when external) | Mock; in tests of fs logic, real temp dir |
+
+**Anti-pattern:** Mocking your own modules so the test is fast. You're now testing the mock setup, not the code.
+
+## 10. Real systems gate final merge
+
+**Pattern:**
+
+```
+unit (mocks ok)        → every commit, run locally and in CI
+integration (real DB)  → every PR, run in CI
+contract (boundary)    → every PR
+E2E (real services)    → before merge to main, run in CI on preview env
+```
+
+No merge to main without a real-system path going green. Mocks are speed, real is truth.
+
+**Anti-pattern:** 100% mocked test suite. "It all passes locally" → first user request fails because the mock didn't match the real API shape.
+
+## 11. Mutation score over coverage percentage
+
+**Pattern:**
+
+Set up mutation testing (Stryker for JS/TS, mutmut for Python, etc.) ONCE per project. Run weekly on critical modules.
+
+```bash
+npx stryker run
+# Output: 87 mutants, 78 killed, 9 survived → mutation score 89.6%
+```
+
+A surviving mutant means: this code path runs in tests, but the tests don't actually assert anything that breaks when the code changes. Investigate each.
+
+**Anti-pattern:** 95% line coverage with assertions like `expect(result).toBeTruthy()` — every line ran, but mutations all survive. The suite is decorative.
+
+## 12. Page Object Model is a tool, not a religion
+
+For small E2E suites (<20 tests, <5 pages), POM is over-engineering — direct queries are clearer.
+
+For large suites (>50 tests, many pages, multi-step flows), POM pays off:
+
+```javascript
+class CheckoutPage {
+  constructor(page) { this.page = page; }
+
+  async fillShipping(addr) { /* ... */ }
+  async selectPayment(method) { /* ... */ }
+  async place() { /* ... */ }
+  async waitForConfirmation() { return this.page.getByText(/confirmed/i); }
+}
+
+test('checkout end-to-end', async ({ page }) => {
+  const checkout = new CheckoutPage(page);
+  await checkout.fillShipping(defaultAddress);
+  await checkout.selectPayment('card');
+  await checkout.place();
+  await expect(checkout.waitForConfirmation()).toBeVisible();
+});
+```
+
+The page object hides the selector mess; tests read like specs. But for a 5-test suite, that wrapper is just noise.
+
+**Rule of thumb:** apply POM when you have ≥3 tests sharing the same page interactions. Otherwise inline.
+
+## Applying these patterns
+
+When `/dw-run-task` generates a new test, it must comply with these 12. `/dw-code-review` checks each diff hunk under test paths against these patterns and the anti-patterns in the sibling reference. Violations become findings.

package/scaffold/skills/{webapp-testing → dw-testing-discipline}/references/security-boundary.md

@@ -1,6 +1,6 @@
 # Security boundary — every browser is hostile
 
-> Adapted from [`addyosmani/agent-skills/browser-devtools`](https://github.com/addyosmani/agent-skills/tree/main/browser-devtools) (MIT). Adopts the security-boundary principle to inform how webapp-testing scenarios should validate trust boundaries.
+> Adapted from [`addyosmani/agent-skills/browser-devtools`](https://github.com/addyosmani/agent-skills/tree/main/browser-devtools) (MIT). Adopts the security-boundary principle to inform how browser-based testing scenarios validate trust boundaries.
 
 The browser is not a secure environment. Anything that runs there — JS, CSS, HTML, devtools — is under the user's control. When you write a webapp test, you're not just verifying functionality; you're often verifying that this assumption holds.
 

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.