YAML field manual · version 1

One file.
A small vocabulary.

Every accepted key is documented here. Compose a page from a fixed shell, ordered section components, and reusable safe primitives.

Download starter View JSON Schema

DOCUMENT / V1

01 Shell 5 blocks
02 Sections 7 types
03 Primitives 3 shapes

Unknown keys → compile error

On this page

00 Minimum document

Start with three ideas.

version: Locks the contract to v1.
page: Names the document and its metadata.
hero: Provides the one required page heading.

Everything else is optional. Add section components only when the page needs them.

version: 1

page:
  name: Northstar
  title: Northstar — Ship with confidence
  description: Release software without release-day surprises.

hero:
  heading: Know what breaks before you ship.
  text: A focused explanation of the product and its value.
  actions:
    - label: Start free
      href: "#start"

sections:
  - type: cta
    id: start
    heading: Ship your next release calmly.
    action:
      label: Contact us
      href: mailto:hello@example.com

— Grammar before styling

Composition rules

01
Use YAML 1.2 with one document and two-space indentation.
02
Start every file with version: 1. Unknown keys are errors.
03
Quote same-page fragments such as "#pricing"; an unquoted # starts a comment.
04
Section order in the sections array is the rendered page order.
05
Section ids must be unique lowercase slugs and make fragment links possible.
06
Aliases, merge keys, custom tags, raw HTML, CSS, Markdown, and scripts are rejected.

01 Global blocks

Document shell

One page identity, one hero, and optional global presentation blocks.

01.01

`design`

optional

Selects the fixed art direction and its single safe color input.

preset: editorial
Fixed layout preset. Editorial is the only v1 value.
accent: #RRGGBB
Six-digit hexadecimal accent color.

design:
  preset: editorial
  accent: "#E94F37"

01.02

`page`

required

Defines identity, browser metadata, language, and the canonical URL.

namerequired: string
Site or product name. Maximum 80 characters.
titlerequired: string
Browser and search title. Maximum 160 characters.
description: string
Search description. Maximum 2,000 characters.
language: language tag
BCP 47 language tag; defaults to en.
canonical: HTTPS URL
Absolute canonical URL without credentials.

page:
  name: Northstar
  title: Northstar — Ship with confidence
  description: Release software without release-day surprises.
  language: en
  canonical: https://northstar.example

01.03

`navigation`

optional

A compact link list plus one emphasized destination.

links: link[]
Up to 6 shared link objects.
action: link
One emphasized shared link object.

navigation:
  links:
    - label: Features
      href: "#features"
    - label: Pricing
      href: "#pricing"
  action:
    label: Start free
    href: https://app.northstar.example

01.04

`hero`

required

The page promise: one heading, supporting copy, actions, and optional image.

eyebrow: string
Short context label. Maximum 80 characters.
headingrequired: string
The page’s single h1. Maximum 160 characters.
text: string
Supporting prose. Maximum 2,000 characters.
actions: action[]
Up to 2 hero action objects.
image: image
One HTTPS raster image with meaningful alt text.

hero:
  eyebrow: Release intelligence
  heading: Know what breaks before you ship.
  text: A focused explanation of the product and its value.
  actions:
    - label: Start free
      href: "#start"
      style: primary

01.05

`footer`

optional

Closing text and a short list of policy or contact links.

text: string
Closing text. Maximum 2,000 characters.
links: link[]
Up to 6 shared link objects.

footer:
  text: © 2026 Northstar
  links:
    - label: Privacy
      href: https://northstar.example/privacy

02 Ordered components

Section registry

Place up to 12 typed components inside sections. Array order is page order.

02.01

`features`

repeatable

A heading and up to 6 icon-supported product benefits.

typerequired: features
Selects this component.
id: slug
Unique fragment target.
heading: string
Section heading. Maximum 160 characters.
text: string
Section introduction. Maximum 2,000 characters.
itemsrequired: feature[]
Up to 6 items with title, text, and optional icon.

- type: features
  id: features
  heading: Built for calm releases
  text: Everything needed between merge and production.
  items:
    - icon: shield
      title: Risk detection
      text: Find dangerous changes before deployment.

02.02

`stats`

