# Design System Inspired by SIR Developer Community

## 1. Visual Theme & Atmosphere

SIR's design system embodies a professional yet approachable developer community aesthetic, combining clean minimalism with purposeful color accents. The interface balances deep navy blues and sophisticated grays with vibrant cyan and blue highlights, creating a tech-forward atmosphere that feels both trustworthy and dynamic. The system prioritizes information density and clarity, with generous whitespace that reduces cognitive load. Subtle shadows and carefully calibrated border radii enhance depth without overwhelming, while the consistent use of the system font stack ensures universal readability across devices. This is a design system built for function—every element serves the community's core mission of connecting developers with resources, tools, and opportunities.

**Key Characteristics**

- Clean, minimal aesthetic with purposeful use of color
- Dark text on light backgrounds for maximum legibility
- Professional navy blues (`#163B6C`, `#135AA7`) paired with energetic cyans (`#06B6D4`)
- Generous whitespace and breathing room between components
- Subtle shadows and soft border radius for depth without harshness
- Accessible color contrasts and system font defaults
- Data-visualization ready with multi-color accent support
- Community-focused, friendly but technical

## 2. Color Palette & Roles

### Primary

- **Deep Navy** (`#163B6C`): Primary text, headings, and semantic focus; establishes authority and trust
- **Primary Blue** (`#2563EB`): Interactive elements, primary CTAs, and emphasized links
- **Dark Slate** (`#3F3F46`): Secondary text, metadata, and interface elements

### Accent Colors

- **Bright Cyan** (`#06B6D4`): Success states, positive feedback, and attention highlights
- **Light Blue** (`#60A5FA`): Hover states and interactive feedback
- **Royal Blue** (`#1D4ED8`): Link underlines and secondary CTAs

### Interactive

- **Cobalt** (`#135AA7`): Active button states and focused elements
- **Blue Sky** (`#2563EB`): Default interactive state and primary buttons

### Neutral Scale

- **Off-White** (`#FFFFFF`): Primary background and card surfaces
- **Light Gray** (`#E4E4E7`): Border lines, dividers, and subtle backgrounds
- **Medium Gray** (`#71717A`): Tertiary text and disabled states
- **Dark Gray** (`#52525B`): Secondary text and labels
- **Charcoal** (`#3F3F46`): Primary text and body copy
- **Nearly Black** (`#27272A`): Dark backgrounds and emphasis
- **Jet Black** (`#000000`): Maximum contrast text and headlines

### Surface & Borders

- **Border Light** (`#E4E4E7`): Primary border color for inputs, cards, and dividers; used 480 times
- **Subtle Gray** (`#A1A1AA`): Secondary borders and disabled states

### Semantic / Status

- **Success Green** (Inferred `#10B981`): Used in visualization bars for positive metrics
- **Warning Orange** (Inferred `#F59E0B`): Used in progress indicators
- **Danger Red** (Inferred `#EF4444`): Error states and critical alerts

## 3. Typography Rules

### Font Family

**Primary:** `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif`  
Fallback stack ensures consistent rendering across macOS, Windows, iOS, and Android. System fonts provide optimal legibility and native feel.

**Secondary:** `Lobster` (Google Fonts import)  
Decorative font for brand moments and special emphasis; used sparingly to maintain professionalism.

### Hierarchy

| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
|------|------|------|--------|-------------|----------------|-------|
| Display / H1 | -apple-system | 40px | 900 | 48px | 0px | Hero headlines and page titles; commanding presence |
| Heading H2 | -apple-system | 30px | 900 | 36px | 0px | Section headers and major content blocks |
| Heading H3 | -apple-system | 16px | 700 | 24px | 0px | Subsection headers and card titles |
| Body Regular | -apple-system | 16px | 400 | 24px | 0px | Primary content, descriptions, and paragraphs |
| Body Strong | -apple-system | 20px | 900 | 21px | 0px | Emphasized body text and data labels |
| Button / Link | -apple-system | 16px | 400 | 24px | 0px | Interactive elements and CTAs |
| Caption / Small | -apple-system | 14px | 400 | 20px | 0px | Metadata, timestamps, and helper text |
| Code / Mono | -apple-system | 13px | 400 | 18px | 0px | Code blocks and technical content |
| Accent / Brand | Lobster | 17.5px | 400 | 17.5px | 0px | Logo type and decorative text |

### Principles

