The DESIGN.md Blueprint Standard

# DESIGN.md — Paperweight Tactile UI System Guidelines

## 1. Overview & Architectural Philosophy
Paperweight UI is an editorial, tactile design system engineered for Next.js, Tailwind CSS, and AI pair-programmers (Antigravity, Cursor, Claude, V0).
It blends physical stationery craft, precision hardware ergonomics, and architectural blueprint layouts.

### Key Rules for AI Coding Agents:
- **Never render plain flat UI**: Components must feature layered tactile depth, top bevel light highlights (`shadow-[inset_0_1px_0_0_rgba(255,255,255,0.4)]`), etched recessed wells, and crisp hairline borders (`border-slate-200/90`).
- **Warm Canvas Standard**: Screen background canvas is soft off-white (`bg-[#fafafa]` or `bg-slate-50/50`). Pure white (`#ffffff`) is strictly reserved for elevated cards and panels.
- **Active Press Physics**: Interactive controls must feature mechanical click feedback (`active:scale-[0.98]`).

---

## 2. Dynamic Theme Tokens (Current Active Accent: Blueprint Blue)
- **Primary Brand Accent**: `#2563EB`
- **Canvas Background**: `#FAFAFA` (Warm Paper Off-White)
- **Canvas Subtle**: `#F6F6F8`
- **Surface Elevated**: `#FFFFFF` (Elevated Cards/Panels)
- **Primary Ink Text**: `#0F172A` (Deep Slate)
- **Secondary Ink Text**: `#475569`
- **Hairline Border**: `rgb(226 232 240 / 0.9)`

---

## 3. Structural Layout & Page Grid Guide
When building full pages (Dashboards, Settings, SaaS Tools, Portfolios):

1. **Page Container**: Wrap main pages in `<div className="min-h-screen bg-slate-50/50 text-slate-900 flex flex-col relative">`.
2. **Background Overlay**: Include architectural blueprint grid background:
   ```tsx
   <div className="fixed inset-0 bg-[linear-gradient(to_right,#00000006_1px,transparent_1px),linear-gradient(to_bottom,#00000006_1px,transparent_1px)] bg-[size:32px_32px] pointer-events-none -z-10" />
   ```
3. **Bento Card Layout Grid**: Structure dashboard sections using 12-column responsive grid:
   ```tsx
   <div className="grid grid-cols-1 md:grid-cols-3 gap-6 max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
     <div className="md:col-span-2 bg-white rounded-xl border border-slate-200 p-6 shadow-xs">Main Workbench Content</div>
     <div className="bg-white rounded-xl border border-slate-200 p-6 shadow-xs">Sidebar / Quick Controls</div>
   </div>
   ```

---

## 4. Comprehensive Component Specifications & Code Snippets

### 1. Tactile Button
Mechanical press physics with top hairline highlight and micro-shadow.
```tsx
<button className="relative inline-flex items-center justify-center px-4 py-2 rounded-lg bg-[#2563EB] text-white font-semibold text-sm border border-slate-900/10 shadow-[inset_0_1px_0_0_rgba(255,255,255,0.3),0_1px_2px_0_rgba(0,0,0,0.05)] hover:brightness-110 active:scale-[0.98] transition-all">
  Tactile Primary Button
</button>
```

### 2. Secondary & Outline Buttons
```tsx
<button className="px-4 py-2 rounded-lg bg-white text-slate-900 font-semibold text-sm border border-slate-200 shadow-[inset_0_1px_0_0_rgba(255,255,255,1),0_1px_2px_0_rgba(0,0,0,0.03)] hover:bg-slate-50 active:scale-[0.98] transition-all">
  Secondary Action
</button>
```

### 3. Recessed Search Input
Etched well surface simulating carved paper depth.
```tsx
<div className="relative w-full">
  <input
    type="text"
    placeholder="Search blueprint specs..."
    className="w-full pl-10 pr-4 py-2 rounded-lg bg-slate-50 border border-slate-200 text-slate-900 shadow-[inset_0_1px_2px_0_rgba(0,0,0,0.05)] focus:bg-white focus:outline-none focus:ring-2 focus:ring-[#2563EB]/20 focus:border-[#2563EB] text-sm transition-all"
  />
</div>
```

