pattern-dump 0.1.0-alpha.0

package/dist/types/contracts/index.d.ts

@@ -0,0 +1,294 @@
+export type Visibility = "public" | "private";
+export type Status = "draft" | "stable" | "deprecated";
+/** Flat partial reference used in templates: `<category>-<name>`, e.g. "atoms-button". */
+export type FlatPartialName = string;
+export interface ComponentRef {
+    id: string;
+    category: string;
+    /** Informational lineage only — no longer an addressing boundary. Nesting records ownership. */
+    visibility?: Visibility;
+    path: string;
+}
+export interface RenderInput {
+    /** Component id (path under patternsDir), e.g. "atoms/button" or "molecules/field". */
+    component: string;
+    /** Name of a `<component>~<variant>.json` data set. Omitted => base (component.json). */
+    variant?: string;
+    /** Live-control overrides; highest precedence in the cascade. */
+    data?: Record<string, unknown>;
+}
+export interface RenderMeta {
+    componentId: string;
+    variant?: string;
+    /** Schema-alignment diagnostics (M4.9); present only when component.schema.json is provided. */
+    diagnostics?: import("./dev-protocol.js").Diagnostic[];
+}
+export interface RenderOutput {
+    /** The rendered component fragment (no document chrome). */
+    html: string;
+    /**
+     * Standalone source document the preview iframe points at:
+     * themeable tokens as `:root`/`[data-theme]` custom properties + compiled CSS + the fragment.
+     * Same isolation model for docs examples.
+     */
+    document: string;
+    meta?: RenderMeta;
+}
+/**
+ * {{id 'name'}} — ambient, named, deterministic, base-seeded accessibility id helper.
+ *
+ * BASE-SEEDED SCOPE:
+ *   Every render scope has a BASE. `{{id 'name'}}` = `<base>-<name>` (deterministic derivation).
+ *   The base is either minted automatically or supplied by a composing parent.
+ *
+ *   - Minted base: when no base is supplied, the renderer derives the base from the component
+ *     slug + composition position. The minted base for the main (top-level) component is
+ *     `pd-<component-slug>`. For composed instances, the minting rule ensures per-instance
+ *     distinctness (see COMPOSITION RULE below).
+ *
+ *   - Supplied base: a composing parent may pass `base="<value>"` as a Handlebars partial
+ *     hash arg — `{{> molecules-field base="email"}}` — to seed the child's entire id cluster.
+ *     Every `{{id 'name'}}` in that subtree then yields `<supplied-base>-<name>`, making the
+ *     cluster externally predictable (e.g. `email-input`, `email-hint`).
+ *
+ * COMPOSITION RULE (minted base, auto-distinct instances):
+ *   When the same partial is composed multiple times within one render tree, the FIRST
+ *   invocation with a given parent base inherits that parent base (base propagation —
+ *   ensures sub-components share the cluster base). Each SUBSEQUENT invocation with the
+ *   same parent base mints a new base (`pd-<partial-slug>-<N>`), disambiguating independent
+ *   instances without hand-numbering. Template authors never write `-2`; composition
+ *   position drives the distinction automatically.
+ *
+ * BASE PROPAGATION THROUGH COMPOSITION:
+ *   When `field` composes `input`, both share the same base (field propagates its base to
+ *   input). `{{id 'input'}}` in `field.hbs` and `id="{{id 'input'}}"` in `input.hbs`
+ *   resolve to the SAME id — the cluster spans partial boundaries coherently.
+ *
+ * SCOPE RULES SUMMARY:
+ *   1. Same name, same scope → same id (wires label `for` ↔ input `id`).
+ *   2. Different name → different id (`hint` ≠ `input`).
+ *   3. Different instance → different base → distinct ids for the same name.
+ *   4. Supplied base seeds the whole cluster; every member is base + name.
+ *   5. Base propagates to composed children (sub-components share the cluster base).
+ *   6. Deterministic: same render() input → byte-identical ids and html.
+ *   7. Ambient: templates write `{{id 'name'}}` only; no per-element id threading by arg.
+ *      The ONLY thing a parent may pass is the BASE for the child's scope.
+ *
+ * OPEN DECISION — all-states-in-one-document seeding:
+ *   Two independent top-level render() calls for the same component produce the same minted
+ *   base and therefore the same ids. When the dev environment renders ALL states/instances
+ *   into one document (snapshot mode, multi-instance preview), id collisions occur.
+ *   Options:
+ *     A. Caller supplies RenderInput.seed (recommended): keeps render() pure; dev-env manages
+ *        distinct seeds per instance. The seed is incorporated into the minted base.
+ *     B. Renderer-managed counter: breaks render() purity (counter leaks across calls).
+ *   Current state: `RenderInput.seed` field is defined but unused by the renderer.
+ *   Resolve before the dev-environment renders multiple instances in one document.
+ */
+export type IdHelperSemantics = never;
+/**
+ * Pure render. Deterministic: same input => byte-identical output.
+ *
+ * DATA CASCADE (lowest → highest precedence), per-key deep merge:
+ *   1. defaults  — component.json (optional; absent = empty object contributes nothing)
+ *   2. composed  — context passed by a parent under a routing key via section descent
+ *                  ({{#routingKey}}{{> flat-name}}{{/routingKey}} → child receives routingKey subtree)
+ *   3. variant   — <component>~<variant>.json (optional; merges only the keys it declares)
+ *   4. live      — input.data (optional; the M3 live-controls seam)
+ *
+ * MERGE SEMANTICS (per key, applied at each level):
+ *   - Object values: merged recursively (deep merge, not whole-object replace).
+ *   - Scalar values: replace (string, number, boolean, null).
+ *   - Arrays: REPLACE — `["c"]` replaces `["a","b"]`, no concatenation.
+ *     ↳ OPEN DECISION: replace vs concat — settle before M3 controls ship.
+ *   - null: CLEARS the inherited value (target key becomes null).
+ *     ↳ OPEN DECISION: clear vs "inherit from defaults" — settle before M3 controls ship.
+ *
+ * PARTIAL RESOLUTION (flat naming model):
+ *   - Templates reference partials by flat `<category>-<name>` (e.g. {{> molecules-input}}).
+ *   - `render({ component })` and graph node ids remain full paths (e.g. "molecules/field/input").
+ *   - The renderer builds a registry mapping FlatPartialName → full path before each render.
+ *   - A collision (two components → same handle) quarantines the newcomer and surfaces a
+ *     HANDLE_COLLISION diagnostic (see CollisionEntry).
+ *   - Nesting records informational ownership (lineage); it is NOT an addressing boundary.
+ *   The graph's `uses` edges are derived from these partial references (one source of truth).
+ */
+export type Render = (input: RenderInput) => Promise<RenderOutput>;
+export interface RendererOptions {
+    /** Root containing the atomic pattern folders (atoms/, molecules/, ...). */
+    patternsDir: string;
+    /** Every patterns folder, project first, when pattern packages are in use. Takes precedence over
+     *  `patternsDir` for discovery. */
+    patternRoots?: PatternRoot[];
+    /** Theme files directory (custom-property value-sets). Optional for M0. */
+    themesDir?: string;
+    /** Default theme name applied via `data-theme` on the preview body. */
+    defaultTheme?: string;
+    /**
+     * Pre-loaded project-specific Handlebars helpers, keyed by name.
+     * Registered after the core helpers; project helpers may override core ones.
+     * Typical flow: core loads `PatternDumpConfig.helpers` path, imports the module, passes here.
+     */
+    helpers?: Record<string, (...args: unknown[]) => unknown>;
+    /**
+     * Project-level global data (e.g. hTWOo's `src/_data/`), merged BENEATH component data — the
+     * lowest tier of the render cascade: global → defaults → variant → live. Component data wins on
+     * every key. Loaded once by the dev-server from `PatternDumpConfig.dataDir`.
+     */
+    globalData?: Record<string, unknown>;
+    /**
+     * Project helper *registrars* — modules that self-register onto the render env, the PatternLab
+     * shape `module.exports = (Handlebars) => { Handlebars.registerHelper(...) }`. Invoked with the
+     * renderer's Handlebars env AFTER partials are registered, so helpers that read
+     * `Handlebars.partials` / `.compile` at CALL time (e.g. `dynamicPartial`) resolve against the real
+     * env — which a flat name→fn map (`helpers`) cannot express. Registered after core + `helpers`.
+     */
+    helperRegistrars?: Array<(handlebars: unknown) => void>;
+    /**
+     * M6: pre-built handle → slash-id map from the dev-server's discovery pass.
+     * When provided together with discoveryMap, the renderer uses these maps to register
+     * Handlebars partials and resolve file paths without running its own discovery walk.
+     * Marked for extraction to a shared discovery module in the refactor round.
+     */
+    handleMap?: HandleMap;
+    /**
+     * M6: pre-built id → DiscoveryEntry map from the dev-server's discovery pass.
+     * Provides the file paths (hbsPath, jsonPath, schemaPath) used by render().
+     * When absent, the renderer calls buildDiscoveryMap(patternsDir) from @pattern-dump/discovery —
+     * the real M6 file-as-component walk, never the old collectComponents folder-per-component walk.
+     */
+    discoveryMap?: DiscoveryMap;
+}
+/** Factory: a configured renderer closes over its source root, keeping `render()` pure. */
+export type CreateRenderer = (options: RendererOptions) => Render;
+/**
+ * Single source of truth for where each component's files live.
+ * Populated by buildDiscoveryMap; every file-read site uses this map — none reconstruct paths.
+ *
+ * Collapse rule: `<dir>/<dir>.hbs` → id = `<dir>` (folder-per-component collapses).
+ * Otherwise id = relative stem, intermediate group folders retained.
+ *
+ * For base-less variant synthesis: ownMarkup=false, hbsPath is empty string (no base file),
+ * variants lists the variant tokens present on disk.
+ */
+export interface DiscoveryEntry {
+    /** The pattern package this component comes from (its npm name); absent for the project's own. */
+    source?: string;
+    hbsPath: string;
+    jsonPath?: string;
+    mdPath?: string;
+    schemaPath?: string;
+    scssPath?: string;
+    ownMarkup: boolean;
+    variants?: string[];
+}
+/** slash id → file entry. The single source of truth for file locations. */
+export type DiscoveryMap = Map<string, DiscoveryEntry>;
+/**
+ * dash handle → slash id.
+ * Bridge for Handlebars partial resolution: `{{> atoms-button}}` → `"atoms/button"`.
+ * Handles are group-less: intermediate folder segments are dropped, only category + name kept.
+ * Variant handles include `~`: `atoms-spinner~small` → `"atoms/loading/spinner~small"`.
+ */
+export type HandleMap = Map<string, string>;
+/** A handle collision detected at discovery time. The incumbent retains the handle. */
+export interface CollisionEntry {
+    handle: string;
+    incumbentId: string;
+    incumbentPath: string;
+    quarantinedPath: string;
+    /** Slash id of the quarantined component (derived from quarantinedPath at discovery time). */
+    quarantinedId: string;
+}
+/** Return value of buildDiscoveryMap. */
+export interface DiscoveryResult {
+    discoveryMap: DiscoveryMap;
+    handleMap: HandleMap;
+    collisions: CollisionEntry[];
+    /** Reverse index: absolute hbsPath → slash id. Populated for all entries with a real .hbs file. */
+    hbsPathToId: Map<string, string>;
+    /** quarantined slash id → CollisionEntry. Used by the detail endpoint to surface HANDLE_COLLISION. */
+    quarantineMap: Map<string, CollisionEntry>;
+    /** A component of an EARLIER source (the project before packages, then packages in order) that
+     *  replaced a later source's component with the same handle. Not an error — it is how a project
+     *  overrides a library component — so the shadowed one is neither quarantined nor a collision. */
+    overrides: OverrideEntry[];
+}
+export interface OverrideEntry {
+    handle: string;
+    /** The id that stays, and where it lives. */
+    id: string;
+    path: string;
+    /** The same-handle component that was replaced, and the package it came from. */
+    shadowedPath: string;
+    shadowedSource: string;
+}
+/** One folder of patterns: the project's own, or a pattern package's. */
+export interface PatternRoot {
+    dir: string;
+    /** The package name; absent for the project. */
+    source?: string;
+    /** Globs relative to `dir` of templates to leave undiscovered. */
+    exclude?: string[];
+}
+/**
+ * A pattern package's self-description: the `patternDump` field of its package.json. Every path is
+ * relative to the package folder. All fields are optional, so one package can carry patterns and
+ * another the styles and themes they need — the second listed as a peerDependency of the first,
+ * which PD follows (`@n8d/htwoo-patterns` → `@n8d/htwoo-core`).
+ */
+export interface PackageManifest {
+    /** Folder of Handlebars patterns (the equivalent of `patternsDir`). */
+    patterns?: string;
+    /** Global template data folder (`dataDir`). */
+    data?: string;
+    /** Handlebars helper module or folder (`helpers`). */
+    helpers?: string;
+    /** Asset folders served under /assets/<folder name>/. */
+    assets?: string[];
+    styles?: {
+        dir: string;
+        /** Compile only these entries (relative to `dir`). */
+        entry?: string | string[];
+        /** Base-origin paths of the shared document layer, as in the project config. */
+        documentBase?: string[];
+    };
+    themes?: {
+        dir: string;
+        default?: string;
+        switch?: import("./dev-protocol.js").ThemeSwitch;
+    };
+    /** Behaviour script sources (`scriptsDir`). */
+    scripts?: string;
+    /** Script ids loaded into every preview. */
+    globalScripts?: string[];
+    /** Globs (relative to `patterns`) of templates the package ships but does not want discovered. */
+    exclude?: string[];
+}
+export interface ThemeSummary {
+    name: string;
+    tokens?: Record<string, string | null>;
+}
+/** Brand slot for the left rail, nested under shell.brand in PatternDumpConfig. */
+export interface ShellBrandConfig {
+    /** Wordmark text. Defaults to "Pattern Dump". */
+    title?: string;
+    /**
+     * Path to a logo image. Replaces the wordmark when set.
+     * A monochrome SVG that inherits currentColor is preferred, but note that
+     * <img> does NOT inherit currentColor — full currentColor shell theming is a
+     * design-tokens milestone concern. { light, dark } renders a <picture> with
+     * prefers-color-scheme sources.
+     */
+    logo?: string | {
+        light: string;
+        dark: string;
+    };
+    /** Alt text for the logo image. */
+    logoAlt?: string;
+    /** Optional href; wraps the brand slot in an <a> (History API navigation). */
+    href?: string;
+}
+/** Ordered list of CSS custom-property names used as swatch slots. */
+export type SwatchSlots = string[];
+export * from "./dev-protocol.js";

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "pattern-dump",
+  "version": "0.1.0-alpha.0",
+  "description": "A workbench for HTML and CSS design systems: live component previews, docs, checks and static publishing.",
+  "keywords": [
+    "design-system",
+    "pattern-library",
+    "styleguide",
+    "patternlab",
+    "handlebars",
+    "scss",
+    "component-library",
+    "workbench",
+    "living-styleguide",
+    "accessibility",
+    "static-site",
+    "htwoo"
+  ],
+  "author": "Stefan Bauer <stefan.bauer@n8d.at> (https://n8d.at)",
+  "license": "MIT",
+  "homepage": "https://github.com/n8design/pattern-dump#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/n8design/pattern-dump.git"
+  },
+  "bugs": "https://github.com/n8design/pattern-dump/issues",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/stfbauer"
+    },
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/n8design"
+    }
+  ],
+  "type": "module",
+  "bin": {
+    "pd": "./dist/pd.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.10"
+  },
+  "dependencies": {
+    "@shikijs/transformers": "^4.1.0",
+    "autoprefixer": "^10.5.0",
+    "axe-core": "^4.11.4",
+    "chokidar": "^3.6.0",
+    "culori": "^4.0.2",
+    "esbuild": "^0.28.2",
+    "handlebars": "^4.7.9",
+    "html-validate": "^11.5.2",
+    "jsdom": "^27.4.0",
+    "markdown-it": "^14.2.0",
+    "node-html-parser": "^7.1.0",
+    "postcss": "^8.5.15",
+    "sass": "^1.100.0",
+    "shiki": "^4.1.0",
+    "source-map": "^0.6.1",
+    "ws": "^8.21.0"
+  }
+}

