juspay/vira / .agents/skills/vira-design
vira-design
VerifiedVira's design system — TailwindCSS conventions, color palette, typography, spacing, components, and accessibility rules. Use when working on UI components, styling, or layout in this project (Lucid HTML in Haskell sources under packages/vira).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.8 KB |
SKILL.md
View on GitHub---
name: vira-design
description: Vira's design system — TailwindCSS conventions, color palette, typography, spacing, components, and accessibility rules. Use when working on UI components, styling, or layout in this project (Lucid HTML in Haskell sources under packages/vira).
---
# Vira Design System
Clean, minimal CI/CD application design system emphasizing clarity and functionality.
## Design Principles
- **KISS (Keep It Simple)**: Minimal, focused design without unnecessary decoration
- **Flat Design**: Clean layouts with selective elevation for hierarchy
- **Technical Clarity**: Clear visual communication over visual flourishes
## Color Palette
### Primary Colors
- **Brand accent**: `brand-600` (primary actions), `brand-700` (hover states). The `brand-*` scale is declared in `packages/vira/src/style.css` as a `@theme` alias to Tailwind's cyan today — change those `var(--color-cyan-*)` aliases to shift the brand without touching widget code.
- **Background**: `gray-50` (page), `white` (cards), `gray-200` (dividers)
- **Dark mode**: `gray-900` (page), `gray-800` (cards), `gray-700` (dividers)
### Semantic Colors
- **Success**: `green-600` (success actions)
- **Destructive**: `red-600` (delete/dangerous actions)
- **Warning**: `yellow-500` (cautionary states)
- **Secondary**: `gray-100` (secondary actions)
- **Dark mode**: `gray-700` (secondary actions)
### Neutrals
- **Text**: `gray-900` (primary), `gray-600` (secondary), `gray-500` (muted)
- **Dark mode**: `gray-100` (primary), `gray-300` (secondary), `gray-400` (muted)
- **Borders**: `gray-200` (default), `gray-300` (interactive)
- **Dark mode**: `gray-700` (default), `gray-600` (interactive)
- **Backgrounds**: `gray-50` (sections), `gray-100` (subtle contrast)
- **Dark mode**: `gray-800` (sections), `gray-700` (subtle contrast)
## Typography
### Font Families
- **Sans-serif**: Geist (variable font, 300-700 weights), system-ui fallbacks
- **Monospace**: Geist Mono (for logs, code, and technical values)
Tokens are declared as `--font-sans` / `--font-mono` in `packages/vira/src/style.css` (the Tailwind v4 input file). Generated `static/tailwind.css` exposes them via `font-sans` / `font-mono` utility classes — prefer those over hard-coded `font-family` declarations.
### Size Scale
| Class | Size | Usage |
| ----------- | ---- | ---------------------------------------------------- |
| `text-xs` | 12px | Badges, table headers (uppercase), tertiary metadata |
| `text-sm` | 14px | Body text, form labels, buttons, timestamps |
| `text-base` | 16px | Breadcrumbs, emphasized body content |
| `text-lg` | 18px | Card subheadings, section descriptions |
| `text-xl` | 20px | Section headers (h2, h3) |
| `text-2xl` | 24px | Page headers (h1) |
### Weight Guidelines
| Weight | Class | Usage |
| ------ | --------------- | ----------------------------------------- |
| 500 | `font-medium` | Badges, subtle emphasis, secondary labels |
| 600 | `font-semibold` | Buttons, tab labels, highlighted text |
| 700 | `font-bold` | All headings (h1-h3), important values |
### Patterns
```haskell
-- Page headers (h1)
h1_ [class_ "text-2xl font-bold text-gray-900 dark:text-gray-100"]
-- Section headers (h2)
h2_ [class_ "text-xl font-bold text-gray-900 dark:text-gray-100 mb-4"]
-- Buttons
button_ [class_ "text-sm font-semibold"]
-- Badges
span_ [class_ "text-xs font-medium"]
-- Table headers
th_ [class_ "text-xs font-medium uppercase tracking-wider"]
```
## Spacing
### Scale
| Class | Size | Common Usage |
| ----- | ---- | ---------------------------------- |
| `1` | 4px | Icon margins, tight gaps |
| `2` | 8px | Badge padding, inline spacing |
| `3` | 12px | Button padding (vertical) |
| `4` | 16px | Card content margins, section gaps |
| `6` | 24px | Section spacing, card padding |
| `8` | 32px | Page section dividers |
### Component Patterns
| Component | Pattern |
| ----------------- | --------------------------------------------------------- |
| **Cards** | `p-6` (content), `mb-6` (between cards) |
| **Buttons** | `px-6 py-3` (primary), `px-4 py-2` (secondary) |
| **Badges** | `px-2 py-1` or `px-3 py-1` |
| **Form groups** | `space-y-6` (between groups), `mb-2` (label to input) |
| **Page sections** | `space-y-6` or `mb-8` |
| **Inline items** | `space-x-2` (tight), `space-x-4` (normal), `gap-4` (flex) |
### Border Radius
| Class | Usage |
| -------------- | ------------------------------------ |
| `rounded` | Small elements, code blocks |
| `rounded-lg` | **Default** - buttons, cards, inputs |
| `rounded-full` | Badges, pills, avatars |
| `rounded-xl` | Large feature cards, modals |
## Components
**All components are defined in `src/Vira/Widgets/*.hs` with full documentation and usage examples.**
### Core Components
- **Buttons**: `viraButton_`, `viraButtonIcon_` (see `Button.hs`)
- **Cards**: `viraCard_` (flat), `viraCardElevated_` (with shadow) (see `Card.hs`)
- **Layout**: `viraSection_`, `viraPageHeader_`, `viraDivider_` (see `Layout.hs`)
- **Forms**: `viraInput_`, `viraLabel_` (see `Form.hs`)
- **Status**: `viraStatusBadge_` (see `Status.hs`)
- **Alerts**: `viraAlert_` (see `Alert.hs`)
### Usage
```haskell
import Vira.Widgets qualified as W
W.viraButton_ W.ButtonPrimary [] $ do
W.viraButtonIcon_ $ toHtmlRaw Icon.plus
"Add Repository"
```
## Icons
- **Library**: Tabler Icons (`Web.TablerIcons.Outline`)
- **Standard sizes**: `w-4 h-4` (buttons), `w-5 h-5` (UI), `w-6 h-6` (headers), `w-8 h-8` (sections), `w-16 h-16` (hero)
- **Centering**: Always use `flex items-center justify-center`
## Visual Hierarchy
- **Elevation**: Flat by default, `shadow-sm` only for important content
- **Spacing**: Consistent spacing scale using Tailwind (`space-y-*`)
- **Typography**: Clear text hierarchy with `text-3xl`, `text-lg`, etc.
- **Color**: Semantic colors communicate meaning, not decoration
## Layout
- **Responsive**: Mobile-first with `md:`, `lg:`, `xl:` breakpoints
- **Grid**: `grid gap-6 md:grid-cols-2 lg:grid-cols-3`
- **Container**: `container mx-auto` with responsive padding
## Accessibility Guidelines
### Color Contrast
- **Primary text**: `text-gray-900` (high contrast)
- **Secondary text**: `text-gray-600` (medium contrast)
- **Muted text**: `text-gray-500` (minimum contrast)
- **Avoid**: `text-gray-400` (insufficient contrast)
### Interactive Elements
- **Focus states**: Clear ring indicators for keyboard navigation
- **Button text**: High contrast white on colored backgrounds
- **Icon colors**: Use `text-gray-500` minimum for functional icons
### Small Text Guidelines
- **Extra small text** (`text-xs`): Use `text-gray-600` minimum
- **Regular text**: Can use `text-gray-500` for secondary information
- **Interactive labels**: Always use `text-gray-600` or darker
## Dark Mode
Vira implements automatic dark mode using Tailwind's `@media (prefers-color-scheme: dark)` strategy. Dark mode activates based on system preferences without any JavaScript or configuration.
### Dark Mode Guidelines
1. **Always add dark variants** - When using gray colors, always include `dark:` variants
2. **Use semantic opacity** - Use opacity for tinted backgrounds (e.g., `dark:bg-red-900/20`)
3. **Maintain contrast** - Ensure text remains readable in both modes
4. **Test both modes** - Always verify styling in light and dark modes
### Common Dark Mode Patterns
```haskell
-- Backgrounds
"bg-white dark:bg-gray-800"
"bg-gray-50 dark:bg-gray-900"
"bg-gray-100 dark:bg-gray-700"
-- Borders
"border-gray-200 dark:border-gray-700"
"border-gray-300 dark:border-gray-600"
-- Text
"text-gray-900 dark:text-gray-100"
"text-gray-600 dark:text-gray-300"
"text-gray-500 dark:text-gray-400"
-- Semantic colors with opacity
"bg-red-50 dark:bg-red-900/20"
"bg-blue-50 dark:bg-blue-900/20"
```
## Guidelines
1. **KISS Principle** - Avoid unnecessary abstractions and complexity
2. **Accessibility First** - Follow WCAG contrast requirements
3. **Dark Mode** - Always include `dark:` variants for gray colors
4. **Use existing widgets** - Check `Widgets/*.hs` first
5. **Follow naming** - `vira[ComponentName]_` pattern
6. **Accept attributes** - `[Attributes]` parameter for extensibility
7. **Minimal shadows** - Only use elevation when creating meaningful hierarchy
8. **No gradients** - Prefer solid colors for clarity and performance
---
**Refer to `src/Vira/Widgets/*.hs` for complete component documentation and implementation details.**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |