@brunosps00/dev-workflow 0.11.0 → 0.15.0

package/scaffold/skills/dw-ui-discipline/references/hard-gate.md

@@ -0,0 +1,162 @@
+# The grounding protocol — full version
+
+Four questions before any UI work touches code. Each has a concrete output. Don't proceed past one without finishing its output.
+
+## Why the grounding matters
+
+Training-data defaults dominate ungrounded UI generation. An LLM proposing a "dashboard" without context will produce:
+- `#3B82F6` blue + `rounded-lg` because those values appeared 10M+ times in training.
+- Glass morphism, gradients, center-aligned blocks because those screenshots dominate web aesthetics.
+- Happy-path layouts only, because most training screenshots show success states.
+
+The four questions pull the design AWAY from the training-data center of mass and TOWARD this project, this surface, this user, this moment.
+
+## Question 1 — Where do design decisions come from?
+
+**Goal:** know the source of truth for visual values. Documented authority, or curated default — never invented.
+
+### How to find it
+
+Search the project in this order:
+
+1. **`.dw/rules/*.md`** — look for sections titled "Design", "Patterns to Follow", "Naming Conventions". The codebase intelligence skill writes these.
+2. **Root-level docs** — `DESIGN.md`, `BRAND.md`, `BRANDING.md`, `STYLE_GUIDE.md`.
+3. **Token configuration** — `tailwind.config.{ts,js}` `theme` block; CSS variables in `globals.css`, `theme.css`, `tokens.css`.
+4. **Component library config** — shadcn `components.json`, MUI/Chakra theme exports.
+5. **Storybook stories** — implicit canonical components.
+
+### What to do based on what you find
+
+**At least one authority exists**: it wins. Defer to it. If you need a token it doesn't have (e.g., a danger-secondary color), propose adding the token to the authority FIRST, then use it. Don't hardcode the new value.
+
+**No authority exists**: read `curated-defaults.md` in this references folder. Pick one of the 10 palettes + one of the 10 font pairings. Mark the choice as a finding in the techspec/PR:
+
+> **Design source**: No project authority found. Using curated default "Cool Stone" (neutral slate + intentional accent) + "Inter / Source Serif" pairing. Recommend establishing `DESIGN.md` to formalize.
+
+### Anti-patterns at this question
+
+- Inventing color hex inline (`bg-[#FF6B35]`).
+- "I'll use Tailwind defaults" — Tailwind defaults are training-data defaults, not project authority.
+- Copying values from "a site I like" without understanding what it solved.
+
+### Output
+
+A one-sentence note in the techspec or PR describing which authority you consulted.
+
+## Question 2 — What does this surface help the user do?
+
+**Goal:** the user's intent at this surface, stated in one specific sentence.
+
+**Format:** "This surface helps the user **`<verb-phrase>`** so that **`<outcome>`**."
+
+### Good examples
+
+- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "...helps the manager approve or reject expense reports without leaving Slack."
+
+### Bad examples
+
+- "This surface displays invoice data." → no user, no outcome.
+- "Settings page for managing the account." → vague.
+- "Dashboard." → one word; says nothing.
+
+### When the brief is vague
+
+If you can't write this sentence, the requirements are unclear. Stop. Push back to the requester:
+
+> "Before designing this surface, I need the job sentence: 'helps the user `<verb-phrase>` so that `<outcome>`.' Can you fill in the verb-phrase and outcome?"
+
+Designing without this sentence produces generic surfaces — the "just another dashboard" outcome.
+
+### Output
+
+One sentence in the techspec/PR description.
+
+## Question 3 — What states does the surface have?
+
+**Goal:** enumerate every state the surface can be in BEFORE designing for the happy path.
+
+### Mandatory minimum
+
+| State | Trigger | What user sees |
+|-------|---------|---------------|
+| `default` | First load, no interaction | Initial render |
+| `hover` | Cursor over interactive element | Visual feedback |
+| `active` | Click in progress (mouse down) | Pressed/depressed |
+| `focus-visible` | Keyboard tab arrives | Distinct outline, NOT same as hover |
+| `disabled` | Interaction unavailable | Reduced opacity + cursor change; NO on-click |
+| `loading` | Async operation in flight | Skeleton, spinner, or progress (context-appropriate) |
+| `empty` | No data to show | Guidance on what to do next |
+| `error` | Operation failed | What broke + how to recover |
+| `success` | Operation succeeded | Confirmation; auto-dismiss when safe |
+
+### Domain-specific states
+
+Add when the surface has matching semantics:
+- `read` / `unread` — notifications, messages.
+- `online` / `offline` / `connecting` — chat, presence.
+- `stale` / `fresh` — dashboards with cached data.
+- `pending` / `approved` / `rejected` — workflow records.
+- `draft` / `saved` / `dirty` — forms, editors.
+- `new` / `existing` — composers (title and CTA wording differ).
+- `partial` / `complete` — multi-step flows.
+- `selected` / `unselected` — lists with multi-select.
+- `expired` / `active` — tokens, subscriptions.
+
+### Tripwire
+
+If your design has only `default`, you missed 8 states. If it has `default` + `loading`, you missed 6. The full enumeration is non-negotiable. Empirically, states added "later" are added after a user reports the bug.
+
+### Output
+
+A state matrix table in the techspec or design doc.
+
+## Question 4 — Who uses this surface, where, and in what mood?
+
+**Goal:** the physical context the surface lives in.
+
+**Format:** "**`<Who>`** uses this on **`<where>`** in **`<what light>`** while **`<what mood>`**."
+
+### Good examples
+
+- "An on-call engineer uses this on a dark-room laptop at 3am while troubleshooting a fire."
+- "A field nurse uses this on a phone in bright outdoor light while juggling clipboards."
+- "A receptionist uses this on a 24″ monitor at a busy front desk while talking to a visitor."
+
+### Why this matters
+
+Decisions cascade from the answer:
+
+- **3am dark room** → dark mode default, high contrast, no flashing animations, generous spacing.
+- **Bright outdoor** → minimum 7:1 contrast, large touch targets, no thin fonts, no subtle hover.
+- **Busy front desk** → glanceable info, no nested menus, large numbers, single-screen layout.
+
+Without the answer, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users find it terrible and you can't articulate why.
+
+### Output
+
+One sentence in the techspec.
+
+## What "passing the grounding" looks like
+
+A PR description or techspec UI section that includes:
+
+```markdown
+## UI Discipline Grounding
+
+**Design source:** `.dw/rules/frontend.md` design tokens (Tailwind theme + custom CSS vars).
+**Surface job:** Helps on-call engineers diagnose which deploy caused the latency spike so they can roll back without paging the team.
+**State matrix:**
+  - default, hover, active, focus-visible, disabled, loading, empty (no spikes detected), error (metrics API down), success (rollback completed)
+  - Plus: stale (>5min old data) — show timestamp + refresh CTA.
+**Context:** On-call engineer uses this on a dark-room laptop at 3am while troubleshooting a production fire.
+```
+
+This is the minimum disclosure. Anything less and the grounding didn't pass.
+
+## After grounding
+
+The downstream references (`visual-slop.md`, `state-matrix.md`, `accessibility-floor.md`) assume the grounding passed. They won't re-verify; if you skipped a question, the output will reflect it.
+
+`/dw-code-review` fails verdict on UI PRs where this disclosure is missing.

