@brunosps00/dev-workflow 1.0.6 → 1.1.0

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

@@ -92,6 +92,11 @@ Without this sentence, defaults take over: light mode, default contrasts, animat
 | Designing state coverage | `references/state-matrix.md` |
 | Interactive widget (button, form, modal, anything clickable) | `references/accessibility-floor.md` |
 | No design authority exists in the project | `references/curated-defaults.md` (palettes / fonts / scales) |
+| Choosing or reviewing a palette / dark mode | `references/color-oklch.md` (OKLCH, tinted neutrals, contrast) |
+| Fonts, sizing, hierarchy, line length | `references/type-scale.md` (modular scale, pairing, measure) |
+| Adding animation or transitions | `references/motion.md` (easing, duration, reduced-motion) |
+| Cross-device / breakpoints / touch | `references/responsive.md` (mobile-first, container queries) |
+| Any user-facing copy (labels, errors, empty states) | `references/ux-writing.md` |
 
 ## The 14 visual-slop patterns (full catalog in `references/visual-slop.md`)
 

package/scaffold/skills/dw-ui-discipline/references/color-oklch.md

@@ -0,0 +1,60 @@
+# Color & contrast — OKLCH, tinted neutrals, dark mode
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when building or reviewing a palette.
+
+## Work in OKLCH, not hex/HSL
+
+OKLCH (`oklch(L C H)`) is perceptually uniform: equal lightness steps *look* equally spaced, and changing
+hue does not shift perceived brightness (HSL's big flaw — HSL yellow at 50% L looks far lighter than HSL
+blue at 50% L). Modern browsers support `oklch()` natively.
+
+- **L** (lightness) 0–100% — drive your scale off this.
+- **C** (chroma) 0–~0.37 — saturation. Keep neutrals low (0.005–0.03), accents moderate (0.1–0.2).
+- **H** (hue) 0–360.
+
+## Tinted neutrals (the single highest-leverage move)
+
+Pure grays (`#777`, `oklch(50% 0 0)`) look dead. Tint every neutral slightly toward one hue — usually the
+brand hue or its complement — so the UI feels intentional.
+
+```css
+/* Cool, slightly blue-tinted neutral scale */
+--n-50:  oklch(98% 0.005 250);
+--n-100: oklch(96% 0.006 250);
+--n-300: oklch(87% 0.010 250);
+--n-500: oklch(62% 0.014 250);
+--n-700: oklch(42% 0.014 250);
+--n-900: oklch(22% 0.012 250);
+--n-950: oklch(14% 0.010 250);
+```
+
+Pure `#000` / `#fff` are anti-patterns (the detector flags `pure-black-white`). Use `oklch(14% 0.01 H)`
+for "black" surfaces and `oklch(98% 0.005 H)` for "white".
+
+## Building a scale
+
+Pick the hue + chroma, then step lightness on a roughly even curve (98 / 96 / 92 / 87 / 78 / 68 / 62 / 52 /
+42 / 32 / 22 / 14). Keep chroma roughly constant for neutrals; for an accent, let chroma peak in the mid
+lightness range (most vivid at 55–65% L) and fall off at the extremes.
+
+## Accent & semantic colors
+
+- One primary accent carries the brand. Avoid the training-data default blue `#3B82F6` — shift the hue or
+  darken it (`oklch(55% 0.18 255)` reads more deliberate).
+- Semantic set: success (green ~145H), warning (amber ~75H), danger (red ~25H), info (blue ~250H). Keep
+  their lightness consistent with each other so badges feel like a family.
+
+## Contrast (non-negotiable, see accessibility-floor.md)
+
+- Body text ≥ 4.5:1; large text (≥24px or ≥18.7px bold) and UI component boundaries ≥ 3:1.
+- Don't rely on hue alone to convey state — pair color with icon/text (color-blind users).
+- Test the *actual* foreground/background pair, not the token names.
+
+## Dark mode
+
+Dark mode is not "invert lightness". Re-tune:
+- Raise surface lightness in steps as elements come forward (`oklch(16%)` page → `18%` card → `22%`
+  popover) instead of borders everywhere.
+- Reduce accent chroma slightly in dark mode — vivid colors vibrate on dark backgrounds.
+- Keep body text around `oklch(90% 0.01 H)`, not pure white, to cut glare.

package/scaffold/skills/dw-ui-discipline/references/motion.md

