# DevKit Design Rules

To keep the entire platform consistent, performant, and developer-friendly, adhere to these 8 foundational design rules across all pages, tools, and components:

---

### 1. Palette Discipline
> **Never introduce random accent colors outside the defined palette.**

All styling must reference the CSS variables defined in `styles/design-system.css`:
- **Backgrounds**: `--bg-primary` (`#09090F`), `--bg-secondary` (`#11111B`), `--bg-tertiary` (`#191927`), `--bg-elevated` (`#202033`)
- **Brand**: `--brand-primary` (`#8B5CF6`), `--brand-secondary` (`#6366F1`), `--brand-highlight` (`#A78BFA`), `--brand-blue` (`#38BDF8`)
- **Text**: `--text-primary` (`#F4F1FF`), `--text-secondary` (`#B5B2C8`), `--text-muted` (`#9290A5`), `--text-disabled` (`#555469`)
- **Borders**: `--border-default` (`#29283A`), `--border-subtle` (`#201F30`), `--border-focus` (`var(--brand-primary)`)
- **Status**: `--color-success` (`#34D399`), `--color-warning` (`#FBBF24`), `--color-error` (`#FB7185`), `--color-info` (`#38BDF8`)

---

### 2. Action & Accent Roles
> **Use purple for primary actions and blue for secondary highlights.**

- **Primary**: Purple gradient (`--gradient-brand`, `#8B5CF6`) for main CTAs, active pills, and primary buttons (`.btn-primary`).
- **Secondary**: Blue (`--brand-blue`, `#38BDF8`) for secondary tags, info badges, and technical accents.

---

### 3. Purposeful Glows
> **Avoid excessive glowing effects. Reserve them for important interactions.**

- Never apply ambient or static glow animations to passive cards.
- Restrict glow effects (`--shadow-glow`, `--shadow-glow-strong`) strictly to active input focus states, interactive hover triggers, and primary CTAs.

---

### 4. 8px-Based Spacing Hierarchy
> **Maintain consistent spacing between components.**

Always use the 8px spacing tokens for margins, paddings, and flex/grid gaps:
| Token | Value | Common Usage |
|---|---|---|
| `--space-1` | 4px | Micro padding, icon gaps |
| `--space-2` | 8px | Badge padding, button gap, inline spacing |
| `--space-3` | 12px | Input internal padding, card gap |
| `--space-4` | 16px | Container padding, toolbar spacing |
| `--space-5` | 24px | Card padding, grid gap |
| `--space-6` | 32px | Section gap, modal padding |
| `--space-7` | 48px | Page margins, hero spacing |
| `--space-8` | 64px | Major section breaks |
| `--space-9` | 96px | Hero top/bottom spacing |

---

### 5. Unified Card Geometry
> **Use the same card radius throughout the application.**

- All tool cards, showcase containers, and preview blocks must use `--radius-lg` (`14px`).
- Radius standards:
  - Badges: `--radius-sm` (`6px`)
  - Buttons & Inputs: `--radius-md` (`10px`)
  - Cards: `--radius-lg` (`14px`)
  - Large Panels: `--radius-xl` (`20px`)
  - Modals: `--radius-2xl` (`24px`)
  - Pills: `--radius-full` (`999px`)

---

### 6. Strict Typography Hierarchy
> **Keep typography hierarchy consistent.**

- **Headings & Branding**: `Space Grotesk` (weights 500–700)
  - Hero Heading: `--text-4xl` (`48px`), weight `700`
  - Page Heading: `--text-3xl` (`32px`), weight `700`
  - Section Heading: `--text-2xl` (`24px`), weight `600`
  - Card Heading: `--text-xl` (`18px`), weight `600`
- **Body & Inputs**: `Inter` (weights 400–600)
  - Body Text: `--text-base` (`14px`), line-height `1.6`
  - Small Text: `--text-sm` (`12px`)
  - Labels: `--text-xs` (`11px`), weight `600`, uppercase, letter-spacing `0.08em`

---

### 7. Subtle Borders Over Heavy Shadows
> **Use subtle borders instead of excessive shadows.**

- Prefer 1px borders using `--border-default` (`#29283A`) or `--border-subtle` (`#201F30`).
- Avoid multi-layered heavy drop shadows; rely on clear background elevation tiers (`--bg-primary` &rarr; `--bg-secondary` &rarr; `--bg-tertiary` &rarr; `--bg-elevated`).

---

### 8. Responsive Across All Form Factors
> **Ensure responsive layouts on mobile, tablet, and desktop.**

- Mobile first mindset: Ensure tool controls and input fields are finger-friendly on mobile (`min-height: 44px`).
- Fluid grids: Tools grid auto-fits with `minmax(300px, 1fr)` down to single column on mobile.
- Horizontal scroll guards: Search bars and filter pill strips gracefully overflow or wrap without horizontal page clipping.