package/templates/base/README.md

@@ -0,0 +1,77 @@
+# __PD_NAME__
+
+A design system worked on with [Pattern Dump](https://www.npmjs.com/package/__PD_PACKAGE__).
+
+```bash
+npm run dev     # the workbench at http://localhost:4000
+npm run audit   # static defects across every component
+npm run typecheck      # type-check the behaviour scripts
+npm run build:scripts  # compile them to lib/scripts (JavaScript + type declarations)
+```
+
+## Layout
+
+| Path | What lives there |
+|---|---|
+| `pattern-dump.config.ts` | where everything is — every path resolves against this folder |
+| `src/patterns/<category>/<name>/` | one component: `<name>.hbs`, `.json` data, `.md` docs, `.schema.json` |
+| `src/patterns/<category>/<name>/<name>~<variant>.json` | a variant that overrides data |
+| `src/patterns/<category>/<name>/<name>~<variant>.hbs` | a variant with its own markup |
+| `src/styles/` | SCSS mirroring `src/patterns/` (`atoms/button.scss` styles `atoms/button`) |
+| `src/styles/base/` | shared rules with no single owner, linked beneath every preview |
+| `themes/<name>.theme.scss` | a theme: custom properties under `[data-theme="<name>"]` |
+| `assets/` | served at `/assets/` |
+| `src/scripts/<id>.ts` | a behaviour script, loaded by the components that name it |
+| `tsconfig.json` | TypeScript settings for `src/scripts` |
+
+Include a component from another with its handle, `<category>-<name>`: `{{> atoms-button }}`.
+A variant handle contains `~`, so quote it: `{{> "atoms-button~secondary" }}`.
+
+A folder's `index.md` titles it and can order its children by name. `...` stands for every child
+the list doesn't name, so a folder you add later needs no edit here:
+
+```md
+---
+title: Atoms
+order: [button, ..., badge]
+---
+```
+
+Any component (in its `.md`) or folder (in its `index.md`) can also rank itself with a number. Without
+one its rank is `0`; lower comes first, whatever the parent's list says. This puts a folder before
+every rank-0 sibling (`order: 10` would put it after them):
+
+```md
+---
+title: Projects
+order: -10
+---
+```
+
+Siblings sort by rank first, then by the parent's list, then alphabetically.
+`src/patterns/index.md` orders the top-level folders.
+
+## Behaviour scripts
+
+A script is a TypeScript module in `src/scripts/`. A component loads it by naming it in its `.md`
+frontmatter, and every preview that shows the component — directly or included in another — loads it:
+
+```md
+---
+title: Search field
+requireScript: [search-field]
+---
+```
+
+To load a script into every preview, list it in `pattern-dump.config.ts`: `globalScripts: ["<id>"]`.
+
+`npm run dev` compiles scripts itself (esbuild) and reloads the preview when one changes; there is no
+build step while you work. `tsconfig.json` is for your editor, `npm run typecheck` and
+`npm run build:scripts`, which writes JavaScript and type declarations to `lib/scripts/`.
+
+To let another package in your repository import the compiled scripts, export them from `package.json`:
+
+```json
+"files": ["lib/scripts"],
+"exports": { "./package.json": "./package.json", "./scripts/*": "./lib/scripts/*" }
+```

package/templates/base/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+lib

package/templates/base/pattern-dump.config.ts

@@ -0,0 +1,36 @@
+import { defineConfig } from "__PD_PACKAGE__";
+
+// Every path below resolves against this project's root (the folder this file lives in).
+export default defineConfig({
+  sourceDir: "./src",
+  patternsDir: "./src/patterns",
+  outDir: "./dist",
+
+  // Styles mirror the patterns tree: src/styles/atoms/button.scss belongs to atoms/button.
+  styles: { strategy: "parallel", dir: "./src/styles" },
+  // Shared, component-less rules (reset, document defaults) linked beneath every preview.
+  documentBase: ["base"],
+
+  themes: {
+    dir: "./themes",
+    default: "light",
+    switch: "attribute",
+    // Custom properties sampled for the swatch strip in the theme picker.
+    swatch: { slots: ["--color-surface", "--color-primary", "--color-text"] },
+  },
+
+  assets: { strategy: "central", dir: "./assets" },
+
+  // Behaviour scripts: src/scripts/<id>.ts, compiled on request. A component loads one with
+  // `requireScript: [<id>]` in its .md frontmatter; ids listed here load into every preview.
+  scriptsDir: "./src/scripts",
+  // globalScripts: ["<id>"],
+
+  // Pattern packages used alongside this project's own patterns — install them, then name them here.
+  // Each package describes its patterns, styles and themes in its package.json ("patternDump").
+  // packages: ["@n8d/htwoo-patterns"],
+
+  shell: {
+    brand: { title: __PD_BRAND_JSON__ },
+  },
+});

package/templates/base/src/scripts/globals.d.ts

@@ -0,0 +1,6 @@
+// Project-wide type declarations for the behaviour scripts in this folder.
+//
+// A script is `src/scripts/<id>.ts`. A component loads it by naming it in its .md frontmatter,
+// `requireScript: [<id>]`; `globalScripts: ["<id>"]` in pattern-dump.config.ts loads it into every
+// preview. `pd dev` compiles it on request — no build step while you work.
+export {};

package/templates/base/src/styles/base/_tokens.scss

@@ -0,0 +1,8 @@
+// Sass tokens shared by every stylesheet. Emits no CSS; @use it where needed.
+// Colours are NOT here: they come from the active theme (themes/*.theme.scss) as custom properties.
+$space-xs: 0.25rem;
+$space-sm: 0.5rem;
+$space-md: 1rem;
+$space-lg: 2rem;
+$radius: 0.375rem;
+$font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;

package/templates/base/src/styles/base/document.scss

@@ -0,0 +1,18 @@
+@use "tokens";
+
+// The document defaults every preview sits on — the base layer named by `documentBase` in the config.
+// Fallbacks keep a preview readable before a theme is chosen.
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: tokens.$font-family;
+  line-height: 1.5;
+  color: var(--color-text, #1b1b1f);
+  background: var(--color-surface, #ffffff);
+}

package/templates/base/themes/dark.theme.scss

@@ -0,0 +1,8 @@
+[data-theme="dark"] {
+  --color-surface: #16181d;
+  --color-text: #eceef2;
+  --color-text-muted: #b4bac4;
+  --color-primary: #7ab8ff;
+  --color-on-primary: #0b1220;
+  --color-border: #9aa1ad;
+}

package/templates/base/themes/light.theme.scss

@@ -0,0 +1,8 @@
+[data-theme="light"] {
+  --color-surface: #ffffff;
+  --color-text: #1b1b1f;
+  --color-text-muted: #4b5563;
+  --color-primary: #0b5cad;
+  --color-on-primary: #ffffff;
+  --color-border: #6b7280;
+}

package/templates/base/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  // Behaviour scripts in src/scripts. `pd dev` compiles them itself with esbuild — this file is for
+  // `npm run typecheck` (tsc --noEmit) and `npm run build:scripts` (tsc → lib/scripts).
+  // Self-contained on purpose: it extends nothing, so it never inherits a parent project's settings.
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "rootDir": "src/scripts",
+    "outDir": "lib/scripts",
+    "declaration": true
+  },
+  "include": ["src/scripts"]
+}

