azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add Sequential Thinking to Code Review + Frontend Validation

Browse Source 
Enhanced code review and frontend validation with intelligent triggers:

Code Review Agent Enhancement:
- Added Sequential Thinking MCP integration for complex issues
- Triggers on 2+ rejections or 3+ critical issues
- New escalation format with root cause analysis
- Comprehensive solution strategies with trade-off evaluation
- Educational feedback to break rejection cycles
- Files: .claude/agents/code-review.md (+308 lines)
- Docs: CODE_REVIEW_ST_ENHANCEMENT.md, CODE_REVIEW_ST_TESTING.md

Frontend Design Skill Enhancement:
- Automatic invocation for ANY UI change
- Comprehensive validation checklist (200+ checkpoints)
- 8 validation categories (visual, interactive, responsive, a11y, etc.)
- 3 validation levels (quick, standard, comprehensive)
- Integration with code review workflow
- Files: .claude/skills/frontend-design/SKILL.md (+120 lines)
- Docs: UI_VALIDATION_CHECKLIST.md (462 lines), AUTOMATIC_VALIDATION_ENHANCEMENT.md (587 lines)

Settings Optimization:
- Repaired .claude/settings.local.json (fixed m365 pattern)
- Reduced permissions from 49 to 33 (33% reduction)
- Removed duplicates, sorted alphabetically
- Created SETTINGS_PERMISSIONS.md documentation

Checkpoint Command Enhancement:
- Dual checkpoint system (git + database)
- Saves session context to API for cross-machine recall
- Includes git metadata in database context
- Files: .claude/commands/checkpoint.md (+139 lines)

Decision Rationale:
- Sequential Thinking MCP breaks rejection cycles by identifying root causes
- Automatic frontend validation catches UI issues before code review
- Dual checkpoints enable complete project memory across machines
- Settings optimization improves maintainability

Total: 1,200+ lines of documentation and enhancements

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-01-17 16:23:52 -07:00
parent 359c2cf1b4
commit 75ce1c2fd5
1089 changed files with 149506 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

588
.claude/skills/frontend-design/AUTOMATIC_VALIDATION_ENHANCEMENT.md Normal file
View File

