Patterns

A [PATTERNS] entity documents one composition — a user menu, a signup panel, a comment thread — together with the states it ships in. The level between a component and a page: bigger than a button, smaller than a screen, and the level most design systems never write down.

It is a [SHOWCASE] with the prop half switched off. A composition has no single component whose API it could extract, so there is no [COMPONENT], no props panel and no controls — a props table documenting one part of a composition would be actively misleading. Everything else is the same: [EXAMPLE] states, [PROSE] between them, [NOTES], [TODO], [GLOSSARY], and the same stages with the same resize handles and code panels.

<script lang="ts">
	import Avatar from './Avatar.svelte';
	import Menu from './Menu.svelte';
</script>

[PATTERNS title="Patterns / User Menu" description="Avatar, menu and badge."]

	[EXAMPLE title="Signed out"]
		<Menu>Sign in</Menu>
	[/EXAMPLE]

	[PROSE]
		Once there is a user, the avatar becomes the trigger.
	[/PROSE]

	[EXAMPLE title="Signed in"]
		<Avatar name="Ada" /> <Menu>Profile · Settings · Sign out</Menu>
	[/EXAMPLE]

[/PATTERNS]

Each [EXAMPLE] is a state of the same composition, and each gets its own sidebar entry under the pattern — the same bookmark icon a [SHOWCASE]'s examples get — and its own route, so a single state is linkable.

Attributes

Attribute	Required	Meaning
title	yes	Sidebar path and display name — "Patterns / User Menu" nests under Patterns
description	no	Short text under the title — inline markdown renders styled
slug	no	Overrides the URL segment (default: slugified title segment)
hide	no	A bare flag: routable, but never listed in a sidebar
maxWidth	no	Default stage width for this entity's examples
padding	no	Default stage padding
direction	no	Default stage flex-direction
gap	no	Default stage gap
contentX	no	Horizontal alignment: left/center/right/justify
contentY	no	Vertical alignment: top/middle/bottom/justify
background	no	Default stage background — a CSS color or a var() from the project's css
minHeight	no	Minimum stage height

Each [EXAMPLE] can override any of the stage attributes for itself.

Your project's context

The stages load the project's css, the same way a [COMPONENT] preview and a [SHOWCASE]'s examples do — the composition looks like your product, not like these docs. An entity-level <script> and <style> work as they do elsewhere: the script's imports are what the examples compose from.

No [COMPONENT]

A pattern has no single component API, so a [COMPONENT] block in one is an error rather than a silently misleading props panel:

error  src/UserMenu.sdoc:3 › Patterns / User Menu
  [COMPONENT] is not allowed in a [PATTERNS] — a pattern documents a
  composition, which has no single component API. Use [SHOWCASE] for a
  component, or [EXAMPLE] to show this composition.

Loose markup is an error too, for the same reason it is in a [SHOWCASE]: every stage belongs to a named state.

When to reach for which

• [PATTERNS] — several components assembled into one reusable thing, with its states. No single API to document.
• [SHOWCASE] — one component, with its extracted API, live controls and as many variants as you like.
• [LAYOUT] — a whole page rather than a piece of one, on a full-bleed canvas you can resize to real viewport widths.
• [DOC] — prose that isn't tied to one thing.

See also

• Component docs — [SHOWCASE] and [COMPONENT]
• Layouts — full-page compositions
• Overview — every entity, side by side