- **Hierarchy through weight and size:** Bold weights (`700`, `900`) create immediate visual emphasis; regular weight (`400`) ensures readability for body text
- **System fonts for performance:** Native font stack eliminates custom font load time and ensures fallbacks match platform expectations
- **Generous line height:** Baseline `24px` line height across body and interactive text improves scannability and accessibility
- **Contrast-first approach:** Deep navy and black text ensures compliance with WCAG AA standards on all light backgrounds
- **Spartan Lobster use:** Decorative font reserved for brand identity; avoids overuse that diminishes impact

## 4. Component Stylings

### Buttons

#### Primary Button
- **Background:** `#2563EB`
- **Text Color:** `#FFFFFF`
- **Font Size:** `16px`
- **Font Weight:** `600`
- **Padding:** `10px 20px`
- **Border Radius:** `8px`
- **Border:** `none`
- **Box Shadow:** `rgba(0, 0, 0, 0.1) 0px 10px 15px -3px, rgba(0, 0, 0, 0.1) 0px 4px 6px -4px`
- **Height:** `40px`
- **Hover State:** Background `#1D4ED8`, shadow intensifies
- **Active State:** Background `#163B6C`, shadow reduces

#### Secondary Button
- **Background:** `#E4E4E7`
- **Text Color:** `#163B6C`
- **Font Size:** `16px`
- **Font Weight:** `500`
- **Padding:** `10px 20px`
- **Border Radius:** `8px`
- **Border:** `1px solid #D4D4D8`
- **Box Shadow:** `none`
- **Height:** `40px`
- **Hover State:** Background `#D4D4D8`, text `#135AA7`
- **Active State:** Background `#C4C4C7`, text `#163B6C`

#### Ghost Button
- **Background:** `transparent`
- **Text Color:** `#163B6C`
- **Font Size:** `16px`
- **Font Weight:** `400`
- **Padding:** `8px 12px`
- **Border Radius:** `8px`
- **Border:** `1px solid #E4E4E7`
- **Box Shadow:** `none`
- **Height:** `36px`
- **Hover State:** Background `#F4F4F5`, border `#D4D4D8`
- **Active State:** Background `#E4E4E7`

#### Icon Button
- **Background:** `transparent`
- **Text Color:** `#163B6C`
- **Font Size:** `16px`
- **Font Weight:** `400`
- **Padding:** `8px`
- **Border Radius:** `9999px`
- **Border:** `none`
- **Box Shadow:** `none`
- **Width:** `36px`
- **Height:** `36px`
- **Hover State:** Background `#F4F4F5`
- **Active State:** Background `#E4E4E7`

#### Small Button (Search/Filter)
- **Background:** `transparent`
- **Text Color:** `#3F3F46`
- **Font Size:** `14px`
- **Font Weight:** `400`
- **Padding:** `8px 12px`
- **Border Radius:** `0px 4px 4px 0px`
- **Border:** `none`
- **Box Shadow:** `none`
- **Height:** `auto`
- **Hover State:** Background `#F9FAFB`, text `#000000`

### Cards & Containers

#### Standard Card
- **Background:** `#FFFFFF`
- **Border:** `1px solid #E4E4E7`
- **Border Radius:** `8px`
- **Padding:** `16px`
- **Box Shadow:** `rgba(0, 0, 0, 0.05) 0px 1px 2px 0px`
- **Hover State:** Border `#D4D4D8`, shadow intensifies to `rgba(0, 0, 0, 0.08) 0px 4px 6px 0px`

#### Elevated Card (Featured)
- **Background:** `#FFFFFF`
- **Border:** `none`
- **Border Radius:** `8px`
- **Padding:** `20px`
- **Box Shadow:** `rgba(0, 0, 0, 0.1) 0px 10px 15px -3px, rgba(0, 0, 0, 0.1) 0px 4px 6px -4px`
- **Hover State:** Shadow increases to `rgba(0, 0, 0, 0.15) 0px 20px 25px -5px`

#### Alert / Notice Container (Light Blue Background)
- **Background:** `#E0F2FE`
- **Border:** `1px solid #BAE6FD`
- **Border Radius:** `8px`
- **Padding:** `12px 16px`
- **Text Color:** `#163B6C`
- **Font Size:** `14px`

#### Alert / Notice Container (Light Cyan Background)
- **Background:** `#CFFAFE`
- **Border:** `1px solid #A5F3FC`
- **Border Radius:** `8px`
- **Padding:** `12px 16px`
- **Text Color:** `#06B6D4`
- **Font Size:** `14px`

### Inputs & Forms

