[@layout]: ../layouts/site.layout.md
[@preview]: ./next-step.components.md

# Next step

End a section with somewhere useful to go. A small accent, a clear title, and
one concrete action give the reader a natural handoff. The same pattern can
invite someone to build, practice, or explore.

<next-step>

## Make your first site

Start with one Markdown file. Run it locally, edit a sentence, and watch the
page update.

[Build your first site →](../docs/start/first-site.guide.md)

</next-step>

---

## Invite practice

A next step can point into a lesson instead of another guide. The component owns
the visual emphasis; the author owns the invitation and the action.

<next-step>

## Make a little room for reading

Choose a book, find a place for it, and try one small change to your day.

[Try the exercise →](../examples/color-context.demo.md)

</next-step>

---

## Author the invitation

Use a short heading, one or two sentences, and a descriptive link. Everything
inside the component is ordinary Markdown, so a page can choose its own heading
level and link destination.

````md
[@next]: ../design-system/next-step.components.md

<next-step>

## Make a little room for reading

Choose a book and try one small change to your day.

[Try the exercise →](./color-context.demo.md)

</next-step>
````

These paths assume a Source in the `examples` folder. Keep this pattern for
meaningful transitions so it retains its emphasis.

---

<!-- componentName: next-step -->

## A quiet invitation

The accent line leads into the content. A lightly tinted surface groups the
invitation without competing with the page's main example. The component adds
no icon, number, or label that an author must work around.

```html
<aside class="pmx-next-step"><slot /></aside>
```

```css
.pmx-next-step {
  margin-block: 2rem;
  padding: clamp(1.25rem, 3vw, 2rem);
  border: 1px solid var(--pmx-color-border);
  border-inline-start: 3px solid var(--pmx-color-accent);
  border-radius: 0 var(--pmx-radius) var(--pmx-radius) 0;
  background: color-mix(in oklch, var(--pmx-color-accent) 6%, var(--pmx-color-surface));
}
.pmx-next-step > :first-child { margin-block-start: 0; }
.pmx-next-step > :last-child { margin-block-end: 0; }
.pmx-next-step :is(h2, h3) {
  font: 650 clamp(1.3rem, 2vw, 1.7rem)/1.2 var(--pmx-font-heading);
  letter-spacing: -0.02em;
  text-wrap: balance;
}
.pmx-next-step p { max-inline-size: 58ch; text-wrap: pretty; }
.pmx-next-step a:not(.pmx-heading-anchor) {
  display: inline-flex;
  align-items: center;
  min-block-size: 2.75rem;
  font-weight: 650;
  text-underline-offset: 0.25em;
}
.pmx-next-step a:focus-visible {
  outline: 2px solid var(--pmx-color-accent);
  outline-offset: 4px;
  border-radius: 2px;
}
```

---

## Keep the choice clear

This pattern is for a next action, not warnings or status messages. Use
[callouts](../docs/authoring/callouts.reference.md) for those. If a section offers
several equal destinations, use a list or a group of
[guide links](./basics.components.md#guide-links).

A possible first use is the [Start page](../docs/start/index.md). It has not been
adopted there. Edit the definition here to refine these examples, then return
to the [design workbench](./index.md) to compare the patterns.