ISA-Frontend/.claude/skills/tailwind/SKILL.md

name, description

name	description
tailwind	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.

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:

// ✅ 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:

<!-- ✅ 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:

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

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

@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:

<!-- 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)

<!-- 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)

<!-- 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)

<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)

<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)

// ✅ Preferred - Use component library
import { ButtonComponent } from '@isa/ui/buttons';

<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)

<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):

<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:

<p class="text-[16px]">Text</p> <!-- Wrong -->
<p class="isa-text-body-1-regular">Text</p> <!-- Correct -->

❌ Don't hardcode hex colors:

<div class="bg-[#DF001B]">...</div> <!-- Wrong -->
<div class="bg-isa-accent-red">...</div> <!-- Correct -->

❌ Don't recreate components with Tailwind:

<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:

<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.