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

---

## Table of Contents

1. [Design Philosophy & Core Rules](#1-design-philosophy--core-rules)
2. [The Dual-Font Law](#2-the-dual-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. [Blue Accent — When and How](#7-blue-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

The Rounded system is built on a single conviction: **approachability earns trust.** Where rigid systems use sharp edges to project authority, Rounded uses generous curves and clear color hierarchies to feel welcoming, capable, and easy to navigate. It is the language of products that want their users to feel confident and in control — not intimidated.

This is not softness for softness's sake. It is the aesthetic language of the best modern consumer software — think Notion, Linear, GitHub in its modern form, Vercel's dashboard. Clean backgrounds, rounded inputs, deep blue as the one action color, strong typographic weight contrast. The message to users is: *this is friendly, modern, and built for you.*

---

### The 10 Commandments of This System

**1. Curved over sharp.**  
Nothing in this system has a corner tighter than 8px (except hairline dividers). Inputs are 10px. Cards are 12px. Modals can go to 16px or 20px. Sharpness reads as hostile in this system.

**2. Blue is the only action color.**  
`#3b82f6` (Blue 500) is the singular primary accent. It appears on: primary buttons, input focus states, active links, selected states, and count badges. Do not introduce a second accent color. Blue has all the meaning in this system.

**3. White surfaces, always.**  
Cards, modals, and input backgrounds are always `#ffffff` — never the blue-grey page background. White surfaces create clear contrast against the `#f0f4f8` page tone. Inputs on white cards still get white backgrounds.

**4. Weight is the hierarchy.**  
Typographic hierarchy is driven by font weight, not color. Display text is weight 800. Section titles are 700. Body is 400. Labels are 600. The dramatic weight swing (800 to 400) creates visual structure without needing size extremes.

**5. Buttons glow on hover.**  
Primary and destructive buttons gain a colored drop shadow on hover. This is the system's signature interactive detail. Do not remove it — it is what makes the system feel tactile and alive.

**6. Focus rings are blue rings.**  
The focus state for inputs uses both `border-color: #3b82f6` AND `box-shadow: 0 0 0 3px rgba(59,130,246,0.12)`. The ring is what makes focus clear across all backgrounds without a garish outline.

**7. Badges are always pills.**  
`border-radius: 20px` (or `border-radius: 9999px`) for all status badges. The pill shape is non-negotiable and is what makes the Rounded badge system feel native.

**8. Cool-tone shadows.**  
Shadows in this system use `rgba(0,0,0,...)` — neutral grey, not warm amber, not pure cool. Only button hover shadows use a tinted variant (`rgba(59,130,246,0.30)`). The system is cool, not warm.

**9. Serif is accent, not structural.**  
Lora serif appears only in subheadings (H3 context), pull quotes, and captions — never as the primary display or body font. Plus Jakarta Sans carries the full UI weight.

**10. Motion is friendly.**  
Hover states transition at 200ms. Press states scale to 0.98 at 50ms. There is no heavy animation — the motion is quick and confirms actions without performing.

---

## 2. The Dual-Font Law

This system uses two font families. Every piece of text belongs to one of them.

### Category 1: Plus Jakarta Sans — Everything
**Assignment question: Is this text UI text, navigation, a title, body copy, a label, or a button?**

If yes → Plus Jakarta Sans, with appropriate weight.

- Hero display (H1): YES → Plus Jakarta Sans 800
- Page / section heading (H2): YES → Plus Jakarta Sans 700
- UI body copy: YES → Plus Jakarta Sans 400
- Button text: YES → Plus Jakarta Sans 600
- Field labels: YES → Plus Jakarta Sans 600
- Table headers: YES → Plus Jakarta Sans 700
- Badge text: YES → Plus Jakarta Sans 700
- Nav items: YES → Plus Jakarta Sans 500
- Metadata / timestamps: YES → Plus Jakarta Sans 400, muted color

**Weight is everything.** Plus Jakarta Sans at 800 looks completely different from Plus Jakarta Sans at 400 — the weight contrast is the system's typographic hierarchy engine.

---

### Category 2: Lora (Serif) — Editorial Accents Only
**Assignment question: Is this text a secondary heading, pull quote, editorial caption, or a `<blockquote>`?**

If yes → Lora, typically italic.

- H3 subheadings (inside cards/sections): YES → Lora regular or Lora 600
- Pull quote / `<blockquote>`: YES → Lora italic 400
- Section caption (explanatory text below a section title): YES → Lora italic, muted
- Body copy: NO → use Plus Jakarta Sans 400

**Lora is decoration, not structure.** It adds editorial warmth without taking over. Never use it as the primary content font.

---

### Font Decision Flowchart

```
Is it a secondary heading, pull quote, or editorial caption? ──YES──► Lora (serif)
        │ NO
        ▼
Everything else ──────────────────────────────────────────────────► Plus Jakarta Sans
        (weight: 800 for hero, 700 for headings, 600 for labels/buttons, 400 for body)
```

---

## 3. Color Application Rules

### 3.1 Background Selection Rules

| Surface | Color | Why |
|---------|-------|-----|
| Page body | `#f0f4f8` | Cool blue-grey — recedes behind white cards |
| Cards, panels | `#ffffff` | Always white — maximum contrast on page bg |
| Modals | `#ffffff` | Same as cards — elevation via shadow |
| Input fields | `#ffffff` | White — clear input affordance |
| Table headers | `#f8fafc` | Barely-lighter — subtle inset feel |
| Row hover | `#f8fafc` | Same as header — minimal disturbance |

**Rule:** You have exactly two background values: `#f0f4f8` (page) and `#ffffff` (everything else). Do not introduce a third mid-tone. The contrast between the page background and the white surfaces is the system's layering model.

---

### 3.2 Blue Usage Rules

Blue is the system's action signal. Use it in exactly these contexts:

1. **Primary button background** — `#3b82f6`
2. **Input focus border + ring** — `border-color: #3b82f6; box-shadow: 0 0 0 3px rgba(59,130,246,0.12)`
3. **Active / hover accent text** — `#2563eb` on links, active nav
4. **Count badge on primary** — blue background, white text for notification counts
5. **Outline button border and text** — `#3b82f6`

**Allowed, use with care:**
- Blue as the accent color on a count badge within a list item
- Blue dot for active navigation items
- Blue underline for the active tab indicator

**Never:**
- Blue as a page or card background
- Blue for decorative graphic elements
- Blue for secondary text in the hierarchy
- Two different shades of blue on the same component simultaneously

---

### 3.3 Text Color Assignment

Always ask: what is the information hierarchy of this text?

| Priority | Color | Hex | Examples |
|----------|-------|-----|---------|
| Highest | Near-black primary | `#0f172a` | Hero titles, H1, H2, modal title |
| High | Dark slate | `#1e293b` | Body copy, secondary headings |
| Medium | Medium slate | `#475569` | Labels, captions, helper text |
| Low | Muted slate | `#64748b` | Timestamps, metadata, placeholder |
| Disabled | Light slate | `#94a3b8` | Disabled state text |
| On blue/dark | White | `#ffffff` | Button text, badge text on dark bg |
| Accent link | Blue | `#2563eb` | Hyperlinks, active states |

**Rule:** Never use the blue accent for non-interactive text. Blue text signals "I am clickable." If something is not interactive, use the slate hierarchy.

---

### 3.4 Semantic Color Rules

For success, warning, error, and info states:
- Always combine: colored badge background + colored text (for compact badges)
- For full input error states: change border color + show message text below
- Never use blue for a semantic state — blue is aesthetic/action, not semantic
- Never use only one of background or text change — do both

---

## 4. Border Radius Decision Framework

This is the system's most visible design decision. Rounded corners are non-negotiable.

### Is this element a primary interactive control?
**Examples:** button (all variants), text input, select, textarea, search field
→ Use `border-radius: 10px` (`--radius-md`)

### Is this element a container or structural panel?
**Examples:** card, modal, dropdown menu (standard), popover, tooltip
→ Use `border-radius: 12px` (`--radius-lg`)

### Is this element a large overlay?
**Examples:** confirmation modal, full-panel modal, featured modal
→ Use `border-radius: 16px` (`--radius-xl`) or `20px` (`--radius-2xl`)

### Is this a status badge or count indicator?
**Examples:** Active, Pending, Error badges, notification count bubble
→ Use `border-radius: 20px` or `9999px` (`--radius-full`) — always pill

### Is this an inline action within a table?
**Examples:** Edit button in table, small action chip
→ Use `border-radius: 8px` (`--radius-sm`)

### Is this a horizontal rule or divider?
→ Use `border-radius: 0px` — always flat

---

### Quick Reference Table

| Element | Radius |
|---------|--------|
| Button (all sizes) | 10px |
| Text input | 10px |
| Textarea | 10px |
| Select dropdown (button) | 10px |
| Dropdown menu (panel) | 12px |
| Dropdown item (inner) | 8px |
| Badge / status chip | 20px (pill) |
| Count badge | 9999px |
| Checkbox | 5px |
| Card | 12px |
| Modal (standard) | 16px |
| Modal (large/confirm) | 20px |
| Table container | 12px |
| Table cell | 0px |
| Toggle track | 9999px |
| Toggle thumb | 9999px |
| Inline table action button | 8px |
| Horizontal rule | 0px |

---

## 5. Background & Surface Rules

### 5.1 The Layering Model

```
Layer 3 (highest): Modals → #ffffff + shadow-modal
Layer 2:           Cards, Panels → #ffffff + shadow-card
Layer 1:           Dropdowns → #ffffff + shadow-lg (when floating)
Layer 0 (lowest):  Page Background → #f0f4f8
```

**Key insight:** Every elevated element is `#ffffff`. Elevation is expressed entirely through shadow depth, never through background color changes.

---

### 5.2 Input Background Rule

Inputs are always `#ffffff`. When on a white card, the input looks the same as the card — the 1.5px border and the slight padding create the input affordance. Do not use the page background (`#f0f4f8`) for inputs; it creates ambiguity between input and non-input areas.

When an input is disabled, add `opacity: 0.4` — do not change the background color.

---

### 5.3 No Gradient Backgrounds

Do not use gradient backgrounds anywhere — not on buttons, not on cards, not on hero sections. The system is clean and flat. The only visual complexity allowed is the shadow system and the colored focus ring.

---

### 5.4 Backdrop on Modal Overlays

Modals use a dark backdrop, not a blur:

```css
.modal-overlay {
  background: rgba(15, 23, 42, 0.5);
}
```

Do not use `backdrop-filter: blur()` — it is expensive and inconsistent across browsers. The semi-transparent dark overlay is sufficient and performs well.

---

### 5.5 When NOT to Use a Background

Ghost buttons, inline text links, and icon buttons should be `background: transparent`. Adding a background to every interactive element creates visual noise — this system's cleanliness comes from restraint.

---

## 6. Shadow & Elevation Rules

### 6.1 The Neutral Shadow Rule

Shadows use neutral `rgba(0,0,0,...)` at low opacity — not warm amber, not blue-tinted. The single exception is button hover shadows, which use the button's own accent color.

---

### 6.2 Elevation and Shadow Pairing

| What You're Building | Shadow to Use |
|---------------------|---------------|
| Card on page background | `--shadow-card` |
| Dropdown / select panel | `--shadow-lg` |
| Modal / dialog | `--shadow-modal` |
| Button on hover (primary) | `0 4px 12px rgba(59,130,246,0.30)` |
| Button on hover (destructive) | `0 4px 12px rgba(239,68,68,0.30)` |

---

### 6.3 The Button Hover Shadow — Mandatory

Every primary button and destructive button must gain a colored shadow on hover. This is what makes buttons feel interactive and alive in this system. It is non-negotiable:

```css
.btn-primary:hover {
  background: #2563eb;
  box-shadow: 0 4px 12px rgba(59, 130, 246, 0.30);
}
```

---

### 6.4 Do Not Use Shadows on Inputs

Inputs use `border-color` and `box-shadow` for the focus ring only — not for elevation. An input should not look "raised" — it should look like a writing surface inset into the card.

---

## 7. Blue Accent — When and How

### When to Use Blue

| Use It | Don't Use It |
|--------|-------------|
| Primary button background | Page background |
| Input focus border + ring | Card background |
| Active navigation indicator | Decorative text |
| Count badge | Section headings |
| Outline button border and text | Table headers |
| Hyperlinks | Labels / form labels |

**Rule:** Blue means action or selection. Any blue element the user sees should either be clickable or indicate a currently active/selected state. Blue on non-interactive text or decoration is a category error.

---

### How to Signal Active State

For navigation items, tabs, and list selections, signal active state with:
1. Color shift to `#2563eb` or `#3b82f6` for text
2. A blue dot, underline, or left border
3. A subtle background shift to `#eff6ff` (blue-50)

Never use a blue background fill on a nav item — reserve fills for buttons and badges.

---

## 8. Typography Application Rules

### 8.0 Component showcase — font names are mandatory

The live component showcase opens with a **Typography** section that must:

1. List every font role (`display`, `body`, `label`, `accent`) in an explicit card grid with **family name + usage** — sourced from `design-systems.json`, never left implicit.
2. Render the full type scale at actual sizes: Display/Hero (48px), page title (32px), section heading (24px), body large (18px), body base (15px), caption (13px), and a label/eyebrow sample.

For Rounded: **Plus Jakarta Sans** for display, body, and labels; **Lora** for serif accent subheads and pull quotes only.

### 8.1 The Title Pattern (No Eyebrow)

Unlike editorial systems, Rounded does not use a formal eyebrow → title pattern. Titles stand alone. The typographic weight is enough:

```
Design System Explorer   ← Plus Jakarta Sans, 48px, weight 800, #0f172a
                         ← 8px gap
Border radius: 12px · Plus Jakarta Sans + Lora · Blue accent
                         ← Small meta info, 13px, weight 500, #94a3b8
```

The weight contrast (800 vs 500/400) creates all necessary hierarchy.

---

### 8.2 The Section Title Pattern

Section titles inside cards use the visual eyebrow pattern but with the section-title class style — small, uppercase, muted:

```
TYPOGRAPHY                        ← 11px, uppercase, letter-spacing 0.10em, #94a3b8
────────────────────────────────  ← 1px border-bottom on the eyebrow element itself
[content below]
```

This label + underline combination (built into the `.section-title` class) separates labeled content areas from each other without heavy dividers.

---

### 8.3 Weight System for Headings

Use weight as hierarchy, not decoration:

| Level | Weight | Context |
|-------|--------|---------|
| Hero | 800 | H1, page display |
| Section | 700 | H2, panel titles |
| Sub-section | 600 | H4, card subtitles, labels |
| Body | 400 | Paragraphs, descriptions |
| Meta | 500 | Navigation, secondary labels |

Never use weight 400 for a heading — at minimum, labels are 600. Never use weight 800 for body copy — it is exclusively display.

---

### 8.4 When to Use Lora (Serif)

Lora earns its place in three scenarios:

**Scenario 1 — Serif subheading inside a card:**
```html
<div style="font-family:'Lora',serif; font-size:22px; font-weight:600; color:#334155;">
  Subhead in Lora Serif
</div>
```

**Scenario 2 — Pull quote / testimonial:**
```html
<blockquote style="font-family:'Lora',serif; font-style:italic; font-size:14px; color:#94a3b8; line-height:1.6;">
  "Lora italic for pullquotes, captions, and elegant secondary text."
</blockquote>
```

**Scenario 3 — Editorial section intro:**
```html
<p style="font-family:'Lora',serif; font-style:italic; font-size:15px; color:#64748b;">
  Introductory editorial sentence before the main content.
</p>
```

Do not use Lora in: buttons, labels, nav items, table headers, badges, or any functional UI element.

---

### 8.5 Letter Spacing Rules

| Font & Context | Spacing | Why |
|----------------|---------|-----|
| Plus Jakarta Sans 800 (hero) | `-0.03em` | Very tight — creates compact display block |
| Plus Jakarta Sans 700 (headings) | `-0.02em` to `-0.01em` | Tighter = more structured |
| Plus Jakarta Sans body | `0em` | Never touch default |
| Plus Jakarta Sans labels | `0.01em` | Slight air for readability at small size |
| Section eyebrow | `0.08em` to `0.10em` | Air needed for uppercase |
| Lora serif | `0em` | Default — let the serif do the work |

---

## 9. Spacing Construction Rules

### 9.1 The Padding Budget for Components

| Component | Padding |
|-----------|---------|
| Badge | 3px vertical, 10px horizontal |
| Form field input | 10px vertical, 14px horizontal |
| Button small | 7px vertical, 14px horizontal |
| Button base | 10px vertical, 20px horizontal |
| Button large | 12px vertical, 24px horizontal |
| Card | 24px all sides |
| Card large | 28px–32px all sides |
| Modal | 32px all sides |
| Sidebar | 24px all sides |
| Page section | 40px vertical, varies horizontal |

---

### 9.2 Vertical Rhythm in Forms

```
[Field Label — Plus Jakarta Sans, 13px, 600]
         ↕ 6px
[Input or Textarea]
         ↕ 5px (if helper text present)
[Helper Text — Manrope, 12px, muted]
         ↕ 20px (between field groups)
[Next Field Label]
```

---

### 9.3 Title → Description Sequence in Modals

```
[Modal Title — Jakarta Sans, 20px, 800]
    ↕ 6px
[Description — Jakarta Sans, 14px, 400, muted]
    ↕ 20px
[Form field or content]
```

No horizontal rule between modal title and content — this system uses spacing alone for separation.

---

### 9.4 Button Group Spacing

When two buttons appear together:
- Gap: `10px`
- Cancel goes left, action goes right
- Both buttons same flex weight unless there's a clear primary action

```css
.btn-group {
  display: flex;
  gap: 10px;
  justify-content: flex-end;  /* Right-aligned in modals */
}
```

---

## 10. Component Construction Guides

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

**Step 1: Backdrop**
- Position fixed, full viewport
- Background: `rgba(15, 23, 42, 0.5)` — dark navy at 50%
- No blur
- Z-index: 400

**Step 2: Modal container**
- Background: `#ffffff`
- Border: none (shadow provides boundary)
- Border-radius: `16px`
- Padding: `32px`
- Max-width: `480px` (standard)
- Box-shadow: `0 24px 64px rgba(0,0,0,0.15)`

**Step 3: Modal title**
- Plus Jakarta Sans, `20px`, weight `800`
- Color: `#0f172a` (primary for action) or semantic color for destructive (`#dc2626`)
- Margin-bottom: `6px`

**Step 4: Description**
- Plus Jakarta Sans, `14px`, weight `400`
- Color: `#64748b` (muted)
- Line-height: `1.6`
- Margin-bottom: `20px`

**Step 5: Form fields (if applicable)**
- Label: Plus Jakarta Sans, 13px, 600, `#475569`
- Input: white bg, 1.5px `#e2e8f0` border, 10px radius
- Margin-bottom on input: `12px`

**Step 6: Button row**
- Flex, gap `10px`, justify-content `flex-end`
- Cancel: `background:#f1f5f9`, 10px radius, text `#475569`
- Confirm: `background:#3b82f6`, 10px radius, white text

---

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

**Step 1: Container**
- Background: `#ffffff`
- Border: `1px solid #e2e8f0`
- Border-radius: `12px`
- Padding: `24px`
- Box-shadow: `0 1px 3px rgba(0,0,0,0.06), 0 4px 12px rgba(0,0,0,0.06)`

**Step 2: Section label (optional)**
- `.section-title` class: 11px uppercase, `#94a3b8`, border-bottom `#e2e8f0`, padding-bottom 8px, margin-bottom 20px

**Step 3: Content**
- Body text: Plus Jakarta Sans, `14px`, `#475569`
- If tabular: use the table system inside the card

**Step 4: Card footer (optional)**
- Border-top: `1px solid #f1f5f9`
- Padding: `16px 24px`
- Background: same as card

---

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

**Step 1: Container**
- No background of its own (inherits card or page)
- Max-width: `480px`–`560px` for standalone forms

**Step 2: Field groups**
Each field group:
```
Label (Jakarta Sans, 13px, 600, #475569)
   ↕ 6px
Input (white, 1.5px border, 10px radius, padding 10px 14px)
   ↕ 5px (if helper text)
Helper text (Jakarta Sans, 12px, 400, muted)
   ↕ 20px to next group
```

**Step 3: Grid layout for multiple fields**
- Use 2-column grid: `grid-template-columns: 1fr 1fr; gap: 16px–20px`
- Full-width fields: `grid-column: 1 / -1`

**Step 4: Submit section**
- Flex row, right-aligned
- Gap: `10px`
- Margin-top: `8px` from last field (the field's own bottom margin handles the rest)

---

### 10.4 How to Build a Data Table — Step by Step

**Step 1: Wrapper container**
- Border: `1px solid #e2e8f0`
- Border-radius: `12px`
- Overflow: hidden
- Shadow: none needed (flat table approach)

**Step 2: Table header**
- Background: `#f8fafc`
- Column headers: Plus Jakarta Sans, 11px, 700, uppercase, `#475569`, tracking `0.06em`
- Border-bottom: `1px solid #e2e8f0`
- Padding: `12px 16px`

**Step 3: Table rows**
- Cell text: Plus Jakarta Sans, `14px`, `#1e293b`
- Border-bottom: `1px solid #f1f5f9` (hairline between rows)
- Padding: `12px 16px`
- Last row: no border-bottom (`border-collapse: separate` + remove last tr's border)

**Step 4: Hover state**
- Background: `#f8fafc`
- Transition: `background 0.1s`

**Step 5: Status badges in cells**
- Use badge component (pill, semantic colors)
- Inside a `<td>` — never inline with text, always its own cell or paired in a flex cell

---

## 11. Interactive States — Full Decision Guide

### 11.1 Hover States

| Element | What Changes | Duration |
|---------|-------------|---------| 
| Primary button | Background `#3b82f6` → `#2563eb` + blue glow shadow | 200ms |
| Secondary button | Background `#f1f5f9` → `#e2e8f0` | 200ms |
| Outline button | Gets `#eff6ff` background wash | 200ms |
| Destructive button | Background darkens + red glow shadow | 200ms |
| Table row | Background → `#f8fafc` | 100ms |
| Input | Border stays same — focus is what changes input state | — |
| Nav item | Background → `#f0f9ff`, color → `#2563eb` | 100ms |
| Dropdown item | Background → `#eff6ff`, color → `#3b82f6` | 100ms |
| Card | Subtle shadow increase optional, not required | 200ms |

---

### 11.2 Focus States

For all form inputs:
```css
input:focus, textarea:focus, select:focus {
  border-color: #3b82f6;
  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.12);
  outline: none;
}
```

For buttons and interactive elements (keyboard navigation):
```css
button:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}
```

---

### 11.3 Active / Press States

```css
button:active { transform: scale(0.98); transition: transform 50ms; }
```

The micro-scale at 50ms confirms press. Never go lower than `scale(0.97)` or higher than `scale(0.99)`.

---

### 11.4 Disabled States

```css
.disabled {
  opacity: 0.4;
  cursor: not-allowed;
  pointer-events: none;
}
```

Use `opacity: 0.4` consistently. Do not change background color for disabled buttons — opacity communicates disability without needing new color tokens.

---

### 11.5 Error States

For form fields with errors:
1. Border: changes to `#fca5a5` (error border)
2. Optional: `box-shadow: 0 0 0 3px rgba(239,68,68,0.12)`
3. Error message below: Plus Jakarta Sans, 12px, `#dc2626`

---

## 12. Layout Construction Rules

### 12.1 Page Structure Pattern

```
[Fixed Header / Nav — 56px–64px]
[Page body — flex or grid]
   [Optional Sidebar — 240px–280px]
   [Main content area — flex 1]
      [Page header — title + subtitle + meta tags]
      [Content grid — cards, tables, forms]
[Optional Footer]
```

---

### 12.2 Card Grid System

Cards in this system sit in grids. Default card grid:
- 2 columns: `grid-template-columns: 1fr 1fr; gap: 20px`
- 3 columns: `grid-template-columns: repeat(3, 1fr); gap: 20px`
- `2fr 1fr` split: for main-content + sidebar-panel layouts within a section

---

### 12.3 Horizontal Breathing Room

- Text lines: never exceed 700px in line width for body copy
- Cards: always separated by at least `20px` gap
- Modals: always `24px` between modal edge and viewport edge
- Page content: minimum `16px` left-right margin at any viewport

---

## 13. Animation Rules

### 13.1 What Gets Animated

| Element | Animation | Trigger |
|---------|-----------|---------|
| Modal | fade in (opacity 0→1) | Open |
| Dropdown panel | scale(0.95→1) + fade | Open |
| Button hover | background + shadow | Hover |
| Button press | scale(0.98) | Click/press |
| Toggle switch | translateX | Toggle |
| Row hover | background color | Hover |

### 13.2 What Never Gets Animated

- Border-radius changes
- Font-weight changes
- Height/width changes (except controlled collapse)
- Box-shadow on inputs (appears instantly on focus)
- Badge colors on state change

### 13.3 Performance Rule

Only animate: `transform`, `opacity`, `background-color`, `border-color`, `box-shadow`.

Toggle switch uses only `transform: translateX` on the thumb — never animate the track width.

---

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

### Typography Anti-Patterns
- ❌ Using Lora for body copy or button text (functional UI must use Jakarta Sans)
- ❌ Using weight 400 for a heading at any size (minimum 600 for any heading)
- ❌ Setting hero display below weight 700 (lose the weight contrast that drives hierarchy)
- ❌ Adding letter-spacing to large display text in the positive direction (tightens look; use negative or zero)
- ❌ Using Lora uppercase — Lora is a text face, not a display face; keep it mixed case

### Color Anti-Patterns
- ❌ Using `#f0f4f8` (page bg) inside a card or modal (cards must be white)
- ❌ Using blue for non-interactive body text (blue means clickable in this system)
- ❌ Adding a warm tint to shadows (this system is cool-toned; warm shadows fight it)
- ❌ Using semantic colors (red, green) for aesthetic decoration
- ❌ Introducing a second accent color alongside blue (blue is the only accent)

### Shape Anti-Patterns
- ❌ Applying `border-radius: 2px` or `4px` to buttons (minimum 10px in this system)
- ❌ Using square badges (badges are always pill-shaped — 20px+)
- ❌ Using sharp corners on modals (minimum 16px for modals)
- ❌ Using `border-radius: 0` on table container (the rounded container with overflow:hidden is the system signature)

### Shadow Anti-Patterns
- ❌ Omitting the button hover shadow on primary buttons (it is required)
- ❌ Using `box-shadow` to elevate inputs at rest (inputs have no shadow — only focus ring)
- ❌ Using warm amber shadows `rgba(100,80,30,...)` — wrong system
- ❌ Using the modal shadow on non-modal cards (over-elevation)

### Spacing Anti-Patterns
- ❌ Gap below 10px in a cancel + confirm button pair
- ❌ Padding below 10px vertical inside any button
- ❌ Padding below 10px vertical inside any input
- ❌ Gap below 6px between label and its input
- ❌ Card padding below 20px (minimum 24px standard)

---

## 15. AI Prompting Instructions

### 15.1 System Context Block

Include this at the start of any AI conversation about building UI:

```
You are building using the Rounded design system. The system uses two fonts:
- Plus Jakarta Sans (300–800) for ALL UI text — display, body, buttons, labels, nav
- Lora (serif, 400/600, usually italic) for editorial accents only (H3 subheads, pull quotes)

Key token values:
- Page background: #f0f4f8 (cool blue-grey)
- Card/surface background: #ffffff (always white)
- Primary text: #0f172a (near-black)
- Secondary text: #1e293b
- Muted text: #64748b
- Blue accent (primary): #3b82f6
- Blue hover: #2563eb
- Border default: #e2e8f0 (1.5px on inputs)
- Input focus: border-color #3b82f6 + box-shadow: 0 0 0 3px rgba(59,130,246,0.12)
- Shadow neutral: rgba(0,0,0, opacity)
- Modal shadow: 0 24px 64px rgba(0,0,0,0.15)
- Button hover shadow: 0 4px 12px rgba(59,130,246,0.30) for primary

Rules:
- Border-radius: 10px for interactive elements (buttons, inputs, badges are excluded — badges use 20px pill)
- Border-radius: 12px for containers (cards, tables)
- Border-radius: 16px for modals
- Badge border-radius: 20px (always pill)
- Shadows use rgba(0,0,0,...) — cool neutral, not warm amber
- Primary buttons must gain colored shadow on hover
- No gradient backgrounds anywhere
- Weight hierarchy: 800 display / 700 headings / 600 labels / 400 body
```

---

### 15.2 Component Prompt Templates

**For a new form:**
```
Build a [form name] form using the Rounded design system.
- Container: white bg (#fff), 1px border #e2e8f0, border-radius 12px, padding 24px
- Font: Plus Jakarta Sans throughout
- Title: Plus Jakarta Sans 800, 20px, #0f172a
- Description: Plus Jakarta Sans 400, 14px, #64748b, line-height 1.6
- Field labels: Plus Jakarta Sans 600, 13px, #475569
- Inputs: white bg, 1.5px border #e2e8f0, border-radius 10px, padding 10px 14px
- Focus state: border-color #3b82f6 + box-shadow 0 0 0 3px rgba(59,130,246,0.12)
- Buttons: Cancel (#f1f5f9, border #e2e8f0) + Submit (bg #3b82f6, white text)
- Button gap: 10px, both border-radius 10px
```

**For a new card:**
```
Build a [card name] card using the Rounded design system.
- Background: #ffffff, border 1px #e2e8f0, border-radius 12px, padding 24px
- Shadow: 0 1px 3px rgba(0,0,0,0.06), 0 4px 12px rgba(0,0,0,0.06)
- Section label: 11px uppercase, #94a3b8, border-bottom 1px #e2e8f0
- Content text: Plus Jakarta Sans, 14px, #475569, line-height 1.65
- Headings inside card: Plus Jakarta Sans 700, #0f172a
```

**For a new data table:**
```
Build a data table using the Rounded design system.
- Wrapper: border 1px #e2e8f0, border-radius 12px, overflow hidden
- Header: background #f8fafc, border-bottom 1px #e2e8f0
- Column headers: Plus Jakarta Sans 700, 11px, uppercase, tracking 0.06em, #475569, padding 12px 16px
- Cells: Plus Jakarta Sans 400, 14px, #1e293b, padding 12px 16px
- Row separator: 1px solid #f1f5f9
- Row hover: background #f8fafc
- Status badges: pill shape (border-radius 20px), semantic colors
```

---

### 15.3 Debugging Prompts

**If it looks too cold / too minimal:**
```
This component needs warmer weight contrast. Increase the title weight to 800,
ensure section headings are at least 700. Body copy should be #475569 not black.
```

**If badges look wrong:**
```
All status badges should use border-radius: 20px (pill shape), not rounded-sm.
Badge text should be font-weight: 700, font-size: 11px.
Use semantic background colors: success #dcfce7, warning #fef9c3, error #fee2e2.
```

**If the focus state is wrong:**
```
Update input focus state: border-color: #3b82f6 AND box-shadow: 0 0 0 3px rgba(59,130,246,0.12).
The ring shadow is required — border color change alone is insufficient in this system.
```

**If border-radius is wrong:**
```
All buttons and inputs should use border-radius: 10px.
Cards and panels should use border-radius: 12px.
Modals should use border-radius: 16px.
Remove any radius below 8px from interactive elements.
```

**If button hover is missing the glow:**
```
Add hover shadow to primary button: box-shadow: 0 4px 12px rgba(59,130,246,0.30) on :hover.
This is a required interactive detail in the Rounded system.
```

---

## 16. New Project Checklist

### Setup Phase
- [ ] Google Fonts link block added (Plus Jakarta Sans + Lora)
- [ ] CSS custom properties (:root block) pasted into global stylesheet
- [ ] CSS reset applied (`*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }`)
- [ ] Body background set to `#f0f4f8`
- [ ] Body font-family set to `'Plus Jakarta Sans', sans-serif`
- [ ] Body color set to `#1e293b`
- [ ] Base heading styles applied (h1: 800, h2: 700, h3: Lora 600, h4–h6: Jakarta Sans)
- [ ] Base paragraph style applied (14px, 1.65 line-height, #475569)
- [ ] Base link style applied (#2563eb, underline)
- [ ] Base input style defined (white bg, 10px radius, #e2e8f0 border 1.5px)
- [ ] Base button reset defined (appearance: none, cursor: pointer)

### Component Phase (for each new component)
- [ ] Font is Plus Jakarta Sans (except H3/blockquote which use Lora)
- [ ] Border-radius follows the decision framework (10px interactive, 12px containers, 16px+ modals)
- [ ] Shadow uses neutral `rgba(0,0,0,...)`
- [ ] Primary buttons have hover shadow defined
- [ ] Input focus uses border-color + box-shadow ring
- [ ] Hover states defined and visible but not dramatic
- [ ] Disabled states at 0.4 opacity with `not-allowed` cursor
- [ ] Badges always pill shape (20px+ radius)

### Review Phase
- [ ] All cards and modal backgrounds are `#ffffff` (not page bg)
- [ ] Blue used only for: buttons, focus, links, active states
- [ ] Headings use weight 700 or 800 (never 400 for a heading)
- [ ] Table container has 12px radius with overflow hidden
- [ ] No warm shadows (no rgba amber)
- [ ] No gradient backgrounds
- [ ] Transition durations within range (50ms–300ms)

---

## 17. Component Pattern Library

### Pattern 1: Page Hero Section
```
[Display title — Jakarta Sans, 48px, 800, tight tracking]
[Subtitle description — Jakarta Sans 400, 15px, muted]
[Meta tags — flex row of pill badges]
[CTA Buttons — primary + secondary, gap 10px]
```

---

### Pattern 2: Settings Section
```
[Section Title — Jakarta Sans, 16px, 700, #0f172a]
[Section Description — Jakarta Sans, 13px, 400, #64748b]
[Hairline rule — 1px #e2e8f0]
[Field rows — label + input + helper, gap 16px–20px]
[Save button — right-aligned, primary]
```

---

### Pattern 3: Status List Item
```
[Container — flex row, justify-content space-between, bg #f8fafc, radius 10px, padding 10px 14px]
[Left: label text — Jakarta Sans, 13px, 600]
[Right: badge — pill, semantic color]
```

---

### Pattern 4: Navigation Bar
```
[Nav — white bg, border-bottom 1px #e2e8f0, height 56px–64px, padding 0 24px]
[Logo — left, Jakarta Sans brand mark]
[Nav items — center or left, Jakarta Sans 500, gap 4px, active: blue]
[Actions — right: avatar, icon buttons]
```

---

### Pattern 5: Empty State
```
[Center-aligned block, max-width 360px, margin auto]
[Icon — 32px, stroke, #94a3b8]
[Title — Jakarta Sans 700, 18px, #0f172a]
[Description — Jakarta Sans 400, 14px, #64748b, centered]
[CTA button — primary, centered, margin-top 20px]
```

---

### Pattern 6: Toast Notification
```
[Container — white bg, border 1px #e2e8f0, radius 12px, shadow-lg, padding 14px 18px]
[Flex row: semantic icon + title + dismiss ×]
[Title: Jakarta Sans 600, 13px, semantic text color]
[Optional body: Jakarta Sans 400, 12px, muted]
[Entry: slide in from right, 300ms]
```

---

## 18. Responsive Construction Rules

### 18.1 Breakpoint Behavior

**Below 480px (Mobile):**
- Modal padding reduces from 32px to 20px
- Modal border-radius reduces from 16px to 12px
- Card padding reduces from 24px to 16px
- 2-column grids collapse to single column
- Display heading reduces 1–2 size steps
- Sidebar becomes off-canvas drawer

**480px–767px (Large Mobile):**
- Modal fills screen with 16px left-right margin
- Card grid: 1 column
- Button groups: stack vertically

**768px–1023px (Tablet):**
- 2-column card grids active
- Full typography scale restored
- Sidebar: 220px if present

**1024px+ (Desktop):**
- Full system at designed specifications
- 3-column grids enabled
- All padding at full token values

---

### 18.2 Typography Scaling

| Element | Desktop | Tablet | Mobile |
|---------|---------|--------|--------|
| Hero H1 | 48px | 36px | 28px |
| Page H2 | 32px | 24px | 20px |
| Section H3 | 22px | 18px | 16px |
| Modal Title | 20px | 18px | 16px |
| Body | 14px | 14px | 14px |

---

## 19. Accessibility Guidelines

### 19.1 Color Contrast Requirements

| Pairing | Contrast | WCAG Level |
|---------|----------|-----------| 
| `#0f172a` on `#f0f4f8` | 18.2:1 | AAA ✓ |
| `#1e293b` on `#ffffff` | 14.7:1 | AAA ✓ |
| `#475569` on `#ffffff` | 5.9:1 | AA ✓ |
| `#ffffff` on `#3b82f6` | 3.9:1 | AA ✓ (large text / bold) |
| `#64748b` on `#ffffff` | 4.6:1 | AA ✓ |
| `#94a3b8` on `#ffffff` | 2.8:1 | ✗ Placeholder only |

**Rules:**
- `--color-text-muted` (`#64748b`) passes AA — use freely for helper/caption text
- `--color-text-disabled` (`#94a3b8`) fails — disabled only, never required reading
- White text on `#3b82f6` passes for large/bold text (buttons at 600+ weight pass)

---

### 19.2 Focus Management

- All interactive elements must have `:focus-visible` state
- Focus: `outline: 2px solid #3b82f6; outline-offset: 2px;` for non-input elements
- Inputs: `border-color: #3b82f6 + box-shadow ring`
- Never use `outline: none` without an alternative
- Modal opening must trap focus within the modal
- Modal closing must return focus to the trigger element

---

### 19.3 ARIA Requirements

```html
<!-- Modal -->
<div role="dialog" aria-modal="true" aria-labelledby="modal-title">
  <h2 id="modal-title">Update Settings</h2>
</div>

<!-- Field label association -->
<label for="name-input">Full Name</label>
<input id="name-input" type="text" />

<!-- Error state -->
<input aria-invalid="true" aria-describedby="field-error" />
<div id="field-error" role="alert">This field is required</div>

<!-- Badge count live region -->
<span aria-live="polite" aria-label="24 notifications">24</span>
```

---

## 20. Common Scenarios — Decision Trees

### Scenario: "Should this badge be pill or rounded-sm?"

```
Is this a status badge (Active, Pending, Error, Running)? ──YES──► Pill (20px radius)
        │ NO
        ▼
Is this a count indicator (notification count)? ──YES──► Pill (9999px)
        │ NO
        ▼
Is this a category label or filter tag? ──YES──► Pill (20px) — all badges are pills
        │ NO
        ▼
Is this an inline table action button? ──YES──► border-radius: 8px (not a badge)
```

---

### Scenario: "Which font weight for this heading?"

```
Is this the page hero title (H1)? ──YES──► 800
        │ NO
        ▼
Is this a section heading (H2)? ──YES──► 700
        │ NO
        ▼
Is this a card/modal title or H3? ──YES──► 600–700 (Jakarta Sans or Lora 600)
        │ NO
        ▼
Is this a label, button, or H4–H6? ──YES──► 600
        │ NO
        ▼
Is this body copy or description? ──YES──► 400
```

---

### Scenario: "Should this element have a shadow?"

```
Is it a floating element (dropdown, select panel)?
──YES──► --shadow-lg (12px 32px ambient)

Is it a modal or dialog?
──YES──► --shadow-modal (24px 64px) — mandatory

Is it a card on the page background?
──YES──► --shadow-card (1px 3px + 4px 12px) — subtle lift

Is it a primary button being hovered?
──YES──► 0 4px 12px rgba(59,130,246,0.30) — mandatory on hover

Is it an input at rest?
──YES──► none — borders only

Is the element flat and embedded?
──YES──► --shadow-none
```

---

### Scenario: "Is this text blue or slate?"

```
Is this element clickable or interactive? ──YES──► Blue (#2563eb for text links)
        │ NO
        ▼
Is this element currently selected or active? ──YES──► Blue (#3b82f6)
        │ NO
        ▼
Use slate hierarchy:
- Primary content → #0f172a
- Secondary content → #1e293b
- Labels / captions → #475569
- Metadata → #64748b
- Disabled → #94a3b8
```

---

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