@@ -0,0 +1,52 @@
+# Motion — easing, duration, stagger, reduced motion
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when adding animation or transitions.
+
+## Motion conveys state, not decoration
+
+Animate to explain a change: where did this come from, what just happened, where did it go. If a motion
+doesn't answer one of those, cut it. Decorative motion is a visual-slop pattern.
+
+## Easing — avoid bounce/elastic
+
+Real objects decelerate smoothly. Bounce and elastic easing feel dated and tacky (the detector flags
+`bounce-easing` / spring overshoot like `cubic-bezier(0.68,-0.55,0.27,1.55)`).
+
+- **Enter** (element appears): ease-out — fast start, soft landing. `cubic-bezier(0.16, 1, 0.3, 1)`
+  (ease-out-expo) or `ease-out`.
+- **Exit** (element leaves): ease-in — accelerate away. `cubic-bezier(0.4, 0, 1, 1)`.
+- **Move/resize on screen:** ease-in-out (standard) `cubic-bezier(0.4, 0, 0.2, 1)`.
+- Never linear for UI (only for continuous things like spinners/marquees).
+
+## Duration
+
+- Micro (hover, small fades): 100–150ms.
+- Standard (dropdowns, toggles, cards): 200–300ms.
+- Large (page/route, full-screen sheets): 300–500ms.
+- Over ~500ms feels sluggish; under ~80ms is imperceptible (just snap with no transition).
+
+## Stagger
+
+When several items enter together, stagger them 20–50ms apart so the eye follows the sequence — but cap
+total stagger (don't make the 12th list item wait 600ms). Stagger entrances, not exits.
+
+## What to animate (performance)
+
+Animate only `transform` and `opacity` — they run on the compositor and don't trigger layout/paint.
+Animating `width`, `height`, `top`, `left`, `margin` janks. Use `transform: translate/scale` instead.
+
+## `prefers-reduced-motion` (required)
+
+Honor it. Replace movement with an instant or opacity-only change.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+Don't remove *feedback* entirely — a state change still needs to be visible, just not kinetic.

package/scaffold/skills/dw-ui-discipline/references/responsive.md

@@ -0,0 +1,52 @@
+# Responsive — mobile-first, container queries, fluid space
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when a surface must work across devices.
+
+## Mobile-first
+
+Author the small-screen layout first, then add complexity at larger widths with `min-width` queries.
+Mobile-first CSS is additive (you enhance up), which produces simpler, smaller rules than desktop-first
+(`max-width`) overrides. `/dw-redesign-ui` requires every proposal to describe mobile AND desktop.
+
+## Breakpoints
+
+Base decisions on content, not device names. Reasonable defaults:
+`640` (sm) · `768` (md) · `1024` (lg) · `1280` (xl). Add a breakpoint when the layout *breaks*, not at a
+fixed phone width.
+
+## Container queries > viewport queries for components
+
+A card that appears in a sidebar and in a main column should respond to *its container*, not the viewport.
+Reusable components are far more robust with container queries:
+
+```css
+.card-wrap { container-type: inline-size; }
+@container (min-width: 28rem) {
+  .card { grid-template-columns: auto 1fr; }
+}
+```
+
+## Fluid space and type
+
+Use `clamp()` to interpolate spacing/type between breakpoints instead of hard jumps:
+
+```css
+--gap: clamp(1rem, 0.5rem + 2vw, 2.5rem);
+h1 { font-size: clamp(1.75rem, 1.2rem + 2.5vw, 3rem); }
+```
+
+Keep body text fixed (≥16px); fluid body harms readability.
+
+## Touch & input
+
+- Touch targets ≥ 24×24 CSS px (≥ 44×44 recommended on mobile). Spacing between targets matters as much
+  as size.
+- Don't hide primary actions behind hover — hover doesn't exist on touch. Provide a tap-visible path.
+- Respect safe-area insets on mobile (`env(safe-area-inset-*)`) for notches/home indicators.
+
+## Layout reflow
+
+State explicitly how elements reorganize between breakpoints: stack vs. side-by-side, what collapses into
+a menu, what hides (and whether hidden content is still reachable). "Hidden on mobile with no alternative"
+is a bug, not a layout decision.

package/scaffold/skills/dw-ui-discipline/references/type-scale.md

@@ -0,0 +1,48 @@
+# Typography — modular scale, pairing, measure
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when choosing fonts or fixing hierarchy.
+
+## Modular scale
+
+Pick a base size (16px body) and a ratio, then derive every step from it — don't hand-pick arbitrary
+sizes. Common ratios: 1.2 (minor third, dense UI), 1.25 (major third, balanced), 1.333 (perfect fourth,
+editorial/marketing).
+
+Example at base 16 / ratio 1.25:
+`12 · 14 · 16 · 20 · 25 · 31 · 39 · 49` (px). Map to roles: caption 12–14, body 16, h4 20, h3 25, h2 31,
+h1 39–49. **Soft hierarchy** (headings barely larger than body) is a visual-slop pattern — make the jump
+visible.
+
+## Fluid type
+
+For headings that should scale with viewport, use `clamp()` instead of breakpoint steps:
+
+```css
+h1 { font-size: clamp(1.75rem, 1.2rem + 2.5vw, 3rem); }
+```
+
+Keep body text fixed (≥16px) — fluid body harms readability and zoom.
+
+## Pairing
+
+- One typeface, multiple weights, is the safest path — pairs fail more often than they succeed.
+- If pairing: contrast roles clearly (e.g., a distinctive display face for headings + a neutral grotesque
+  for body). Don't pair two similar sans fonts.
+- Avoid the overused defaults that signal "no thought": Inter-everywhere, system-ui only, Montserrat
+  headings, Lobster/Pacifico for "personality". A deliberate grotesque or a good serif body reads better.
+
+## Weight, line-height, measure
+
+- **Weight:** body 400–450; don't set body below 400 (thin fonts fail in bright light — see the scene
+  question). Headings 600–700. Avoid 300 for anything users must read.
+- **Line-height:** body ~1.5–1.6; headings tighter ~1.1–1.25; the larger the text, the tighter.
+- **Measure (line length):** 45–75 characters for body. Cap with `max-width: 65ch`. Over ~80ch the eye
+  loses the next line — the detector flags long lines.
+
+## Letter-spacing & numerics
+
+- Tighten large headings slightly (`letter-spacing: -0.01em` to `-0.02em`); leave body alone.
+- All-caps labels need positive tracking (`0.05em`).
+- Use tabular figures (`font-variant-numeric: tabular-nums`) for tables, timers, prices so digits don't
+  jitter.

