# Blocks & Patterns Reference

Reusable UI compositions built from AdiaUI components. **Blocks** are standalone sections (hero, pricing, footer). **Patterns** are functional interfaces (auth flows, chat, kanban, settings).

Each entry describes what to build, not how to copy-paste. An agent should decompose the description, select the right components, and compose a faithful recreation using AdiaUI conventions.

---

## Conventions

Every block and pattern follows these rules:

- **Card anatomy:** `card-ui > header > section > footer` — never skip the section wrapper
- **Section content:** Always wrap in `col-ui` — never place content directly in `<section>`
- **Headings:** Every heading element has `data-heading` — `display` for hero, `title` for page-level, `section` for card headings, `label` for group names, `eyebrow` for overlines, `caption` for meta text
- **Slots:** `slot="heading"` only on non-heading elements (`<span>`). Native `h1-h6` inside `<header>` are auto-targeted by card CSS
- **Spacing:** `col-ui gap="md"` for standard vertical stacks, `row-ui gap="sm"` for inline groups
- **Buttons:** `text` attribute for label, `variant` for style, `icon-leading`/`icon-trailing` for icons
- **Form fields:** Always have `label` and `name` attributes
- **Layout:** `grid-ui columns="3"` for equal columns, `row-ui` for content-sized
- **Typography tokens:** `--a-{role}-size` for role-based sizing (e.g. `--a-heading-size`, `--a-body-size`)
- **UI scale tokens:** `--a-ui-size-{size}` for component font sizes
- **Parametric spacing:** All spacing scales with `--a-density`, all radii scale with `--a-radius-k`

---

## Blocks (8)

Standalone landing page sections. Each is a self-contained composition meant to be dropped into a page layout.

### Hero

A centered call-to-action section with prominent heading, subheading, dual CTA buttons, and an image/illustration area below.

**Structure:**
- Centered column (max-width ~600px, text-align center)
- `h1` with `data-heading="display"` — large, bold, hero-scale
- `p` description — muted color, standard body text
- Row of 2 buttons centered: primary (large, with trailing icon) + outline (large)
- Below: placeholder image area with dashed border (or actual `image-ui`)

**Components:** `button-ui` (primary + outline, size lg, with icons), `icon-ui`

---

### Navbar

Horizontal top navigation bar with brand, links, and action buttons.

**Structure:**
- Flex row with 3 zones: brand (left), nav links (center), actions (right)
- Brand: `icon-ui` logo + text span
- Nav links: `<a>` elements with active state styling (bold + accent underline)
- Actions: ghost icon button (search) + primary button (CTA, size sm)

**Components:** `icon-ui`, `button-ui` (ghost + primary, size sm)

---

### Feature Grid

Responsive grid of feature/benefit cards, each with icon, heading, and description.

**Structure:**
- Responsive grid: `auto-fit, minmax(250px, 1fr)` (3 columns on desktop, collapses on mobile)
- Each card: `card-ui` with header containing icon badge + `slot="heading"` with `data-heading="section"`, and section with paragraph text
- Icons: `icon-ui` inside a small circle/badge container in the header

**Components:** `card-ui`, `icon-ui`, `col-ui`

**Content:** 6 feature cards. Each has: icon name, heading text, description paragraph.

---

### Pricing

Three-tier pricing table with plan comparison, feature lists, and CTA buttons.

**Structure:**
- 3-column responsive grid (`auto-fit, minmax(280px, 1fr)`)
- Each tier: `card-ui` with header (`slot="heading"` + `slot="description"`), section with price display + feature checklist, footer with CTA button
- Middle tier (Pro) highlighted: accent border, `badge-ui text="Popular"` in header
- Feature list: `col-ui` of `row-ui` items, each with `icon-ui name="check"` + text

**Components:** `card-ui`, `badge-ui`, `icon-ui`, `col-ui`, `row-ui`, `button-ui` (primary for featured, outline for others, stretch width)

**Content:** 3 tiers (Starter $0, Pro $19, Enterprise $49). Each with 4-6 features.

---

### Stat Cards

Grid of KPI metric cards showing key numbers with trend indicators.

**Structure:**
- 4-column responsive grid
- Each card: `card-ui` with header containing icon slot + label heading (`data-heading="label"`), section with large display value (`data-heading="title"` or `display`) + row with trend icon + delta text
- Trend: `icon-ui name="trending-up"` (green for positive) or `trending-down` (red for negative)

**Components:** `card-ui`, `icon-ui`, `col-ui`, `row-ui`

**Content:** 4 cards (Total Revenue $45k +20%, Active Users 2.3k +8%, Orders 12k +19%, Growth +573 +201/hr)

---

### CTA (Call to Action)

Banner section encouraging user action with heading, description, and buttons.

**Structure:**
- Full-width banner (surface background, padding, border-radius)
- Flex row: text column (heading `data-heading="title"` + description) on left, button row on right
- 2 buttons: primary + ghost (with icons)

**Components:** `button-ui` (primary + ghost, with icon-trailing)

---

### Footer

Multi-column site footer with branding, link groups, copyright, and social icons.

**Structure:**
- Grid: 4 columns (brand 2fr, 3 link columns 1fr each)
- Brand column: logo + subtitle text
- Link columns: each has heading (`data-heading="label"`) + vertical stack of `<a>` links
- Bottom bar (border-top): copyright text left, social icon buttons right
- Social: `icon-ui` buttons for Twitter, GitHub, Discord, etc.

**Components:** `col-ui`, `icon-ui`, `badge-ui`, `button-ui` (ghost, icon-only)

---

### Testimonials

Customer quote cards in a grid, plus a featured large testimonial.

**Structure:**
- 3-column responsive grid of `card-ui variant="outlined"`
- Each card: section with italicized quote (with decorative quote marks), then `row-ui` with `avatar-ui` + name/title column
- Below grid: featured testimonial — large `card-ui` centered with `icon-ui name="quotes"` (large), prominent quote text, avatar + name centered

**Components:** `card-ui` (outlined), `avatar-ui`, `col-ui`, `row-ui`, `icon-ui`

---

## Patterns (16)

Functional interface compositions. Each is a complete UI flow, not just a visual block.

### Auth

Authentication forms: login, signup, social login, and magic link.

**4 variants:**

1. **Centered Login** — `card-ui` centered (max-width 400px): header with lock icon + heading + description, section with email `input-ui` + password `input-ui` + row (remember `check-ui` + forgot link), footer with primary block button + sign-up link

2. **Split Signup** — 2-column grid: left column is branding panel (dark bg, display heading, feature list), right column is form card with name + email + password fields + terms checkbox + submit button

3. **Social Login** — `card-ui` centered: 2 OAuth buttons (Google, Apple with icons, outline variant, block), decorative divider with "or continue with email" text, email + password fields, submit button

4. **Magic Link** — `card-ui` centered: mail icon, heading, description, single email field, submit button, back-to-login link

**Key components:** `card-ui`, `input-ui`, `check-ui`, `button-ui`, `icon-ui`, `col-ui`, `row-ui`

---

### Chat

Messaging interface with bubble layout, typing indicators, and AI chat variant.

**4 variants:**

1. **Basic Chat** — Container with message list: sent messages right-aligned (accent bg), received messages left-aligned (subtle bg) with `avatar-ui`, timestamps below bubbles

2. **Typing Indicator** — Same as basic + animated 3-dot typing indicator in a received bubble (CSS keyframe bounce animation)

3. **AI Chat** — Received messages have `icon-ui` badge instead of avatar, different bubble styling (no border-radius on bottom-left)

4. **Group Chat** — Received messages show sender name label above bubble, different avatar per sender

**Key components:** `avatar-ui`, `icon-ui`, custom bubble CSS (border-radius manipulation: full except one corner)

---

### Chat List

Contact/conversation list with message previews, timestamps, and unread indicators.

**3 variants:**

1. **Contact List** — Vertical bordered list, each item: `avatar-ui` + name + preview text + time badge + optional unread count `badge-ui`

2. **With Online Indicators** — Same + green dot absolutely positioned on avatar corner

3. **With Search** — `search-ui` in header above the list

**Key components:** `avatar-ui`, `badge-ui`, `search-ui`

---

### AI Input

Compose areas for AI chat with formatting tools and response display.

**4 variants:**

1. **Basic** — `textarea-ui` + row with markdown label + send `button-ui`

2. **With Suggestions** — Same + row of `tag-ui` suggestion chips above the textarea

3. **With File Attach** — Same + file preview cards (name + size + remove button) above textarea

4. **Streaming Response** — Response area with text + blinking cursor animation (2px wide, `animation: blink 0.8s step-end infinite`)

**Key components:** `textarea-ui`, `button-ui`, `tag-ui`, `toolbar-ui`, `icon-ui`, `progress-ui`

---

### Data Table

Full-featured data table with search, filter, sort, selection, and pagination.

**Structure:**
- `card-ui` container
- Header: `search-ui` + `select-ui` filter dropdown + action buttons
- Body: `table-ui` (sortable, selectable) — data set via JS `.columns` and `.data`
- Footer: page info text + `pagination-ui`
- Optional: bulk action bar (accent background) that appears when rows are selected

**Key components:** `card-ui`, `table-ui`, `search-ui`, `select-ui`, `button-ui`, `pagination-ui`

---

### Settings

Full settings page with sidebar navigation and card-based form sections.

**Structure:**
- 2-column layout: sidebar (200px) + main content
- Sidebar: section headings + items with active state
- Main: stacked `card-ui` sections, each with header (h3 `data-heading="subtitle"` + description) + form section + footer with action buttons
- 4 sections: Profile (avatar + name + email + bio), Notifications (toggle rows), Appearance (segmented theme + select font), Danger Zone (delete button, variant danger)

**Key components:** `card-ui`, `input-ui`, `avatar-ui`, `switch-ui`, `segmented-ui`, `select-ui`, `button-ui`

---

### Kanban

Three-column task board with cards, assignees, and priority tags.

**Structure:**
- 3-column grid (equal width, gap md)
- Column header: status icon + title + count `badge-ui` + add `button-ui` (icon-only)
- Task cards: `card-ui` with title (h4), description (p, muted), footer with `tag-ui` labels + `avatar-ui` assignee
- Status columns: Todo (circle icon), In Progress (clock icon), Done (check-circle icon)

**Key components:** `card-ui`, `badge-ui`, `tag-ui`, `avatar-ui`, `button-ui`, `icon-ui`, `col-ui`, `row-ui`

**Content:** 10 task cards distributed across 3 columns with varied tags (Design, Testing, Frontend, Backend).

---

### Notifications

Notification center with filtering, read/unread states, and mark-all-read action.

**Structure:**
- `card-ui` with header: title + unread count `badge-ui` + "Mark all read" `button-ui` (ghost)
- `segmented-ui` filter: All, Unread, Mentions
- List of notification items: `avatar-ui` + title (bold if unread) + description + time + unread dot `badge-ui`
- Unread items have subtle highlighted background

**Key components:** `card-ui`, `avatar-ui`, `badge-ui` (dot + count), `segmented-ui`, `segment-ui`, `button-ui`

---

### Stat (Pattern)

KPI cards in various configurations beyond the basic stat block.

**5 variants:**

1. **Basic** — Value + delta badge (success/error variant)
2. **With Icon** — Same + icon in header slot
3. **With Sparkline** — Same + `chart-ui type="sparkline"` below the value
4. **With Trend Arrow** — Delta row uses `icon-ui name="trending-up/down"` instead of badge
5. **Stat Grid** — 4-column grid combining all variants

**Key components:** `card-ui`, `badge-ui`, `icon-ui`, `chart-ui` (sparkline type), `col-ui`, `row-ui`

---

### Steps

Step-by-step progress indicators for multi-stage flows.

**4 variants:**

1. **Horizontal** — `timeline-ui` with numbered circles connected by lines, active step highlighted
2. **Vertical** — Same but stacked vertically with descriptions
3. **With Icons** — Icon attribute replaces numbers (user, credit-card, check-circle)
4. **With Content** — Active step shows detail `card-ui` below with form fields or summary

**Key components:** `timeline-ui`, `timeline-item-ui`, `card-ui`, `input-ui`, `button-ui`, `avatar-group-ui`

