Foundation
Spacing & layout
Nerio owns spacing values, density-aware component geometry, and resilient component behavior. Products compose those contracts into grids, shells, routes, and domain hierarchy without turning application layout into a Core primitive.
Responsibility model
| Owner | Responsibility |
|---|---|
| Nerio Core | The primitive spacing scale, comfortable and compact density aliases, component-internal geometry, logical-property guidance, and resilient behavior for component-owned content and overflow. |
| Product team | Application shells, page grids, breakpoints, container strategy, route layouts, content priority, table or chart overflow policy, and product-specific spacing aliases. |
| Nerio Pro | Reusable product shells, dashboard sections, domain layouts, templates, and advanced composition systems built from Core contracts. |
Spacing architecture
Choose the most specific durable contract. Components use their own aliases; product composition may use semantic density aliases or immutable primitive steps without creating a parallel spacing source.
| Layer | Selection rule |
|---|---|
| Component contract | Use the component's existing gap, padding, size, and geometry aliases first. They preserve anatomy and can respond to density without product code duplicating the recipe. |
| Semantic density alias | Use --n-density-space-md, --n-density-space-lg, or --n-density-space-xl for recurring product composition that should intentionally tighten in compact density. |
| Primitive step | Use an immutable --n-space-* step for a local product relationship only when no reviewed component or semantic role exists. |
| Local semantic token | Promote a repeated product relationship into a product-owned alias when its meaning is stable across several independent screens. Do not add it to Core without shared evidence. |
Source-backed primitive scale
These values render from spacing.primitiveScale, projected from the canonical token CSS. Primitive spacing stays unchanged across theme, mode, and density.
| Step | Token | Value | 16 px equivalent |
|---|---|---|---|
| 0 | --n-space-0 | 0 | 0px |
| 0.5 | --n-space-0-5 | 0.125rem | 2px |
| 1 | --n-space-1 | 0.25rem | 4px |
| 1.5 | --n-space-1-5 | 0.375rem | 6px |
| 2 | --n-space-2 | 0.5rem | 8px |
| 2.5 | --n-space-2-5 | 0.625rem | 10px |
| 3 | --n-space-3 | 0.75rem | 12px |
| 4 | --n-space-4 | 1rem | 16px |
| 5 | --n-space-5 | 1.25rem | 20px |
| 6 | --n-space-6 | 1.5rem | 24px |
| 8 | --n-space-8 | 2rem | 32px |
| 10 | --n-space-10 | 2.5rem | 40px |
| 12 | --n-space-12 | 3rem | 48px |
Density and component geometry
Comfortable is the default. Compact remaps semantic and component contracts; it does not redefine primitive spacing or automatically reduce text size, visible focus, content, or usable interaction targets.
| Density | Alias | Mapping |
|---|---|---|
| comfortable (default) | --n-density-space-md | --n-space-3 |
| comfortable (default) | --n-density-space-lg | --n-space-4 |
| comfortable (default) | --n-density-space-xl | --n-space-5 |
| compact | --n-density-space-md | --n-space-2-5 |
| compact | --n-density-space-lg | 0.875rem |
| compact | --n-density-space-xl | --n-space-4 |
| Component contract | Default mapping |
|---|---|
--n-button-gap | --n-control-gap-md |
--n-button-padding-inline-md | --n-density-space-md |
--n-field-gap | --n-space-1-5 |
--n-form-group-gap | --n-density-space-md |
--n-card-padding | --n-card-padding-md |
--n-card-gap | --n-density-space-lg |
--n-card-section-gap | --n-space-4 |
--n-table-cell-padding-y | --n-density-space-md |
--n-table-cell-padding-x | --n-density-space-md |
--n-item-gap | --n-density-space-md |
--n-dialog-padding | --n-space-6 |
--n-sidebar-region-padding | --n-density-space-xl |
Applied examples
The preview composes existing public components. The narrow settings panel, field group, wrapping action toolbar, section spacing, repeated table rows, and horizontal overflow policy remain product composition rather than a new Grid, Stack, Container, application shell, or breakpoint API.
Workspace settings
Keep long labels, helper text, and translated content available in narrow panels.
This name appears in navigation, invitations, and audit exports.
Team access
Repeated rows keep scanning alignment while compact density tightens component contracts.
| Workspace member | Role | Last active |
|---|---|---|
| Alex Morgan | Administrator | Today |
| Samira Okafor | Operations analyst | Yesterday |
import { Button } from "@nerio-ui/ui/client";import { Field, Input } from "@nerio-ui/ui";<section className="settings-section"> <Field label="Workspace name"> <Input defaultValue="Northstar operations" /> </Field> <div className="settings-actions"> <Button variant="secondary">Cancel</Button> <Button>Save changes</Button> </div></section>/* Product composition: Core tokens, consumer-owned layout. */.settings-section { display: grid; min-inline-size: 0; gap: var(--n-density-space-lg);}.settings-actions { display: flex; flex-wrap: wrap; gap: var(--n-density-space-md);}Rhythm and hierarchy
Proximity establishes hierarchy before decorative containers. Use consistent relationships, not one rigid page grid, so dense operational interfaces and quieter editorial surfaces can share the same Core primitives.
| Relationship | Guidance |
|---|---|
| Inside one control | Keep the component's own padding and internal gap contract. |
| Related controls | Use a small repeatable gap and keep labels, help, and errors with their field. |
| Repeated rows | Preserve scanning alignment; let density tighten row geometry without hiding content. |
| Sections | Use stronger separation than inside a group. Prefer whitespace before another card or border. |
| Page composition | Let the product define grid, breakpoint, hierarchy, and container policy. |
Resilient layout
| Risk | Expectation |
|---|---|
| Intrinsic sizing | Give flex and grid children min-inline-size: 0 where content must shrink. Avoid fixed block sizes for labels, descriptions, errors, and translated content. |
| Wrapping | Wrap labels and action groups by default. Treat truncation as a product decision and keep essential full content available. |
| Zoom and reflow | Keep information and operation available at 200% and 400% zoom and at 320 CSS pixels without page-level two-dimensional scrolling. |
| Long localization | Test expanded labels, helper and error text, mixed scripts, and realistic translated strings. Content-driven block growth is expected. |
| Overflow ownership | A component owns overflow created by its anatomy. The product owns unbounded application data and content-priority policy. |
| Tables and charts | Keep genuinely two-dimensional content in a labeled horizontal scroll container instead of forcing the whole page to scroll sideways. |
| Viewport edges | Safe-area and dynamic-viewport behavior belongs to a component only when it owns a viewport edge; otherwise the application shell owns it. |
The Accessibility foundation defines the complete reflow, zoom, text-spacing, target, focus, and evidence boundary. Product teams still validate their real content and workflows.
Direction and logical properties
| Concern | Guidance |
|---|---|
| Spacing | Prefer margin-inline, padding-inline, margin-block, padding-block, and gap. |
| Placement | Prefer inset-inline and logical alignment. Inherit the document dir value. |
| Physical sides | Use left or right only when the public API deliberately describes a physical side, then test the result in both LTR and RTL. |
See the Localization foundation for the inherited dir contract, DirectionProvider boundary, deterministic locale output, and consumer-owned translation policy.
Review checklist
- Start with the existing component geometry contract before choosing a density alias or primitive step.
- Use proximity, alignment, and whitespace for hierarchy before adding another surface or border.
- Review comfortable and compact density without shrinking text, focus, targets, or available content arbitrarily.
- Exercise narrow containers, 320 CSS pixel reflow, 200% zoom, text spacing, and long localized content.
- Confirm flex and grid children can shrink, actions wrap, and essential text remains available.
- Keep tables and charts in bounded horizontal scroll containers when their two-dimensional structure requires it.
- Repeat direction-sensitive compositions in RTL and use logical properties by default.
- Keep page grids, breakpoints, application shells, routing layouts, and domain hierarchy consumer- or Pro-owned.
Run pnpm validate:foundation-metadata, pnpm validate:docs, pnpm test:a11y, pnpm test:browser:pr, pnpm validate:route-budgets, and the production build. Automated checks do not replace manual review at narrow widths, browser zoom, text-spacing overrides, long localization, LTR/RTL, and both density values.
Known limitations: Nerio does not expose a public Grid, Stack, Container, breakpoint, container-query abstraction, application shell, dashboard layout, or a density value beyond comfortable and compact. Those remain consumer, Pro, or separately reviewed future work.