# Jiffy Design System Rules

Use these rules when building UI for Jiffy Labs. This file can be used as:
- `CLAUDE.md` for Claude Code
- `.cursorrules` for Cursor
- `.windsurfrules` for Windsurf
- Pasted into any AI coding tool's system context

Design system docs: https://arty.jiffylabs.app

## Stack

- Next.js 15 (App Router) + React 19 + TypeScript
- CSS Modules (`.module.css`) -- NOT Tailwind
- Clean structured enterprise design -- NOT glassmorphism
- Design tokens in `src/styles/variables.css`
- Icons: `@radix-ui/react-icons` via `<Icon name="..." />`
- Package manager: `pnpm` only (never npm/npx)

## Color Palette (CSS variables)

```
--color-dark-blue-900: #040E27    (darkest bg)
--color-dark-blue-700: #09132D    (card bg dark)
--color-dark-blue-500: #0E182B    (primary text, buttons)
--color-blue-500: #95ADDA         (secondary, accents)
--color-blue-300: #D7E1F4         (light accent)
--color-blue-200: #E7EEFA         (hover bg, accent bg)
--color-red-500: #FF4E4E          (error, critical)
--color-red-200: #FFC5C5          (error bg, hover shadow)
--color-orange-500: #F5BB53       (warning, caution)
--color-lavender-500: #AA9FF3     (highlight, badge)
--color-pink-500: #FF97BF         (accent)
--color-green-500: #5A935A        (success, trusted)
```

## Elevation

```
--shadow-sm: resting state (cards, inputs)
--shadow-md: hover/active (popovers)
--shadow-lg: modals, dropdowns, elevated panels
--shadow-hover: 4px 4px 0px #FFC5C5 (pink offset -- button hover ONLY)
```

Z-index scale: sidebar (50), dropdown (100), modal (200), toast (300), tooltip (400)

## Theme Variables

```
Light: --background: #fff, --foreground: #0E182B, --card: #fff, --border: rgba(14,24,43,0.20)
Dark:  --background: #040E27, --foreground: #E7EEFA, --card: #09132D, --border: rgba(149,173,218,0.20)
```

## Typography

- Headings: `font-family: var(--font-heading)` (Parkinsans)
- Body: `font-family: var(--font-sans)` (Inter / Google Sans)
- Code: `font-family: var(--font-mono)` (JetBrains Mono)
- Sizes: xs (12px), sm (14px), base (16px), md (18px), lg (22px), xl (44px), 2xl (64px), 3xl (72px)

## Components (import from `@/components`)

### Button
```tsx
<Button variant="standard" size="md">Get a Demo</Button>
<Button variant="transparent">Get started</Button>
<Button variant="outline">Cancel</Button>
<Button variant="icon" size="sm">+</Button>
```
Variants: standard (filled dark blue), transparent, outline, ghost, icon
Sizes: sm, md, lg. Props: darkBg, fullWidth, disabled

### Input
```tsx
<Input label="Email" placeholder="you@company.com" error="Required" />
```
Props: label, error, helperText, inputSize (sm/md/lg), disabled

### Tag
```tsx
<Tag shape="rounded" color="lavender" size="sm">AI Generated</Tag>
```
Shapes: squared, rounded. Colors: blue, darkBlue, red, orange, lavender, pink, green, gray

### Cards
```tsx
<ProofCard value="80%" label="Code reviewed by governance" color="yellow" />
<TestimonialCard text="We needed this." flagColor="red" />
<InfoCard title="Getting Started">Connect your first endpoint.</InfoCard>
```

### Badges
```tsx
<SeverityBadge severity="CRITICAL" />   // CRITICAL, HIGH, MEDIUM, LOW, INFO
<TierBadge tier="TRUSTED" />            // TRUSTED, CAUTION, RISKY, MALICIOUS
<StatusBadge status="healthy" />        // healthy, stale, issues, unknown
```
Use SeverityBadge for findings. TierBadge for trust scores. Tag for everything else.

### Icon
```tsx
import { Icon } from '@/components/Icon/Icon';
<Icon name="dashboard" size={18} />
```
Uses Radix Icons. Available names: dashboard, scan, inventory, detections, baselines, endpoints, graph, outliers, alerts, sessions, history, agents, events, policies, settings, threat-intel, integrations, reports, compliance, close, back, search, upload, trash, download, chevron-right, chevron-down, chevron-left, arrow-right, copy, info, warning, success, no-entry, lock, clock, trend-up, trend-down, check, circle-slash, mcp-server, tool, model, secret, globe, blast-radius, user, shield, lightning, document, monitor, rocket, layers, stopwatch, update, sun, moon

### Logo
```tsx
<Logo theme="light" type="full" size="md" />
<Logo theme="dark" type="icon" size="sm" />
```

### Toast
```tsx
const { showToast } = useToast();
showToast('Scan complete', 'success');  // error, success, info, warning
```

### Tabs
```tsx
<VerticalTabs tabs={[{ id: 'scan', title: 'Scan', content: <div>...</div> }]} />
```

## CSS Module Pattern

```tsx
import styles from './Component.module.css';
export function Component() {
  return <div className={styles.wrapper}>...</div>;
}
```

```css
.wrapper {
  background: var(--card);
  border: 1px solid var(--border);
  border-radius: var(--radius-lg);
  padding: var(--space-6);
}
```

## Patterns

### Error States
- Use Toast for transient errors (auto-dismiss 5s)
- Use TestimonialCard with red flag for inline warnings
- Be specific: "Scan failed -- artifact unreachable" not "Something went wrong"
- Never fail silently. Never show raw HTTP codes to users.

### Loading
- Skeleton placeholders for known layouts (tables, cards)
- Spinner for unknown content size
- Progress bar for scans with known steps
- Never show empty state before loading finishes

### Tags
- SeverityBadge for CRITICAL/HIGH/MEDIUM/LOW/INFO
- TierBadge for TRUSTED/CAUTION/RISKY/MALICIOUS
- Tag component for all other metadata
- Color mapping: blue=default, red=error, orange=warning, green=success, lavender=AI, pink=findings, gray=inactive

### Data Visualization
- Chart colors: #95ADDA, #AA9FF3, #5A935A, #F5BB53, #FF97BF (max 5 per chart)
- ScoreCard for trust scores. Recharts for time series. @xyflow/react for graphs.
- Always label axes. Always include legends for multi-series.

## Accessibility

- WCAG 2.1 Level AA minimum
- All interactive elements keyboard-focusable
- Visible focus ring: 2px solid var(--color-blue-500)
- Never rely on color alone -- pair with text/icons
- Boolean props: isDisabled, hasError (not shouldNotRender)
- Handler props: onChange, onDismiss (never past tense)
- aria-label on icon-only buttons
- aria-live="polite" for toast notifications

## Do NOT

- Use Tailwind classes
- Use emojis in UI or code
- Use npm or npx (use pnpm / pnpm dlx)
- Add unnecessary badges or decorative elements
- Create inline SVG icons (use the Icon component with Radix)
- Use hardcoded colors (use CSS variables)
- Add blur, transparency, or glassmorphism effects
- Stack shadows on elements
- Use the pink shadow on anything other than primary action button hover