---
name: tailwind
description: This skill should be used when working with Tailwind CSS styling in the ISA-Frontend project. Use it when writing component styles, choosing color values, applying typography, creating buttons, or determining appropriate spacing and layout utilities. Essential for maintaining design system consistency.
---

# ISA Tailwind Design System

## Overview

Assist with applying the ISA-specific Tailwind CSS design system throughout the ISA-Frontend Angular monorepo. This skill provides comprehensive knowledge of custom utilities, color palettes, typography classes, button variants, and layout patterns specific to this project.

## When to Use This Skill

Invoke this skill when:
- **After** checking `libs/ui/**` for existing components (always check first!)
- Styling layout and spacing for components
- Choosing appropriate color values for custom elements
- Applying typography classes to text content
- Determining spacing, layout, or responsive breakpoints
- Customizing or extending existing UI components
- Ensuring design system consistency
- Questions about which Tailwind utility classes are available

**Important**: This skill provides Tailwind utilities. Always prefer using components from `@isa/ui/*` libraries before applying custom Tailwind styles.

**Works together with:**
- **[angular-template](../angular-template/SKILL.md)** - Angular template syntax, control flow (@if, @for, @defer), and binding patterns
- **[html-template](../html-template/SKILL.md)** - E2E testing attributes (`data-what`, `data-which`) and ARIA accessibility

When building Angular components, these three skills work together:
1. Use **angular-template** for Angular syntax and control flow
2. Use **html-template** for `data-*` and ARIA attributes
3. Use **tailwind** (this skill) for styling with the ISA design system

## Core Design System Principles

### 0. Component Libraries First (Most Important)

**Always check `libs/ui/**` for existing components before writing custom Tailwind styles.**

The project has 17 specialized UI component libraries:
- `@isa/ui/buttons` - Button components
- `@isa/ui/dialogs` - Dialog/modal components
- `@isa/ui/inputs` - Input field components
- `@isa/ui/forms` - Form components
- `@isa/ui/cards` - Card components
- `@isa/ui/layout` - Layout components (including breakpoint service)
- `@isa/ui/tables` - Table components
- And 10+ more specialized libraries

**Workflow**:
1. First, search for existing components in `libs/ui/**` that match your needs
2. If found, import and use the component (prefer composition over custom styling)
3. Only use Tailwind utilities for:
   - Layout/spacing adjustments
   - Component-specific customizations
   - Cases where no suitable UI component exists

**Example**:
```typescript
// ✅ Correct - Use existing component
import { ButtonComponent } from '@isa/ui/buttons';

// ❌ Wrong - Don't recreate with Tailwind
<button class="btn btn-accent-1">...</button>
```

### 1. ISA-Prefixed Colors Only

**Always use `isa-*` prefixed color utilities.** Other color names exist only for backwards compatibility and should not be used in new code.

**Correct color usage**:
- `bg-isa-accent-red`, `bg-isa-accent-blue`, `bg-isa-accent-green`
- `bg-isa-secondary-100` through `bg-isa-secondary-900`
- `bg-isa-neutral-100` through `bg-isa-neutral-900`
- `text-isa-white`, `text-isa-black`

**Example**:
```html
<!-- ✅ Correct -->
<div class="bg-isa-accent-red text-isa-white">Error message</div>
<button class="bg-isa-secondary-600 hover:bg-isa-secondary-700">Action</button>

<!-- ❌ Wrong - deprecated colors -->
<div class="bg-accent-1 text-accent-1-content">...</div>
<div class="bg-brand">...</div>
```

### 2. ISA-Prefixed Typography

Always use ISA typography classes instead of arbitrary font sizes:
- **Headings**: `.isa-text-heading-1-bold`, `.isa-text-heading-2-bold`, `.isa-text-heading-3-bold`
- **Subtitles**: `.isa-text-subtitle-1-bold`, `.isa-text-subtitle-2-bold`
- **Body**: `.isa-text-body-1-regular`, `.isa-text-body-1-bold`, `.isa-text-body-2-regular`, `.isa-text-body-2-bold`
- **Captions**: `.isa-text-caption-regular`, `.isa-text-caption-bold`, `.isa-text-caption-caps`

### 3. Responsive Design with Breakpoint Service

Prefer the breakpoint service from `@isa/ui/layout` for reactive breakpoint detection:

```typescript
import { breakpoint, Breakpoint } from '@isa/ui/layout';

// In component
isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.DekstopXL]);
```

```html
@if (isDesktop()) {
  <div class="desktop-layout">...</div>
}
```

Only use Tailwind breakpoint utilities (`isa-desktop:`, `isa-desktop-l:`, `isa-desktop-xl:`) when the breakpoint service is not appropriate (e.g., pure CSS solutions).

## Quick Reference

### Typography Selection Guide

**Headings**:
- Large hero text: `.isa-text-heading-1-bold` (60px)
- Section headers: `.isa-text-heading-2-bold` (48px)
- Subsection headers: `.isa-text-heading-3-bold` (40px)

**Subtitles**:
- Prominent subtitles: `.isa-text-subtitle-1-bold` (28px)
- Section labels: `.isa-text-subtitle-2-bold` (16px, uppercase)

**Body Text**:
- Standard text: `.isa-text-body-1-regular` (16px)
- Emphasized text: `.isa-text-body-1-bold` (16px)
- Smaller text: `.isa-text-body-2-regular` (14px)
- Smaller emphasized: `.isa-text-body-2-bold` (14px)

**Captions**:
- Small labels: `.isa-text-caption-regular` (12px)
- Small emphasized: `.isa-text-caption-bold` (12px)
- Uppercase labels: `.isa-text-caption-caps` (12px, uppercase)

Each variant has `-big` and `-xl` responsive sizes for larger breakpoints.

### Color Selection Guide

**Always use `isa-*` prefixed colors. Other colors are deprecated.**

**Status/Accent Colors**:
- Success/Confirm: `bg-isa-accent-green`
- Error/Danger: `bg-isa-accent-red`
- Primary/Info: `bg-isa-accent-blue`

**Brand Secondary Colors** (100 = lightest, 900 = darkest):
- Very light: `bg-isa-secondary-100`, `bg-isa-secondary-200`
- Light: `bg-isa-secondary-300`, `bg-isa-secondary-400`
- Medium: `bg-isa-secondary-500`, `bg-isa-secondary-600`
- Dark: `bg-isa-secondary-700`, `bg-isa-secondary-800`
- Very dark: `bg-isa-secondary-900`

**Neutral UI** (100 = lightest, 900 = darkest):
- Light backgrounds: `bg-isa-neutral-100`, `bg-isa-neutral-200`, `bg-isa-neutral-300`
- Medium backgrounds: `bg-isa-neutral-400`, `bg-isa-neutral-500`, `bg-isa-neutral-600`
- Dark backgrounds/text: `bg-isa-neutral-700`, `bg-isa-neutral-800`, `bg-isa-neutral-900`

**Basic Colors**:
- White: `bg-isa-white`, `text-isa-white`
- Black: `bg-isa-black`, `text-isa-black`

**Example Usage**:
```html
<!-- Status indicators -->
<div class="bg-isa-accent-green text-isa-white">Success</div>
<div class="bg-isa-accent-red text-isa-white">Error</div>

<!-- Backgrounds -->
<div class="bg-isa-neutral-100">Light surface</div>
<div class="bg-isa-secondary-600 text-isa-white">Brand element</div>
```

### Spacing Patterns

**Component Padding**:
- Cards: `p-card` (20px) or `p-5` (1.25rem)
- General spacing: `p-4` (1rem), `p-6` (1.5rem), `p-8` (2rem)
- Tight spacing: `p-2` (0.5rem), `p-3` (0.75rem)

**Gap/Grid Spacing**:
- Tight spacing: `gap-2` (0.5rem), `gap-3` (0.75rem)
- Medium spacing: `gap-4` (1rem), `gap-6` (1.5rem)
- Wide spacing: `gap-8` (2rem), `gap-10` (2.5rem)
- Split screen: `gap-split-screen`

**Note**: Prefer Tailwind's standard rem-based spacing (e.g., `p-4`, `gap-6`) over pixel-based utilities (`px-*`) for better scalability and accessibility.

**Layout Heights**:
- Split screen tablet: `h-split-screen-tablet`
- Split screen desktop: `h-split-screen-desktop`

### Z-Index Layering

Apply semantic z-index values for proper layering:
- Dropdowns: `z-dropdown` (50)
- Sticky elements: `z-sticky` (100)
- Fixed elements: `z-fixed` (150)
- Modal backdrops: `z-modalBackdrop` (200)
- Modals: `z-modal` (250)
- Popovers: `z-popover` (300)
- Tooltips: `z-tooltip` (350)

