Design System
Complete design tokens, components, and patterns for recommend.ai
Introduction
This design system is built on Tailwind CSS v4 and follows modern accessibility standards (WCAG 2.1 AA). It provides a consistent, scalable foundation for building recommend.ai's user interface.
Design Principles
- Accessible: WCAG 2.1 AA compliant with proper contrast, keyboard navigation, and screen reader support
- Consistent: Unified design language across all touchpoints
- Responsive: Mobile-first approach with touch-friendly targets (min 44x44px)
- Performant: Optimized for speed with smooth transitions and reduced motion support
Colors
Our color palette is designed to work in both light and dark modes, with all colors meeting WCAG 2.1 AA contrast requirements.
Semantic Colors
Typography
We use Inter as our primary typeface for its excellent readability and modern aesthetic.
Spacing Scale
Consistent spacing creates visual harmony and improves scanability.
Border Radius
Rounded corners soften the interface and create a friendly, modern feel.
Shadows
Subtle shadows create depth and hierarchy in the interface.
Inputs
Form inputs allow users to enter and edit text data.
Default
<Label>Email address</Label>
<Input type="email" placeholder="you@example.com" />With Error
Password must be at least 8 characters
Disabled
- Always pair inputs with labels using htmlFor attribute
- Use aria-invalid and aria-describedby for error states
- Focus ring has 2px width with proper contrast
- Placeholder text meets 4.5:1 contrast ratio
Cards
Cards contain content and actions about a single subject.
Simple Card
This is a simple card with a title and description. Cards provide a clean container for content.
Card with Action
Cards can contain actions and interactive elements.
<Card>
<CardHeader>
<CardTitle>Card Title</CardTitle>
<CardDescription>Card description</CardDescription>
</CardHeader>
<CardContent>
{/* Content here */}
</CardContent>
<CardFooter>
<Button>Action</Button>
</CardFooter>
</Card>Badges
Badges are used to label, categorize, or organize items using keywords.
<Badge variant="default">Default</Badge>
<Badge variant="secondary">Secondary</Badge>
<Badge variant="destructive">Destructive</Badge>
<Badge variant="outline">Outline</Badge>Tabs
Tabs organize content into separate views where only one view can be visible at a time.
This is the overview tab content. Tabs help organize related information into digestible sections.
This is the features tab content. Users can navigate between tabs to find the information they need.
This is the pricing tab content. Each tab maintains its own state and content.
<Tabs defaultValue="overview">
<TabsList>
<TabsTrigger value="overview">Overview</TabsTrigger>
<TabsTrigger value="features">Features</TabsTrigger>
<TabsTrigger value="pricing">Pricing</TabsTrigger>
</TabsList>
<TabsContent value="overview">...</TabsContent>
<TabsContent value="features">...</TabsContent>
<TabsContent value="pricing">...</TabsContent>
</Tabs>- Use arrow keys to navigate between tabs
- Tabs use proper ARIA roles and states
- Active tab has visual indicator and aria-selected
Accordion
Accordions allow users to expand and collapse sections of content.
<Accordion type="single" collapsible>
<AccordionItem value="item-1">
<AccordionTrigger>Question</AccordionTrigger>
<AccordionContent>Answer</AccordionContent>
</AccordionItem>
</Accordion>Switch
Switches toggle between two mutually exclusive states.
<Switch />
<Switch checked={true} />Skeleton
Skeletons provide a placeholder while content is loading.
<Skeleton className="h-6 w-48" />
<Skeleton className="h-4 w-full" />
<Skeleton className="h-4 w-3/4" />Solution Card
Solution cards display AI tools in the catalog with all relevant information.
Advanced AI chatbot for natural conversations and task assistance
Key Features:
- Natural language understanding
- Code generation and debugging
<Card>
<CardHeader>
<CardTitle>{solution.name}</CardTitle>
<div className="flex items-center gap-2">
<Badge>{solution.category}</Badge>
<span>{solution.pricing}</span>
</div>
<CardDescription>{solution.description}</CardDescription>
</CardHeader>
<CardContent>
<div className="flex items-center gap-1">
<Star /> {solution.rating}
</div>
</CardContent>
<CardFooter>
<Button>View Details</Button>
</CardFooter>
</Card>- Rating has proper aria-label describing the score
- External links indicate they open in new tab
- Hover states provide clear visual feedback
- Focus ring visible on all interactive elements
Layout Patterns
Common layout patterns used throughout the application.
Responsive Breakpoints
| Breakpoint | Value | Usage |
|---|---|---|
| sm | 640px | Small devices |
| md | 768px | Tablets |
| lg | 1024px | Laptops |
| xl | 1280px | Desktops |
| 2xl | 1536px | Large desktops |
Container Widths
Maximum width for main content areas to ensure optimal readability:
- Small: 640px - For focused content
- Medium: 768px - For forms and articles
- Large: 1024px - For general pages
- Extra Large: 1280px - For catalog grids
Accessibility
Our design system is built with accessibility at its core, ensuring all users can effectively use our platform.
Color Contrast
All color combinations meet WCAG 2.1 AA standards:
- Normal text: 4.5:1 minimum
- Large text: 3:1 minimum
- UI components: 3:1 minimum
Keyboard Navigation
All interactive elements are keyboard accessible:
- Tab to navigate forward
- Shift + Tab to navigate backward
- Enter/Space to activate
- Arrow keys for menus and tabs
Touch Targets
All interactive elements meet minimum size requirements:
- Buttons: 44x44px minimum
- Input fields: 44px height
- Links: Adequate spacing
Screen Readers
Semantic HTML and ARIA attributes ensure compatibility:
- Proper heading hierarchy
- Descriptive labels and alt text
- ARIA landmarks and roles
- Live regions for dynamic content