@brunosps00/dev-workflow 0.11.0 → 0.13.0

package/scaffold/skills/dw-ui-discipline/references/curated-defaults.md

@@ -0,0 +1,195 @@
+# Curated defaults — 10 palettes + 10 font pairings + spacing scale
+
+Use this reference when the project has **no design authority** (no `.dw/rules/` design section, no `DESIGN.md`, no Tailwind theme tokens, no component library config).
+
+The values below cover ~90% of cases that need a starting point. Not opinionated branding — neutral, accessible, professional defaults.
+
+## How to use
+
+1. Pick ONE palette + ONE font pairing + the spacing scale.
+2. Commit the choice to the project (`.dw/rules/<frontend>.md` design section OR a new `DESIGN.md`).
+3. From there, the project HAS a design authority; downstream `dw-ui-discipline` invocations defer to that authority.
+
+This is bootstrap, not destination. The goal is to escape "no authority" mode within the first feature.
+
+## The 10 palettes
+
+Each palette below: neutral scale (gray, slate, etc.) + 1 accent + semantic colors. All WCAG 2.2 AA compliant for body text.
+
+### 1. Cool Stone
+- Neutrals: Tailwind `slate` (50-950)
+- Accent: `#3B82F6` (blue-500) — wait, no, see Anti-Slop. Use `#0066CC` instead.
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Calm, corporate, trustworthy. Default for SaaS dashboards.
+
+### 2. Warm Sand
+- Neutrals: Tailwind `stone` (50-950)
+- Accent: `#CA8A04` (warm amber)
+- Semantic: success `#16A34A`, warning `#EA580C`, danger `#DC2626`
+- **Tone:** Approachable, hospitality-adjacent, organic.
+
+### 3. Forest Pine
+- Neutrals: Tailwind `gray` (50-950)
+- Accent: `#15803D` (deep green)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#B91C1C`
+- **Tone:** Steady, financial, sustainable.
+
+### 4. Plum Velvet
+- Neutrals: Tailwind `zinc` (50-950)
+- Accent: `#7C3AED` (violet-600)
+- Semantic: success `#22C55E`, warning `#EAB308`, danger `#E11D48`
+- **Tone:** Creative, premium, design-tool.
+
+### 5. Coral Reef
+- Neutrals: Tailwind `neutral` (50-950)
+- Accent: `#E11D48` (rose-600)
+- Semantic: success `#16A34A`, warning `#F59E0B`, danger `#B91C1C`
+- **Tone:** Energetic, consumer, retail.
+
+### 6. Steel Blue
+- Neutrals: Tailwind `slate` (50-950)
+- Accent: `#0F766E` (teal-700)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Technical, infrastructure, devops.
+
+### 7. Burnt Sienna
+- Neutrals: Tailwind `stone` (50-950)
+- Accent: `#C2410C` (orange-700)
+- Semantic: success `#15803D`, warning `#A16207`, danger `#B91C1C`
+- **Tone:** Bold, news, sports.
+
+### 8. Ink and Paper
+- Neutrals: Pure `#000` and `#FFF` with `#E5E5E5` divider
+- Accent: `#000` (no accent — minimal)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Editorial, brutalist, magazine. Pair with serif body.
+
+### 9. Midnight Indigo
+- Neutrals: Tailwind `slate` dark-mode-first (900-50)
+- Accent: `#6366F1` (indigo-500)
+- Semantic: success `#22C55E`, warning `#FACC15`, danger `#EF4444`
+- **Tone:** Tech-forward, dark-mode-default, on-call tooling.
+
+### 10. Sea Salt
+- Neutrals: Tailwind `gray` cool (50-950)
+- Accent: `#0891B2` (cyan-600)
+- Semantic: success `#10B981`, warning `#F59E0B`, danger `#F43F5E`
+- **Tone:** Fresh, healthcare, education.
+
+## The 10 font pairings
+
+Each pairing: heading font / body font. All available on Google Fonts. Variable fonts where possible.
+
+| # | Headings | Body | Tone |
+|---|----------|------|------|
+| 1 | Inter | Inter | Modern SaaS default. Workhorse pairing. |
+| 2 | Geist Sans | Geist Sans | Vercel-aesthetic; clean, geometric. |
+| 3 | Söhne (or Manrope) | Söhne (or Manrope) | Editorial-modern; replaces Inter when Inter feels overused. |
+| 4 | DM Serif Display | Inter | Editorial-meets-product. Strong headlines, neutral body. |
+| 5 | Fraunces | Inter | Variable serif headlines, sans body. Premium feel. |
+| 6 | Source Serif 4 | Source Sans 3 | Adobe pairing; balanced editorial. |
+| 7 | Space Grotesk | Inter | Slightly quirky headlines, neutral body. Tech with personality. |
+| 8 | IBM Plex Serif | IBM Plex Sans | Industrial, opinionated. Good for enterprise tooling. |
+| 9 | Playfair Display | Manrope | High contrast pairing; hospitality, lifestyle. |
+| 10 | JetBrains Mono | Inter | Code-first products; mono for headlines and accents. |
+
+**Anti-default reminder:** Inter / Inter is fine. Inter / Inter as the ONLY pairing you ever pick is a tell.
+
+## Spacing scale
+
+Use a 4px-base scale with intentional jumps:
+
+```
+0:   0px
+1:   4px   (tight controls, icon padding)
+2:   8px   (compact spacing)
+3:   12px  (default gap in form fields)
+4:   16px  (default gap between blocks)
+6:   24px  (section padding)
+8:   32px  (large section spacing)
+12:  48px  (page header / hero padding)
+16:  64px  (between major sections)
+24:  96px  (hero / landing block separators)
+32:  128px (rare; signature spacing)
+```
+
+**Skip these by default:** 5, 7, 9, 10, 11, 13, 14, 15. Picking exactly 4-6-8-12-16 reads more intentional than 1-2-3-4-5-6-...
+
+## Border radius scale
+
+Pick a "personality" once and use it consistently:
+
+| Radius | Tone |
+|--------|------|
+| 0 (square) | Brutalist, editorial |
+| 2px | Subtle modernist |
+| 4px (Tailwind `rounded`) | Standard |
+| 6px | Slightly friendly |
+| 8px (Tailwind `rounded-lg`) | Default SaaS; **anti-default if used universally** |
+| 12px | Softer, consumer |
+| 16px+ | Rounded everything; friendly/youth-oriented |
+| Full / 9999px | Pills, buttons, avatars only |
+
+Don't mix more than 2 radii in one surface (e.g., 4px for inputs, 8px for cards). Three+ radii = visual noise.
+
+## Type scale
+
+For body=16px baseline:
+
+```
+xs:    12px  (captions, helper text — minimum 11px)
+sm:    14px  (secondary, labels)
+base:  16px  (body)
+lg:    18px  (lead paragraphs)
+xl:    20px  (small headings)
+2xl:   24px  (subheadings)
+3xl:   30px  (section headings)
+4xl:   36px  (page titles)
+5xl:   48px  (hero, marketing)
+6xl+:  60-96px (display, marketing only)
+```
+
+Line-height pairs:
+- Body text: 1.5 to 1.6
+- Headings: 1.1 to 1.25
+- Buttons: 1 (tight)
+
+## How to commit a choice
+
+After picking a palette + pairing + spacing, write `.dw/rules/<frontend>.md` (or `DESIGN.md`) with:
+
+```markdown
+## Design System (bootstrap)
+
+**Source:** Curated default — `dw-ui-discipline/references/curated-defaults.md`, picked Cool Stone + Inter/Inter + 4px-base scale on 2026-05-12.
+
+### Colors
+- Neutrals: Tailwind slate (50-950)
+- Accent: #0066CC (links, primary buttons, focus rings)
+- Success: #16A34A · Warning: #D97706 · Danger: #DC2626
+
+### Typography
+- Headings: Inter, weight 600-700
+- Body: Inter, weight 400-500
+- Mono: JetBrains Mono (code blocks only)
+
+### Spacing
+4px base scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96.
+
+### Border radius
+4px on inputs, 8px on cards, full on pills/avatars.
+
+### Updates
+This file is the canonical design source. To change a value, propose a PR
+that updates this file FIRST, then propagates through code.
+```
+
+Once written, `dw-ui-discipline` reads this file instead of `curated-defaults.md`. The bootstrap step is done.
+
+## What this catalog is NOT
+
+- Not 161 palettes. Not 57 fonts. By design.
+- Not a substitute for brand work — for a serious product, hire a designer.
+- Not opinionated about industry-specific aesthetics (med-tech, gaming, kids' content). Those need real design pass.
+
+The point is: have ONE intentional starting point so the agent isn't reaching for `#3B82F6` and `rounded-lg`. Project-specific design follows.

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

@@ -0,0 +1,142 @@
+# The hard-gate protocol — full version
+
+Four checkpoints before any UI work touches code. Each has a concrete output. Don't proceed without finishing the current one.
+
+## Why a gate at all
+
+Training-data defaults are the enemy. An LLM proposing UI without grounding will:
+- Reach for `#3B82F6` blue and `rounded-lg` because they appeared 10M times in training data.
+- Default to glass morphism, gradient backgrounds, and center-aligned everything because those screenshots dominate the web.
+- Skip empty/error states because happy-path screenshots are the most common training signal.
+
+The gate forces grounding in this project's reality before training-data autopilot fires.
+
+## Checkpoint 1: Brand authorities OR curated defaults
+
+**Goal:** know where visual decisions come from. Documented authority, or curated default — never invented.
+
+**How:**
+
+1. Search the project for design source-of-truth:
+   - `.dw/rules/*.md` — look for "Design", "Patterns to Follow", "Naming Conventions" sections.
+   - `DESIGN.md`, `BRAND.md`, `BRANDING.md`, `STYLE_GUIDE.md` at root.
+   - Tailwind `tailwind.config.{ts,js}` — theme tokens.
+   - CSS variables in `globals.css`, `theme.css`, `tokens.css`.
+   - Component library config (shadcn `components.json`, MUI theme, Chakra theme).
+   - Storybook stories — implicit canonical components.
+
+2. If **at least one** authority exists: it wins. Decisions defer to it. If a needed token doesn't exist (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
+
+3. If **none exists**: pick a curated default. Read `curated-defaults.md` in this references folder. Pick one of the 10 palettes + one of the 10 font pairings. Mark the choice in the techspec/PR description:
+
+   > **Design source:** No project authority found. Using curated default "Cool Stone" (neutral grays + electric blue accent) + "Inter / Source Serif" pairing. Recommend establishing `DESIGN.md` to formalize.
+
+**Anti-patterns at this checkpoint:**
+
+- Inventing color hex values 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/PR describing the authority consulted.
+
+## Checkpoint 2: Surface job sentence
+
+**Goal:** the user's intent at this surface, stated in one specific sentence.
+
+**Format:** "This surface helps the user **<verb-phrase>** so that **<outcome>**."
+
+**Examples — good:**
+
+- "This surface helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "This surface helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "This surface helps the manager approve or reject expense reports without leaving Slack."
+
+**Examples — bad:**
+
+- "This surface displays invoice data." (no user, no outcome)
+- "Settings page for managing the account." (vague, no specificity)
+- "Dashboard." (one word)
+
+**How to push back when the brief is vague:**
+
+If the requester can't articulate the job, the requirements aren't ready. Reply with: "Before I design this surface, I need the job sentence: <example>. Can you fill in the verb-phrase and outcome?"
+
+Designing without this sentence produces generic surfaces — the "just another dashboard" outcome.
+
+**Output:** The one-sentence job, committed to the techspec/PR description.
+
+## Checkpoint 3: Complete state matrix
+
+**Goal:** enumerate every state the surface can be in, BEFORE designing for the happy path.
+
+**Minimum states (always enumerate):**
+
+| State | Trigger | What user sees |
+|-------|---------|---------------|
+| `default` | First load, no interaction | Initial render |
+| `hover` | Cursor over interactive element | Visual feedback |
+| `active` | Click in progress | Pressed/depressed visual |
+| `focus-visible` | Keyboard tab arrived | Distinct outline, not the same as hover |
+| `disabled` | Interaction unavailable | Reduced opacity + cursor change, NO action |
+| `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 that doesn't require ack |
+
+**Add domain-specific states as needed:**
+
+- Read/unread (notifications, messages)
+- Online/offline (chat, collaborative tools)
+- Stale/fresh (dashboards with cached data)
+- Pending/approved/rejected (workflow states)
+- New/saved/dirty (forms)
+
+**Tripwire:** if the design has only `default`, you missed 8 states. If it has `default` + `loading`, you missed 6. The full matrix is non-negotiable.
+
+**Output:** A state matrix table in the techspec or design doc.
+
+## Checkpoint 4: Scene sentence
+
+**Goal:** the physical context the surface lives in.
+
+**Format:** "**<Who>** uses this **<where>** in **<what light>** while **<what mood>**."
+
+**Examples — good:**
+
+- "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 scene:
+- 3am dark room → dark mode, high contrast, no flashing animations.
+- Bright outdoor → minimum 7:1 contrast, larger touch targets, no thin fonts.
+- Busy front desk → glanceable info, no nested menus, big numbers.
+
+Without the scene, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
+
+**Output:** Scene sentence in the techspec.
+
+## What "passing the gate" looks like
+
+A PR description / techspec UI section that includes:
+
+```markdown
+## UI Discipline Gate
+
+**Authority:** `.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.
+**Scene:** 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 gate didn't pass.
+
+## When this gate has been run
+
+The downstream skills (`anti-slop.md`, `state-matrix.md`, `accessibility-floor.md`) assume gate passed. They won't re-verify; if you skipped, you get bad output.
+
+`/dw-code-review` failing verdict on a UI PR 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/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.