@r1z4x/tezgah 1.9.2 → 1.13.0

package/skills/hallmark/references/macrostructures/12-letter.md

@@ -0,0 +1,21 @@
+## 12 · Letter
+
+First-person, written, intimate. Opens with a greeting. Reads as a personal note from the founder.
+
+- **Heading:** the salutation in the display italic ("Dear reader,"), 1.5 to 2 times body size; the whole line one style.
+- **Body:** prose, single column, narrow measure (50ch), as if typed.
+- **Divider:** paragraph spacing only; an occasional `* * *` separator.
+- **Button:** no button. The sign-off link at the foot carries a verb ("Join the list"). In the fold the one visible action is the link in the first paragraph (44b).
+- **Image:** one signature scan, or a quiet inline photograph, or nothing.
+- **Reveal:** none.
+
+Reach for it for personal brands, indie founder announcements, sabbatical or pivot pages, donation appeals.
+
+Avoid for transactional commerce. Letter is intimate; commerce is functional.
+
+Compositions: the Corridor hero (`layout.md` § 6); the footer is a letter close (§ 7).
+
+**Sample opening lines** (first-person greetings, dated, with a place if it matters):
+> *"Hello, I'm Anya."* One line: a name, a full stop.
+> *"Saturday, 6:14 a.m. The dough went in at midnight."* Opens on a moment, then explains it (Maple Street Bread).
+> *"Hey there. This page is soft because the surface should be soft."* A colloquial open and a principle.

package/skills/hallmark/references/macrostructures/13-index-first.md

@@ -0,0 +1,21 @@
+## 13 · Index-First
+
+The page is a list of links. No hero image, no narrative flow. Navigation as design.
+
+- **Heading:** a short head at the hero size naming the index (*Everything published here, newest first*) and one line; the index starts on the first screen.
+- **Body:** a vertical list of categorised links; a filter row above it or a disclosure, never a sidebar by default.
+- **Divider:** hairline rules between rows, or no rules and bands of paper.
+- **Button:** the links are the buttons.
+- **Image:** none, or one photograph of the collection itself, and a small mark by each entry.
+- **Reveal:** none.
+
+Reach for it for documentation hubs, knowledge bases, archive front pages, design-system entries, link pages with substance.
+
+Avoid for a hard sell (a launch, a checkout). Index-First serves a browsing audience; a personal site that offers its owner's time is fine.
+
+Compositions: Rows at full width (`layout.md` § 5).
+
+**Sample opening lines** (headers for what sits below, sometimes no more than a line):
+> *"Selected work, 2018 to 2026."* A date range, no preamble.
+> *"Everything published here, newest first."* Names the sort and the scope.
+> *"Writer and photographer."* Three words that summarise the whole site.

package/skills/hallmark/references/macrostructures/14-narrative-workflow.md

@@ -0,0 +1,21 @@
+## 14 · Narrative Workflow
+
+Numbered stages tell the story of how the user uses the product over time. Each section is a phase; the page is a process timeline.
+
+- **Heading:** the stage number rides inside the heading (`<h2>1.0 Intake</h2>`) or is generated by `<ol>` with `counter()`. Never a separate label beside the heading: that is an eyebrow at stage scale (54).
+- **Body:** each stage has a short explanation and one object at full size: a product capture 360px tall or more when the user gave screens, otherwise a figure or rows from the prompt (a timer, a count, the thing the stage makes). Three stages holding the same kind of object read as three features (8): vary the object from stage to stage.
+- **Divider:** a rule between stages, in the theme's rule weight; the number stays in the heading, never on the rule.
+- **Button:** the hero's one action (44b), returning once at the foot ("Start at stage one"); links inside stages.
+- **Image:** a real capture per stage, often annotated, in a `<figure>` or a slot; with one screen or none, never a slot per stage (68).
+- **Reveal:** one horizontal sweep, on the first stage, when the theme allows a reveal; the later stages are simply there. A scrub-linked stage sequence may use [`../scroll-choreography.md`](../scroll-choreography.md) § 1 Pinned chapter instead: one pattern per page.
+
+Reach for it for products with explicit workflows: project management, design-to-dev pipelines, writing tools.
+
+Avoid for tools that work in one moment. Narrative Workflow needs a real sequence.
+
+Compositions: Steps, each stage with its capture (`layout.md` § 5).
+
+**Sample opening lines** (stage headings: numbered, declarative, in process language, one stage per line):
+> *"1. Sourdough overnight. 2. Score at dawn. 3. Pull at seven."* Three numbered stages, no marketing (Maple Street Bread).
+> *"1.0 Parse. 2.0 Filter. 3.0 Route."* Versioned numbers, three concrete verbs (Streampipe).
+> *"I. We design products that last twelve years. II. A material is sustainable when someone can repair it."* Roman numerals and declaratives (Meridian).

package/skills/hallmark/references/macrostructures/15-split-studio.md

@@ -0,0 +1,21 @@
+## 15 · Split Studio
+
+Diptych. Every major block divides the screen, text on one side, proof on the other, and the proof keeps its side down the page (one mirror at most, never a zigzag, `layout.md` § 7).
+
+- **Heading:** half the screen wide; the other half holds a capture or a supplied quote.
+- **Body:** text-and-proof rows that vary by weight, not by side: one lead row gives the proof the larger share, the rest split evenly; one column gap for all of them (F15).
+- **Divider:** a clear gutter between halves; no rules.
+- **Button:** an outlined chip below the text half.
+- **Image:** on the proof side in every row: a real capture, or the product built in a slot (`imagery.md` § 4).
+- **Reveal:** the hero's two halves fade in once, 60 to 100ms apart; the rows below are simply there.
+
+Reach for it for SaaS feature pages, developer tools that pair explanation with code, anything where every claim wants a visual proof.
+
+Avoid for narrative or photographic brands. Split halves the attention; some pages need one focus.
+
+Compositions: Split (`layout.md` § 5), the proof keeping its side.
+
+**Sample opening lines** (a positioning statement paired with a proof column):
+> *"A studio for what comes next."* Italic display beside a selected-work column.
+> *"Print discipline, on screen."* Two phrases, set like a masthead.
+> *"We design and build products for small ambitious teams."* Names the verbs and the audience.

package/skills/hallmark/references/macrostructures/16-feature-stack.md

@@ -0,0 +1,23 @@
+## 16 · Feature Stack
+
+Sticky left pane holding the heading, scroll-synced right pane cycling through related captures. Paced like film.
+
+- **Heading:** held inside the sticky pane; persists while content cycles beside it.
+- **Body:** two columns, left sticky, right scrolling; the right pane plays through 3 to 6 detail captures per section.
+- **Divider:** section bands; the sticky pane re-anchors per section, at `top: var(--banner-height)` under a sticky nav (56).
+- **Button:** in the sticky pane, shown once the section's last capture is reached; with scripting off it is simply there (62).
+- **Image:** the scrolling column is real captures, or the product built in slots until they arrive (`imagery.md` § 4); never a run of empty frames (68).
+- **Reveal:** none of the fade kind; the sticky scroll is the motion. Choreograph it with [`../scroll-choreography.md`](../scroll-choreography.md) § 4 Sticky diptych with the pane kept on the left, or § 1 Pinned chapter: one pattern per page.
+
+Reach for it for premium products, complex feature stories, anywhere the pacing should be controlled as the visitor scrolls.
+
+Avoid for mobile-first audiences without a strong fallback. Sticky scroll-sync is rough on small screens.
+
+Compositions: a pinned Split (`layout.md` § 5), the pin per `scroll-choreography.md` § 4.
+
+Mobile: under 60rem the sticky pane becomes a heading above its captures, stacked in flow.
+
+**Sample opening lines** (pin one statement, then walk the visitor through):
+> *"Plan, build, ship."* Three verbs, three sticky panes.
+> *"Read anything that emits lines."* Names what is possible, then walks through it (Streampipe).
+> *"From stdin, through the pipe, into your dashboard."* Names the data path, then explains each step.

package/skills/hallmark/references/macrostructures/17-type-specimen.md

@@ -0,0 +1,19 @@
+## 17 · Type Specimen
+
+The typeface is the design. Foundry pages and design systems where a custom face is the proof.
+
+- **Heading:** the typeface set at several sizes, demonstrating what it does.
+- **Body:** a progressive demonstration: display size, body size, italic, language coverage, OpenType features.
+- **Divider:** a `<figcaption>` under each specimen; a caption below is legal, a label above is an eyebrow (54).
+- **Button:** one outlined action ("Buy the family") in the fold (44b), returning at the foot.
+- **Image:** none; the typography is the imagery.
+- **Reveal:** one type-unmask, on the first specimen as it paints; the rest is simply there.
+
+Reach for it for type foundries, design systems where a custom face is the differentiator, font product pages.
+
+Avoid when the brand uses an off-the-shelf face. Type Specimen needs something distinctive to celebrate.
+
+**Sample opening lines** (foundry voice: name the face, the weights, the use):
+> *"Corvid Display, set at 96pt."* Names the face and the size, nothing else.
+> *"Eight weights. Three optical sizes. One good italic."* Counts the system in three short phrases.
+> *"A type system for editorial."* Refusal of the verb, one noun phrase.

package/skills/hallmark/references/macrostructures/18-portfolio-grid.md

@@ -0,0 +1,21 @@
+## 18 · Portfolio Grid
+
+Filterable cards of projects. Studio and designer homepages where the work is the product.
+
+- **Heading:** a short line above the grid; no display.
+- **Body:** a responsive grid of project cards, same size or with slight size variation; image tracks `minmax(0, 1fr)` (50).
+- **Divider:** the filter row above the grid; no internal rules.
+- **Button:** a link inside each card ("View the case study"); no global CTA. The fold's one visible action is the first card's link (44b).
+- **Image:** a thumbnail per card, from the user's work; until it arrives, the projects are set in type with one slot at most (68).
+- **Reveal:** card fade on filter change.
+
+Reach for it for design studios, agencies, photographer portfolios, any creative business where the work is the pitch.
+
+Avoid for products. Portfolio Grid is a service-business shape.
+
+Compositions: Grid with a filter row (`layout.md` § 5).
+
+**Sample opening lines** (name the volume and the era):
+> *"Selected work, 2018 to 2026."* A date range, nothing else.
+> *"Twelve projects, six clients, two countries."* Three counts, no adjective.
+> *"Work, indexed by year."* The index is the whole site.

package/skills/hallmark/references/macrostructures/19-map-diagram.md

@@ -0,0 +1,21 @@
+## 19 · Map / Diagram
+
+A single large spatial diagram organises the page: flowchart, floor plan, network graph, system map. Information is laid out spatially, not linearly.
+
+- **Heading:** an orientation head at the section size above or beside the map; the map carries the page.
+- **Body:** the map itself, nodes and edges, with a legend.
+- **Divider:** none inside; the diagram is one composition.
+- **Button:** links inside nodes; the page's one action sits with the orientation phrase, inside the fold (44b), never under the map.
+- **Image:** the map is the image: SVG drawn from the real places or the real system, with hover states, labelled or `aria-hidden` with a text legend carrying every fact (33). Geometry that is geometry is a first-class medium (47c).
+- **Reveal:** node-by-node ink-on as the map enters the viewport, capped at five nodes, once.
+
+Reach for it for system overviews, ecosystem maps, process diagrams, organisation charts.
+
+Avoid as a substitute for narrative. Some stories should not be read spatially.
+
+Mobile: under 60rem the map scrolls sideways inside a wrapper, or collapses to an ordered list of its nodes.
+
+**Sample opening lines** (name the path or the territory):
+> *"Browser, then API, then database. Tracejam sits between the last two."* Names the layers and the position.
+> *"From stdin, through the pipe, into your dashboard."* Labels the flow drawn below.
+> *"Three tiers across two regions, one ledger."* Counts the system, geographic and structural.

package/skills/hallmark/references/macrostructures/20-ecosystem-index.md

@@ -0,0 +1,19 @@
+## 20 · Ecosystem Index
+
+Multiple discovery surfaces: featured, latest, by category, by people. The platform's value is browsing, not declaration.
+
+- **Heading:** a prompt positioning line; no display.
+- **Body:** several horizontal rails or grids, each surfacing a different cut of the platform's content.
+- **Divider:** each rail opens with its own `<h2>`, never a label band; a hairline or a change of paper between rails.
+- **Button:** a link at each rail's edge carrying a verb ("See all templates"); rarely a global CTA, so the fold's one visible action is the first rail's link (44b).
+- **Image:** thumbnails throughout; the page is dense imagery, all of it the platform's real content.
+- **Reveal:** none.
+
+Reach for it for community platforms, content marketplaces, asset stores, any curated catalogue front page.
+
+Avoid for single-product pages. Ecosystem needs several things to surface.
+
+**Sample opening lines** (rail headings, dated, with a count):
+> *"Featured this week."* Then *"Latest."* Then *"By category."* Three rail headings, each on its own line.
+> *"What is on this week, the editor's pick, and the whole catalogue."* Names cadence, curation and breadth in one sentence.
+> *"Made by the people who use it, sorted by the people who read it."* Second-position copy that breaks the template.