### 4. Recessed Multi-line Textarea
```tsx
<textarea
  rows={4}
  placeholder="Write specification notes..."
  className="w-full p-3 rounded-lg bg-slate-50 border border-slate-200 text-slate-900 shadow-[inset_0_1px_2px_0_rgba(0,0,0,0.05)] focus:bg-white focus:outline-none focus:ring-2 focus:ring-[#2563EB]/20 focus:border-[#2563EB] text-sm font-mono transition-all"
/>
```

### 5. Elevated Bento Card
Top light refraction gradient and hover lift elevation.
```tsx
<div className="relative bg-white rounded-xl border border-slate-200 p-6 shadow-[0_2px_8px_-2px_rgba(0,0,0,0.04)] hover:-translate-y-1 hover:shadow-[0_8px_24px_-4px_rgba(0,0,0,0.08)] transition-all">
  <div className="flex items-center justify-between mb-3">
    <h3 className="font-bold text-slate-900 text-lg">Card Header</h3>
    <span className="px-2 py-0.5 rounded text-xs font-mono font-medium bg-blue-50 text-slate-800 border-blue-200 border">Spec v0.1</span>
  </div>
  <p className="text-sm text-slate-600">Bento card container with warm paper background fill.</p>
</div>
```

### 6. Segmented Controller / Tabs
Carved track background with elevated active tab.
```tsx
<div className="inline-flex p-1 rounded-xl bg-slate-100 border border-slate-200/80 shadow-[inset_0_1px_2px_0_rgba(0,0,0,0.06)]">
  <button className="px-3.5 py-1.5 rounded-lg text-xs font-semibold bg-white text-slate-900 shadow-sm border border-slate-200/80">Active Tab</button>
  <button className="px-3.5 py-1.5 rounded-lg text-xs font-medium text-slate-600 hover:text-slate-900">Inactive Tab</button>
</div>
```

### 7. Toggle Switch
Slide switch with carved track and paper-elevated knob.
```tsx
<label className="inline-flex items-center gap-3 cursor-pointer">
  <div className="relative w-11 h-6 bg-slate-200 rounded-full border border-slate-300 shadow-[inset_0_1px_2px_0_rgba(0,0,0,0.1)] transition-colors">
    <div className="absolute top-0.5 left-0.5 w-5 h-5 bg-white rounded-full border border-slate-200 shadow-sm transition-transform translate-x-5" />
  </div>
  <span className="text-xs font-mono font-medium text-slate-700">Toggle Feature</span>
</label>
```

### 8. Custom Checkbox & Radio
```tsx
<label className="flex items-center gap-2 cursor-pointer">
  <input type="checkbox" className="w-4 h-4 rounded border-slate-300 text-[#2563EB] focus:ring-[#2563EB]" defaultChecked />
  <span className="text-xs font-mono text-slate-700">Remember spec configuration</span>
</label>
```

### 9. Tactile Badges & Hardware Keycaps (Kbd)
```tsx
<span className="inline-flex items-center gap-1.5 px-2.5 py-0.5 rounded-md text-xs font-mono font-medium bg-blue-50 text-slate-800 border-blue-200 border">
  <span className="w-1.5 h-1.5 rounded-full bg-[#2563EB]" />
  Active Badge
</span>

<kbd className="inline-flex items-center px-1.5 py-0.5 text-[10px] font-mono font-semibold text-slate-700 bg-slate-100 border border-slate-300 rounded shadow-[inset_0_-1px_0_0_rgba(0,0,0,0.1)]">
  ⌘K
</kbd>
```

### 10. Command Palette Modal (⌘K)
```tsx
<div className="fixed inset-0 z-50 bg-slate-900/60 backdrop-blur-xs flex items-start justify-center pt-20">
  <div className="w-full max-w-lg bg-white rounded-2xl border border-slate-200 shadow-2xl overflow-hidden animate-in fade-in zoom-in-95">
    <div className="p-4 border-b border-slate-100">
      <input type="text" placeholder="Type a command or search..." className="w-full bg-transparent text-sm focus:outline-none font-mono" />
    </div>
  </div>
</div>
```

---

## 5. Instructions for AI Coding Assistants (Antigravity, Cursor, Claude)
- Strictly generate components and pages matching this tactile design language.
- Maintain consistent spacing (`gap-4`, `p-6`, `rounded-xl`).
- Ensure all interactive elements include keyboard focus states (`focus-visible:outline-2`) and ARIA labels.