docs/DESIGN_SYSTEM.md

# NETRA Design System & Component Library

## 🎨 Color Palette

### Primary Colors

- **Blue 900**: `#082a63` - Dark backgrounds, headings
- **Blue 800**: `#0b3b8a` - Secondary headings
- **Blue 700**: `#0f55c7` - Primary accent
- **Blue 600**: `#1c6ef2` - Interactive elements

### Accent Colors

- **Orange 600**: `#ff7a00` - CTAs, highlights
- **Orange 500**: `#ff922b` - Hover states
- **Orange 100**: `#fff1e6` - Light backgrounds

### Neutral Colors

- **White**: `#ffffff` - Primary background
- **Slate 900**: `#1b2a4a` - Text
- **Slate 700**: `#41557c` - Secondary text
- **Slate 500**: `#7284a8` - Tertiary text

### Status Colors

- **Success (Green)**: `#1f9d55`
- **Warning (Orange)**: `#ff9f1a`
- **Danger (Red)**: `#e53935`
- **Info (Blue)**: `#1c6ef2`

### Semantic Colors

- **Line/Border**: `#d9e4ff`
- **Glass (Semi-transparent)**: `rgba(255, 255, 255, 0.82)`

---

## 📏 Spacing System

```css

/* Base unit: 0.25rem (4px) */

0.25rem = 4px

0.5rem = 8px

0.75rem = 12px

1rem = 16px

1.2rem = 19px

1.5rem = 24px

2rem = 32px

2.2rem = 35px

2.4rem = 38px

```

### Padding & Margin Guidelines

- **Cards/Sections**: 1.2rem - 1.5rem
- **Form Groups**: 0.85rem
- **Buttons**: 0.72rem (vertical), 1.1rem (horizontal)
- **Section Padding**: 4.2rem (vertical), 1rem (horizontal)

---

## 🔤 Typography

### Font Families

- **Headings**: Sora (weights: 400, 500, 600, 700, 800)
- **Body**: IBM Plex Sans (weights: 400, 500, 600, 700)

### Font Sizes (with `clamp()`)

- **H1 (Hero)**: `clamp(2.4rem, 6vw, 4.1rem)`
- **H2 (Section Title)**: `clamp(1.7rem, 4vw, 2.45rem)`
- **H3 (Subsection)**: `1.3rem`
- **Body**: `1rem`
- **Small**: `0.9rem`
- **Extra Small**: `0.85rem`

### Line Heights

- **Headings**: -0.02em letter-spacing
- **Body**: 1.6 line-height
- **Descriptions**: 1.7 line-height

---

## 🛇 Border Radius System

```css

--radius-md: 14px;   /* Standard components */

--radius-lg: 22px;   /* Large sections, modals */

999px;               /* Pill-shaped (badges, chips) */

```

### Usage

- **Buttons**: 12px
- **Input Fields**: 10px
- **Cards**: 22px
- **Badges/Chips**: 999px

---

## 💫 Shadow System

```css

--shadow-sm: 0 8px 20px rgba(11, 59, 138, 0.08);

--shadow-md: 0 16px 35px rgba(11, 59, 138, 0.12);

--shadow-lg: 0 24px 60px rgba(11, 59, 138, 0.18);

```

### Application

- **Small**: Hover states, subtle elements
- **Medium**: Cards, panels, modals
- **Large**: Hero sections, prominent cards

---

## 🎭 Component Specifications

### Buttons

#### Variants

| Type      | Background              | Color | Shadow                    |
| --------- | ----------------------- | ----- | ------------------------- |
| Primary   | Linear gradient (blue)  | White | sm on normal, md on hover |
| Secondary | Linear gradient (blue)  | White | sm on normal, md on hover |
| Danger    | Linear gradient (red)   | White | sm on normal, md on hover |
| Success   | Linear gradient (green) | White | sm on normal, md on hover |
| Outline   | Transparent + border    | White | sm                        |

#### Sizes

- **Normal**: `0.72rem` padding, `1.1rem` horizontal
- **Large**: `0.95rem` padding, `1.6rem` horizontal

#### States

- **Normal**: Full opacity
- **Hover**: `translateY(-2px)`, enhanced shadow
- **Active**: `translateY(0)`
- **Disabled**: 60% opacity, no interaction
- **Loading**: Spinner appended, disabled

### Cards

#### Types

- **Stat Card**: Summary statistics
- **Feature Card**: Feature descriptions
- **Tech Card**: Technology highlights
- **Dashboard Card**: Main navigation cards
- **Info Card**: Information panels

#### Standard Specifications

- **Padding**: 1.35rem
- **Background**: Glass effect (`rgba(255, 255, 255, 0.82)`)
- **Border**: 1px solid `rgba(255, 255, 255, 0.76)`
- **Border Radius**: 22px
- **Transition**: 0.25s ease on transform and shadow

### Forms

#### Input Fields

- **Border**: 1px solid `#d9e4ff`
- **Border Radius**: 10px
- **Padding**: 0.72rem 0.8rem
- **Focus**: Blue border + 0 0 0 4px shadow

#### Labels

- **Color**: `#1b2a4a`
- **Font Weight**: 600
- **Margin Bottom**: 0.4rem

#### Error States

- **Border Color**: Red
- **Background**: Red tint
- **Error Message**: Red text below field

### Status Chips

```css

.status-chip {

  border-radius: 999px;

  padding: 0.38rem 0.8rem;

  font-size: 0.85rem;

  font-weight: 600;

  display: inline-flex;

  align-items: center;

  gap: 0.45rem;

}

```

#### Variants

