Astro Components Skill

Purpose

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

Scope

✅ Use For	❌ NOT For
Marketing sites	Web apps
Lead gen pages	Dashboards
Service websites	E-commerce carts

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

Element	Use	Never
<button>	Actions, toggles	<div onclick>
<a>	Navigation	<span onclick>
<input>	Form data	Contenteditable div

Rule: If it does something → <button>. If it goes somewhere → <a>.

Component Variants

Fixed variants only. Claude cannot invent new variants.

Component	Allowed Variants
Button	primary, secondary, outline, ghost
Card	default, elevated, outlined
Badge	default, success, warning, error, info
Alert	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

Allowed	Forbidden
client:visible islands	Inline onclick
Astro actions	<script> in component
Separate .ts files	Any DOM manipulation

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

Rule	Requirement
Label	Always visible, linked via for
Placeholder	Hint only, never replaces label
Error	Below input, role="alert"
Required	Visual indicator (*) + required attr

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