package/scaffold/skills/dw-ui-discipline/references/state-matrix.md

@@ -0,0 +1,101 @@
+# State matrix — enumerate before designing the happy path
+
+The single biggest UI bug factory: designing for the default state, shipping it, and discovering empty/error/loading at production time. This reference enforces enumeration BEFORE design.
+
+## The mandatory minimum (every interactive surface)
+
+| State | When it fires | Visual rule | Common mistake |
+|-------|---------------|-------------|----------------|
+| `default` | First load, no interaction | Calm baseline; nothing competes with content | Designing only this state |
+| `hover` | Cursor over interactive element | Subtle change signals click affordance | Hover on non-clickable shapes (fake interactivity) |
+| `active` | Click in progress (mouse down) | Distinct from hover; pressed/depressed | Skipping; click feels unresponsive |
+| `focus-visible` | Keyboard tab arrives | Distinct outline, NOT same as hover | Using `outline: none` and not replacing |
+| `disabled` | Interaction unavailable | Reduced opacity + cursor change; no on-click | Looks like enabled, confuses user |
+| `loading` | Async operation in flight | Skeleton/spinner sized to incoming content | Generic spinner regardless of context |
+| `empty` | No data to show | Why-it's-empty + what-to-do-next CTA | "No items found." centered, full stop |
+| `error` | Operation failed | What broke + how to recover + retry CTA | Generic "Something went wrong." |
+| `success` | Operation succeeded | Brief confirmation; auto-dismiss when safe | Toast spam |
+
+## Common domain states
+
+Add these when the surface has matching semantics:
+
+| State | Surfaces | Visual rule |
+|-------|----------|-------------|
+| `read` / `unread` | Notifications, messages, inbox | Weight differential; new is bolder |
+| `online` / `offline` / `connecting` | Chat, presence indicators | Color dot + label; offline is visually quieter |
+| `stale` / `fresh` | Dashboards with cached data | Timestamp + refresh CTA when stale > N min |
+| `pending` / `approved` / `rejected` | Workflow records | Color-coded badges; never color alone (a11y) |
+| `draft` / `saved` / `dirty` | Forms, editors | Indicator near save button; "unsaved changes" |
+| `new` / `existing` | Composers, dialogs | Title and CTA wording differ ("Create" vs "Update") |
+| `partial` / `complete` | Multi-step flows | Progress indicator; remaining steps visible |
+| `selected` / `unselected` | Lists with multi-select | Border + bg change + checkbox mark |
+| `expired` / `active` | Tokens, subscriptions | Visual deemphasis when expired + revocation CTA |
+
+## Loading state granularity (don't just pick "spinner")
+
+| Operation duration | Right loading treatment |
+|--------------------|-------------------------|
+| <300ms | Show nothing. Spinner appearing then vanishing = flicker. |
+| 300ms – 2s | Skeleton loader matching content shape |
+| 2s – 10s | Spinner + status text ("Loading orders...") |
+| 10s – 60s | Progress bar with percentage + cancel button |
+| >60s | Step indicator OR async with notify-when-done |
+
+A spinner that runs forever with no progress info is one of the worst UX patterns. If the operation can take >10s, show progress; if it can take >60s, make it background-able.
+
+## Error state granularity
+
+Errors are not all equal:
+
+| Error type | Treatment |
+|------------|-----------|
+| Validation (client-side, single field) | Inline below field; red text + icon |
+| Validation (form-level) | Summary at top + per-field inline |
+| Authorization (401/403) | Modal or banner; sign-in CTA |
+| Not found (404) | Inline empty-state variant with "go back" |
+| Server error (5xx) | Banner with retry button; preserve user input |
+| Network timeout | Inline message + auto-retry button |
+| Partial data | Show what loaded + indicator for what failed |
+
+Generic "Something went wrong" is the lazy default. Categorize the failure; show actionable guidance.
+
+## Empty state granularity
+
+Empty is not always "no data ever existed":
+
+| Empty reason | Treatment |
+|--------------|-----------|
+| Genuinely first-time empty (new user) | Welcoming illustration + onboarding CTA |
+| Filter excluded everything | Show filter chips + "Clear filters" CTA |
+| Search returned nothing | Echo the query + spelling suggestions / refinement tips |
+| All items completed / archived | Acknowledge + "View archived" CTA |
+| Permissions block visibility | Explain (don't pretend it's empty) + request-access CTA |
+| Loading hasn't completed | This is `loading`, not `empty` — different state |
+
+## Verification checklist
+
+Before declaring the design "done":
+
+- [ ] All 9 minimum states are designed (not just default).
+- [ ] All applicable domain states are designed.
+- [ ] Loading granularity matches operation duration.
+- [ ] Error states are categorized (not all "something went wrong").
+- [ ] Empty states explain WHY and offer WHAT to do.
+- [ ] `disabled` state has visual + cursor differentiation, NO on-click handler.
+- [ ] `focus-visible` is distinct from `hover` (keyboard users need their own affordance).
+- [ ] Color is never the SOLE differentiator (a11y); pair with shape/text/position.
+
+## Integration with `/dw-code-review`
+
+Review fails verdict (REJECTED) on a UI PR when:
+- A new component handles async data but renders only the default state.
+- An interactive element has `:hover` but no `:focus-visible`.
+- An error path falls through to a generic message with no recovery action.
+- Loading state is a spinner where the operation takes >2s (should be progress).
+
+These are not stylistic preferences — they're production bugs waiting to surface.
+
+## Anti-pattern: "We'll add states later"
+
+Empirically: states added later are added under duress (after a user reports). The cost of designing them now is small (15-30 minutes for a component); the cost of finding them in production is large (user trust + incident response). The matrix is non-negotiable.

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