#### Text Input
- **Background:** `#FFFFFF`
- **Border:** `1px solid #E4E4E7`
- **Border Radius:** `6px`
- **Padding:** `10px 12px`
- **Font Size:** `16px`
- **Font Weight:** `400`
- **Color:** `#3F3F46`
- **Line Height:** `24px`
- **Focus State:** Border `#2563EB`, box shadow `0 0 0 3px rgba(37, 99, 235, 0.1)`
- **Disabled State:** Background `#F3F4F6`, border `#E5E7EB`, color `#9CA3AF`

#### Dropdown / Select
- **Background:** `#FFFFFF`
- **Border:** `1px solid #E4E4E7`
- **Border Radius:** `6px`
- **Padding:** `10px 12px`
- **Font Size:** `16px`
- **Color:** `#3F3F46`
- **Hover State:** Border `#D4D4D8`
- **Focus State:** Border `#2563EB`, box shadow `0 0 0 3px rgba(37, 99, 235, 0.1)`

#### Checkbox / Radio
- **Size:** `16px × 16px`
- **Border:** `2px solid #E4E4E7`
- **Border Radius:** `4px` (checkbox) / `50%` (radio)
- **Checked Background:** `#2563EB`
- **Checked Border:** `#2563EB`
- **Focus State:** Box shadow `0 0 0 3px rgba(37, 99, 235, 0.1)`

### Navigation

#### Top Navigation Bar
- **Background:** `#FFFFFF`
- **Border Bottom:** `1px solid #E4E4E7`
- **Height:** `64px`
- **Padding:** `0px 24px`
- **Box Shadow:** `rgba(0, 0, 0, 0.05) 0px 1px 2px 0px`
- **Position:** Sticky top

#### Navigation Link
- **Color:** `#000000`
- **Font Size:** `16px`
- **Font Weight:** `400`
- **Padding:** `8px 12px`
- **Border Radius:** `0px`
- **Hover State:** Color `#2563EB`, background `transparent`
- **Active State:** Color `#2563EB`, border bottom `2px solid #2563EB`

#### Dropdown Menu Item
- **Background:** `#FFFFFF`
- **Color:** `#3F3F46`
- **Font Size:** `14px`
- **Padding:** `10px 16px`
- **Border Radius:** `0px`
- **Hover State:** Background `#F3F4F6`, color `#163B6C`
- **Border Bottom:** `1px solid #E4E4E7` (between items)

### Badges & Tags

#### Badge Primary
- **Background:** `#DBEAFE`
- **Text Color:** `#1E40AF`
- **Font Size:** `12px`
- **Font Weight:** `500`
- **Padding:** `4px 8px`
- **Border Radius:** `9999px`
- **Border:** `none`

#### Badge Success
- **Background:** `#D1FAE5`
- **Text Color:** `#047857`
- **Font Size:** `12px`
- **Font Weight:** `500`
- **Padding:** `4px 8px`
- **Border Radius:** `9999px`

#### Badge Neutral
- **Background:** `#E4E4E7`
- **Text Color:** `#3F3F46`
- **Font Size:** `12px`
- **Font Weight:** `500`
- **Padding:** `4px 8px`
- **Border Radius:** `9999px`

### Progress Bar

#### Linear Progress
- **Background Gradient:** Left to right through `#2563EB` (32%), `#EC4899` (23%), `#10B981` (45%)
- **Height:** `8px`
- **Border Radius:** `4px`
- **Segments:** Color-coded by section

## 5. Layout Principles

### Spacing System

**Base Unit:** `4px`

Spacing values follow a modular scale:
- `4px` — Micro gaps, component internals
- `8px` — Tight spacing, icon padding
- `12px` — Component padding, form inputs
- `16px` — Standard padding, card content
- `20px` — Section gaps, element separation
- `24px` — Card margins, list spacing
- `32px` — Section padding, container margins
- `40px` — Large padding, emphasized spacing
- `48px` — Major section breaks
- `80px` — Hero-to-content spacing
- `96px` — Full-height spacing, page sections

**Usage Context:**
- Inputs and buttons use `8px` to `12px` internal padding
- Cards and containers use `16px` to `32px` padding
- Page sections use `48px` to `96px` margins for breathing room
- Lists and grids use `12px` to `20px` gaps between items

### Grid & Container

**Max Width:** `1280px` (standard content container)  
**Narrow Container:** `960px` (text-focused content)  
**Full Width:** Stretches to viewport edges with `24px` side margins

**Column Strategy:** 
- Desktop: 12-column layout
- Tablet (768px): 8-column layout
- Mobile (375px): 4-column layout with `16px` gutters

**Section Patterns:**
- Hero sections: Full width with `80px` vertical padding
- Content sections: Contained within `1280px` with alternating left/right alignment
- Footer: Full width, dark background (`#27272A`), `48px` padding top/bottom
- Modals and overlays: Centered, max-width `600px`