package/skills/hallmark/references/macrostructures/21-component-playground.md

@@ -0,0 +1,21 @@
+## 21 · Component Playground
+
+Interactive code-and-preview blocks are the page's primary content. Each block previews a thing and shows how to copy it.
+
+- **Heading:** each category is a real `<h2>` ("Buttons", "Forms", "Cards") in the display face, sentence case; never a label band.
+- **Body:** a preview, then its code, block after block, often with a tab row to switch frameworks; the row scrolls sideways under 60rem.
+- **Divider:** a change of paper per category; hairlines between examples.
+- **Button:** a "Copy" button on every code block; its label swaps to "Copied", never a toast (16).
+- **Image:** the previews are the imagery; one photograph band of the real machines or setting at most.
+- **Reveal:** none.
+
+Reach for it for design systems, component libraries, snippet sites, framework documentation.
+
+Avoid for marketing pages. Playground is utility, not pitch.
+
+Mono is legal here only inside the code blocks (64); tab labels and captions stay in the body face.
+
+**Sample opening lines** (tangible: open on a real example, not a claim):
+> *"Try it inline. Then take it home."* Two short imperatives.
+> *"Every example is editable. Every output is real."* Pairs the claim with its proof.
+> *"From `npm install` to your first chart in eight lines."* Names the step count, makes a concrete promise.

package/skills/hallmark/references/macrostructures.md