@@ -0,0 +1,588 @@
# Frontend Design Skill - Automatic Validation Enhancement
**Enhancement Date:** 2026-01-17
**Status:** COMPLETED
---
## Summary
Enhanced the frontend-design skill to be automatically invoked whenever ANY action affects a UI element. This ensures all UI changes are validated for visual correctness, functionality, responsive behavior, and accessibility before being finalized.
---
## What Changed
### 1. Updated Skill Metadata
**File:** `.claude/skills/frontend-design/SKILL.md`
**Description Updated:**
- Added "MANDATORY AUTOMATIC INVOCATION" to skill description
- Clarified that skill must be invoked whenever ANY action affects UI
- Made validation a core function alongside creation
**Before:**
```
Use this skill when the user asks to build web components...
```
**After:**
```
MANDATORY AUTOMATIC INVOCATION: Use this skill whenever ANY action
affects a UI element to validate visual correctness, functionality,
and user experience. Also use when the user asks to build...
```
### 2. New Section: "CRITICAL: Automatic Invocation Triggers"
**Location:** After introduction, before "Design Thinking" section
**Added 120+ lines covering:**
- When to invoke this skill (mandatory triggers)
- Purpose of automatic invocation
- Validation workflow (5-step process)
- Examples of automatic invocation
- Integration with other agents
- Rule of thumb
### 3. Created Comprehensive Validation Checklist
**New File:** `.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md`
**Contents:**
- 8 validation categories (200+ checkpoints)
- 3 validation workflows (quick, standard, comprehensive)
- Validation report formats
- Common issues to watch for
- Decision matrix (pass, warn, or block)
---
## Automatic Invocation Triggers
### MANDATORY Triggers
The skill MUST be invoked for:
**1. UI Creation**
- Creating new web pages, components, or interfaces
- Building dashboards, forms, or layouts
- Designing landing pages or marketing sites
- Generating HTML/CSS/React/Vue code
**2. UI Modification**
- Changing styles, colors, fonts, or layouts
- Updating component appearance or behavior
- Refactoring frontend code
- Adding animations or interactions
**3. UI Validation**
- After ANY code change that affects UI
- After updating styles or markup
- After adding features to UI components
- After refactoring frontend code
- After fixing UI bugs
### Rule of Thumb
**If the change appears in a browser, invoke this skill to validate it.**
---
## Validation Workflow
When invoked for UI validation:
```markdown
1. REVIEW: What UI elements were changed?
2. ASSESS: How should they appear/behave?
3. VALIDATE:
- Visual appearance (layout, colors, fonts, spacing)
- Interactive behavior (hover, click, focus states)
- Responsive behavior (mobile, tablet, desktop)
- Accessibility (keyboard nav, screen readers)
4. REPORT:
- [OK] Working correctly
- [WARNING] Minor issues detected
- [ERROR] Critical issues found
5. FIX: If issues found, provide corrected code
```
---
## Validation Categories (8 Total)
### 1. Visual Appearance
- Layout & structure (positioning, grid/flex, z-index)
- Typography (fonts, sizes, hierarchy)
- Colors & contrast (WCAG compliance)
- Spacing & rhythm (padding, margins, whitespace)
- Visual effects (shadows, borders, backgrounds)
### 2. Interactive Behavior
- Click/tap interactions (buttons, links, forms)
- Hover states (feedback, cursor changes)
- Focus states (keyboard navigation)
- Active states (pressed/loading)
- Disabled states (visual indication)
### 3. Responsive Behavior
- Breakpoints (6 ranges from 320px to 1920px+)
- Adaptive layout (reflow, no horizontal scroll)
- Responsive typography (scaling, line length)
- Mobile-specific (touch targets, gestures, keyboard)
### 4. Animations & Transitions
- Animation quality (smoothness, timing, easing)
- Performance (GPU acceleration, no jank)
- Transition states (enter, exit, loading)
- Scroll animations (parallax, sticky, progress)
### 5. Accessibility
- Keyboard navigation (tab order, shortcuts)
- Screen reader support (semantic HTML, ARIA)
- Visual accessibility (contrast, focus, resize)
- Alternative content (alt text, captions)
### 6. Performance
- Load performance (critical CSS, font loading, lazy loading)
- Runtime performance (no layout shifts, smooth scrolling)
- Resource optimization (image compression, minification)
### 7. Cross-Browser Compatibility
- Modern browsers (Chrome, Firefox, Safari, Mobile)
- Fallbacks (graceful degradation, polyfills)
### 8. Content & Copy
- Text quality (no typos, proper capitalization)
- Internationalization (RTL, long text handling)
---
## Three Validation Levels
### Quick Validation (1-2 minutes)
**For:** Minor changes (color updates, spacing tweaks)
**Checks:**
- Visual check at 1-2 breakpoints
- Verify hover/focus states
- Quick accessibility scan
- Report: [OK] or [WARNING]
### Standard Validation (3-5 minutes)
**For:** Component modifications, feature additions
**Checks:**
- Visual check at all breakpoints
- Test all interactive states
- Keyboard navigation test
- Basic performance check
- Report: [OK], [WARNING], or [ERROR]
### Comprehensive Validation (10-15 minutes)
**For:** New components, major refactors
**Checks:**
- Complete visual review (all 8 categories)
- Full interaction testing
- Cross-browser testing
- Accessibility audit
- Performance profiling
- Report: Detailed findings with fixes
---
## Examples of Automatic Invocation
### Example 1: Adding a Button
```
User: "Add a submit button to the form"
Assistant: [Adds button code]
→ TRIGGER: Invoke frontend-design skill
→ VALIDATE: Button appears correctly, hover states work, accessible
→ REPORT: "[OK] Submit button added and validated"
```
### Example 2: Styling Update
```
User: "Change the header background to blue"
Assistant: [Updates CSS]
→ TRIGGER: Invoke frontend-design skill
→ VALIDATE: Blue renders correctly, contrast is readable, responsive
→ REPORT: "[OK] Header background updated and validated"
```
### Example 3: Component Refactor
```
User: "Refactor the navigation component"
Assistant: [Refactors code]
→ TRIGGER: Invoke frontend-design skill
→ VALIDATE: Navigation still works, styles intact, mobile menu functions
→ REPORT: "[OK] Navigation refactored and validated"
OR
"[WARNING] Mobile menu broken - fixing..."
```
---
## Integration with Other Agents
### Coordination with Code Review Agent
**Code Review Agent:**
- Checks code quality (readability, maintainability)
- Checks security (XSS, injection vulnerabilities)
- Checks performance (algorithmic complexity)
**Frontend Design Skill:**
- Checks visual correctness (layout, colors, fonts)
- Checks UX functionality (interactions, responsiveness)
- Checks accessibility (WCAG compliance)
**Both must approve before UI changes are finalized.**
### Coordination with Testing Agent
**Testing Agent:**
- Runs automated tests (unit, integration, e2e)
- Validates functionality programmatically
- Checks for regressions
**Frontend Design Skill:**
- Validates visual/UX manually
- Checks design quality and aesthetics
- Ensures accessibility compliance
**Complementary validation approaches.**
---
## Decision Matrix
### PASS - Approve Changes
- All critical validations passed
- No major issues detected
- Minor observations noted but don't block
- Ready for code review/testing
**Report Format:**
```markdown
## UI Validation: PASSED
**Component:** Button Component
**Changes:** Added hover animation
**Validation Results:**
- [OK] Visual appearance correct
- [OK] Interactive behavior working
- [OK] Responsive at all breakpoints
- [OK] Accessibility requirements met
```
### WARN - Approve with Notes
- Minor issues detected
- Issues fixed during validation
- Recommendations for improvement
- Can proceed but note improvements
**Report Format:**
```markdown
## UI Validation: WARNINGS
**Component:** Navigation Menu
**Changes:** Updated styles
**Validation Results:**
- [OK] Visual appearance correct
- [WARNING] Minor transition timing issue
- [OK] Responsive at all breakpoints
- [OK] Accessibility requirements met
**Issues Found:**
1. Hover transition too slow (500ms → 200ms) - FIXED
```
### BLOCK - Require Fixes
- Critical functionality broken
- Accessibility violations (WCAG A/AA)
- Visual appearance significantly wrong
- Responsive layout broken
- Performance severely degraded
**Report Format:**
```markdown
## UI Validation: ERRORS
**Component:** Login Form
**Changes:** Added validation
**Validation Results:**
- [ERROR] Interactive behavior broken
- [ERROR] Accessibility violations
- [WARNING] Responsive issues on mobile
**Critical Issues:**
1. CRITICAL: Submit button not clickable
2. CRITICAL: No keyboard accessibility
3. MAJOR: Mobile layout broken
**Status:** BLOCKED - fixes required
```
---
## Benefits
### 1. Consistent Quality
- Every UI change is validated
- No "ship and hope" for visual changes
- Quality gate before code review
### 2. Catch Issues Early
- Visual bugs caught before testing phase
- Accessibility issues identified immediately
- Responsive problems detected upfront
### 3. Better User Experience
- Interactions work correctly
- Responsive behavior validated
- Accessibility ensured
### 4. Reduced Rework
- Issues fixed during development
- Fewer back-and-forth with designers
- Less QA rejection
### 5. Learning & Improvement
- Validation reports document common issues
- Patterns emerge for prevention
- Team learns best practices
---
## Common Issues Detected
### Most Frequent Issues
1. **Missing hover states** - Interactive elements without feedback
2. **Insufficient contrast** - Text/background fails WCAG
3. **Broken mobile layouts** - Responsive breakpoints not tested
4. **No keyboard accessibility** - Focus states missing
5. **Slow animations** - Performance issues on mobile
6. **Missing alt text** - Accessibility violations
7. **Text overflow** - Long content breaks layout
8. **Click targets too small** - Mobile usability issues
### Prevention Strategies
**From Validation Insights:**
- Always add hover/focus states together
- Test contrast ratios during color selection
- Mobile-first development approach
- Include keyboard testing in workflow
- Use CSS transforms for animations
- Alt text checklist for all images
- Text overflow handling by default
- Minimum 44x44px touch targets
---
## Usage Guide
### For Developers Using Main Claude
**After ANY UI change:**
1. **Expect automatic validation** - Frontend skill will be invoked
2. **Review validation report** - Check for [OK], [WARNING], or [ERROR]
3. **Address issues if found** - Apply fixes or ask for help
4. **Get final approval** - Both frontend and code review must pass
### For Main Claude (Coordinator)
**When UI code is modified:**
1. **Recognize UI change** - Any HTML/CSS/JSX/styling code
2. **Invoke frontend-design skill** - Use Skill tool
3. **Receive validation report** - Parse results
4. **Act on findings:**
- [OK] → Proceed to code review
- [WARNING] → Note issues, proceed
- [ERROR] → Fix issues before proceeding
**Example Coordination:**
```
User: "Add dark mode toggle"
Main Claude: [Writes dark mode code]
Main Claude: [Invokes frontend-design skill]
Frontend Skill: [Validates - finds contrast issue]
Frontend Skill: [Fixes contrast issue]
Frontend Skill: [Returns PASS report]
Main Claude: [Proceeds to code review]
```
---
## Files Modified/Created
### Modified Files
1. **`.claude/skills/frontend-design/SKILL.md`**
- Updated metadata description
- Added "CRITICAL: Automatic Invocation Triggers" section (120+ lines)
- Added validation workflow
- Added examples and integration notes
### Created Files
2. **`.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md`** (NEW)
- 8 validation categories
- 200+ checkpoint items
- 3 validation workflows
- Report formats
- Common issues guide
3. **`.claude/skills/frontend-design/AUTOMATIC_VALIDATION_ENHANCEMENT.md`** (NEW - this file)
- Enhancement documentation
- Usage guide
- Benefits and metrics
- Integration details
---
## Configuration
**No configuration needed.** The frontend-design skill now has automatic invocation built into its guidelines.
**Skill Location:** `.claude/skills/frontend-design/`
**Verify Skill Available:**
```bash
# Check skill exists
ls .claude/skills/frontend-design/SKILL.md
# View skill metadata
head -n 10 .claude/skills/frontend-design/SKILL.md
```
---
## Success Metrics
Track these to validate enhancement effectiveness:
### Quality Metrics
- **UI bugs caught pre-release** - Should increase
- **Accessibility violations** - Should decrease to near zero
- **QA rejection rate** - Should decrease
- **User-reported UI issues** - Should decrease
### Process Metrics
- **Time to fix UI issues** - Faster (caught earlier)
- **Rework cycles** - Fewer (issues caught first time)
- **Validation coverage** - Higher (automatic invocation)
### User Satisfaction
- **Designer feedback** - Better alignment with designs
- **User feedback** - Fewer UI complaints
- **Accessibility compliance** - WCAG AA or higher
---
## Testing Recommendations
### Test Scenario 1: Simple CSS Change
```
User: "Make the button text bold"
Expected: Quick validation (1-2 min), PASS report
```
### Test Scenario 2: New Component
```
User: "Create a card component with image, title, and description"
Expected: Standard validation (3-5 min), comprehensive report
```
### Test Scenario 3: Broken Layout
```
User: "Add flexbox to the grid layout"
[Code has error that breaks layout]
Expected: Comprehensive validation, ERROR report with fixes
```
### Test Scenario 4: Accessibility Issue
```
User: "Add icon-only buttons to the toolbar"
[Code missing ARIA labels]
Expected: BLOCK report for accessibility violations
```
---
## Future Enhancements
Potential improvements:
1. **Automated Screenshot Capture**
- Take screenshots at key breakpoints
- Visual regression testing
- Before/after comparisons
2. **Lighthouse Integration**
- Automatic Lighthouse audits
- Performance scoring
- Accessibility scoring
3. **Design Token Validation**
- Verify CSS variables used correctly
- Check against design system
- Flag hardcoded values
4. **AI-Powered Visual Comparison**
- Compare to design mockups
- Detect visual differences
- Flag unexpected changes
5. **Validation Metrics Dashboard**
- Track validation pass/fail rates
- Common issues trending
- Team performance metrics
---
## Rollback
If needed, revert to previous version:
```bash
git diff HEAD~1 .claude/skills/frontend-design/SKILL.md
git checkout HEAD~1 .claude/skills/frontend-design/SKILL.md
```
**Note:** Keep checklist and enhancement docs for future reference.
---
## Related Files
- **Skill Config:** `.claude/skills/frontend-design/SKILL.md`
- **Validation Checklist:** `.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md`
- **Code Review Agent:** `.claude/agents/code-review.md`
- **Testing Agent:** `.claude/agents/testing.md`
- **Coding Guidelines:** `.claude/CODING_GUIDELINES.md`
---
**Last Updated:** 2026-01-17
**Status:** COMPLETED & READY FOR USE
**Enhanced By:** Claude Code
**User Requirement:** "Any time any action affects a UI item, call frontend to validate the UI is working/appearing/behaving correctly."

