Components

Core Rules

1. Always Use the Component Library

Never create custom components. Use only the provided components from Windmill's library. If you need functionality that doesn't exist, request it from the design system team.

2. No Style Hacking

Do not override component styles. Components provide props for all supported variants and configurations. If you need a different appearance, use the appropriate prop variant.

// ✅ Correct - use provided variants
<Button variant="primary" size="large">Submit</Button>

// ❌ Wrong - don't add custom styles
<Button class="bg-red-500 px-8">Submit</Button>

3. Check Guidelines First

Always consult these component guidelines before implementing. Each component section specifies:

• When to use each variant
• Proper implementation patterns
• Accessibility requirements
• Common mistakes to avoid

Quick Reference

Before You Code

1. Check if a component exists for your use case
2. Read the component's specific guidelines
3. Use only the documented props and variants
4. Test accessibility with keyboard navigation

Buttons

Windmill uses 4 button types with clear hierarchy. Each button type comes in 3 variants (text, icon+text, icon-only) and supports multiple states including hover, active, disabled, and selected (default and subtle only).

Accent Button

Use only for the most important action of the page/CTA. Avoid having multiple accent buttons in the same view.

Accent Secondary Button

Use exclusively for main Call-to-Action (CTA) buttons. Reserved for the primary conversion action on landing pages and marketing materials.

Default Button

Use for most actions. This is your primary button type for standard interactions.

Subtle Button

Use with care, only in areas where it is clear that the element is a button, next to other buttons for example.

Button Hierarchy:

• Accent Secondary (Highest Priority): Main conversion CTAs on landing pages - "Sign up", "Get started", "Download"
• Accent (High Priority): Most important action per view - "Save", "Submit", "Create" (only one per screen)
• Default (Standard Priority): Secondary actions and most UI interactions - "Cancel", "Edit", "Delete"
• Subtle (Low Priority): Tertiary actions in dense interfaces - toolbars, button groups

Button States:

• Default: Standard button appearance
• Hover: Interactive feedback when cursor hovers over button
• Active/Pressed: Visual feedback when button is clicked or pressed
• Disabled: Non-interactive state for unavailable actions
• Selected: Active selection state (available only for Default and Subtle variants)

Usage Rules:

• ✅ Use appropriate hierarchy, provide tooltips for icon-only buttons, test all states including disabled and selected
• ❌ Don't use multiple Accent buttons per view, use Accent Secondary outside marketing, create custom styles, or use selected state on Accent variants

Implementation Notes

When implementing any component:

1. Follow the design system: Use only the components and variants documented here
2. Accessibility first: All components include built-in accessibility features
3. Test thoroughly: Verify functionality across different states and themes
4. Ask questions: When in doubt, consult the design system team before creating custom solutions