name	xanbzs-frontend-specialist
description	XanBZS design system expert for implementing, validating, and migrating Tamagui and shadcn components with automated compliance checking

XanBZS Frontend Specialist

A comprehensive frontend development skill for the XanBZS FinTech platform that understands the complete design system, validates component compliance, and assists with implementation and migration of Tamagui and shadcn/ui components.

Capabilities

Component Implementation: Create new components following Tamagui or shadcn patterns with proper theme tokens
Design System Validation: Automatically validate components against spacing, color, and accessibility rules
Migration Support: Convert shadcn components to Tamagui when appropriate with migration guidance
Theme Token Usage: Ensure proper usage of CSS variables and Tailwind v4 theme tokens
Accessibility Validation: Check WCAG compliance for contrast, touch targets, and focus states
Glassmorphism & Effects: Apply dark mode glassmorphism and glow effects correctly (small components only)
Auto-fixing: Run validation tools and apply safe fixes automatically
Component Audit: Scan entire directories for design system compliance

Design System Knowledge

Dual-Theme Strategy

Light Mode: "Clean Finance"

Solid colors, warm gray scale, minimal effects
Focus on clarity, trust, and accessibility
WCAG AA+ compliant (4.5:1 minimum contrast)

Dark Mode: "Advanced Futuristic Tech - Midnight Blue"

Deep saturated midnight blue background (hsl(228 45% 12%))
Glassmorphism effects, enhanced glows, gradient combinations
Focus on visual interest and depth
WCAG AAA compliant (7:1+ contrast)

Color System

Primary Colors:

Light: Sapphire 600 hsl(221 82% 48%) #2563EB → bg-primary
Dark: Plasma Blue hsl(221 84% 66%) #3C83F6 → bg-primary

Secondary Colors:

Light: Cyan hsl(204 85% 54%) #3B9DD4 → bg-secondary
Dark: Cyan hsl(204 86% 62%) #22D3EE → bg-secondary

Semantic Colors:

Success: hsl(154 65% 45%) → bg-success
Warning: hsl(35 88% 55%) → bg-warning
Destructive: hsl(350 75% 52%) → bg-destructive
Purple: hsl(271 91% 65%) → bg-purple (Tron Purple)
Pink: hsl(327 87% 67%) → bg-pink (Pulse Pink)

Modern Spacing System

Component Sizing:

Cards: p-8 (32px) default, p-6 small, p-10 large
Buttons: h-12 (48px) default, h-10 small, h-14 large
Inputs: h-12 (48px) default with px-4 py-3 padding
Badges: h-7 px-3 py-1.5 (28px min height)

Touch Targets:

Minimum: 44x44px (WCAG AAA)
Recommended: 48x48px (buttons, inputs)

Component Libraries

Tamagui (src/tamagui/ui/)

Cross-platform (React Native + Web)
Use theme tokens: $primary, $background, $4, etc.
Priority for new features

Shadcn (src/components/ui/)

Web-only components
Use Tailwind classes: bg-primary, text-foreground, etc.
Legacy system, migrate to Tamagui when appropriate

Input Requirements

For Component Implementation

Required:

Component type (Button, Card, Input, Badge, etc.)
Target platform (Web, Mobile, Cross-platform)
Variant requirements (primary, secondary, size variants)

Optional:

Specific design requirements
Accessibility needs
Animation/interaction patterns
Dark mode behavior

For Validation

Required:

File path(s) to validate
Validation scope (single file, directory, full repository)

Optional:

Safety level for auto-fixes (safe, medium, risky)
Specific validation categories (colors, spacing, wcag, dark_mode)
Dry-run mode for preview

For Migration

Required:

Source file path (shadcn component)
Target component library (Tamagui)

Optional:

Migration strategy (progressive, complete)
Breaking change tolerance
Test coverage requirements

Output Formats

Component Implementation

Complete TypeScript component files
Tamagui styled() components with variants
Proper YAML frontmatter and exports
Usage examples with proper imports
Accessibility annotations (ARIA attributes, roles)

Validation Reports

Compliance score (0-100)
Categorized violations:
- Colors (hardcoded values, deprecated classes)
- Spacing (old padding/height values)
- WCAG (contrast, touch targets, focus states)
- Dark mode (glassmorphism misuse, missing dark: prefixes)
Suggested fixes with safety levels
Auto-fix preview or applied changes

Migration Guidance

Step-by-step migration plan
Breaking changes analysis
Component API mapping (shadcn → Tamagui)
Test cases for validation
Rollback strategy

Validation Tools Integration

This skill integrates with XanBZS validation tooling:

Location: /Users/jay/dev/kiro/xanbzs/scripts/theme/