## Common Styling Patterns

**Important**: These are examples for when UI components don't exist. Always check `@isa/ui/*` libraries first!

### Layout Spacing (Use Tailwind)
```html
<!-- Container with padding -->
<div class="p-6">
  <h2 class="isa-text-heading-2-bold mb-4">Section Title</h2>
  <div class="flex flex-col gap-4">
    <!-- Content items -->
  </div>
</div>
```

### Grid Layout (Use Tailwind)
```html
<!-- Responsive grid with gap -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  <!-- Grid items -->
</div>
```

### Card Layout (Prefer @isa/ui/cards if available)
```html
<div class="bg-isa-white p-5 rounded shadow-card">
  <h3 class="isa-text-subtitle-1-bold mb-4">Card Title</h3>
  <p class="isa-text-body-1-regular">Card content...</p>
</div>
```

### Form Group (Prefer @isa/ui/forms if available)
```html
<div class="flex flex-col gap-2">
  <label class="isa-text-body-2-semibold text-isa-black">Field Label</label>
  <!-- Use component from @isa/ui/inputs if available -->
  <input class="shadow-input rounded border border-isa-neutral-400 p-2.5" />
</div>
```

### Button Group (Use @isa/ui/buttons)
```typescript
// ✅ Preferred - Use component library
import { ButtonComponent } from '@isa/ui/buttons';
```

```html
<div class="flex gap-4">
  <!-- Use actual button components from @isa/ui/buttons -->
  <isa-button variant="primary">Save</isa-button>
  <isa-button variant="secondary">Cancel</isa-button>
</div>
```

### Split Screen Layout (Use Tailwind)
```html
<div class="grid grid-cols-split-screen gap-split-screen h-split-screen-desktop">
  <aside class="bg-isa-neutral-100 p-5">Sidebar</aside>
  <main class="bg-isa-white p-8">Content</main>
</div>
```

## Resources

### references/design-system.md

Comprehensive reference documentation containing:
- Complete color palette with hex values
- All typography class specifications
- Button plugin CSS custom properties
- Spacing and layout utilities
- Border radius, shadows, and z-index values
- Custom variants and best practices

Load this reference when:
- Looking up specific hex color values
- Determining exact typography specifications
- Understanding button CSS custom properties
- Finding less common utility classes
- Verifying available shadow or radius utilities

## Best Practices

1. **Component libraries first**: Always check `libs/ui/**` before writing custom Tailwind styles
2. **ISA-prefixed colors only**: Always use `isa-*` colors (e.g., `bg-isa-accent-red`, `text-isa-neutral-700`)
3. **Use rem over px**: Prefer Tailwind's default rem-based spacing (e.g., `p-4`, `gap-6`) over pixel-based utilities
4. **Typography system**: Never use arbitrary font sizes - always use `.isa-text-*` classes
5. **Breakpoints**: Use breakpoint service from `@isa/ui/layout` for logic
6. **Z-index**: Always use semantic z-index utilities, never arbitrary values
7. **Consistency**: Always use design system utilities instead of arbitrary values

## Anti-Patterns to Avoid

❌ **Don't** use deprecated colors (backwards compatibility only):
```html
<div class="bg-accent-1">...</div> <!-- Wrong - deprecated -->
<div class="bg-brand">...</div> <!-- Wrong - deprecated -->
<div class="bg-surface">...</div> <!-- Wrong - deprecated -->
<div class="bg-isa-secondary-600">...</div> <!-- Correct -->
```

❌ **Don't** use arbitrary values when utilities exist:
```html
<p class="text-[16px]">Text</p> <!-- Wrong -->
<p class="isa-text-body-1-regular">Text</p> <!-- Correct -->
```

❌ **Don't** hardcode hex colors:
```html
<div class="bg-[#DF001B]">...</div> <!-- Wrong -->
<div class="bg-isa-accent-red">...</div> <!-- Correct -->
```

❌ **Don't** recreate components with Tailwind:
```html
<button class="btn btn-accent-1">...</button> <!-- Wrong - use @isa/ui/buttons -->
<isa-button variant="primary">...</isa-button> <!-- Correct -->
```

❌ **Don't** use arbitrary z-index:
```html
<div class="z-[999]">...</div> <!-- Wrong -->
<div class="z-modal">...</div> <!-- Correct -->
```

✅ **Do** leverage the component libraries and ISA design system for consistency and maintainability.