@@ -0,0 +1,152 @@
+# Visual slop — 14 patterns + 17 default values to avoid
+
+Two parts:
+1. **Fourteen patterns** an ungrounded UI agent produces.
+2. **Seventeen specific values** that signal "no thought went into this."
+
+Used by `/dw-code-review` against UI diffs and by `/dw-redesign-ui` as a self-check during proposal.
+
+## The 14 patterns
+
+### 1. Uniform-section flatness
+
+Every section uses the same card style, same padding, same text size, same emphasis weight. The eye finds no anchor.
+
+- **Why it happens:** Default of "consistent = good" without realizing hierarchy needs deliberate variation.
+- **Fix:** One primary section per scroll height. Differentiate by size, weight, color saturation, or whitespace by ≥30%. Everything else recedes.
+- **Example violation:** Dashboard with 6 identical metric cards.
+- **Example fix:** One hero metric (largest, top); 3 supporting metrics; 2 minor metrics in a different visual treatment.
+
+### 2. Soft hierarchy
+
+Headings barely larger than body. Primary CTA same color as secondary. The user can't tell what to look at first.
+
+- **Why it happens:** "Elegant restraint" applied without ensuring guidance still works.
+- **Fix:** Squint at the design (literally). What jumps out? If nothing jumps out, increase contrast in size, weight, or color for the primary element.
+
+### 3. Decorative hover
+
+Hover effects on elements that have no click handler. Cards that fade slightly but don't link anywhere.
+
+- **Why it happens:** Default "apply hover to anything card-shaped."
+- **Fix:** Hover effect lives only on elements with an on-click. Non-interactive shapes get `cursor: default`. If it's hoverable, it must do something.
+
+### 4. Emoji as ornament
+
+Emojis in headers and section labels where they add no information: 🎯 Goals · 🚀 Launch · ✨ Features · 📊 Analytics · 🔥 Trending.
+
+- **Why it happens:** Training data has many "emoji-in-headers = engaging" patterns.
+- **Fix:** Use icons (lucide, heroicons, tabler) for semantic meaning. Reserve emojis for genuinely emotive contexts (celebrations, errors needing empathy). If removing the emoji preserves the meaning, remove it.
+
+### 5. Gradient cover
+
+Hero with diagonal purple-to-pink gradient. Buttons with subtle gradient. Card backgrounds with mesh gradients. Gradient as visual fallback for weak composition.
+
+- **Why it happens:** AI-art aesthetics leak into UI; gradients hide compositional weakness.
+- **Fix:** A gradient must earn its place — usually for hero zones with poetic copy. Solid colors with strong hierarchy beat gradients in utility surfaces.
+
+### 6. Glass-on-everything
+
+Frosted-glass effect on modals, cards, dropdowns, side panels — anywhere a surface can be layered. Including on top of plain backgrounds where the blur effect has nothing to blur.
+
+- **Why it happens:** macOS aesthetic. Looks premium without effort.
+- **Fix:** Glass only when there's meaningful content visible behind the surface. Glass over plain backgrounds adds visual noise without semantic gain.
+
+### 7. Center-aligned by default
+
+Body paragraphs center-aligned. Headlines centered. Forms with labels centered above inputs. Tabular data centered instead of column-aligned.
+
+- **Why it happens:** Marketing-page training data biases toward center.
+- **Fix:** Center for hero headlines and small CTA labels only. Body text and forms read better left-aligned in LTR scripts. Tabular data reads in columns.
+
+### 8. Grayscale wash
+
+Neutral gray palette everywhere — `slate-50`, `gray-100`, `zinc-200` — for backgrounds, borders, text, accents. No accent color, no character.
+
+- **Why it happens:** "Neutral = safe" plus shadcn/ui's neutral starting point.
+- **Fix:** Establish ONE accent color (from brand or curated defaults). Use it intentionally on the primary CTA, the active state, the one place the user looks first. Gray is the canvas, not the painting.
+
+### 9. Verb-less CTAs
+
+"Get Started" · "Learn More" · "Click Here" · "Submit" · "OK" buttons. Generic verbs that say nothing.
+
+- **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".
+
+### 10. Stock-illustration hero
+
+Figure-with-laptop hero art. Diverse-team-around-table illustration. Abstract floating shapes. Generic figures from illustration kits.
+
+- **Why it happens:** "Illustration = friendly" default. Cheap to produce.
+- **Fix:** Use product screenshots (real screens, real data, sanitized) or skip illustration entirely. A clean hero with strong typography beats generic illustration.
+
+### 11. Shadow soup
+
+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 use elevation systematically (Material 3), enforce the elevation hierarchy.
+
+### 12. Generic spinner
+
+Spinner overlay for every async operation, regardless of duration or context.
+
+- **Why it happens:** Default fallback in every UI library.
+- **Fix granularity:**
+  - <300ms: show nothing (spinner appearing then vanishing is flicker).
+  - 300ms–2s: skeleton loader matching content shape.
+  - 2s–10s: spinner + status text ("Loading orders...").
+  - 10s+: progress bar or step indicator + cancel button.
+
+### 13. Silent empty state
+
+"No items found." Centered. Nothing else. User has no idea what to do.
+
+- **Why it happens:** Empty state treated as edge case, not as a real screen.
+- **Fix:** Every empty state answers two questions: WHY is it empty (no data yet vs filter excluded everything vs error)? WHAT should the user do (CTA, like "Create your first invoice")?
+
+### 14. Toast spam
+
+Every UI event becomes a toast. Save successful → toast. Validation error → toast. Network slow → toast. Five stack up and the user reads none.
+
+- **Why it happens:** Toast is the default feedback mechanism in component libraries.
+- **Fix:** Toasts only for actions that need confirmation AWAY from the originating surface (background save, undo-able deletion). Inline feedback for form validation. Modal/banner for blocking errors. Cap at 2 stacked toasts.
+
+## The 17 anti-default values
+
+Specific values that signal "no thought went into this." Avoid unless you can articulate WHY you picked exactly this one:
+
+| Anti-default | 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` | "AI startup landing page" gradient |
+| Inter as the only font choice | Default font of ~60% of new SaaS |
+| `font-bold` for every emphasis | Bold is one tool, not the only tool |
+| Lucide icons exclusively | One icon family is fine; signature is none |
+| Generic "happy team" hero illustration | Placeholder energy |
+| "Get Started" / "Learn More" CTA copy | Verb-less; says nothing |
+| 4 / 8 / 12 / 16 spacing exclusively | The default 4-step scale; no rhythm |
+| `border-gray-200` for every divider | Visual whisper; no intent |
+| Sans-serif headlines + sans-serif body | No typographic contrast |
+| Center-aligned everything | See pattern #7 |
+| Animated CSS confetti on success | Cheesy; mismatches most brands |
+| `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 every interaction | Most modals should be inline editing |
+
+## How to apply this catalog
+
+In `/dw-redesign-ui` step 4 (propose) — before presenting design directions, self-check against this list. If you're using a pattern, say why explicitly ("gradient crutch — intentional for marketing hero"). Sometimes the pattern IS the right call; the discipline is awareness, not absolutism.
+
+In `/dw-code-review` UI section — grep the diff for the anti-default values and the patterns. Each hit becomes a finding under `dw-review-rigor`:
+- Pattern on a NEW surface → `medium` severity.
+- Pattern propagating EXISTING slop further → `low` severity (consistency wins).
+- Pattern on a redesign that was supposed to fix slop → `high` severity (regression).
+
+## When the patterns bend
+
+- **Marketing pages** can use gradients and emojis with more freedom — different surface job.
+- **Brand-mandated** values override this list (if your brand IS `#3B82F6`, use it).
+- **Component libraries** like shadcn ship neutral defaults — the discipline is to ADD character on top, not remove the neutrality.

package/scaffold/skills/ui-ux-pro-max/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Next Level Builder
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.