@@ -0,0 +1,119 @@
+# Macrostructures
+
+Twenty-one named landing-page shapes. Each is a complete fingerprint (heading placement, body composition, divider language, button voice, image treatment, reveal pattern) bundled under one name. **This is a vocabulary, not a menu.** Design the page the prompt asks for, then name the shape you designed so Rotation and gate 32 have something to read; reaching in here first and building whatever comes back is how twenty-one shapes collapse into the same three. When nothing here fits what you designed, say so, describe the shape as a fingerprint (§ The fingerprint, below), and give it a short name for the stamp and the log (*a season page*).
+
+## The 21 macrostructures, index
+
+**Read only the one file** for the shape you landed on, from `references/macrostructures/`. Do not load the whole catalogue. Slugs are stable; Rotation reads the shape from the stamp and the log. Nav and footer are part of the shape, settled with the hero. Each shape file names the `layout.md` compositions it is built from; the code is yours.
+
+- **01 · Bento Grid.** Modular blocks of varying sizes laid out as an irregular grid. Each block is a feature, a figure, an image or a quote the user supplied. Rhythm comes from size variation, not card uniformity. [`macrostructures/01-bento-grid.md`](macrostructures/01-bento-grid.md)
+- **02 · Long Document.** Reads like a memo, a letter or a journal entry. No marketing structure. Continuous prose with inline section heads. The page is literature about the product. [`macrostructures/02-long-document.md`](macrostructures/02-long-document.md)
+- **03 · Marquee Hero.** The hero is the page above the fold. A single statement or visual fills the viewport. Below the fold the page becomes something else (a list, a grid, prose). [`macrostructures/03-marquee-hero.md`](macrostructures/03-marquee-hero.md)
+- **04 · Stat-Led.** The hero is a figure the user gave, with the line that says what it means. Everything that follows supports or qualifies it. [`macrostructures/04-stat-led.md`](macrostructures/04-stat-led.md)
+- **05 · Workbench.** Real product captures are the primary content. The page is a guided tour of the app in use, with short captions in place of marketing copy. [`macrostructures/05-workbench.md`](macrostructures/05-workbench.md)
+- **06 · Conversational FAQ.** Bold questions, prompt answers. The page reads like an honest interview with the product. Each pair may be a disclosure. [`macrostructures/06-conversational-faq.md`](macrostructures/06-conversational-faq.md)
+- **07 · Manifesto.** Polemical large type. The page tells the reader what to believe before it tells them what to buy. [`macrostructures/07-manifesto.md`](macrostructures/07-manifesto.md)
+- **08 · Photographic.** A single huge image dominates each fold. Text is small annotation, not headline. The design says look before it says read. [`macrostructures/08-photographic.md`](macrostructures/08-photographic.md)
+- **09 · Quote-Led.** The hero is a quote the user supplied, with its attribution. The headline is someone else's voice. [`macrostructures/09-quote-led.md`](macrostructures/09-quote-led.md)
+- **10 · Specimen.** Large serif display, asymmetric spans, hairline rules, a typographic CTA, generous whitespace. Only for prompts about type, publishing or writing (a foundry, a journal, a press); the editorial genre alone does not qualify. [`macrostructures/10-specimen.md`](macrostructures/10-specimen.md)
+- **11 · Catalogue.** Uniform grid of variations of the same thing: typefaces, palettes, SKUs. The page is a visual index of inventory. [`macrostructures/11-catalogue.md`](macrostructures/11-catalogue.md)
+- **12 · Letter.** First-person, written, intimate. Opens with a greeting. Reads as a personal note from the founder. [`macrostructures/12-letter.md`](macrostructures/12-letter.md)
+- **13 · Index-First.** The page is a list of links. No hero image, no narrative flow. Navigation as design. [`macrostructures/13-index-first.md`](macrostructures/13-index-first.md)
+- **14 · Narrative Workflow.** Numbered stages tell the story of how the user uses the product over time. Each section is a phase; the page is a process timeline. [`macrostructures/14-narrative-workflow.md`](macrostructures/14-narrative-workflow.md)
+- **15 · Split Studio.** Diptych. Every major block divides the screen, text on one side, proof on the other; the proof keeps its side and the rows vary by weight. [`macrostructures/15-split-studio.md`](macrostructures/15-split-studio.md)
+- **16 · Feature Stack.** Sticky left pane holding the heading, scroll-synced right pane cycling through related captures. Paced like film. [`macrostructures/16-feature-stack.md`](macrostructures/16-feature-stack.md)
+- **17 · Type Specimen.** The typeface is the design. Foundry pages and design systems where a custom face is the proof. [`macrostructures/17-type-specimen.md`](macrostructures/17-type-specimen.md)
+- **18 · Portfolio Grid.** Filterable cards of projects. Studio and designer homepages where the work is the product. [`macrostructures/18-portfolio-grid.md`](macrostructures/18-portfolio-grid.md)
+- **19 · Map / Diagram.** A single large spatial diagram organises the page: flowchart, floor plan, network graph, system map. [`macrostructures/19-map-diagram.md`](macrostructures/19-map-diagram.md)
+- **20 · Ecosystem Index.** Multiple discovery surfaces: featured, latest, by category, by people. The platform's value is browsing, not declaration. [`macrostructures/20-ecosystem-index.md`](macrostructures/20-ecosystem-index.md)
+- **21 · Component Playground.** Interactive code-and-preview blocks are the page's primary content. Each block previews a thing and shows how to copy it. [`macrostructures/21-component-playground.md`](macrostructures/21-component-playground.md)
+
+---
+
+## SaaS section deck: deal it, do not sequence it
+
+When the shape is **Bento Grid, Stat-Led, Workbench or Marquee Hero** and the prompt is a B2B SaaS page, build from this deck. Cards have roles, not positions. The base of the deck is made of things the page can show honestly without inventing anything; the top of the deck exists only when the user handed over the material.
+
+**Base cards** (always available):
+
+| Card | Role | Composition |
+| --- | --- | --- |
+| Spec sheet | what it is, in figures the product ships with: limits, formats, versions, regions | Table or Rows (`layout.md` § 5) |
+| Worked example | the product doing one real job on the user's material: a command and its output, a capture and its caption | Showcase or Split |
+| Changelog | the last three or four entries with their real dates; the page proves it is alive | Rows |
+| Comparison anatomy | the product beside the way it is done today, row by row, no scores | Table |
+| Pricing table | the actual price, two or three tiers; "Contact sales" on every tier says the brand does not trust the buyer | `craft.md` § 9 Pricing |
+| FAQ | real objections answered like a person; "Yes, both providers work out of the box" beats "integrates with leading providers" | [`macrostructures/06-conversational-faq.md`](macrostructures/06-conversational-faq.md) |
+| CTA strip | the ask, once, one button | Band |
+| Footer | the close, in the theme's voice | `layout.md` § 7 |
+
+**Material cards** (exist only when the user supplied the material, and the Picks block names what was supplied):
+
+| Card | Needs | Without it |
+| --- | --- | --- |
+| Hero visual | a real capture | the product built in a `data-slot` (`imagery.md` § 4), or a typographic hero; never a styled-div UI outside a slot (47c) |
+| Logo row | the user's own customer marks, with permission to show them | the card does not exist; no invented marks, no "Trusted by" line (46a, 54) |
+| Three features | three named capabilities, each with a capture or figure to show | fold them into the worked example or the spec sheet |
+| Testimonials | quotes the user supplied verbatim, with the person's name, role and company as given | the card does not exist; no plausible names, no paraphrase (46a, 19) |
+
+**Every deal deviates twice.** (a) Drop at least one base card and name it (the CTA strip is the usual cut; footer never drops). (b) Either promote a second base card into the hero's place (a spec sheet as the hero object says "the numbers are the pitch"; a worked example as the hero says "watch it work") or reorder one adjacent pair meaningfully (pricing before the example says "the price is the pitch"). State both moves in the Picks block: `deck: -cta +changelog` or `deck: -faq · pricing<example`. A deal that keeps at least five cards still reads complete; below five it is a landing strip, not a landing page: re-add cards or switch shape.
+
+Cards part by the three `--section-gap` steps, mixed (59), and each fills its section (`layout.md` § 4).
+
+The deck is not a template you stamp out: the shape determines how each card looks. A Bento Grid page interleaves the spec sheet and the example inside the grid; a Stat-Led page sequences them top to bottom under the figure; a Marquee Hero page lets the marquee carry the claim and the example carry the proof.
+
+For non-SaaS work (Editorial, Manifesto, Letter, Long Document, Quote-Led) this deck does not apply. A bakery does not need a pricing tier comparison.
+
+---
+
+## How to pick
+
+On a theme build the draw deals the shape (SKILL.md Step 2); these steps are for a swap the material forces, or a run without Node.
+
+0. **Read the material inventory** (SKILL.md Step 2). A shape built on screenshots or figures needs them, real or as slots the user asked for; with neither, pick a shape that carries type and facts.
+1. **Read the prompt.** Note any words that strongly signal one shape ("data heavy", "tell a story", "a list of links", "many small features", "personal note").
+2. **Read `.hallmark/log.json`** (newest first) and the `shape:` field of any Hallmark stamp in the project; the last three shapes are excluded.
+3. **Match the prompt to a shape** using the index lines above and § Domain to trio below, then open only the file you land on. Most prompts match two to four; pick the one most distant from the logged shapes, and check the mirror test in SKILL.md Step 2.
+4. **State the pick once**, in the Picks block's Shape row and the stamp's `shape:` field.
+5. If torn, take the domain's trio (§ Domain to trio) and pick the one most distant from the log.
+
+Two pages Hallmark builds for two different prompts must look like different sites, not colour swaps of one template.
+
+## The fingerprint: six axes
+
+**1. Heading placement.** Left-margin (marginalia beside the body; a label beside a heading is an eyebrow, gate 54) · Hanging (the heading floats above in air) · Centred display · Bottom-aligned (the heading anchors the base, content above) · Overlapping (over a photo or colour block) · Sticky or pinned · Numbered by structure (a real `<ol>` with `counter()`, or one numeral at graphic scale) · Inline with the body (no break, the heading emerges from the prose). Any placement is fair; what reads as a mistake is a narrow auto-centred head over full-width left-flush content.
+
+**2. Body composition.** Single column · Two-column asymmetric (wide body, narrow margin for captions) · Multi-column justified with hyphenation · Marginalia (sidenotes in the outer margin) · Three equal columns (reference density) · Full-bleed with margin reset (65ch body, pull quotes and images bleed) · Asymmetric spans (2-1-3 ratios on a grid).
+
+**3. Divider language.** Hairline rule (0.5 to 1px, inset or full-bleed) · Ornament (a fleuron, a dot, a mark) · Negative space (the gap is the divider) · Bleed-colour block (a paper change is the edge) · Double rule. Pick one language for the page and vary its weight and placement by seam (9): the same rule at the same gap at every seam is the template.
+
+**4. Button voice.** Solid (one filled primary) · Outlined · Unstyled link (an underlined word) · Oversized solid · Typographic only (a word in a weight, no box) · Form as CTA (the action is fill-this-field).
+
+**5. Image treatment.** Full-bleed · Tightly cropped to the grid · Inline with the text · Margin-aligned · None.
+
+**6. Reveal pattern.** Fade-up stagger (once, orchestrated) · Horizontal sweep · Type-unmask (a clip-path opening over text) · Number-tick (counters, only on real figures) · Typewriter (a terminal only, the caret inside a typed command) · None.
+
+Fingerprint: one choice per axis, written `Hanging|Asymmetric spans|Hairline|Outlined|Margin-aligned|None`. Two rules: coherence (choices from the same world; a justified newspaper body wants a typographic CTA, not an oversized solid) and anti-repetition (no more than three of six axes shared with any of the last three logged entries; a None on Image or Reveal that the theme or the material forces is not a shared choice).
+
+## Domain to trio, when the prompt names no shape
+
+Three shapes from different families (grid-led, document-led, poster-led, product-led) that fit the domain, never three near-twins; the one most distant from the last logged shape is the pick:
+
+| Domain words | Trio |
+| --- | --- |
+| podcast, audio, music, listening | Photographic · Quote-Led · Letter |
+| shop, store, product, merch, commerce | Catalogue · Photographic · Bento Grid |
+| docs, CLI, SDK, API, library, open source | Workbench · Long Document · Component Playground |
+| platform, infra, observability, B2B tool | Bento Grid · Workbench · Stat-Led |
+| agency, studio, case studies, portfolio | Portfolio Grid · Split Studio · Index-First |
+| personal one-pager, about-me, resume | Long Document · Letter · Index-First |
+| restaurant, café, bar, food, menu | Photographic · Long Document · Catalogue |
+| fashion, apparel, beauty, lookbook | Photographic (with real photographs) · Catalogue · Marquee Hero |
+| fintech, banking, payments, trading | Stat-Led · Workbench · Long Document |
+| manifesto, campaign, cause, advocacy | Manifesto · Quote-Led · Stat-Led |
+| editorial, foundry, magazine, type | Specimen · Long Document · Type Specimen |
+| product launch, SaaS marketing | Bento Grid · Workbench · Stat-Led |
+| conference, event, speaker | Marquee Hero · Manifesto · Photographic |
+| no signal at all | Bento Grid · Long Document · Manifesto |
+
+Developer docs and developer marketing are different prompts (a walkthrough wants Workbench; the landing wants Bento plus Stat-Led), as are a one-pager and a case-study portfolio; the Step 1 use decides. A vague tone word ("modern", "clean") is read through the genre and stated as an inference, never a second question.