Available Commands:

Single File Validation:

python3 scripts/theme/1-validation/validate-component.py <file>

Repository Scan:

python3 scripts/theme/1-validation/scan-repo.py --path src/components/

Complete Workflow:

./scripts/theme/bin/run-full-workflow.sh

Validation Categories:

colors - Color classes, hex, HSL violations
spacing - Padding, height, sizing violations
wcag - Contrast, focus, accessibility violations
layout - Transform effects, pattern violations
dark_mode - Glassmorphism, isDark check violations

Safety Levels:

safe - Auto-fixable (color classes, spacing)
medium - Review recommended (HSL colors, patterns)
risky - Manual review required (ARIA labels, complex logic)

Shadcn MCP Integration

This skill integrates with the shadcn MCP server for component discovery and installation from custom registries.

Available MCP Tools

1. Get Project Registries

mcp__shadcn-mcp__get_project_registries

Returns configured registry names from components.json
Returns error if no components.json exists (use init_project to create)
Note: If you can't see @my-patterns, run: shadcn-patterns (alias to start local registry server)

2. Search Items in Registries (PRIORITY TOOL)

mcp__shadcn-mcp__search_items_in_registries

Search for components using fuzzy matching
Registry Priority: @my-patterns → @reui → @blocks → shadcn (default)
Requires components.json to be configured
After finding an item, use get_item_examples_from_registries to see usage examples
Fallback: If @my-patterns fails, ensure local server is running (shadcn-patterns alias)

3. Get Item Examples from Registries

mcp__shadcn-mcp__get_item_examples_from_registries

Shows examples and demos with full implementation and dependencies
Workflow: Install dependencies → Use code for the component
Provides complete implementation details

4. Get Audit Checklist (MANDATORY FINAL STEP)

mcp__shadcn-mcp__get_audit_checklist

Verify if everything works after installation/implementation
ALWAYS run after all required steps
Validates component integration and dependencies

Registry Configuration

The XanBZS project uses custom registries defined in components.json:

{
  "registries": {
    "@my-patterns": {
      "url": "http://localhost:3000/r/{name}.json"
    },
    "@reui": {
      "url": "https://reui.io/r/{name}.json"
    },
    "@blocks": "https://blocks.so/r/{name}.json"
  }
}

Component Installation Workflow

Standard Workflow:

Search for component: search_items_in_registries (check @my-patterns, @reui, @blocks first)
Get examples: get_item_examples_from_registries (review implementation and dependencies)
Install dependencies: Install any required packages from examples
Implement component: Use provided code with XanBZS theme tokens
Audit: get_audit_checklist (verify everything works)

Registry Fallback:

If @my-patterns registry fails, ensure local server is running: shadcn-patterns
Check registry availability before searching
Use get_project_registries to confirm configuration

Tamagui Template Library

Location: docs/tamagui/templates/config.json

The project has a comprehensive Tamagui template library with 23+ exported modules:

Categories:

Animation: Buttons, Microinteractions, Slide, Avatars
Elements: Avatars, Buttons, Cards (GlassCard, StatCard), Chips, Status Badges, Datepickers, Dialogs, List, Pickers, Tables
Forms: Inputs (10+ variants), Checkboxes, Radio Groups, Switches, Textareas, Layouts (Multi-step Wizard, Sign-in/Sign-up screens)
E-commerce: Payment, Product List, Product Page
Shells: Navbars, Tabbars

Usage Pattern:

Browse templates in config.json (lookup by category/key)
Copy only needed components (no bulk copies)
Place in correct folder (src/tamagui/ui/_shared/ or src/tamagui/<feature>/ui/)

Tamagui Official Documentation

Complete Documentation: https://tamagui.dev/llms-full.txt (single document for LLMs)

Core Concepts:

Animations - Animation system and utilities
Configuration - Config options and setup
Styled - Styled component system
Theme - Theming system
Tokens - Design tokens ($primary, $4, etc.)
Variants - Component variants system
Use Media - Media query hooks
Use Theme - Theme hooks

Essential Components:

Button - Customizable button with variants
Card - Container for grouped content
Input - Text input components
Dialog - Modal dialog component
Sheet - Bottom sheet/modal
Form - Form components and validation
Checkbox - Selection control
RadioGroup - Radio button group
Select - Dropdown selection
Switch - Toggle switch
Tabs - Tabbed interface
Accordion - Expandable sections
Avatar - User avatar display
Badge - Status badges (via Shapes)
Separator - Visual dividers
Progress - Progress indicators
Slider - Range input
Toast - Notifications
Tooltip - Informational tooltips
Popover - Floating content

Layout & Typography:

Stacks - XStack, YStack, ZStack layout
Text - Text display component
Headings - H1-H6 typography
ScrollView - Scrollable container
Group - Component grouping

Advanced Components:

AlertDialog - Important action dialogs
Portal - Render in different DOM locations
VisuallyHidden - Accessible hidden content
LinearGradient - Gradient backgrounds
Image - Image component
ListItem - List item component
Spinner - Loading indicators

Compiler & Performance:

Compiler Installation - Setup guide
Why a Compiler? - Benefits
Benchmarks - Performance metrics

Reference Pattern: When implementing Tamagui components, always reference official docs for:

Component API (props, variants, events)
Theme token usage ($primary, $background, $space, etc.)
Accessibility patterns (ARIA attributes, keyboard nav)
Cross-platform considerations (web vs native)

Shadcn Component Status

Migration Status: ✅ All 35 core shadcn components migrated (Nov 2024)

Key Migrations Completed:

All components updated with dark mode glassmorphism
Consistent text color hierarchy (white → white/90 → white/70)
Proper contrast for stacked divs
Dark mode borders (dark:border-border/50)

Component Library Prioritization:

New features: Use Tamagui ONLY (cross-platform)
Existing shadcn components: Migrate to Tamagui when refactoring
Web-only features: Can use shadcn but prefer Tamagui when possible
Do NOT mix: Avoid mixing shadcn and Tamagui in same feature

Scripts

This skill uses Python integration to run validation tools and process results:

validate_component.py: Validates component files against design system rules
process_violations.py: Categorizes and prioritizes violations
apply_fixes.py: Applies safe automated fixes to components
migration_helper.py: Assists with shadcn → Tamagui migrations

How to Use

Component Implementation

"Create a Tamagui Button component with primary, secondary, and ghost variants following XanBZS design system"

"Implement a Card component with proper dark mode glassmorphism effects for small badges"

"Build a responsive Input component with validation states (error, success) using Tamagui"

Validation Workflows

"Validate all components in src/components/ui/ against the design system"

"Check if this Button component follows proper spacing and color token usage"

"Run full validation workflow and apply safe fixes to spacing violations"

Migration Tasks

"Migrate src/components/ui/button.tsx from shadcn to Tamagui"

"Analyze breaking changes for converting shadcn Dialog to Tamagui Sheet"

Best Practices

Component Development

Start with Design System Reference: Always consult THEME.md and DESIGN_SYSTEM_GUIDE.md
Use Semantic Tokens: Prefer bg-primary over bg-blue-500
Mobile-First Responsive: Use Tamagui's responsive props ($sm, $md, $lg)
Accessibility First: Include ARIA attributes, keyboard navigation, focus states
Test Both Themes: Validate components in light and dark modes

Validation Workflow

Scan Before Fix: Always run validation before applying fixes
Preview First: Use --dry-run to preview changes
Process by Safety: Apply safe fixes first, review medium/risky manually
Verify After: Re-scan after fixes to confirm compliance
Git Workflow: Commit validation results separately from fixes

Migration Strategy

Incremental Migration: Migrate feature-by-feature, not all at once
Test Coverage: Ensure tests exist before migration
API Compatibility: Document breaking changes clearly
Rollback Plan: Use git branches for safe rollback
Co-location: Keep old and new components side-by-side during transition

Glassmorphism Rules

ONLY in Dark Mode:

Small components only (badges, pills, tags)
Use dark: prefix for all glassmorphism classes
Proper backdrop-blur and saturation

NEVER:

Large components (cards, dialogs, sheets)
Light mode glassmorphism
Buttons (use dark backgrounds with colored borders instead)

Reference Files

Primary Documentation

/Users/jay/dev/kiro/xanbzs/THEME.md - Quick theme reference
/Users/jay/dev/kiro/xanbzs/docs/frontend/DESIGN_SYSTEM_GUIDE.md - Complete design system
/Users/jay/dev/kiro/xanbzs/docs/tamagui/component-library.md - Tamagui patterns

Validation Tools

/Users/jay/dev/kiro/xanbzs/scripts/theme/AI_GUIDE.md - AI validation guide
/Users/jay/dev/kiro/xanbzs/scripts/theme/WORKFLOW.md - Validation workflow
/Users/jay/dev/kiro/xanbzs/scripts/theme/1-validation/validate-component.py - Validator

Expert System

/Users/jay/dev/kiro/xanbzs/AGENTS_TAMAGUI.md - Tamagui expert system prompt
/Users/jay/dev/kiro/xanbzs/src/index.css - Tailwind v4 theme tokens

Limitations

Validation Scope

Validation rules are hardcoded in Python (not template-based detection)
New validation rules require Python code changes
Some complex patterns may require manual review