177
.claude/skills/frontend-design/LICENSE.txt Normal file
View File

@@ -0,0 +1,177 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS

163
.claude/skills/frontend-design/SKILL.md Normal file
View File

@@ -0,0 +1,163 @@
---
name: frontend-design
description: Create distinctive, production-grade frontend interfaces with high design quality. MANDATORY AUTOMATIC INVOCATION: Use this skill whenever ANY action affects a UI element to validate visual correctness, functionality, and user experience. Also use when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
license: Complete terms in LICENSE.txt
---
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
## CRITICAL: Automatic Invocation Triggers
**This skill MUST be invoked automatically whenever ANY action affects a UI element.**
### When to Invoke This Skill
**MANDATORY Triggers - Invoke this skill for:**
1. **UI Creation**
- Creating new web pages, components, or interfaces
- Building dashboards, forms, or layouts
- Designing landing pages or marketing sites
- Generating HTML/CSS/React/Vue code
2. **UI Modification**
- Changing styles, colors, fonts, or layouts
- Updating component appearance or behavior
- Refactoring frontend code
- Adding animations or interactions
3. **UI Validation (CRITICAL)**
- **After ANY code change that affects UI**
- After updating styles or markup
- After adding features to UI components
- After refactoring frontend code
- After fixing UI bugs
### Purpose of Automatic Invocation
**When invoked for validation, this skill:**
1. **Verifies Visual Correctness**
- Layout renders as expected
- Spacing and alignment are correct
- Colors and fonts display properly
- Responsive behavior works
2. **Checks Functionality**
- Interactive elements work (buttons, forms, links)
- Animations trigger correctly
- State changes reflect visually
- Event handlers fire properly
3. **Validates User Experience**
- Navigation flows logically
- Feedback is clear (hover states, loading indicators)
- Accessibility features work
- Mobile/responsive layout functions
4. **Ensures Design Quality**
- Visual hierarchy is clear
- Aesthetic direction is maintained
- No generic AI patterns introduced
- Polished, production-ready appearance
### Validation Workflow
When invoked for UI validation after changes:
```markdown
1. REVIEW: What UI elements were changed?
2. ASSESS: How should they appear/behave?
3. VALIDATE:
- Visual appearance (layout, colors, fonts, spacing)
- Interactive behavior (hover, click, focus states)
- Responsive behavior (mobile, tablet, desktop)
- Accessibility (keyboard nav, screen readers)
4. REPORT:
- [OK] Working correctly
- [WARNING] Minor issues detected
- [ERROR] Critical issues found
5. FIX: If issues found, provide corrected code
```
### Examples of Automatic Invocation
**Example 1: After Adding Button**
```
User: "Add a submit button to the form"
Assistant: [Adds button code]
→ TRIGGER: Invoke frontend-design skill
→ VALIDATE: Button appears correctly, hover states work, accessible
→ REPORT: "[OK] Submit button added and validated"
```
**Example 2: After Styling Update**
```
User: "Change the header background to blue"
Assistant: [Updates CSS]
→ TRIGGER: Invoke frontend-design skill
→ VALIDATE: Blue renders correctly, contrast is readable, responsive
→ REPORT: "[OK] Header background updated and validated"
```
**Example 3: After Component Refactor**
```
User: "Refactor the navigation component"
Assistant: [Refactors code]
→ TRIGGER: Invoke frontend-design skill
→ VALIDATE: Navigation still works, styles intact, mobile menu functions
→ REPORT: "[OK] Navigation refactored and validated" OR "[WARNING] Mobile menu broken - fixing..."
```
### Integration with Other Agents
**Coordination with Code Review Agent:**
- Code Review Agent checks code quality/security
- Frontend Skill checks visual/UX correctness
- Both must approve before UI changes are final
**Coordination with Testing Agent:**
- Testing Agent runs automated tests
- Frontend Skill validates visual/UX manually
- Complementary validation approaches
### Rule of Thumb
**If the change appears in a browser, invoke this skill to validate it.**
---
## Design Thinking
Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
- Production-grade and functional
- Visually striking and memorable
- Cohesive with a clear aesthetic point-of-view
- Meticulously refined in every detail
## Frontend Aesthetics Guidelines
Focus on:
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

