Black-Tortoise UI Reviewer

This skill focuses on the Black-Tortoise Angular 20 + Material Design 3 UI stack, identifying and fixing presentation-layer issues at the source code level.

Scope of Application

• Black-Tortoise Angular 20 presentation layer
• Material Design 3 component styles and tokens
• Standalone component templates and SCSS files

Prerequisites

Required

1. Target UI must be reachable

   • Local dev server (e.g., http://localhost:4200, configurable)
   • Staging environment
   • Production environment (read-only reviews)

2. Browser automation must be available

   • Screenshot capture
   • Page navigation
   • DOM information retrieval

3. Access to source code (when making fixes)

   • Project must exist within the workspace
   • Edits must be limited to presentation-layer files

Workflow Overview

flowchart TD
    A[Step 1: Information Gathering] --> B[Step 2: Visual Inspection]
    B --> C[Step 3: Issue Fixing]
    C --> D[Step 4: Re-verification]
    D --> E{Issues Remaining?}
    E -->|Yes| B
    E -->|No| F[Completion Report]

---

Step 1: Information Gathering Phase

1.1 URL Confirmation

If the URL is not provided, ask the user:

Please provide the URL of the website to review (e.g., http://localhost:3000)

1.2 Understanding Project Structure

When making fixes, gather the following information:

Item	Example Question
Framework	Confirm Angular 20 standalone components?
Styling Method	SCSS with Material Design 3 tokens?
Source Location	Which presentation components or styles?
Review Scope	Specific pages only or entire UI?

1.3 Automatic Project Detection

Attempt automatic detection from files in the workspace:

Detection targets:
├── package.json     → Angular 20 + Material + @ngrx/signals
├── angular.json     → Angular CLI configuration
├── src/**/*.scss    → component styles (prefer presentation layer)
├── src/styles/**    → style configuration (M3 tokens if present)
└── src/app/presentation/** → UI source (if present)

1.4 Identifying Styling Method

Method	Detection	Edit Target
SCSS (primary)	src/**/*.scss (presentation first)	Component SCSS files
Global styles	src/styles.scss (if present)	Global SCSS
M3 tokens	src/styles/** (if present)	Token definitions

---

Step 2: Visual Inspection Phase

2.1 Page Traversal

1. Navigate to the specified URL
2. Capture screenshots
3. Retrieve DOM structure/snapshot (if possible)
4. If additional pages exist, traverse through navigation

2.2 Inspection Items

Layout Issues

Issue	Description	Severity
Element Overflow	Content overflows from parent element or viewport	High
Element Overlap	Unintended overlapping of elements	High
Alignment Issues	Grid or flex alignment problems	Medium
Inconsistent Spacing	Padding/margin inconsistencies	Medium
Text Clipping	Long text not handled properly	Medium

Responsive Issues

Issue	Description	Severity
Non-mobile Friendly	Layout breaks on small screens	High
Breakpoint Issues	Unnatural transitions when screen size changes	Medium
Touch Targets	Buttons too small on mobile	Medium

Accessibility Issues

Issue	Description	Severity
Insufficient Contrast	Low contrast ratio between text and background	High
No Focus State	Cannot determine state during keyboard navigation	High
Missing alt Text	No alternative text for images	Medium

Visual Consistency

Issue	Description	Severity
Font Inconsistency	Mixed font families	Medium
Color Inconsistency	Non-unified brand colors	Medium
Spacing Inconsistency	Non-uniform spacing between similar elements	Low

2.3 Viewport Testing (Responsive)

Test at the following viewports:

Name	Width	Representative Device
Mobile	375px	iPhone SE/12 mini
Tablet	768px	iPad
Desktop	1280px	Standard PC
Wide	1920px	Large display

---

Step 3: Issue Fixing Phase

3.1 Issue Prioritization

block-beta
    columns 1
    block:priority["Priority Matrix"]
        P1["P1: Fix Immediately\n(Layout issues affecting functionality)"]
        P2["P2: Fix Next\n(Visual issues degrading UX)"]
        P3["P3: Fix If Possible\n(Minor visual inconsistencies)"]
    end

3.2 Identifying Source Files

Identify source files from problematic elements:

1. Selector-based Search

   • Search codebase by class name or ID
   • Explore style definitions with grep_search

2. Component-based Search

   • Identify components from element text or structure
   • Explore related files with semantic_search

3. File Pattern Filtering

    Style files: src/**/*.scss, src/styles/**
    Components: src/app/presentation/** (if present)
    Pages: src/app/presentation/pages/** (if present)

3.3 Applying Fixes

Framework-specific Fix Guidelines

See references/framework-fixes.md for details.

Fix Principles

1. Minimal Changes: Only make the minimum changes necessary to resolve the issue
2. Respect Existing Patterns: Follow Angular + M3 token usage and existing structure
3. Avoid Breaking Changes: Be careful not to affect other areas
4. Layer Safety: Edit presentation styles/templates only; do not touch domain/application

---

Step 4: Re-verification Phase

4.1 Post-fix Confirmation

1. Reload browser (or wait for development server HMR)
2. Capture screenshots of fixed areas
3. Compare before and after

4.2 Regression Testing

• Verify that fixes haven't affected other areas
• Confirm responsive display is not broken

4.3 Iteration Decision

flowchart TD
    A{Issues Remaining?}
    A -->|Yes| B[Return to Step 2]
    A -->|No| C[Proceed to Completion Report]

Iteration Limit: If more than 3 fix attempts are needed for a specific issue, consult the user

---

Output Format

Review Results Report

# Web Design Review Results

## Summary

| Item | Value |
|------|-------|
| Target URL | {URL} |
| Framework | Angular 20 + Standalone |
| Styling | SCSS + Material Design 3 tokens |
| Tested Viewports | Desktop, Mobile |
| Issues Detected | {N} |
| Issues Fixed | {M} |

## Detected Issues

### [P1] {Issue Title}

- **Page**: {Page path}
- **Element**: {Selector or description}
- **Issue**: {Detailed description of the issue}
- **Fixed File**: `{File path}`
- **Fix Details**: {Description of changes}
- **Screenshot**: Before/After

### [P2] {Issue Title}
...

## Unfixed Issues (if any)

### {Issue Title}
- **Reason**: {Why it was not fixed/could not be fixed}
- **Recommended Action**: {Recommendations for user}

## Recommendations

- {Suggestions for future improvements}

---

Required Capabilities

Capability	Description	Required
Web Page Navigation	Access URLs, page transitions	✅
Screenshot Capture	Page image capture	✅
Image Analysis	Visual issue detection	✅
DOM Retrieval	Page structure retrieval	Recommended
File Read/Write	Source code reading and editing	Required for fixes
Code Search	Code search within project	Required for fixes

---

Reference Implementation

Implementation with Playwright MCP

Playwright MCP is recommended as the reference implementation for this skill.

Capability	Playwright MCP Tool	Purpose
Navigation	browser_navigate	Access URLs
Snapshot	browser_snapshot	Retrieve DOM structure
Screenshot	browser_take_screenshot	Images for visual inspection
Click	browser_click	Interact with interactive elements
Resize	browser_resize	Responsive testing
Console	browser_console_messages	Detect JS errors

Configuration Example (MCP Server)

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--caps=vision"]
    }
  }
}

Other Compatible Browser Automation Tools

Tool	Features
Selenium	Broad browser support, multi-language support
Puppeteer	Chrome/Chromium focused, Node.js
Cypress	Easy integration with E2E testing
WebDriver BiDi	Standardized next-generation protocol

The same workflow can be implemented with these tools. As long as they provide the necessary capabilities (navigation, screenshot, DOM retrieval), the choice of tool is flexible.

---

Best Practices

DO (Recommended)

• ✅ Always save screenshots before making fixes
• ✅ Fix one issue at a time and verify each
• ✅ Use Material Design 3 tokens for styling updates
• ✅ Respect Angular 20 control-flow syntax in templates
• ✅ Document fix details thoroughly

DON'T (Not Recommended)

• ❌ Large-scale refactoring without confirmation
• ❌ Ignoring design systems or brand guidelines
• ❌ Fixes that ignore performance
• ❌ Fixing multiple issues at once (difficult to verify)

---

Troubleshooting

Problem: Style files not found

1. Check dependencies in package.json
2. Consider the possibility of CSS-in-JS
3. Consider CSS generated at build time
4. Ask user about styling method

Problem: Fixes not reflected

1. Check if development server HMR is working
2. Clear browser cache
3. Rebuild if project requires build
4. Check CSS specificity issues

Problem: Fixes affecting other areas

1. Rollback changes
2. Use more specific selectors
3. Consider using CSS Modules or scoped styles
4. Consult user to confirm impact scope