Astro Components Skill

Purpose

Provides reusable UI components. Does NOT handle sections, layouts, or business logic.

Scope

Core Rules

1. All styling via design-tokens — No hardcoded colors/spacing
2. Token missing = build error — Never fallback to arbitrary values
3. Mobile-first — Base styles for mobile,

   md:

   for larger
4. 44px minimum touch targets — All interactive elements
5. Zero external dependencies — Pure Astro + Tailwind only

Semantic HTML Rules

<button>

<div onclick>

<a>

<span onclick>

<input>

Rule: If it does something →

<button>

<a>

Component Variants

Fixed variants only. Claude cannot invent new variants.

primary

secondary

outline

ghost

default

elevated

outlined

default

success

warning

error

info

info

success

warning

error

New variant needed? → Update this skill first, then use.

Props Pattern (All Components)

interface Props {
  variant?: 'primary' | 'secondary';  // Explicit union, no string
  size?: 'sm' | 'md' | 'lg';          // Fixed sizes only
  class?: string;                      // Allow extension
  // ... component-specific
}

const { variant = 'primary', size = 'md' } = Astro.props;

JavaScript Rules

client:visible

onclick

<script>

.ts

Exception: None. If JS needed, use island architecture.

Icon Handling

// If icon name not found → render nothing + console.warn
const path = icons[name];
if (!path) {
  console.warn(`Icon "${name}" not found`);
  return null;
}

No silent failures. Missing icon = visible warning in dev.

Form Components

for

role="alert"

*

required

Component Boundaries

Components must NOT:

• Fetch data
• Format/transform data
• Access global state
• Import other components (except Icon)
• Contain business logic

Rule: Component receives props → renders UI. Nothing else.

File Structure

src/components/ui/
├── Button.astro
├── Input.astro
├── Card.astro
├── Badge.astro
├── Alert.astro
├── Icon.astro
└── index.ts

Forbidden

• ❌ External UI libraries
• ❌ Hardcoded colors/spacing
• ❌ Touch targets under 44px
• ❌ Missing focus states
• ❌ Inline JavaScript
• ❌ Inventing new variants
• ❌ Silent failures

References

• button.md — Button component code
• input.md — Input component code
• card.md — Card component code
• icon.md — Icon component + full icon list

Definition of Done

• Uses design-tokens only
• All interactive: focus states + 44px touch
• TypeScript Props interface
• No inline JavaScript
• Tested on mobile 375px