462
.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md Normal file
View File

@@ -0,0 +1,462 @@
# Frontend UI Validation Checklist
**Purpose:** Use this checklist when frontend-design skill is invoked to validate UI changes.
**Last Updated:** 2026-01-17
---
## When to Use This Checklist
**MANDATORY:** After ANY code change that affects UI elements:
- Creating new UI components
- Modifying existing styles or markup
- Adding features to frontend code
- Refactoring frontend components
- Fixing UI bugs
---
## Validation Categories
### 1. Visual Appearance
**Layout & Structure:**
- [ ] Elements render in correct positions
- [ ] Grid/flexbox layouts work as expected
- [ ] Z-index stacking is correct
- [ ] No unexpected overlaps or gaps
- [ ] Aspect ratios are maintained
- [ ] Images load and display correctly
**Typography:**
- [ ] Fonts load and display correctly
- [ ] Font sizes are appropriate (readability)
- [ ] Line height provides good readability
- [ ] Text alignment is intentional
- [ ] No text overflow or truncation issues
- [ ] Headings have proper hierarchy
**Colors & Contrast:**
- [ ] Colors match design specifications
- [ ] Sufficient contrast for readability (WCAG AA minimum)
- [ ] Color themes (light/dark) work correctly
- [ ] CSS variables applied consistently
- [ ] Gradients render smoothly
- [ ] Transparency/opacity levels correct
**Spacing & Rhythm:**
- [ ] Padding is consistent and intentional
- [ ] Margins create proper visual separation
- [ ] Whitespace enhances readability
- [ ] Vertical rhythm is maintained
- [ ] No cramped or overly sparse areas
- [ ] Spacing scales appropriately
**Visual Effects:**
- [ ] Shadows render correctly (no performance issues)
- [ ] Border-radius values are consistent
- [ ] Background images/patterns display properly
- [ ] Filters (blur, grayscale, etc.) work as expected
- [ ] Decorative elements enhance, don't distract
- [ ] No visual glitches or rendering artifacts
---
### 2. Interactive Behavior
**Click/Tap Interactions:**
- [ ] Buttons respond to clicks
- [ ] Links navigate correctly
- [ ] Forms submit properly
- [ ] Checkboxes/radios toggle
- [ ] Dropdowns open/close
- [ ] Click targets are appropriately sized (minimum 44x44px)
**Hover States:**
- [ ] Hover effects trigger on desktop
- [ ] Cursor changes appropriately (pointer, text, etc.)
- [ ] Visual feedback is clear
- [ ] Transitions are smooth
- [ ] No flickering or jank
- [ ] Tooltips appear when expected
**Focus States:**
- [ ] Focus indicators visible (keyboard navigation)
- [ ] Focus order is logical
- [ ] Focus trap works in modals/dialogs
- [ ] Skip links function correctly
- [ ] Focus doesn't get lost
- [ ] Custom focus styles meet contrast requirements
**Active States:**
- [ ] Pressed/active states provide feedback
- [ ] Buttons show active state during click
- [ ] Form inputs show active state when selected
- [ ] Loading states appear during async operations
**Disabled States:**
- [ ] Disabled elements are visually distinct
- [ ] Disabled elements don't respond to interaction
- [ ] Cursor indicates disabled state
- [ ] Tooltips explain why disabled (if applicable)
---
### 3. Responsive Behavior
**Breakpoints:**
- [ ] Desktop (1920px+) layout works
- [ ] Laptop (1366px-1919px) layout works
- [ ] Tablet landscape (1024px-1365px) layout works
- [ ] Tablet portrait (768px-1023px) layout works
- [ ] Mobile landscape (568px-767px) layout works
- [ ] Mobile portrait (320px-567px) layout works
**Adaptive Layout:**
- [ ] Content reflows appropriately
- [ ] No horizontal scrolling (unless intentional)
- [ ] Touch targets are finger-sized on mobile (44x44px min)
- [ ] Navigation adapts (hamburger menu, etc.)
- [ ] Images scale/crop appropriately
- [ ] Text remains readable at all sizes
**Responsive Typography:**
- [ ] Font sizes scale appropriately
- [ ] Line length stays readable (45-75 characters)
- [ ] Headings scale proportionally
- [ ] No text overflow at any breakpoint
**Mobile-Specific:**
- [ ] Touch gestures work (swipe, pinch, etc.)
- [ ] No hover-dependent interactions
- [ ] Virtual keyboard doesn't obscure inputs
- [ ] Mobile browser chrome accounted for
- [ ] Fixed elements don't interfere with scrolling
---
### 4. Animations & Transitions
**Animation Quality:**
- [ ] Animations run smoothly (60fps)
- [ ] No janky or stuttering motion
- [ ] Timing feels natural (not too slow/fast)
- [ ] Easing curves are appropriate
- [ ] Animation-delay creates stagger effect (if intended)
**Performance:**
- [ ] Animations use transform/opacity (GPU-accelerated)
- [ ] No layout thrashing
- [ ] Will-change used appropriately (if needed)
- [ ] Animations don't block interactions
- [ ] Reduce motion preference respected
**Transition States:**
- [ ] Enter animations work
- [ ] Exit animations work
- [ ] State transitions are smooth
- [ ] Loading spinners/skeletons appear
- [ ] No flash of unstyled content (FOUC)
**Scroll Animations:**
- [ ] Scroll-triggered animations fire correctly
- [ ] Parallax effects are subtle, not nauseating
- [ ] Sticky elements stick at right position
- [ ] Scroll progress indicators update
- [ ] Smooth scroll behavior works
---
### 5. Accessibility
**Keyboard Navigation:**
- [ ] All interactive elements are keyboard accessible
- [ ] Tab order is logical
- [ ] Enter/Space activate buttons/links
- [ ] Escape closes modals/dropdowns
- [ ] Arrow keys navigate menus/lists (if applicable)
- [ ] No keyboard traps
**Screen Reader Support:**
- [ ] Semantic HTML used (header, nav, main, article, etc.)
- [ ] ARIA labels on icons/buttons without text
- [ ] ARIA live regions for dynamic content
- [ ] Form inputs have associated labels
- [ ] Error messages are announced
- [ ] Skip links present
**Visual Accessibility:**
- [ ] Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
- [ ] Color isn't the only indicator (use icons/text too)
- [ ] Focus indicators are highly visible
- [ ] Text can be resized to 200% without breaking layout
- [ ] No content hidden by fixed elements
**Alternative Content:**
- [ ] Images have descriptive alt text
- [ ] Decorative images have empty alt=""
- [ ] Icons have labels or tooltips
- [ ] Videos have captions/transcripts
- [ ] Complex graphics have text alternatives
---
### 6. Performance
**Load Performance:**
- [ ] Critical CSS inlined (if applicable)
- [ ] Fonts load efficiently (font-display: swap)
- [ ] Images lazy-loaded (below fold)
- [ ] No render-blocking resources
- [ ] First contentful paint is fast (<2s)
**Runtime Performance:**
- [ ] No layout shifts (CLS near 0)
- [ ] Smooth scrolling (no jank)
- [ ] Animations run at 60fps
- [ ] No memory leaks
- [ ] Event handlers don't block main thread
**Resource Optimization:**
- [ ] Images optimized (WebP, compression)
- [ ] CSS is minified (in production)
- [ ] JavaScript is minified (in production)
- [ ] Unused CSS removed
- [ ] Critical resources preloaded
---
### 7. Cross-Browser Compatibility
**Modern Browsers:**
- [ ] Chrome/Edge (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Mobile Safari (iOS)
- [ ] Chrome Mobile (Android)
**Fallbacks:**
- [ ] Graceful degradation for older browsers
- [ ] Feature detection (not browser sniffing)
- [ ] Polyfills loaded if needed
- [ ] CSS fallbacks for modern features (grid, flexbox)
- [ ] No JavaScript errors in console
---
### 8. Content & Copy
**Text Quality:**
- [ ] No typos or grammatical errors
- [ ] Placeholder text replaced with real content
- [ ] Proper capitalization (title case, sentence case)
- [ ] Consistent voice and tone
- [ ] Microcopy is helpful and clear
**Internationalization:**
- [ ] Text doesn't break layout in longer languages
- [ ] RTL support if needed
- [ ] Date/number formatting appropriate
- [ ] No hardcoded strings (use i18n keys)
---
## Validation Workflow
### Quick Validation (Simple Changes)
For minor changes like color updates or spacing tweaks:
1. Visual check at 1-2 breakpoints
2. Verify hover/focus states
3. Quick accessibility scan
4. Report: [OK] or [WARNING]
**Time:** 1-2 minutes
### Standard Validation (Component Changes)
For component modifications or feature additions:
1. Visual check at all breakpoints
2. Test all interactive states
3. Keyboard navigation test
4. Basic performance check
5. Report: [OK], [WARNING], or [ERROR]
**Time:** 3-5 minutes
### Comprehensive Validation (New Features)
For new components or major refactors:
1. Complete visual review (all categories above)
2. Full interaction testing
3. Cross-browser testing
4. Accessibility audit
5. Performance profiling
6. Report: Detailed findings with fixes
**Time:** 10-15 minutes
---
## Validation Report Format
### Success Report
```markdown
## UI Validation: PASSED
**Component:** [Component name]
**Changes:** [Brief description]
**Validation Results:**
- [OK] Visual appearance correct
- [OK] Interactive behavior working
- [OK] Responsive at all breakpoints
- [OK] Accessibility requirements met
**Notes:** [Any observations or recommendations]
```
### Warning Report
```markdown
## UI Validation: WARNINGS
**Component:** [Component name]
**Changes:** [Brief description]
**Validation Results:**
- [OK] Visual appearance correct
- [WARNING] Minor hover state issue detected
- [OK] Responsive at all breakpoints
- [OK] Accessibility requirements met
**Issues Found:**
1. **Minor: Hover state transition**
- **Problem:** Transition is too slow (500ms)
- **Fix:** Reduce to 200ms for better UX
- **Fixed:** Yes
**Status:** Issues resolved, ready to proceed
```
### Error Report
```markdown
## UI Validation: ERRORS
**Component:** [Component name]
**Changes:** [Brief description]
**Validation Results:**
- [OK] Visual appearance correct
- [ERROR] Interactive behavior broken
- [WARNING] Responsive issues on mobile
- [ERROR] Accessibility violations
**Critical Issues:**
1. **CRITICAL: Button click handler not working**
- **Problem:** Event listener not attached
- **Impact:** Form cannot be submitted
- **Fix Required:** Add onClick handler
2. **CRITICAL: Missing keyboard accessibility**
- **Problem:** Modal cannot be closed with Escape
- **Impact:** Keyboard users trapped
- **Fix Required:** Add keydown listener
**Status:** BLOCKED - fixes required before proceeding
```
---
## Common Issues to Watch For
### Layout Issues
- Flexbox/grid container missing
- Z-index conflicts
- Overflow hidden cutting off content
- Fixed positioning causing mobile issues
### Typography Issues
- Font not loading (fallback showing)
- Line-height too tight/loose
- Text overflow not handled
- Inconsistent font weights
### Color Issues
- Insufficient contrast
- Theme not applied consistently
- CSS variable not defined
- Color only indicator (accessibility)
### Interaction Issues
- Event handler not attached
- Hover state persisting on mobile
- Focus outline removed without replacement
- Click target too small
### Responsive Issues
- Breakpoint gaps (768.5px edge cases)
- Images not scaling
- Text wrapping awkwardly
- Mobile menu not working
### Animation Issues
- Animating width/height (use transform)
- No will-change on expensive animations
- Animations running on page load (jarring)
- Reduce motion not respected
### Accessibility Issues
- Missing alt text
- No keyboard focus indicators
- Color contrast too low
- ARIA labels missing
---
## Decision Matrix: Pass, Warn, or Block
### PASS - Approve Changes
- All critical validations passed
- No major issues detected
- Minor observations noted but don't block
- Ready for code review/testing
### WARN - Approve with Notes
- Minor issues detected
- Issues fixed during validation
- Recommendations for improvement
- Can proceed but note improvements
### BLOCK - Require Fixes
- Critical functionality broken
- Accessibility violations (WCAG A/AA)
- Visual appearance significantly wrong
- Responsive layout broken
- Performance severely degraded
---
## Integration with Other Tools
**Works alongside:**
- Code Review Agent (checks code quality)
- Testing Agent (runs automated tests)
- Browser DevTools (performance profiling)
- Lighthouse (accessibility/performance audits)
- Screen readers (NVDA, JAWS, VoiceOver)
**Reports to:**
- Main Claude (coordination)
- Code Review Agent (combined approval)
- User (final validation)
---
**Remember:** This skill is invoked AUTOMATICALLY for ANY UI change. Quick validations keep velocity high while ensuring quality.