# Lerianstudio Ring Pre Dev Design Validation

> Design Validation Gate

- Skill: `tomevault-io/lerianstudio-ring-pre-dev-design-validation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/lerianstudio-ring-pre-dev-design-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/lerianstudio-ring-pre-dev-design-validation/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/lerianstudio-ring-pre-dev-design-validation

---


# Design Validation Gate

## ⛔ MANDATORY GATE - CANNOT BE SKIPPED

**This gate is REQUIRED for all features with UI. No exceptions. No shortcuts.**

### Enforcement Points

| Enforcement | What Happens |
|-------------|--------------|
| **TRD checks for design-validation.md** | TRD skill will STOP if this file is missing or verdict is not VALIDATED |
| **Commands enforce gate order** | pre-dev-feature and pre-dev-full require this gate before TRD |
| **Critical gaps = HARD STOP** | Any Section 1-2 failure blocks progression to TRD |

### Why This Gate Exists

| Without Validation | With Validation |
|-------------------|-----------------|
| Missing UI states discovered during coding | All states defined upfront |
| "Mobile later" becomes "Mobile never" | Responsive specs locked in |
| Accessibility retrofitted expensively | A11y baked in from start |
| 10x implementation rework | Design complete before code |

---

## Standards Loading (MANDATORY)

This skill is a validation/checklist skill and does NOT require WebFetch of language-specific standards.

**Purpose:** Design Validation verifies UX artifact completeness against a checklist. Technical standards are irrelevant at this stage—they apply during TRD (Gate 3) and implementation.

**However**, if validating component library alignment (Section 8), MUST reference the UI library's documentation to verify component availability and variant names.

---

## Purpose

**Verify that UX specifications are COMPLETE before investing in technical architecture.**

This gate prevents:
- Incomplete wireframes reaching implementation
- Missing UI states causing implementation rework
- Accessibility gaps discovered late
- Responsive behavior undefined until coding

**This is a VALIDATION gate, not a CREATION gate.** It checks existing artifacts, does not create new ones.

---

## Gate Entry Criteria

**MUST have these artifacts before running this gate:**

| Artifact | Location | Required For |
|----------|----------|--------------|
| `prd.md` | `docs/pre-dev/{feature}/` | all features |
| `ux-criteria.md` | `docs/pre-dev/{feature}/` | all features with UI |
| `wireframes/` | `docs/pre-dev/{feature}/wireframes/` | all features with UI |
| `user-flows.md` | `docs/pre-dev/{feature}/wireframes/` | all features with UI |
| `feature-map.md` | `docs/pre-dev/{feature}/` | Large track only |

**If artifacts do not exist -> STOP. Return to previous gate.**

---

## UI Detection

**Feature has UI if PRD contains any of:**
- User stories with: "see", "view", "click", "navigate", "page", "screen", "button", "form"
- Features involving: login, dashboard, settings, profile, reports, notifications
- Any direct user-facing interaction

**If feature has NO UI -> Skip this gate, proceed to TRD.**

---

## Validation Checklist

### Section 1: Wireframe Completeness (CRITICAL)

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **all screens defined** | Every user-facing screen has a `.yaml` file | List missing screens |
| **ASCII prototype present** | Every wireframe has `ascii_prototype:` section | List wireframes without ASCII |
| **Components specified** | Every wireframe has `components:` with types | List incomplete wireframes |
| **Route defined** | Every wireframe has `route:` field | List wireframes without routes |

### Section 2: UI States Coverage (CRITICAL)

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **Loading state** | Every data-fetching screen defines loading | List screens missing loading |
| **Error state** | Every data-fetching screen defines error | List screens missing error |
| **Empty state** | Every list/table screen defines empty | List screens missing empty |
| **Success state** | Every form/action screen defines success | List screens missing success |

**State Detection Rules:**
- Screen has `data_source:` or API reference -> Needs loading/error states
- Screen has `type: table` or `type: list` -> Needs empty state
- Screen has `type: form` or `type: button` with action -> Needs success state

### Section 3: Accessibility Specifications

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **Keyboard navigation** | `ux-criteria.md` has "Keyboard accessible" criteria | Flag missing |
| **Screen reader support** | `ux-criteria.md` has "ARIA" or "screen reader" criteria | Flag missing |
| **Contrast requirements** | `ux-criteria.md` specifies contrast ratio | Flag missing |
| **Focus management** | Modal/dialog wireframes specify focus behavior | List modals without focus spec |

### Section 4: Responsive Specifications

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **Mobile layout defined** | Wireframes with significant layout have mobile ASCII | List wireframes without mobile |
| **Breakpoints documented** | `ux-criteria.md` specifies breakpoint behavior | Flag missing |
| **Touch targets noted** | Mobile wireframes consider 44x44px targets | Flag if not mentioned |

### Section 5: User Flow Completeness

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **Happy path documented** | `user-flows.md` has primary success flow | Flag missing |
| **Error paths documented** | `user-flows.md` has at least one error flow | Flag missing |
| **Entry points defined** | Flows specify how user arrives | Flag missing |
| **Exit points defined** | Flows specify where user goes after | Flag missing |

### Section 6: Content Specifications

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **Button labels defined** | all buttons have explicit `label:` | List buttons with generic labels |
| **Error messages specified** | Error states have specific messages | List generic error messages |
| **Empty state CTAs** | Empty states have actionable CTAs | List empty states without CTA |
| **Form validation messages** | Form fields with validation have error text | List fields without error text |

### Section 7: Design System (New Projects)

**This section applies when:** Project is new (no existing design system detected).

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **design-system.md exists** | `docs/pre-dev/{feature}/design-system.md` present | Flag: "Missing design-system.md" |
| **Color palette defined** | Primary, neutral, semantic colors documented | Flag: "Incomplete color palette" |
| **Typography specified** | Font family, scale, line heights documented | Flag: "Missing typography specs" |
| **Contrast validated** | Accessibility contrast ratios calculated | Flag: "Missing contrast validation" |
| **CSS variables listed** | All required CSS custom properties documented | Flag: "Missing CSS variables" |

**Detection Rule:** Project is "new" if:
- No `globals.css` with CSS variables exists, OR
- No `tailwind.config.*` with custom colors exists

**Why This Matters:**
- Frontend engineers need design tokens before implementation
- TRD references design-system.md for styling architecture
- Missing design system = styling decisions made ad-hoc during coding

### Section 8: Component Library Alignment (All UI Features)

**This section validates that wireframes use components available in the project's UI library.**

| Check | Pass Criteria | Fail Action |
|-------|---------------|-------------|
| **UI library identified** | `ux-criteria.md` specifies UI library (shadcn, Chakra, etc.) | Flag: "Missing UI library specification" |
| **Components exist in library** | all `components:` in wireframes exist in specified library | List unavailable components |
| **Variants match library** | Button variants, input types match library's variants | List incorrect variant usage |
| **Custom components flagged** | Components not in library marked as `custom: true` | List unmarked custom components |

**Validation Process:**

1. **Read UI library from ux-criteria.md:**
   ```yaml
   ui_library: shadcn/ui | Chakra UI | Material UI | Custom
   ```

2. **For each wireframe, check components:**
   ```yaml
   components:
     - type: Button        # Exists in shadcn? ✅
       variant: primary    # Valid variant? ✅
     - type: DataGrid      # Exists in shadcn? ❌ (custom needed)
   ```

3. **Flag mismatches:**
   - Component doesn't exist → Needs `custom: true` or different component
   - Variant doesn't exist → Use correct library variant

**Why This Matters:**
- Prevents wireframes specifying components that don't exist
- Prevents implementation errors from incorrect variant names
- Identifies custom component work needed before TRD

---

## Validation Process

### Phase 1: Artifact Discovery

```
1. Read docs/pre-dev/{feature}/prd.md
2. Detect if feature has UI (see UI Detection rules)
3. If no UI -> Skip validation, proceed to TRD
4. Read docs/pre-dev/{feature}/ux-criteria.md
5. Glob docs/pre-dev/{feature}/wireframes/*.yaml
6. Read docs/pre-dev/{feature}/wireframes/user-flows.md
7. If Large track: Read docs/pre-dev/{feature}/feature-map.md
```

### Phase 2: Systematic Validation

```
FOR EACH section in checklist:
  FOR EACH check in section:
    - Evaluate against artifacts
    - Record PASS or FAIL
    - If FAIL: Record specific gaps with file locations
```

### Phase 3: Verdict

| Condition | Verdict | Action |
|-----------|---------|--------|
| all checks PASS | DESIGN VALIDATED | Proceed to TRD |
| Any Section 1-2 check FAIL | CRITICAL GAPS | Return to UX gate, fix gaps |
| Only Section 3-6 checks FAIL | MINOR GAPS | Document gaps, user decides |

---

## Output Format

```markdown
# Design Validation Report

## Feature: {feature_name}

## Validation Date: {date}

## Artifacts Validated

| Artifact | Status | Location |
|----------|--------|----------|
| PRD | Found/Not Found | docs/pre-dev/{feature}/prd.md |
| UX Criteria | Found/Not Found | docs/pre-dev/{feature}/ux-criteria.md |
| Wireframes | Found (N files) | docs/pre-dev/{feature}/wireframes/ |
| User Flows | Found/Not Found | docs/pre-dev/{feature}/wireframes/user-flows.md |

## Validation Results

### Section 1: Wireframe Completeness

| Check | Status | Details |
|-------|--------|---------|
| all screens defined | PASS/FAIL | N/N screens have wireframes |
| ASCII prototype present | PASS/FAIL | Details |
| Components specified | PASS/FAIL | Details |
| Route defined | PASS/FAIL | Details |

### Section 2: UI States Coverage

| Check | Status | Details |
|-------|--------|---------|
| Loading state | PASS/FAIL | Details |
| Error state | PASS/FAIL | Details |
| Empty state | PASS/FAIL | Details |
| Success state | PASS/FAIL | Details |

### Section 3: Accessibility Specifications

| Check | Status | Details |
|-------|--------|---------|
| Keyboard navigation | PASS/FAIL | Details |
| Screen reader support | PASS/FAIL | Details |
| Contrast requirements | PASS/FAIL | Details |
| Focus management | PASS/FAIL | Details |

### Section 4: Responsive Specifications

| Check | Status | Details |
|-------|--------|---------|
| Mobile layout defined | PASS/FAIL | Details |
| Breakpoints documented | PASS/FAIL | Details |
| Touch targets noted | PASS/FAIL | Details |

### Section 5: User Flow Completeness

| Check | Status | Details |
|-------|--------|---------|
| Happy path documented | PASS/FAIL | Details |
| Error paths documented | PASS/FAIL | Details |
| Entry points defined | PASS/FAIL | Details |
| Exit points defined | PASS/FAIL | Details |

### Section 6: Content Specifications

| Check | Status | Details |
|-------|--------|---------|
| Button labels defined | PASS/FAIL | Details |
| Error messages specified | PASS/FAIL | Details |
| Empty state CTAs | PASS/FAIL | Details |
| Form validation messages | PASS/FAIL | Details |

### Section 7: Design System (New Projects Only)

| Check | Status | Details |
|-------|--------|---------|
| design-system.md exists | PASS/FAIL/N/A | Details |
| Color palette defined | PASS/FAIL/N/A | Details |
| Typography specified | PASS/FAIL/N/A | Details |
| Contrast validated | PASS/FAIL/N/A | Details |
| CSS variables listed | PASS/FAIL/N/A | Details |

### Section 8: Component Library Alignment

| Check | Status | Details |
|-------|--------|---------|
| UI library identified | PASS/FAIL | Details |
| Components exist in library | PASS/FAIL | Details |
| Variants match library | PASS/FAIL | Details |
| Custom components flagged | PASS/FAIL | Details |

## Summary

| Section | Status | Critical? |
|---------|--------|-----------|
| Wireframe Completeness | PASS/FAIL | Yes |
| UI States Coverage | PASS/FAIL | Yes |
| Accessibility | PASS/FAIL | Yes |
| Responsive | PASS/FAIL | No |
| User Flows | PASS/FAIL | Yes |
| Content | PASS/FAIL | No |
| Design System (new projects) | PASS/FAIL/N/A | Yes (if applicable) |
| Component Library Alignment | PASS/FAIL | Yes |

## Verdict: [DESIGN VALIDATED | CRITICAL GAPS | MINOR GAPS]

### Critical Gaps (MUST fix before TRD)

[List each critical gap with:]
1. **Gap description**
   - File: `path/to/file`
   - Required: What needs to be added

### Minor Gaps (Recommended to fix)

[List each minor gap with:]
1. **Gap description**
   - File: `path/to/file`
   - Issue: What's missing or incomplete

## Next Steps

| Priority | Action | Gate |
|----------|--------|------|
| P0 | Fix critical gaps | Return to Gate 1/2 |
| P1 | Review minor gaps | Optional |
| - | Re-run validation | After fixes |
| - | Proceed to TRD | After validation passes |
```

---

## Anti-Rationalization Table

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "Error states are implementation details" | Error states are UX decisions. Users experience errors. | **Specify all error states before TRD** |
| "We'll figure out mobile layout during coding" | Responsive is design decision, not implementation. | **Specify mobile layout now** |
| "Loading state is just a spinner" | Loading UX varies: skeleton, spinner, progressive. | **Specify loading behavior explicitly** |
| "Accessibility can be added later" | Retrofitting a11y is 10x more expensive. | **Include a11y specs from start** |
| "These are minor gaps, let's proceed" | Minor gaps compound. Fix them now. | **Fix gaps or explicitly accept risk** |
| "The wireframe is self-explanatory" | Self-explanatory to you does not mean clear to developer. | **Document all states explicitly** |
| "This validation is slowing us down" | Incomplete design slows implementation 10x more. | **Complete validation before TRD** |
| "We have tight deadlines" | Incomplete specs cause missed deadlines. | **Invest time now, save time later** |
| "Designer already approved this" | Designer approval does not equal completeness check. | **Run systematic validation** |
| "We'll add states as we implement" | Adding states during implementation causes scope creep. | **Define all states upfront** |

---

## Pressure Resistance

| User Says | Your Response |
|-----------|---------------|
| "Skip validation, design is good enough" | "Design validation prevents implementation rework. 'Good enough' does not equal complete." |
| "We don't have time for this gate" | "Incomplete design costs 10x in implementation. Time invested now saves time later." |
| "Just the critical sections, skip the rest" | "all sections exist because they prevent real problems. No cherry-picking." |
| "Error states are obvious, no need to specify" | "Obvious to you does not equal obvious to developer does not equal obvious to user. Specify them." |
| "Mobile can wait for v2" | "Mobile users are 60%+ of traffic. Responsive is not optional." |
| "Let's start TRD in parallel" | "TRD depends on complete design. Starting with gaps creates rework." |
| "The previous feature didn't need this" | "Each feature is validated independently. Past shortcuts don't justify current ones." |
| "I'll fix gaps after TRD" | "Fixing design after technical architecture causes cascade changes. Fix now." |

---

## Blocker Criteria - STOP and Report

| Condition | Action |
|-----------|--------|
| PRD not found | **STOP.** Return to Gate 1 to create PRD. |
| Feature has UI but no ux-criteria.md | **STOP.** Return to Gate 1 to create UX criteria. |
| Feature has UI but no wireframes | **STOP.** Return to Gate 1/2 to create wireframes. |
| Critical gaps found (Section 1-2) | **STOP.** Return to UX gate to fix gaps. |
| Minor gaps found (Section 3-6) | **ASK USER.** Proceed with documented risk or fix first? |

---

## Severity Calibration

| Severity | Criteria | Examples | Action |
|----------|----------|----------|--------|
| **CRITICAL** | Missing Section 1-2 items | No wireframe for screen, no error state, no loading state | STOP, return to previous gate |
| **CRITICAL** | Missing Section 7 items (new projects) | No design-system.md, no color palette | STOP, return to PRD creation |
| **CRITICAL** | Missing Section 8 items | Components don't exist in library, wrong variants | STOP, fix wireframes |
| **HIGH** | Missing Section 3-5 items | No a11y criteria, no mobile layout, no error flow | Document, strongly recommend fix |
| **MEDIUM** | Missing Section 6 items | Generic button labels, missing CTA on empty state | Document, recommend fix |
| **LOW** | Incomplete but present | Mobile layout exists but lacks touch target note | Note for future improvement |

---

## When Validation is Not Needed

**Skip this gate when all conditions are true:**

- Feature is backend-only (no user-facing UI)
- Feature is pure API/infrastructure
- PRD explicitly states "No UI changes"
- Feature is bug fix with no UX modifications

**If any UI exists -> Validation is REQUIRED.**

---

## Metrics

| Metric | Description | Target |
|--------|-------------|--------|
| `validation_pass_rate` | % of features passing on first validation | > 70% |
| `critical_gaps_per_validation` | Average critical gaps found | < 2 |
| `validation_time_minutes` | Time to complete validation | < 15 |
| `rework_reduction` | Implementation rework after validation | -50% |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/lerianstudio) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->