---

### File Upload

File upload flow with drag-and-drop zone, progress tracking, and status display.

**Structure:**
- `upload-ui` drag-and-drop zone at top
- Below: file list showing upload states
- Each file item: type `icon-ui` + name/size info + `progress-ui` (during upload) or `badge-ui` status (Done/Error) + remove `button-ui`
- Error items: red-tinted border, error badge

**Key components:** `upload-ui`, `icon-ui`, `badge-ui`, `progress-ui`, `button-ui`

---

### OTP Input

One-time password entry with variants.

**3 variants:**

1. **Basic** — `otp-input-ui length="6"` + verify button
2. **With Separator** — Same with `separator` attribute (dash between groups of 3)
3. **With Timer** — Wrapped in `card-ui` with icon header, `progress-ui` countdown bar, resend link

**Key components:** `otp-input-ui`, `button-ui`, `progress-ui`, `icon-ui`, `card-ui`

---

### Theme Builder

Interactive theme customizer with live preview.

**Structure:**
- 2-column layout: controls (340px left), preview (right)
- Controls card: sliders (`slider-ui`) for radius/spacing/hue/chroma/lightness, `segmented-ui` for color scheme, `select-ui` for font, preset `button-ui` row
- Preview card: wrapped with `[data-theme]` attribute with live binding — shows sample components (button variants, form fields, cards, badges)
- Export card: `code-ui` showing generated CSS + copy `button-ui`

**Key components:** `card-ui`, `slider-ui`, `segmented-ui`, `select-ui`, `button-ui`, `badge-ui`, `input-ui`, `check-ui`, `switch-ui`, `code-ui`

---

### Timeline

Chronological event sequences with connected timeline indicators.

**4 variants:**

1. **Vertical** — `timeline-ui` with `timeline-item-ui` items, vertical line connecting dots, content right-aligned
2. **Horizontal** — Same but horizontal layout, compact
3. **With Icons** — Dot replaced by `icon-ui` (check, star, flag, etc.)
4. **Variant Colors** — Items use semantic variants (success=green, accent=blue, warning=yellow, danger=red)

**Key components:** `timeline-ui`, `timeline-item-ui`, `icon-ui`

---

### User Profile

Profile display patterns with stats, bio, and social links.

**3 variants:**

1. **Full Profile Card** — Large `avatar-ui`, name (`data-heading="title"`), role, email, 3-column stat cards (Projects/Contributions/Teams), bio paragraph, social icon button row, Edit Profile + Settings buttons

2. **Compact Profile** — Horizontal row: `avatar-ui` + name/role column + action buttons right-aligned

3. **Team Members Grid** — 3-column grid of profile `card-ui` elements, each with centered avatar, name, role, social row

**Key components:** `card-ui`, `avatar-ui`, `badge-ui`, `button-ui` (icon-only for social), `row-ui`, `col-ui`, `icon-ui`

---

### Empty State

Placeholder patterns for when content is absent.

**5 variants:**

1. **Default** — Centered: `icon-ui` (48px, folder-open), subtitle heading, description, primary CTA button
2. **Search No Results** — magnifying-glass icon, "No results" heading, "Try different keywords" description, "Clear search" outline button
3. **Error** — warning icon, "Something went wrong" heading, "Please try again" description, "Retry" primary button
4. **First Use/Onboarding** — rocket icon, welcome heading, getting-started checklist with `check-ui` items and `progress-ui` completion bar
5. **Inline** — Horizontal `row-ui` variant: icon left + text right, for embedding in existing layouts

**Key components:** `card-ui` (outlined), `icon-ui` (48px container), `col-ui` (centered), `button-ui`, `check-ui`, `progress-ui`

---

## Source Files

| Type | Directory | Count |
|------|-----------|-------|
| Blocks | `site/blocks/*.content.html` | 8 |
| Patterns | `site/patterns/*.content.html` | 16 |
| Block setups | `site/blocks/*.setup.js` | varies |
| Pattern setups | `site/patterns/*.setup.js` | varies |

Total: **24 compositions** with **62 variant examples**.