| Status  | Background                 | Color     | Border                    |
| ------- | -------------------------- | --------- | ------------------------- |
| Success | `rgba(31, 157, 85, 0.12)`  | `#1f9d55` | `rgba(31, 157, 85, 0.3)`  |
| Warning | `rgba(255, 159, 26, 0.12)` | `#ff9f1a` | `rgba(255, 159, 26, 0.3)` |
| Danger  | `rgba(229, 57, 53, 0.12)`  | `#e53935` | `rgba(229, 57, 53, 0.3)`  |
| Info    | `rgba(28, 110, 242, 0.12)` | `#1c6ef2` | `rgba(28, 110, 242, 0.3)` |

### Modals

- **Background**: White
- **Border**: 1px solid `#d9e4ff`
- **Border Radius**: 22px
- **Shadow**: Large shadow
- **Max Width**: 540px
- **Padding**: 1.4rem

### Notifications (Toast)

- **Background**: White
- **Border Left**: 4px colored
- **Border Radius**: 12px
- **Padding**: 1rem 1.2rem
- **Min Width**: 280px
- **Auto Dismiss**: 3000ms

---

## 📱 Responsive Breakpoints

### Desktop (960px+)

- Full multi-column layouts
- Side-by-side panels
- All features visible
- Desktop navigation

### Tablet (640px - 960px)

- 2-column grids reduced to 2 columns max
- Single column for main content
- Optimized spacing
- Dropdown menus

### Mobile (480px - 640px)

- Single column layouts
- Touch-friendly spacing (minimum 44px taps)
- Simplified navigation
- Condensed modals

### Small Mobile (< 480px)

- Maximum 1 column
- Minimal padding
- Simplified components
- Essential features only

### Landscape (<600px height)

- Reduced vertical padding
- Compact sections
- Optimized for long, narrow screens

---

## 🎬 Animation System

### Keyframe Animations

```css

/* Entrance Animations */

fadeIn           /* Opacity fade */

slideInUp        /* Slide from bottom */

slideInDown      /* Slide from top */

slideInLeft      /* Slide from left */

slideInRight     /* Slide from right */

riseIn           /* Rise with fade */



/* Action Animations */

pulse            /* Box-shadow pulse */

spin             /* Full rotation */

bounce           /* Vertical bounce */

shimmer          /* Shimmer effect */

```

### Transition Timing

```css

--transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);

```

### Animation Timing

- **Fast**: 0.2s - 0.3s (hover states, small changes)
- **Normal**: 0.4s - 0.6s (page transitions, major changes)
- **Slow**: 0.8s - 1s (scroll reveals, long animations)
- **Continuous**: 1.5s - 2s (looping animations)

---

## 🔐 Accessibility Standards

### Color Contrast

- Text on background: 4.5:1 minimum (WCAG AA)
- Large text: 3:1 minimum
- Icons: 3:1 minimum

### Focus States

- All interactive elements have visible focus states
- Focus outline: 2px solid, contrasting color
- Not removed, only repositioned if necessary

### Semantic HTML

- Proper heading hierarchy (H1, H2, H3...)
- Form labels associated with inputs
- Buttons used for actions, links for navigation
- ARIA labels where needed

### Motion

- Reduced motion respected via `prefers-reduced-motion`
- No animations longer than 3 seconds that can't be paused
- Auto-playing content has pause controls

---

## 🚀 Implementation Guide

### New Components

1. Follow spacing system for padding/margins
2. Use shadow system for depth
3. Apply proper border radius
4. Use CSS variables for colors
5. Implement animation transitions
6. Test on all breakpoints
7. Verify accessibility standards

### New Pages

1. Include `ui-utils.js` script
2. Add `#toast-container` div
3. Use `.reveal` class for animations
4. Apply consistent button styles
5. Use grid layouts with `auto-fit`
6. Test responsive design
7. Verify form accessibility

### Customization

All design values are CSS variables in `:root`:

```css

:root {

  --blue-900: #082a63;

  --radius-md: 14px;

  --transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);

  /* ... etc ... */

}

```

---

## 📚 Component Examples

### Button Group

```html

<div class="hero-buttons">

  <a href="#" class="btn btn-primary btn-large">Primary</a>

  <a href="#" class="btn btn-outline btn-large">Outline</a>

</div>

```

### Status Card

```html

<div class="info-card">

  <h3>System Health</h3>

  <p>All services operational</p>

  <span class="status-chip ok">Operational</span>

</div>

```

### Card Grid

```html

<div class="stats-grid">

  <div class="stat-card">

    <div class="stat-number">99%</div>

    <div class="stat-label">Uptime</div>

  </div>

  <!-- More cards... -->

</div>

```

---

## 🎯 Best Practices

1. **Use CSS Variables**: Always use `--variable-name` for colors and sizes
2. **Consistent Spacing**: Maintain spacing system throughout
3. **Semantic HTML**: Use proper HTML tags for meaning
4. **Mobile First**: Design for small screens first
5. **Animation Moderation**: Use animations purposefully, not excessively
6. **Performance**: Prefer CSS transforms over layout changes
7. **Testing**: Test all components on mobile, tablet, desktop
8. **Accessibility**: Always include keyboard navigation and focus states

---

## 📝 Version History

### v2.0 (Current)

- Enhanced animations and transitions
- Responsive design improvements
- New UI utility library
- Status chips redesign
- Modal dialog system
- Toast notification system

### v1.0

- Initial design system
- Color palette
- Typography
- Basic components

---

_Design System Documentation_
_Last Updated: May 2, 2026_
_NETRA Frontend v2.0_