Block | NDS - Vanilla National Design System

Structure

Blocks live inside .nds-section-body and hold flow content directly. An optional .nds-block-title heading sits at the top of the block.

Component Tree


section.nds-content-section nds-demo-section
└── div.nds-section-body
    └── div.nds-block
        ├── h3.nds-block-title   (optional)
        └── p, ul, ol, table, img...   (direct flow content)

Standard

Group related paragraphs, lists, or tables under a shared heading. Blocks stack vertically inside the section body with consistent spacing.

Titled and Untitled Blocks

Block Title

First paragraph of content inside the block. Paragraphs, lists, and media get automatic styling when inside .nds-block.

Second paragraph to demonstrate spacing between content elements.

Another Block

List items work inside blocks
With automatic padding and spacing

Blocks without a title work too. The title is optional.

Built-in Features

Auto Flow Styling

Paragraphs, images, and video nested inside a block pick up primary paragraph color, pretty wrapping, and responsive media caps automatically.

Optional Titled Heading

Add .nds-block-title when the block needs a heading. Every title token is overridable through CSS custom properties.

Consistent Vertical Rhythm

Blocks carry a 2rem bottom margin that collapses on the last child, so stacks of blocks inside a section body breathe without extra classes.

Works Anywhere

Drop blocks inside any section body — default, color-themed, horizontal, or full-width. Positioning and spacing stay consistent across layouts.

Container Query Anchor

Each block establishes a named block CSS container. Descendants like grids and quotes respond to the block's actual width, not the viewport — correct sizing in multi-column layouts where the block is narrower than the section.

Usage Guidelines

Best Practices

Use blocks to subdivide content inside a single section instead of starting a new section — they share the same visual container but group related paragraphs under their own heading
Prefer one section per topic, with multiple blocks inside when the topic has distinct sub-groups (best practices, modifier tables, API references, etc.)
Keep block titles short and descriptive. They render at --typo-text-xl-FS by default, sitting below the section title in visual hierarchy
Do not wrap cards, grids, or other full components in a block. Place them directly under .nds-section-body so the block-title hierarchy stays reserved for flow content
Do not nest blocks. If a sub-group needs its own heading level, consider whether it belongs in a new section instead
Skip the title on a single-block section where the section title already carries the heading — the wrapper is still useful for the automatic flow styling

CSS Custom Properties

Property	Default	Description
`--block-title-FS`	var(--typo-text-xl-FS)	Block title font size
`--block-title-LH`	var(--typo-text-xl-LH)	Block title line height
`--block-title-FW`	600	Block title font weight
`--block-title-MB`	var(--spacing-lg)	Spacing below the title (when exposed via the shared token)
`--block-title-color`	var(--text-display)	Block title color