repeatable

A compact proof band containing up to 6 value-and-label pairs.

typerequired: stats
Selects this component.
id: slug
Unique fragment target.
itemsrequired: stat[]
Up to 6 items; value and label are required.

- type: stats
  id: proof
  items:
    - value: "42%"
      label: fewer failed releases
    - value: "3 min"
      label: setup time

02.03

`logos`

repeatable

A text-only trust strip for up to 12 customer or partner names.

typerequired: logos
Selects this component.
id: slug
Unique fragment target.
heading: string
Trust statement. Maximum 160 characters.
itemsrequired: string[]
Up to 12 names; images are not accepted in v1.

- type: logos
  heading: Trusted on release day
  items:
    - Northline
    - Acme Systems
    - Fieldnote Lab

02.04

`quote`

repeatable

One testimonial with an attributed author and optional role.

typerequired: quote
Selects this component.
id: slug
Unique fragment target.
quoterequired: string
Quotation text. Maximum 2,000 characters.
authorrequired: string
Author name. Maximum 80 characters.
role: string
Role or organization. Maximum 160 characters.

- type: quote
  quote: Northstar changed how we release.
  author: Jane Doe
  role: VP Engineering, Acme

02.05

`pricing`

repeatable

Up to 4 plans with one optional featured choice.

typerequired: pricing
Selects this component.
id: slug
Unique fragment target.
heading: string
Section heading. Maximum 160 characters.
plansrequired: plan[]
Up to 4 plans; at most one may be featured.

- type: pricing
  id: pricing
  heading: Simple pricing
  plans:
    - name: Team
      price: "$49"
      period: per month
      features:
        - Unlimited releases
        - Five projects
      featured: true
      action:
        label: Start free
        href: https://app.northstar.example

02.06

`faq`

repeatable

An accessible disclosure list containing up to 12 answers.

typerequired: faq
Selects this component.
id: slug
Unique fragment target.
heading: string
Section heading. Maximum 160 characters.
itemsrequired: faq item[]
Up to 12 required question-and-answer pairs.

- type: faq
  heading: Questions
  items:
    - question: Can I cancel?
      answer: Yes, at any time.

02.07

`cta`

repeatable

A closing call to action with one required destination.

typerequired: cta
Selects this component.
id: slug
Unique fragment target.
headingrequired: string
Call-to-action heading. Maximum 160 characters.
text: string
Supporting prose. Maximum 2,000 characters.
actionrequired: link
One shared link object.

- type: cta
  id: start
  heading: Ship your next release calmly.
  text: Start with one project. No credit card required.
  action:
    label: Start free
    href: https://app.northstar.example

Feature icon registry

15 fixed names

bolt
camera
chart
check
clock
code
compass
globe
heart
layers
lock
refresh
shield
spark
star

03 Reusable shapes

Shared primitives

Small objects keep labels, destinations, actions, and images consistent.

03.01

`link`

shared

Used by navigation, pricing plans, calls to action, and the footer.

labelrequired: string
Visible purpose. Maximum 80 characters.
hrefrequired: safe URL
HTTPS, mailto, tel, or a live same-page fragment.

label: View pricing
href: "#pricing"

03.02

`hero action`

shared

A link with optional visual priority, used only in hero.actions.

labelrequired: string
Visible purpose. Maximum 80 characters.
hrefrequired: safe URL
HTTPS, mailto, tel, or a live same-page fragment.
style: primary | secondary
Visual priority; inferred when omitted.

label: Start free
href: https://app.northstar.example
style: primary

03.03

`image`

shared

A remote raster image. External availability is not guaranteed offline.

srcrequired: HTTPS URL
Absolute HTTPS raster URL; SVG is rejected.
altrequired: string
Meaningful alternative text. Maximum 300 characters.

src: https://images.example/hero.webp
alt: Northstar release dashboard

04 / Stability

The file is a contract.

Additive optional fields may remain in v1. Renaming, removing, or changing meaning requires v2. New section types ship with schema, renderer, documentation, accessibility review, and security fixtures together.

Build a page Inspect the canonical schema

One file.A small vocabulary.

The file is a contract.

One file.
A small vocabulary.