package/templates/examples/src/patterns/atoms/button/button.hbs

@@ -0,0 +1 @@
+<button type="{{type}}" class="button button-{{variant}}">{{label}}</button>

package/templates/examples/src/patterns/atoms/button/button.json

@@ -0,0 +1 @@
+{ "label": "Save", "variant": "primary", "type": "button" }

package/templates/examples/src/patterns/atoms/button/button.md

@@ -0,0 +1,21 @@
+---
+title: Button
+description: Triggers an action.
+status: stable
+---
+
+Triggers an action. `variant` picks the emphasis.
+
+Two kinds of variant live next to the base component:
+
+- **`button~secondary.json`** only overrides data — same markup, different `label` and `variant`.
+- **`button~icon.hbs`** has its own markup — an icon-only button that keeps `label` as its accessible name.
+
+```pattern atoms/button
+```
+
+```pattern atoms/button~secondary
+```
+
+```pattern atoms/button~icon
+```

package/templates/examples/src/patterns/atoms/button/button.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Button",
+  "type": "object",
+  "required": ["label", "variant", "type"],
+  "properties": {
+    "label":   { "type": "string", "description": "Visible text, or the accessible name of the icon variant" },
+    "variant": { "type": "string", "enum": ["primary", "secondary"], "default": "primary" },
+    "type":    { "type": "string", "enum": ["button", "submit", "reset"], "default": "button" }
+  }
+}

