# Blueprint — Construction Instructions & AI Prompting Guide
> Version 1.0 · Complete decision framework for building with the Blueprint system

---

## Table of Contents

1. [Design Philosophy & Core Rules](#1-design-philosophy--core-rules)
2. [The Two-Font Law](#2-the-two-font-law)
3. [Color Application Rules](#3-color-application-rules)
4. [Border Radius Decision Framework](#4-border-radius-decision-framework)
5. [Background & Surface Rules](#5-background--surface-rules)
6. [Shadow & Elevation Rules](#6-shadow--elevation-rules)
7. [The Cyan Accent — When and How](#7-the-cyan-accent--when-and-how)
8. [Typography Application Rules](#8-typography-application-rules)
9. [Spacing Construction Rules](#9-spacing-construction-rules)
10. [Component Construction Guides](#10-component-construction-guides)
11. [Interactive States — Full Decision Guide](#11-interactive-states--full-decision-guide)
12. [Layout Construction Rules](#12-layout-construction-rules)
13. [Animation Rules](#13-animation-rules)
14. [What Never to Do — Anti-Pattern List](#14-what-never-to-do--anti-pattern-list)
15. [AI Prompting Instructions](#15-ai-prompting-instructions)
16. [New Project Checklist](#16-new-project-checklist)
17. [Component Pattern Library](#17-component-pattern-library)
18. [Responsive Construction Rules](#18-responsive-construction-rules)
19. [Accessibility Guidelines](#19-accessibility-guidelines)
20. [Common Scenarios — Decision Trees](#20-common-scenarios--decision-trees)

---

## 1. Design Philosophy & Core Rules

### The Fundamental Premise

Blueprint is built on the metaphor of a **technical drawing pinned to a drafting table**: a deep navy sheet, a faint cyan grid, hairline borders, and open corner registration marks. Nothing curves. Nothing glows softly. Every visual decision should look like it was drawn with a technical pen and a ruler, not painted or lit.

This is the aesthetic of CAD software, an architect's blueprint roll, or an old oscilloscope schematic — cold, exact, and confident in its precision. If an element in your build has a soft shadow, a rounded corner, or a filled solid badge, you have drifted out of this system.

---

### The 10 Commandments of This System

**1. Radius is always exactly zero.**
Not `2px`, not `4px` — `0px`, on every single element: cards, buttons, inputs, badges, dropdowns, tables, checkboxes. This is the strictest radius rule in the entire collection.

**2. The background grid is permanent.**
The `28px × 28px` cyan graph-paper grid (via two overlapping `linear-gradient`s) must always be visible behind every screen. Removing it turns Blueprint into a generic dark theme.

**3. Cards are drawn, not lit.**
No card in this system uses a soft `box-shadow` for elevation. Instead, every card gets a `1px solid rgba(79,209,255,0.35)` border plus two open corner brackets (top-left, bottom-right) via `::before`/`::after`.

**4. The corner bracket is a two-sided "L", never a full box.**
`border-right:none; border-bottom:none` on the top-left bracket, `border-left:none; border-top:none` on the bottom-right — this creates the open registration-mark look. A full 4-sided bracket square is wrong.

**5. Section titles always carry a `// ` prefix; subheadings always carry a `> ` prefix.**
These two comment/prompt markers are the system's core "annotated document" signal and must appear consistently, never omitted for a "cleaner" look.

**6. Buttons are line-drawings, not filled shapes (except primary).**
Only the primary button has a solid cyan fill. Every other variant (secondary, outline, destructive, dashed) is `background:transparent` with only a border and text color distinguishing it.

**7. Badges are outline-only.**
`border: 1px solid currentColor`, transparent background, text color signals the semantic meaning. There is no solid/filled badge anywhere in this system.

**8. Cyan is the only cool accent; warm colors are reserved strictly for warning/error.**
`#4fd1ff` handles primary/info/success roles. `#ffd166` (warning) and `#ff8080` (error) are the only other hues permitted, and only for their specific semantic role.

**9. Two fonts split by function, not by size.**
Space Grotesk governs headings and button labels (structural UI). JetBrains Mono governs everything read or measured — body, inputs, labels, tables, badges. This split is by *role*, not by size threshold.

**10. Motion is minimal and instant.**
No entrance animations beyond a quick opacity fade on dropdowns. No hover lifts, no glow transitions. A drafting table does not animate.

---

## 2. The Two-Font Law

### Category 1: Structural — Space Grotesk
**Assignment question: Is this a heading, section title, or button label?**

If yes → Space Grotesk, weight 600.

- Page hero title (h1): YES → Space Grotesk 600
- Section heading (h2): YES → Space Grotesk 600
- Section title (`// ` prefix): YES → Space Grotesk 600
- Button label: YES → Space Grotesk 600
- Subheading (`> ` prefix): NO → JetBrains Mono (subheadings are content, not structure, despite appearing near headings)
- Body text: NO → JetBrains Mono

### Category 2: Measured / Read — JetBrains Mono
**Assignment question: Is this content the user reads, measures, types, or scans in a table?**

If yes → JetBrains Mono.

- Body paragraph: YES → JetBrains Mono 400
- Input text / placeholder: YES → JetBrains Mono 400
- Field label: YES → JetBrains Mono 600 (uppercase)
- Table header / cell: YES → JetBrains Mono
- Badge text: YES → JetBrains Mono 600
- Subheading (`> spec text`): YES → JetBrains Mono 400

### Font Decision Flowchart

```
Is it a heading, section title, or button label? ──YES──► Space Grotesk, 600
        │ NO
        ▼
Default to JetBrains Mono
```

---

## 3. Color Application Rules

### 3.1 Background Selection Rules

| Surface | Value | Why |
|---------|-------|-----|
| Page | `#0b3d63` + grid overlay | Deep navy drafting sheet |
| Card | `rgba(11,40,66,0.7)` | Translucent — grid shows through |
| Dropdown panel | `#0e2c47` | More opaque — floats above the card layer |
| Input | `rgba(255,255,255,0.03)` | Barely-there lightening, reads as an inset field |

**Rule:** never introduce a fully opaque light background anywhere. Every surface stays within the navy family; only opacity changes.

---

### 3.2 Cyan Accent Usage Rules

Cyan is the interactive and structural signal. Use it in exactly these contexts:

1. **Primary button fill** — `#4fd1ff` background, `#0b3d63` text
2. **Card border + corner brackets** — `rgba(79,209,255,0.35)` border, `#4fd1ff` bracket strokes
3. **Section title text + `// ` prefix**
4. **Subheading text + `> ` prefix**
5. **Input focus border/ring**
6. **Table header text and rule line**
7. **Outline/dashed button border + text**

**Never:**
- Cyan as a page or card background fill (it is an ink/line color, not a surface color)
- A second cool accent hue introduced alongside cyan
- A soft cyan glow shadow — the focus ring is a hard 1px line, not a blur

---

### 3.3 Text Color Assignment

| Priority | Color | Examples |
|----------|-------|----------|
| Highest | `#e8f4fc` | Headings, display text |
| High | `#cfe9fb` | Body copy |
| Medium | `#bcdff0` | Section headings |
| Low | `#7fa9c4` | Labels, captions, secondary text |
| Disabled | `#4a6b85` | Greyed-out states, borders |
| Accent | `#4fd1ff` | Links, section titles, subheadings |

---

### 3.4 Semantic Color Rules

Blueprint deliberately **shares its primary cyan for both "info" and "success"** — there is no separate green in this system, because a technical drafting sheet doesn't distinguish "good" from "informational"; both are simply "in spec." Only warning (`#ffd166`) and error (`#ff8080`) get distinct hues, since those require urgent visual differentiation.

---

## 4. Border Radius Decision Framework

The rule could not be simpler: **every element is `0px`.** There are no exceptions, no "soft square" compromises, no circular radios. If you find yourself writing any `border-radius` value other than `0`, you have left this system.

### Quick Reference Table

| Element | Radius |
|---------|--------|
| Card | 0px |
| Button (all variants) | 0px |
| Text input / textarea | 0px |
| Dropdown panel / item | 0px |
| Badge | 0px |
| Checkbox | 0px |
| Radio | 0px (a bordered square with a filled dot or diagonal mark when selected — not a circle) |
| Switch track | 0px |
| Table / table cell | 0px |
| Modal | 0px |

---

## 5. Background & Surface Rules

### 5.1 The Grid Is Structural, Not Decorative

```css
.page {
  background: #0b3d63;
  background-image:
    linear-gradient(rgba(79,209,255,0.08) 1px, transparent 1px),
    linear-gradient(90deg, rgba(79,209,255,0.08) 1px, transparent 1px);
  background-size: 28px 28px;
}
```

This must be present on every screen. It is what makes translucent cards (`rgba(11,40,66,0.7)`) visually meaningful — without the grid showing through, the translucency has no purpose.

### 5.2 Elevation via Opacity, Not Color

| Layer | Background |
|-------|------------|
| Page | `#0b3d63` solid + grid |
| Card | `rgba(11,40,66,0.7)` — 70% opaque, grid partially visible |
| Dropdown / modal | `#0e2c47` — fully opaque, floats above everything |

### 5.3 No Warm or Light Surfaces

There is no light-mode variant. Every surface lives in the navy family; warmth only appears in the warning/error semantic colors, never structurally.

---

## 6. Shadow & Elevation Rules

### 6.1 The No-Soft-Shadow Rule

Cards and buttons use **zero** diffuse box-shadow. Elevation is communicated by:
1. Border presence/opacity
2. Corner brackets (cards only)
3. Background opacity (translucent card vs. opaque dropdown)

### 6.2 The One Exception: Dropdown Drop Shadow

```css
--shadow-dropdown: 0 12px 28px rgba(0, 0, 0, 0.45);
```

Dropdown panels are the single component allowed a real, soft ambient shadow — because they float above the page in a way cards do not, and need a legibility cue against whatever content sits behind them.

### 6.3 Focus Is a Hard Ring, Never a Glow

```css
.input:focus { box-shadow: 0 0 0 1px #4fd1ff; }
```

`1px`, zero blur — a hairline outline, not a soft halo. This distinguishes Blueprint sharply from Glass or Capsule's glow-ring focus treatments.

---

## 7. The Cyan Accent — When and How

### When to Use Cyan

| Use It | Don't Use It |
|--------|--------------|
| Primary button fill | Card/page backgrounds |
| Card border + corner brackets | Warning/error badges |
| Section title / subheading text + prefix | Body copy at length |
| Input focus ring | Disabled states |
| Table header text/rule | — |

### How NOT to Use Cyan

- Never as a large fill (cards, page backgrounds) — it is an ink/line color only
- Never with a soft blur/glow — always a hard-edged application
- Never for both warning and error — those get their own hues

---

## 8. Typography Application Rules

### 8.1 The Comment-Prefix Section Title Pattern

```
// Typography                       ← Space Grotesk 600, 11px, uppercase, #4fd1ff, tracking 0.14em, "// " prefix at 0.6 opacity
                                     ← 18px gap before content
[Section content begins]
```

### 8.2 The Prompt-Prefix Subheading Pattern

```
> Subheading text style              ← JetBrains Mono 400, 15px, #4fd1ff, "> " prefix
```

### 8.3 The Header Eyebrow Pattern

```
FIG.09 // THEME-11                   ← eyebrow, JetBrains Mono/Space Grotesk 10.5px, tracking 0.16em, uppercase, #4fd1ff
BLUEPRINT_UI                         ← title, Space Grotesk 600, clamp(28px,4vw,44px), #e8f4fc, accent suffix in cyan
Space Grotesk + JetBrains Mono ·...  ← subtitle, JetBrains Mono 13.5px, #7fa9c4
```

### 8.4 Weight as Hierarchy

| Hierarchy Level | Font | Weight | Color |
|-----------------|------|--------|-------|
| Display | Space Grotesk | 600 | `#e8f4fc` |
| Section heading | Space Grotesk | 600 | `#bcdff0` |
| Subheading | JetBrains Mono | 400 | `#4fd1ff` |
| Body | JetBrains Mono | 400 | `#cfe9fb` |
| Label | JetBrains Mono | 600 | `#7fa9c4` |

Because JetBrains Mono has limited weight variance in practice (mostly 400/600), hierarchy leans on **color** more than weight — similar to Mono (Theme 06), but even more pronounced here since almost all mono text sits at 400.

---

## 9. Spacing Construction Rules

### 9.1 The Padding Budget for Components

| Component | Padding |
|-----------|---------|
| Badge | 3px vertical, 9px horizontal |
| Input | 11px vertical, 14px horizontal |
| Button | 11px vertical, 22px horizontal |
| Card | 26px vertical, 30px horizontal |
| Table header cell | 10px vertical, 14px horizontal |
| Table body cell | 10px vertical, 14px horizontal |
| Dropdown item | 10px vertical, 14px horizontal |

### 9.2 Vertical Rhythm in Forms

```
[Field Label — JetBrains Mono 10.5px, uppercase, #7fa9c4]
         ↕ 7px
[Input — 0px radius, #365a76 border]
         ↕ 14–18px (between field groups)
[Next Field Label]
```

---

## 10. Component Construction Guides

### 10.1 How to Build a Card — Step by Step

**Step 1: Container** — `rgba(11,40,66,0.7)` background, `1px solid rgba(79,209,255,0.35)` border, `position: relative`, `padding: 26px 30px`, `border-radius: 0`

**Step 2: Corner brackets** — add `::before` (top-left) and `::after` (bottom-right) pseudo-elements, `10px × 10px`, `1.5px solid #4fd1ff`, each missing two adjacent sides

**Step 3: Section title** — `// ` prefix, Space Grotesk 600, 11px, uppercase, `#4fd1ff`, tracking `0.14em`, margin-bottom `18px`

**Step 4: Content** — body text JetBrains Mono 400, 14px, `#cfe9fb`

### 10.2 How to Build a Button — Step by Step

**Step 1: Shape** — always `border-radius: 0`, `padding: 11px 22px`, Space Grotesk 600 13px label

**Step 2: Primary** — solid `#4fd1ff` fill, `#0b3d63` text, `1px solid #4fd1ff` border

**Step 3: All other variants** — `background: transparent`, distinguish via border style (solid/dashed) and text color only

**Step 4: Hover** — primary lightens to `#7de0ff`; transparent variants gain a faint `rgba(79,209,255,0.08)` tint

### 10.3 How to Build a Badge — Step by Step

**Step 1: Shell** — `border-radius: 0`, `padding: 3px 9px`, `border: 1px solid currentColor`, transparent background

**Step 2: Pick the semantic color** — info/success: `#4fd1ff`; warning: `#ffd166`; error: `#ff8080`

**Step 3: Typography** — JetBrains Mono 600, 10.5px

### 10.4 How to Build a Dropdown — Step by Step

**Step 1: Panel** — `#0e2c47` background, `1px solid #4fd1ff` border, `border-radius: 0`, `margin-top: 6px`, `--shadow-dropdown`

**Step 2: Items** — `10px 14px` padding, `1px solid rgba(79,209,255,0.12)` divider between items (removed on `:last-child`)

**Step 3: Hover/selected** — `rgba(79,209,255,0.15)` background, `#4fd1ff` text

---

## 11. Interactive States — Full Decision Guide

### 11.1 Button States

**Primary (filled cyan):**
- Default: `background:#4fd1ff`, `color:#0b3d63`
- Hover: `background:#7de0ff`
- Disabled: `opacity:0.4`

**Secondary/Outline/Dashed (transparent):**
- Default: `background:transparent`, bordered
- Hover: `background: rgba(79,209,255,0.08)`

### 11.2 Input Focus

```css
.input:focus { border-color: #4fd1ff; box-shadow: 0 0 0 1px #4fd1ff; }
```

### 11.3 Table Row Hover

```css
tr:hover td { background: rgba(79,209,255,0.08); }
```

---

## 12. Layout Construction Rules

### 12.1 Page Layout Model

```css
.page-content {
  max-width: 1200px;
  margin: 0 auto;
  padding: 40px 24px 100px;
}
```

### 12.2 Dashboard Grid Pattern

```css
.layout-2col { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
.layout-3col { display: grid; grid-template-columns: 1fr 1fr 1fr; gap: 18px; }
```

---

## 13. Animation Rules

### 13.1 What Can Animate

| Element | Property | Duration | Easing |
|---------|----------|----------|--------|
| Button hover | `background` | 150ms | ease-out |
| Input focus | `border-color`, `box-shadow` | 150ms | ease-out |
| Dropdown open | `opacity` | 100ms | ease-out |

### 13.2 What Should Not Animate

- Card appearance (no entrance animation)
- Corner brackets (always static)
- Border-radius (never present, therefore never animated)
- Any bounce/spring easing

---

## 14. What Never to Do — Anti-Pattern List

### Typography Anti-Patterns

| ❌ Never | ✅ Instead |
|---------|----------|
| Use Space Grotesk for body/table text | Space Grotesk is headings/buttons only |
| Omit the `// ` or `> ` prefixes | Both are mandatory system signatures |

### Color Anti-Patterns

| ❌ Never | ✅ Instead |
|---------|----------|
| Fill a card or page with cyan | Cyan is an ink/line color, not a surface fill |
| Add a soft cyan glow | Focus/borders are hard 1px lines |
| Introduce green for success | Success shares cyan; only warning/error get distinct hues |

### Border Radius Anti-Patterns

| ❌ Never | ✅ Instead |
|---------|----------|
| Use any radius > 0px | Every element is 0px, no exceptions |
| Round the radio into a circle | Radios are square with a mark, not circular |

### Structural Anti-Patterns

| ❌ Never | ✅ Instead |
|---------|----------|
| Add a soft `box-shadow` to a card | Use border + corner brackets only |
| Fill a badge with a solid color | Badges are outline-only, `border:1px solid currentColor` |
| Remove the background grid | The grid is a permanent structural element |
| Add bounce/spring easing | All motion is ease-out, instant and utilitarian |

---

## 15. AI Prompting Instructions

**System prompt to include:**

> Build this UI using the Blueprint design system.
>
> Core rules:
> — Page background is deep navy `#0b3d63` with a permanent cyan graph-paper grid: two overlapping `linear-gradient`s at `28px × 28px`, `rgba(79,209,255,0.08)` lines. Never remove this grid.
> — Border-radius is `0px` on every element, without exception — cards, buttons, inputs, badges, dropdowns, tables.
> — Cards are `rgba(11,40,66,0.7)` background, `1px solid rgba(79,209,255,0.35)` border, with two open corner brackets (`::before` top-left, `::after` bottom-right, `10px`, `1.5px solid #4fd1ff`, each missing two sides). No soft box-shadow on cards.
> — Primary accent: `#4fd1ff` cyan. Use for primary button fill, card borders/brackets, section titles, subheadings, input focus (hard `1px` ring, no blur), table header rules.
> — Only the primary button is filled solid cyan; every other button variant is `background:transparent` with a border.
> — Badges are outline-only: `border:1px solid currentColor`, transparent background, no solid fills.
> — Fonts: Space Grotesk for headings and button labels (weight 600). JetBrains Mono for everything else — body, inputs, labels, tables, badges.
> — Every section title is prefixed with `// ` and every subheading with `> `.
> — Warning is `#ffd166`, error is `#ff8080`; success/info both share the primary cyan `#4fd1ff`.
> — Motion is minimal: no entrance animations beyond opacity fades, no hover lifts or glows.

---

## 16. New Project Checklist

**Fonts:**
- [ ] Space Grotesk imported (weight 600)
- [ ] JetBrains Mono imported (weights 400–700)

**Colors:**
- [ ] Navy background + grid overlay applied
- [ ] `#4fd1ff` set as the single accent

**Radius:**
- [ ] Every element confirmed at `border-radius: 0`

**Shadows:**
- [ ] No soft box-shadows on cards or buttons
- [ ] Dropdown panel has the one permitted drop shadow
- [ ] Input focus is a hard 1px ring

**Structure:**
- [ ] Cards have corner brackets
- [ ] Section titles have `// ` prefix
- [ ] Subheadings have `> ` prefix
- [ ] Badges are outline-only

---

## 17. Component Pattern Library

### Pattern: Spec Card

```html
<div class="bp-card">
  <div class="bp-section-title">Typography</div>
  <div style="font-family:'JetBrains Mono';color:#4fd1ff;">&gt; Subheading text style</div>
</div>
```

### Pattern: Page Header

```html
<div class="bp-card" style="margin-bottom:32px;">
  <div style="font-size:10.5px;font-weight:600;letter-spacing:0.16em;text-transform:uppercase;color:#4fd1ff;margin-bottom:10px;">FIG.09 // THEME-11</div>
  <h1 style="font-family:'Space Grotesk';font-size:clamp(28px,4vw,44px);font-weight:600;margin:0;color:#e8f4fc;">BLUEPRINT<span style="color:#4fd1ff;">_UI</span></h1>
</div>
```

### Pattern: Outline Badge Row

```html
<span class="badge" style="color:#4fd1ff;">Info</span>
<span class="badge" style="color:#ffd166;">Warning</span>
<span class="badge" style="color:#ff8080;">Error</span>
```

---

## 18. Responsive Construction Rules

**Below 480px:**
- Grids collapse to single column
- Card padding reduces from 26–30px to 18px

**480px–1023px:**
- Two/three-column layouts remain where space allows

**1024px+:**
- Full system at designed specifications

---

## 19. Accessibility Guidelines

### 19.1 Color Contrast Requirements

| Pairing | Contrast | Notes |
|---------|----------|-------|
| `#e8f4fc` on `#0b3d63` | ~11:1 | AAA safe |
| `#cfe9fb` on `#0b3d63` | ~9:1 | AAA safe |
| `#7fa9c4` on `#0b3d63` | ~5.2:1 | AA safe |
| `#4fd1ff` on `#0b3d63` | ~8.5:1 | AAA safe |

**Rules:**
- `#4a6b85` (disabled/border) is decorative-only and should never carry required reading content.
- Verify text placed directly over the grid pattern remains legible — the grid opacity (`0.08`) is intentionally low to avoid interfering with text contrast.

### 19.2 Focus Management

- All interactive elements need `outline: 2px solid #4fd1ff; outline-offset: 2px;` for `:focus-visible`
- The 1px focus ring on inputs is a minimum; do not remove it in favor of only a border-color change

---

## 20. Common Scenarios — Decision Trees

### Scenario: "What radius do I use?"

```
Always 0px. There is no decision tree — this system has no radius variance.
```

### Scenario: "Should this button be filled or outline?"

```
Is it the single primary/main action on the screen? ──YES──► Filled cyan
        │ NO
        ▼
Default: transparent + border (secondary, outline, destructive, dashed)
```

### Scenario: "What color for this badge?"

```
Is it a warning-level message? ──YES──► #ffd166
        │ NO
        ▼
Is it an error/failure state? ──YES──► #ff8080
        │ NO
        ▼
Default: #4fd1ff (info/success share this)
```

---

*End of Instructions — Blueprint v1.0*
*Design System Document: blueprint-design-system.md*
*Instructions Document: blueprint-instructions.md*