package/skills/hallmark/references/microinteractions.md

@@ -0,0 +1,80 @@
+# Microinteractions
+
+Loaded when the page has stateful UI. `craft.md` § 5 owns the durations, the three easings and the bans; `gates.md` owns the tells (10, 11, 12, 15, 16, 17, 18, 26, 27, 62); the theme's Motion section decides how much moves. This file owns the recipes, and repeats none of them.
+
+## Principles
+
+- **Motion has a job or it is cut.** Every animation clarifies, guides or confirms. Ask what would be lost if it were instant; if nothing, remove it.
+- **Silent success.** When the user can see the result, no toast. Toasts are for failures and for effects the page cannot show.
+- **Optimism with rollback.** Update the interface at once, send the request behind it, and roll back with a way to retry when it fails.
+- **Reduced motion is a state, not an afterthought.** Every recipe below names it: spatial motion collapses to a 150ms opacity crossfade, functional state still changes.
+- **Keyboard first.** Every hover affordance has a focus equivalent; nothing is hover-only.
+- **Three primitives at most per page** (a reveal, a hover signal, one functional loop such as a marquee or a counter count as three). A theme whose character is still runs none beyond functional state changes.
+
+## Recipes
+
+Durations are `--dur-micro` 120ms, `--dur-short` 220ms and `--dur-long` 420ms; enters `--ease-out`, exits `--ease-in` at 60 to 75% of the enter, toggles `--ease-in-out`. A spring appears only under a declared spring posture on a playful theme, on the primary control and one character moment (12).
+
+**Button press.** Hover is one signal, a colour change; press is a 1px drop, released on pointer up. The focus ring never animates.
+
+```css
+.btn { transition: background-color var(--dur-short) var(--ease-out), transform var(--dur-micro) var(--ease-out); }
+.btn:hover { background: var(--color-paper-3); }
+.btn:active { transform: translateY(1px); }
+```
+
+**Input focus.** The outline appears at once, inset on inputs; the border may deepen one step but its width never changes (39a). The label sits above the field at rest and never moves: a floating label starts life as a placeholder, which is the tell.
+
+**Validation.** First on blur once the field has been touched, then on every input; never on the first keystroke. The helper line swaps for the error in the same reserved line (F14): what broke, why, what to do. `aria-invalid` and `aria-describedby` on the field.
+
+**Toast.** Failures and invisible effects only (16). One corner, newest pushes the stack one way, nothing else repositions. In over `--dur-long`, 4 to 6s dwell, out at 65%; auto-dismiss pauses on hover and focus; an error toast carries one retry action and does not leave on its own.
+
+**Modal.** A `<dialog>` opened with `showModal()`, `inert` on the page behind it. Backdrop fades and the panel scales 0.96 to 1 over `--dur-long` `--ease-out`; it closes at about 65% with `--ease-in`. First focus goes to the first interactive element, not the close button. Reduced motion: the 150ms crossfade.
+
+**Menu.** The Popover API (light-dismiss, Escape and stacking for free), CSS anchor positioning that flips within 16px of an edge. Opens over `--dur-short` `--ease-out`, closes at 65% with `--ease-in`; items may stagger 30ms when there are eight or fewer.
+
+**Tooltip.** Hover delay 800 to 1000ms, focus delay 0 (17); opacity over `--dur-micro`. It stays while the pointer moves onto it and leaves on Escape (WCAG 1.4.13).
+
+**Tab change.** The indicator moves by `transform` (translate and scale on the x axis, never `width`) over `--dur-short`; the outgoing panel fades at `--dur-micro`, the incoming one follows. A panel that changes height animates `grid-template-rows: 0fr` to `1fr`, never `height`.
+
+**Number tick.** Real figures only (46a). On data load, count from the previous value (zero on first load) over 400 to 800ms with `--ease-out` applied to the value, formatted by `Intl.NumberFormat`. Announce only the final value (`aria-live="polite"`). Reduced motion: the final value at once.
+
+**Copy to clipboard.** The label swaps to *Copied* for 2.5s; no toast, the label is the feedback.
+
+```js
+btn.addEventListener("click", async () => {
+  await navigator.clipboard.writeText(value);
+  btn.dataset.state = "copied";
+  setTimeout(() => delete btn.dataset.state, 2500);
+});
+```
+
+**Drag to reorder.** The handle appears on hover and on focus; the cursor is `grab`, then `grabbing`; a ghost at 50% opacity follows the pointer and a 1px accent line marks the drop target. Release snaps over `--dur-short` `--ease-out`, no spring. Arrow keys reorder a focused row; `aria-live` announces the move.
+
+**Optimistic update.** The row changes at once and the request runs behind it. Success says nothing. Failure rolls the row back over `--dur-short` and raises a toast with *Try again*, which stays until acted on.
+
+```js
+const prev = item.done;
+item.done = !prev; render();
+try { await api.update(item); }
+catch { item.done = prev; render(); toast({ tone: "error", message: "Could not save.", action: { label: "Try again", run: retry } }); }
+```
+
+**Search as you type.** Debounce 250ms; while waiting, a quiet signal on the field (the border one step deeper). Matches in `<mark>`. Announce the result count once the debounce settles, never per keystroke.
+
+**Command palette.** Opens at once on ⌘K or `/`; the input keeps focus throughout. Arrow keys move a highlight that slides by `transform` over `--dur-micro`; the rows themselves never move. Enter selects, Escape closes. Rows may fade in on first open, never on filtering.
+
+**Page-load reveal.** One orchestrated entrance, per `craft.md` § 5: staggered by DOM order, 0.4 to 0.8s in all, IntersectionObserver rather than scroll listeners, once. A still theme skips it, and that is correct.
+
+## Motion character
+
+Every system declares one: a catalog theme in its Motion section, a custom page in its own stylesheet. The same press is louder in a severe system than in a calm one.
+
+| Character | Duration scale | Feels like |
+| --- | --- | --- |
+| **still** | none | Print. Nothing moves; a caret may blink inside a typed command, four or five beats and then solid, never on its own. |
+| **severe** | 0.7 to 0.75 times | Fast and decisive; snaps into place; no spring anywhere. |
+| **brisk** | 0.85 to 0.9 times | Technical and functional: an instrument panel. |
+| **calm** | 1.0 to 1.3 times | Restrained to generous, `--ease-out` at its gentlest. |
+
+Most pages have too much motion, not too little. The static answer is usually the right one.