package/scaffold/skills/dw-ui-discipline/references/ux-writing.md

@@ -0,0 +1,52 @@
+# UX writing — labels, errors, empty states
+
+> Patterns adapted from [impeccable](https://github.com/pbakaus/impeccable) (Apache-2.0, derived from
+> Anthropic's frontend-design skill). Read when writing any user-facing copy in UI.
+
+## Principles
+
+- **Specific over generic.** Copy should be self-explanatory without a manual.
+- **Verb-led for actions.** Tell the user what happens.
+- **User's language, not the system's.** "Couldn't save your changes", not "Error 500".
+- **Front-load.** Put the meaningful word first ("Delete project", not "Are you sure you want to…").
+
+## Button & link labels
+
+Verb-less CTAs ("Get Started", "Learn More", "Submit", "OK", "Click Here") are a visual-slop pattern —
+they make the user guess the outcome. Name the action and, when useful, the object:
+
+- ✅ "Create invoice" · "Send reset link" · "Delete 3 files" · "Save and continue"
+- ❌ "Submit" · "OK" · "Continue" (alone) · "Get Started"
+
+Destructive actions say what they destroy and are visually distinct (not the same color as primary).
+
+## Error messages
+
+A good error answers: what happened, why, and what to do next.
+
+- ❌ "Invalid input." / "Something went wrong."
+- ✅ "That email is already registered. Try signing in instead."
+- ✅ "Card declined by your bank. Use a different card or contact your bank."
+
+Attach errors to the field that caused them, announce them to screen readers (see accessibility-floor.md),
+and never blame the user ("you entered it wrong" → "Enter a date in the future").
+
+## Empty states
+
+A silent "No items found." centered on a blank page is a visual-slop pattern. An empty state should:
+1. Explain why it's empty (new vs. filtered-out vs. error).
+2. Give the next action (a primary button to create the first item, or "Clear filters").
+3. Optionally set expectations ("Invoices you create will appear here.").
+
+Distinguish **first-run empty** (onboarding tone, call to create) from **no-results empty** (offer to
+adjust the search/filter) from **error empty** (explain + retry).
+
+## Microcopy details
+
+- Loading: say what's loading ("Loading invoices…") rather than a bare spinner for long ops.
+- Success: confirm the outcome and, if relevant, where the result went — don't stack a toast for every
+  trivial event (toast-everywhere is slop).
+- Numbers & dates: format for the locale; use relative time ("2 hours ago") where recency matters, exact
+  timestamps where precision matters.
+- Sentence case for UI labels and buttons reads friendlier than Title Case in most product UIs; be
+  consistent either way.

package/scaffold/skills/security-review/SKILL.md

@@ -37,6 +37,25 @@ Before flagging any issue, you MUST research the codebase to understand:
 | **MEDIUM** | Vulnerable pattern, input source unclear | **Note** as "Needs verification" |
 | **LOW** | Theoretical, best practice, defense-in-depth | **Do not report** |
 
+## Automated scanners + false-positive validation (fp-check)
+
+The Security Gate (`/dw-secure-audit`) pairs this human-style review with deterministic tools:
+- **SAST** — Semgrep, diff-focused on the generated code. See `references/sast.md`.
+- **Secrets** — gitleaks (dedicated) + Trivy. See `references/secrets.md`. Any secret = REJECTED.
+
+Tool findings are **not** auto-trusted to block. Apply the SAME reachability discipline to them before a
+finding blocks the gate (the **fp-check** step):
+
+1. **Reachable?** Trace the flagged sink back — is it on a path attacker-controlled input can reach?
+2. **Controlled?** Is the input actually attacker-controlled, or a constant / server-controlled value
+   (see the table below) / framework-mitigated?
+3. **Verdict:** If both hold → keep as blocking at its tier. If provably unreachable or
+   trusted-input → **downgrade to advisory** and write the one-line justification in the findings file.
+   Never silently drop a tool finding — log every downgrade so the pattern stays auditable.
+
+Exception: **secrets do not get an fp-check downgrade** — a real-looking credential is removed and
+rotated, not argued away (only committed `.gitleaks.toml` allowlist entries for known fixtures apply).
+
 ## Do Not Flag
 
 ### General Rules

package/scaffold/skills/security-review/references/sast.md

@@ -0,0 +1,67 @@
+# SAST with Semgrep — semantic analysis of generated code
+
+Static review by reading is necessary but misses patterns at scale. Semgrep adds deterministic,
+semantic SAST. The Security Gate (`/dw-secure-audit`) runs it; this reference is the HOW.
+
+> Tool: [Semgrep](https://semgrep.dev) (LGPL-2.1, OSS engine). Wrapped natively — no rule content is
+> copied. Rulesets are pulled by name from the Semgrep registry (cached after first run).
+
+## Default invocation (diff-focused — the generated code)
+
+The gate's primary job is the code just written, so scope Semgrep to the diff against the PR base:
+
+```bash
+semgrep scan \
+  --config p/security-audit --config p/owasp-top-ten --config p/secrets \
+  --baseline-commit "$(git merge-base HEAD origin/main)" \
+  --json --output .dw/secure-audit/semgrep.json
+```
+
+- `--baseline-commit` makes Semgrep report only findings **introduced** by the diff — no noise from
+  pre-existing code. Use the merge-base with the target branch (fall back to the branch point).
+- Pinned rulesets keep runs reproducible: `p/security-audit`, `p/owasp-top-ten`, `p/secrets`. Add
+  language packs as detected (`p/javascript`, `p/python`, `p/csharp`, `p/rust`, `p/golang`).
+
+### Full-tree mode (`--full`)
+
+For a periodic deep pass (not per-PR), drop `--baseline-commit` to scan the whole tree. Slower; use
+when auditing an inherited codebase or on a schedule.
+
+## Severity mapping → gate tiers
+
+Semgrep severities map to the Security Gate tiers (Rigoroso):
+
+| Semgrep `severity` | Gate tier | Block? |
+|--------------------|-----------|--------|
+| `ERROR` | HIGH (or CRITICAL if CWE is RCE/authn-bypass/SQLi) | **YES** |
+| `WARNING` | MEDIUM | Advisory |
+| `INFO` | LOW | Advisory |
+
+Read each finding's `extra.metadata` (`cwe`, `owasp`, `confidence`) to escalate ERROR→CRITICAL when the
+CWE is in the high-impact set (CWE-89 SQLi, CWE-78 OS command, CWE-94 code injection, CWE-502
+deserialization, CWE-287 authn, CWE-918 SSRF).
+
+## Parsing the JSON
+
+Findings live under `results[]`: `check_id`, `path`, `start.line`, `extra.severity`,
+`extra.message`, `extra.metadata`. Write a human report to `.dw/secure-audit/sast-findings.md`
+grouped by tier, each finding citing `path:line` and the rule id. Errors under `errors[]` (e.g.,
+ruleset fetch failure offline) → note "SAST partial" in the summary, do not crash.
+
+## False-positive validation (before blocking)
+
+A blocking SAST finding must survive reachability validation (see the fp-check discipline in
+`SKILL.md`): confirm the flagged sink is reached by attacker-controlled input. If the pattern is
+provably unreachable or the input is fully trusted/constant, **downgrade to advisory** and record the
+one-line justification in `sast-findings.md`. Never silently drop — always log the downgrade.
+
+## Tool absent
+
+If `semgrep` is not installed, the gate skips this layer, records "SAST: skipped (semgrep not
+installed)" in `audit-summary.md`, and points to `npx @brunosps00/dev-workflow install-deps`. The
+gate does not fail merely because a scanner is missing — but the missing coverage is visible.
+
+## CodeQL (optional, advisory)
+
+CodeQL is deeper but requires a build + database and is too slow for a per-PR gate. Treat it as an
+opt-in periodic scan, not part of the default Security Gate path.

package/scaffold/skills/security-review/references/secrets.md

@@ -0,0 +1,46 @@
+# Secret scanning with gitleaks
+
+Hardcoded secrets are the highest-severity, lowest-tolerance finding: **any hit blocks the Security
+Gate, with no ADR exception**. Trivy catches some; gitleaks is the dedicated, diff-aware scanner.
+
+> Tool: [gitleaks](https://github.com/gitleaks/gitleaks) (MIT, OSS). Wrapped natively.
+
+## Diff-focused invocation (the generated code)
+
+Scan what the diff introduced, so a pre-existing (already-rotated/allowlisted) secret doesn't block a
+new PR, while any newly added secret does:
+
+```bash
+# Uncommitted/staged changes (pre-commit style):
+gitleaks protect --staged --redact --report-format json --report-path .dw/secure-audit/gitleaks.json
+
+# Commits on this branch vs base (PR style):
+gitleaks detect --redact --log-opts "$(git merge-base HEAD origin/main)..HEAD" \
+  --report-format json --report-path .dw/secure-audit/gitleaks.json
+```
+
+`--redact` keeps the actual secret value out of the report/logs. A full-tree scan
+(`gitleaks detect` with no `--log-opts`) is the periodic deep pass.
+
+## Verdict
+
+- **≥1 finding → REJECTED.** No exception, no ADR. A leaked credential is rotated, not justified.
+- Write `.dw/secure-audit/secret-findings.md`: rule id, `file:line`, commit, and the redacted match.
+  The remediation is always: remove from code + history, rotate the credential, move to a secret store.
+
+## Allowlisting (test fixtures / examples only)
+
+Legitimate non-secrets (obvious placeholders, test fixtures) are allowlisted in a committed
+`.gitleaks.toml` (regexes/paths), reviewed like code — not by skipping the scan. A real-looking
+secret in a fixture should still be a fake (e.g., `AKIAIOSFODNN7EXAMPLE`), never a live one.
+
+## Relationship to Trivy
+
+Trivy's secret scan stays (defense in depth, covers files gitleaks' git-history mode may miss).
+gitleaks is authoritative for the diff. Dedupe by `file:line` in the report so one leak isn't
+double-counted across tools.
+
+## Tool absent
+
+If `gitleaks` is not installed, the gate falls back to Trivy secrets only and records "dedicated
+secret scan: skipped (gitleaks not installed)" in the summary, pointing to `install-deps`.

package/scaffold/en/templates/functional-doc/playwright.spec.ts.tpl

@@ -1,19 +0,0 @@
-import { test, expect } from "@playwright/test";
-
-const BASE_URL = process.env.BASE_URL ?? "{{baseUrl}}";
-
-test("{{testTitle}}", async ({ page }) => {
-  const evidence = [] as string[];
-
-  await test.step("Open target route", async () => {
-    await page.goto(`${BASE_URL}{{routePath}}`);
-    await expect(page).toHaveURL(new RegExp("{{routeRegex}}"));
-    evidence.push("navigation");
-  });
-
-{{testSteps}}
-
-  await test.step("Record final context", async () => {
-    expect(evidence.length).toBeGreaterThan(0);
-  });
-});

package/scaffold/pt-br/templates/functional-doc/playwright.spec.ts.tpl

@@ -1,19 +0,0 @@
-import { test, expect } from "@playwright/test";
-
-const BASE_URL = process.env.BASE_URL ?? "{{baseUrl}}";
-
-test("{{testTitle}}", async ({ page }) => {
-  const evidence = [] as string[];
-
-  await test.step("Abrir rota alvo", async () => {
-    await page.goto(`${BASE_URL}{{routePath}}`);
-    await expect(page).toHaveURL(new RegExp("{{routeRegex}}"));
-    evidence.push("navigation");
-  });
-
-{{testSteps}}
-
-  await test.step("Registrar contexto final", async () => {
-    expect(evidence.length).toBeGreaterThan(0);
-  });
-});