Migration Constraints

Not all shadcn components have direct Tamagui equivalents
Some web-specific features (right-click menus) don't translate to mobile
Breaking changes may require refactoring consuming code

Platform Differences

Tamagui components must be React Native-safe (no DOM APIs)
Web-only features require separate implementations
Some CSS features (backdrop-filter) have limited mobile support

Accessibility Notes

Automated tools can't catch all accessibility issues
Manual testing with screen readers still required
Color contrast validation is algorithmic, not perceptual

Example Patterns

Tamagui Button with Variants

import { styled, Button as TamaguiButton } from 'tamagui'

export const Button = styled(TamaguiButton, {
  name: 'Button',
  height: '$12', // 48px
  paddingHorizontal: '$6',
  paddingVertical: '$3',
  borderRadius: '$4',
  fontWeight: '500',

  variants: {
    variant: {
      primary: {
        backgroundColor: '$primary',
        color: '$white',
        hoverStyle: {
          backgroundColor: '$primary',
          opacity: 0.9,
        },
      },
      secondary: {
        backgroundColor: '$secondary',
        color: '$white',
        hoverStyle: {
          backgroundColor: '$secondary',
          opacity: 0.9,
        },
      },
      ghost: {
        backgroundColor: 'transparent',
        color: '$primary',
        hoverStyle: {
          backgroundColor: '$primaryForeground',
          opacity: 0.1,
        },
      },
    },
    size: {
      sm: { height: '$10', paddingHorizontal: '$5', paddingVertical: '$2.5' },
      md: { height: '$12', paddingHorizontal: '$6', paddingVertical: '$3' },
      lg: { height: '$14', paddingHorizontal: '$8', paddingVertical: '$4' },
    },
  } as const,

  defaultVariants: {
    variant: 'primary',
    size: 'md',
  },
})

Dark Mode Glassmorphism Badge

<span className="px-3 py-1.5 h-7 inline-flex items-center gap-2
  bg-primary/10 text-primary border border-primary/20
  dark:bg-[hsla(221,84%,66%,0.15)] dark:backdrop-blur-xl
  dark:border-[hsla(221,84%,66%,0.5)] dark:text-white
  dark:shadow-[0_0_20px_hsla(221,84%,66%,0.3)]
  rounded-md font-medium">
  Premium
</span>

Validation Workflow Example

from xanbzs_frontend_specialist import validate_component, apply_fixes

# 1. Validate component
result = validate_component(
    file_path="src/components/ui/button.tsx",
    categories=["colors", "spacing", "wcag"]
)

# 2. Review violations
for violation in result.violations_categorized:
    print(f"{violation['category']}: {violation['pattern']} → {violation['replacement']}")

# 3. Apply safe fixes
fixes = apply_fixes(
    file_path="src/components/ui/button.tsx",
    safety_level="safe",
    dry_run=True  # Preview first
)

# 4. Apply for real
if confirm_fixes(fixes):
    apply_fixes(
        file_path="src/components/ui/button.tsx",
        safety_level="safe",
        dry_run=False
    )

Integration with XanBZS Project

This skill is specifically designed for the XanBZS FinTech application located at: /Users/jay/dev/kiro/xanbzs

Active Project Context:

Component libraries: Tamagui (priority) + shadcn (legacy)
Theme system: Tailwind v4 with @theme directive
Validation tools: Python-based automated compliance checking
Migration strategy: Progressive shadcn → Tamagui conversion

When working on XanBZS:

Always reference project-specific documentation
Run validation tools from project root
Follow existing component patterns in src/tamagui/ui/
Check AGENTS_TAMAGUI.md for detailed Tamagui guidance
Use validation workflow for all component changes

Install Skill

SKILL.md

XanBZS Frontend Specialist

Capabilities

Design System Knowledge

Dual-Theme Strategy

Color System

Modern Spacing System

Component Libraries

Input Requirements

For Component Implementation

For Validation

For Migration

Output Formats

Component Implementation

Validation Reports

Migration Guidance

Validation Tools Integration

Shadcn MCP Integration

Available MCP Tools

Registry Configuration

Component Installation Workflow

Tamagui Template Library

Tamagui Official Documentation

Shadcn Component Status

Scripts

How to Use

Component Implementation

Validation Workflows

Migration Tasks

Best Practices

Component Development

Validation Workflow

Migration Strategy

Glassmorphism Rules

Reference Files

Primary Documentation

Validation Tools

Expert System

Limitations

Validation Scope

Migration Constraints

Platform Differences

Accessibility Notes

Example Patterns

Tamagui Button with Variants

Dark Mode Glassmorphism Badge

Validation Workflow Example

Integration with XanBZS Project