What is a Block?

Blocks are the primitive building elements that compose surfaces. 45 production blocks across 4 first-party packs (24 UI + 7 data + 5 nav + 9 forms), plus custom blocks you can author and publish.

Block philosophy

PhiWebs ships a real, typed, manifest-described block catalog. PhiCo composes from this catalog — it never invents components. If a block does not exist, AI cannot summon it. You can extend the catalog by writing your own with defineBlock and shipping it through pwpack publish, the same pipeline that ships our first-party 45.

blocks compose into surfaces enhanced by capabilities

Foundational primitives

A small sample of the primitives. The full live catalog (45 blocks across 4 packs) is available in the marketplace and via the live schema endpoint.

Layout blocks

• container — The fundamental layout unit. Holds other blocks, controls spacing, width, and background. Example: page sections, card wrappers, content areas.
• grid — Creates responsive column layouts. Adapts to screen size automatically. Example: feature grids, image galleries, comparison tables.

Typography blocks

• heading — Titles and section headers. Supports h1–h6 semantic levels. Example: page titles, section headers, subheadings.
• text — Paragraphs and body content. Rich formatting support. Example: descriptions, articles, explanatory content.

Interactive blocks

• button — Clickable actions. Triggers navigation, submissions, or custom actions. Example: CTAs, form submissions, navigation links.

Media blocks

• image — Visual content. Optimized loading, responsive sizing, alt text support. Example: photos, illustrations, icons, logos.

Form blocks

• form — Form container. Groups inputs, handles validation and submission. Example: contact forms, signup forms, surveys.
• input — Data entry fields. Text, email, select, checkbox, and more. Example: email fields, text areas, dropdown selects.

Block properties

Every block has configurable properties:

• Content — The actual content: text, images, labels.
• Styling — Colors, typography, borders, shadows.
• Spacing — Margin, padding, gaps.
• Responsive — Behavior at different screen sizes.

Blocks vs. components

You might wonder: aren’t these just components?

Blocks are higher-level than components. They’re the atoms of the Surface OS, rendered at runtime, portable across contexts.

What about complex UI?

You might expect blocks for “hero sections”, “pricing tables”, or “testimonials”. PhiWebs handles these differently:

• Starter surfaces — Pre-composed combinations of blocks for common patterns.
• Marketplace — Community-shared surface compositions.
• Copy + customize — Start from any starter, make it yours.

This keeps the primitive set small while providing the building blocks (literally) for any complex UI.

Block composition example

How blocks compose into a hero section:

container (full-width, centered)
├── heading (h1: "Welcome to PhiWebs")
├── text ("Create living digital surfaces...")
├── grid (2 columns)
│   ├── button (primary: "Get Started")
│   └── button (secondary: "Learn More")
└── image (hero-illustration.svg)

Same blocks, different composition = different experience.

Continue learning

• What is a Surface?
• Composition model
• Using blocks guide