Skip to content

ui.instructions.md

Latest commit

 

History

History
68 lines (48 loc) · 2.32 KB

ui.instructions.md

File metadata and controls

68 lines (48 loc) · 2.32 KB
description Central UI strategy and component development philosophy

UI Component Strategy

This file defines the central UI development strategy for Tailspin Toys. Technology-specific guidance is in separate instruction files.

Component Architecture

Technology Separation

  • Astro (.astro files): Page routing, layouts, static content
  • Svelte (.svelte files): Interactive components, client-side state
  • Tailwind CSS (.css files): Styling via utility classes

Refer to technology-specific instruction files:

Core Principles

Testability

  • Every interactive element MUST include a data-testid attribute
  • Use descriptive test IDs that identify the element's purpose and context
  • Examples: data-testid="game-card-{game.id}", data-testid="submit-button", data-testid="nav-home"

Accessibility

  • Use semantic HTML elements (<nav>, <main>, <article>, <button>)
  • Provide ARIA labels and roles where semantic HTML isn't sufficient
  • Ensure keyboard navigation works for all interactive elements
  • Include visible focus states: focus:ring-2 focus:ring-blue-500 focus:outline-none
  • Maintain sufficient color contrast (especially in dark theme)

Design Consistency

  • Dark theme throughout the application
  • Modern, clean UI with rounded corners and smooth transitions
  • Consistent spacing and visual hierarchy
  • Responsive design that works on mobile, tablet, and desktop

Component Reusability

  • Create reusable components for common UI patterns
  • Keep components focused on a single responsibility
  • Use props for configuration, not duplication
  • Document component APIs with TypeScript types

Development Workflow

  1. Choose the right technology:

    • Static content → Astro
    • Interactivity → Svelte
    • Styling → Tailwind

  2. Follow technology-specific patterns:

    • Refer to the appropriate instruction file

  3. Ensure testability:

    • Add data-testid to all interactive elements

  4. Verify accessibility:

    • Test keyboard navigation
    • Check focus states
    • Validate semantic structure