### Whitespace Philosophy

SIR's design embraces generous whitespace as a core design principle. Rather than filling every pixel, the system uses negative space to create clarity and focus. Content blocks are separated by minimum `24px` gaps; card-based layouts use `20px` gaps. This breathing room reduces cognitive overload and guides the user's eye to primary actions and information. Whitespace also serves as a visual hierarchy tool—dense sections feel interactive, sparse sections feel contemplative.

### Border Radius Scale

- `0px` — Sharp, architectural, rarely used (special cases only)
- `4px` — Slight softness; buttons, input corners, badge corners
- `6px` — Soft refinement; inputs, overlays, smaller containers
- `8px` — Standard softness; cards, modals, larger buttons
- `9999px` — Full pill shape; icon buttons, badges, pill inputs

## 6. Depth & Elevation

| Level | Treatment | Use |
|-------|-----------|-----|
| Flat (None) | `box-shadow: none` | Flat buttons, text links, bare elements |
| Subtle (sm) | `rgba(0, 0, 0, 0.05) 0px 1px 2px 0px` | Secondary cards, hover states, delicate elevation |
| Base (md) | `rgba(0, 0, 0, 0.1) 0px 10px 15px -3px, rgba(0, 0, 0, 0.1) 0px 4px 6px -4px` | Primary cards, navigation bars, standard components |
| Lifted (lg) | `rgba(0, 0, 0, 0.15) 0px 20px 25px -5px, rgba(0, 0, 0, 0.1) 0px 10px 10px -5px` | Featured cards, popovers, modals on hover |
| Floating (xl) | `rgba(0, 0, 0, 0.2) 0px 25px 50px -12px` | Topmost modals, dropdown menus, toast notifications |

**Shadow Philosophy:**

SIR uses measured shadows to create subtle depth without dramatic layering. Shadows are warm and directional, suggesting light from slightly above-left. The system employs a two-component shadow model: a larger spread shadow for perceivable depth, and a tighter shadow for edge definition. This creates a natural, almost 3D appearance while maintaining a clean, modern aesthetic. Shadows intensify on hover and interaction states, providing tactile feedback without overwhelming the interface.

## 7. Do's and Don'ts

### Do

- **Use system fonts** — `-apple-system` provides native rendering and performance
- **Maintain 16px minimum body text** — Ensures accessibility and mobile readability
- **Apply consistent 24px line height** — Improves scannability across all text
- **Respect the spacing scale** — Use `4px`, `8px`, `12px`, `16px`, etc., for alignment and rhythm
- **Combine shadows with interaction** — Shadows should increase on hover/focus to signal interactivity
- **Use the full color palette** — Navy for authority, cyan for success, blues for CTAs
- **Ensure 4.5:1 minimum contrast** — Text color on background must meet WCAG AA standards
- **Apply border radius consistently** — Use `8px` for cards and containers, `9999px` for pills
- **Center focus states visually** — Ring should be 3px offset with `rgba(37, 99, 235, 0.1)` color
- **Group related elements spatially** — Use consistent `16px` to `24px` gaps for coherence

### Don't

- **Mix multiple font families** — Stick to system fonts; reserve Lobster for brand moments only
- **Use shadows heavier than lg level** — Excessive shadows flatten the design hierarchy
- **Apply custom fonts without fallbacks** — Always provide the full system stack as fallback
- **Forget disabled states** — Disable buttons should be `#D1D5DB` background with `#9CA3AF` text
- **Ignore keyboard navigation** — Always provide visible focus states with `0 0 0 3px` outline
- **Break the spacing scale** — Arbitrary spacing values create visual discord
- **Use cyan or green for errors** — Reserve these for success/positive states; use red for errors
- **Create contrast lower than 3:1** — Secondary text minimum, 4.5:1 for body
- **Over-shadow interactive elements** — A single shadow level is sufficient; don't stack multiple
- **Crop or distort the brand Lobster font** — Use at intended weight (400) and size
- **Use more than two accent colors per section** — Prevents visual noise and maintains focus
- **Skip responsive breakpoints** — Always test and design for mobile-first approach

## 8. Responsive Behavior

### Breakpoints

| Breakpoint | Width | Key Changes |
|-----------|-------|------------|
| Mobile | `375px–599px` | 4-column grid, `16px` side margins, single-column layout for cards, bottom navigation, hamburger menu, `14px` body text |
| Tablet | `600px–767px` | 8-column grid, `20px` side margins, 2-column card layouts, `16px` body text, collapsible navigation |
| Desktop | `768px–1024px` | 12-column grid, `24px` side margins, 3-column card layouts, `16px` body text, full navigation |
| Large Desktop | `1025px+` | 12-column grid, `24px` side margins, full layout with max-width `1280px`, sidebar navigation, `16px` body text |