package/templates/examples/src/patterns/atoms/button/button~icon.hbs

@@ -0,0 +1,5 @@
+<button type="{{type}}" class="button button-{{variant}} button-icon" aria-label="{{label}}">
+  <svg class="button-glyph" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false">
+    <path d="M3 8.5l3 3 7-7" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>
+</button>

package/templates/examples/src/patterns/atoms/button/button~secondary.json

@@ -0,0 +1 @@
+{ "label": "Cancel", "variant": "secondary" }

package/templates/examples/src/patterns/atoms/index.md

@@ -0,0 +1,6 @@
+---
+title: Atoms
+preview: centered
+---
+
+The smallest building blocks. Each renders centered in the stage, hugging its content.

package/templates/examples/src/patterns/index.md

@@ -0,0 +1,3 @@
+---
+order: [atoms, molecules, pages, ...]
+---

package/templates/examples/src/patterns/molecules/index.md

@@ -0,0 +1,6 @@
+---
+title: Molecules
+preview: centered
+---
+
+Small groups of atoms that work as a unit.

package/templates/examples/src/patterns/molecules/search-field/input/input.hbs

@@ -0,0 +1,4 @@
+<label class="input">
+  <span class="input-label">{{inputLabel}}</span>
+  <input class="input-control" type="search" name="q" placeholder="{{placeholder}}">
+</label>

package/templates/examples/src/patterns/molecules/search-field/input/input.json

@@ -0,0 +1 @@
+{ "inputLabel": "Search", "placeholder": "Components, tokens…" }

package/templates/examples/src/patterns/molecules/search-field/input/input.md

@@ -0,0 +1,8 @@
+---
+title: Input
+description: The search field's labelled input.
+status: draft
+visibility: private
+---
+
+A private sub-component: it exists to be composed by `molecules/search-field`, not used on its own.