### Touch Targets

- **Minimum interactive size:** `44px × 44px` (buttons, links, icon buttons on mobile)
- **Icon buttons:** `36px × 36px` minimum (desktop); `44px × 44px` (mobile)
- **Text links:** `24px` minimum height with `8px` vertical padding
- **Checkboxes / Radio:** `20px × 20px` (desktop); `24px × 24px` (mobile)
- **Form inputs:** `40px` minimum height for comfortable mobile interaction
- **Spacing between targets:** Minimum `8px` to prevent accidental double-taps

### Collapsing Strategy

**Mobile (< 600px):**
- Hide secondary navigation; show hamburger menu in top-left corner
- Stack cards vertically; remove multi-column layouts
- Reduce padding to `12px` for compact spacing
- Fullscreen modals instead of centered overlays
- Bottom navigation for primary section switching
- Collapse data tables into card-based stacked view
- Reduce font sizes by 1–2 sizes (e.g., `16px` → `14px` for body)

**Tablet (600px–768px):**
- Show primary navigation; collapse secondary into dropdown
- 2-column card layouts; 1-column for tight spaces
- Padding reduced to `16px`
- Floating action button for primary CTAs
- Adjust max-width containers to `900px`
- Show/hide non-essential UI based on available width

**Desktop (> 768px):**
- Full navigation bar with all items visible
- 3+ column layouts for optimal space use
- Padding standardized at `20px–24px`
- Sidebar navigation or mega menus
- Standard max-width `1280px`
- All secondary UI elements visible by default

## 9. Agent Prompt Guide

### Quick Color Reference

Use these colors directly when implementing components:

- **Primary CTA / Active State:** Primary Blue (`#2563EB`)
- **Secondary CTA / Hover State:** Light Blue (`#60A5FA`)
- **Disabled / Inactive:** Light Gray (`#E4E4E7`) background with `#71717A` text
- **Body Text / Headings:** Deep Navy (`#163B6C`) or Jet Black (`#000000`)
- **Border / Divider:** Border Light (`#E4E4E7`)
- **Card Background:** Off-White (`#FFFFFF`)
- **Success / Positive:** Bright Cyan (`#06B6D4`)
- **Error / Danger:** Danger Red (`#EF4444`)
- **Warning:** Warning Orange (`#F59E0B`)
- **Neutral / Tertiary Text:** Medium Gray (`#71717A`)

### Iteration Guide

Follow these numbered rules to implement SIR-inspired UI components accurately:

1. **Always use system fonts** — `-apple-system` with fallback stack; never substitute with custom fonts without explicit brand requirement
2. **Apply 16px minimum body text** — Except captions (14px) and code (13px); never go below 14px for readable content
3. **Pair colors with purpose** — Navy for authority, cyan for success, blue for CTAs; never mix semantic meanings
4. **Use the spacing scale exclusively** — `4px`, `8px`, `12px`, `16px`, `20px`, `24px`, `32px`, `40px`, `48px`, `80px`, `96px`; no arbitrary values
5. **Default to 8px border radius** — Except pills (9999px), sharp corners (0px), or slight softness (4px)
6. **Include shadow on cards and buttons** — Use `md` shadow (`rgba(0, 0, 0, 0.1) 0px 10px 15px -3px, rgba(0, 0, 0, 0.1) 0px 4px 6px -4px`) by default
7. **Provide focus states** — Always include `:focus` with `0 0 0 3px rgba(37, 99, 235, 0.1)` outline in `#2563EB`
8. **Maintain 4.5:1 contrast minimum** — Test all text colors against backgrounds using contrast checker
9. **Layer elevation consistently** — Flat < Subtle < Base < Lifted < Floating; never jump levels
10. **Design mobile-first, enhance for desktop** — Start with mobile constraints (4-column, 44px targets); expand to desktop layouts
11. **Use the typography hierarchy exactly** — Don't invent sizes; H1, H2, H3, Body, Caption are standardized
12. **Test responsiveness at 375px, 768px, 1280px** — These are critical breakpoints where layouts shift
13. **Reserve Lobster font for brand accents only** — Never use for body text; size at 17.5px weight 400
14. **Ensure disabled states are obvious** — Gray background with lighter gray text; never rely on opacity alone
15. **Hover states should intensify, not change meaning** — A blue button stays blue on hover; shadow increases, never decreases