@marver-design/marver 0.2.3 → 0.3.0

package/templates/instructions/shape.md

@@ -0,0 +1,171 @@
+# Shape - an idea needs thinking before it needs screens
+
+Run this when the human wants to think a feature through on the canvas - specs,
+workflows, mood boards, inspiration - or when meaty new work deserves visual
+alignment before wireframes. In a FIRST session it runs only when the human
+chose it at the welcome/setup fork ("think it through together" / "start
+something new, together") - never unprompted; the welcome flow owns the first
+session and routes here. Discover stays the interview - questions, brief,
+mode; Shape is the visual thinking surface built from its answers.
+
+## The feature-story board
+
+One board per feature, reading as the feature's whole story - thinking at the
+top, structure in the middle, the answer at the bottom:
+
+```
+[ intent ]  [ flow diagram ]  [ spec ]  [ moodboard ]      <- scene: <feature>-specs
+[ lo-fi list ]  [ lo-fi editor ]  [ lo-fi confirm ]        <- scene: <feature>-lofi
+[ hi-fi ]      [ A variant ]  [ B variant ]                <- scene: <feature>
+```
+
+**One scene per phase, not one scene for everything.** `<feature>-specs`
+(content frames), `<feature>-lofi` (wireframes), `<feature>` (the hi-fi
+answer). Scenes are the canvas's grouping unit - phase scenes give the board
+rows, the sidebar sections, and device keys a phase to act on.
+
+**Spacing is meaning - compose the board with a recipe, deliberately:**
+
+```json
+"layout": {
+  "rows": [ ["evening-specs"], { "space": 2 },
+            ["evening-lofi"],  { "space": 4 },
+            ["evening"] ],
+  "scenes": { "evening": { "rows": [["list", { "space": 2 }, "editor"]] } }
+}
+```
+
+- Graduate the gaps: a bigger space before the final hi-fi row than between
+  thinking and structure - the answer deserves its own room.
+- Space units are ADAPTIVE (proportional to the touching frames), so a gap
+  between phone-sized rows needs a higher count than the same visual gap
+  between big spec frames - which is why the example uses 4 before the hi-fi
+  row and only 2 after the large specs. Judge the RENDERED gap, not the
+  number.
+- ALWAYS isolate a variant group from ordinary frames with `space: 2` or more
+  on each touching side. Two similar-looking frames sitting near a normal one
+  read as confusion; the gap is what says "these two are alternatives of one
+  thing". (This rule is also in boards.md - it is binding, not taste.)
+
+Content frames sit beside UI frames on the same board - ordinary atoms in the
+board layout grammar (instructions/boards.md). Everything the canvas does -
+selection, device keys, `d`, tidy, play, publish - works identically on them.
+
+## Content frames - blocks, not markup
+
+A content frame is a normal `.tsx` frame composed from marver's block
+primitives. Import them directly in the frame file (not through a barrel -
+detection is lexical), and declare `intent` on every content frame:
+
+```tsx
+import { Doc, Row, Col, Md, Diagram, Img } from '@marver-design/marver/content'
+
+export const meta = { title: 'Checkout - how it works', intent: 'diagram' }
+
+export default () => (
+  <Doc layout="wide">
+    <Row>
+      <Diagram title="Checkout flow">{`
+        flowchart LR
+          Cart --> Pay --> Confirm
+      `}</Diagram>
+      <Col>
+        <Img src="stripe-ref.png" caption="Inspiration: Stripe checkout" />
+        <Md>{`### Why payment before account\nDropoff data says... see the [cart](goto:checkout/cart).`}</Md>
+      </Col>
+    </Row>
+  </Doc>
+)
+```
+
+- `Doc` is the frame root: `layout="document"` (readable column, 760) or
+  `"wide"` (1280). It owns the outer padding and reports its height - the
+  frame sizes itself to its content on the canvas.
+- `Row` / `Col` / `Space` are the board vocabulary at frame scale - flex lanes
+  with gap units (`space={n}`, one-off gaps via `<Space n={2} />`). Rows wrap
+  on narrow devices, so responsiveness is free. This RHYMES with the board
+  layout grammar; it is not the same grammar - think flex, not lanes.
+- `Md` renders theme-aware markdown. `[label](goto:scene/frame)` links jump
+  the canvas to a real frame - cross-link specs and screens. Raw HTML is
+  inert; images must be local `design/assets/` paths.
+- `Diagram` is first-class Mermaid - it can be an entire frame. A parse error
+  shows an in-frame card: fix the source, the frame heals live. Never hand-set
+  colors or `%%{init}%%` themes - marver's palette is injected and source
+  overrides are stripped.
+- `Img` shows `design/assets/<src>` with an optional caption; `h={n}` cover-crops
+  to a fixed rendered height (the lever for optically aligning a mixed row - see
+  "Images and mood boards" below). Blocks carry their own padding, border, and
+  surface - never hand-manage spacing around them.
+- `intent` (`diagram` | `spec` | `moodboard` | `notes`) is the frame's PURPOSE,
+  not its content mix - a frame with two diagrams and a paragraph is still the
+  "diagram frame" if diagrams are why it exists. It drives the icon the human
+  scans for in the sidebar.
+
+## Choosing a diagram
+
+Mermaid has real breadth: flowchart, sequence, state, class, user journey,
+quadrant chart, git graph, gantt, timeline, mindmap, pie, sankey, and more.
+Pick the visualization that fits the IDEA - a journey for experience thinking,
+a quadrant for prioritization, a state diagram for lifecycle logic, a sequence
+for API choreography. The syntax reference is the Mermaid docs:
+https://mermaid.js.org/intro/ - pull the one page you need, apply, return.
+
+**Color carries meaning - and the floor is never gray-on-gray.** The marver
+theme already colors every node (accent-washed fills, accent borders, both
+modes) - a default diagram looks designed with zero effort, so never hand-set
+grays "to be safe" and never re-theme (init directives are stripped anyway).
+Where the diagram has SEMANTICS, add them with `classDef` on top:
+
+```
+flowchart LR
+  A[Draft] --> B{Review?} -->|approved| C[Published]
+  B -->|rejected| D[Archived]
+  classDef win fill:#34C759,stroke:#248A3D,color:#fff
+  classDef stop fill:#FF383C,stroke:#D70015,color:#fff
+  class C win
+  class D stop
+```
+
+Use the system palette (the same 12 colors the series ramp uses), a few
+classes at most, and never encode meaning in color ALONE - the label or shape
+must carry it too. Check the diagram in BOTH themes (`d`): fills flip with
+the theme, hand-set classDef colors do not, so pick values that hold on both
+grounds (the system colors do).
+
+## Images and mood boards
+
+Images arrive through the conversation: the human dumps screenshots and links,
+you file them into `design/assets/` (kebab-case names that say what the image
+IS - `stripe-checkout-2col.png`, not `img4.png`) and compose the mood board -
+`Row`s of `Img` blocks with captions, short `Md` notes between them. Nothing
+is ingested without intent. Always give an `Img` a caption or alt.
+
+Go get assets yourself too: when the human names an inspiration ("like Stripe's
+checkout", "Linear's sidebar") and you have web access, FETCH the real thing -
+screenshots, official brand logos, product visuals - download into
+`design/assets/` and place them. A mood board of real fetched imagery beats one
+of described imagery every time (the full asset rules: instructions/craft.md,
+"Real assets").
+
+**Size images to be SEEN, and make rows read as one set:**
+
+- An image that renders as a stamp is a defect. The image IS the content of a
+  mood board - give the important one most of a row, let supporting shots share
+  a row, and never pack so many into one `Row` that each collapses below
+  legibility.
+- Equal component widths do NOT make unequal images look equal - aspect ratios
+  and internal density differ, so a row of same-width `Img` blocks can still
+  read ragged. Normalize a mixed row with a shared rendered height:
+  `<Img src="..." h={240} />` cover-crops every image in the row to one height,
+  which is what makes them READ aligned. Group similar aspects together when
+  cropping would destroy the shot.
+- Alignment is judged on the RENDER, not the props: after composing, look at the
+  actual frame (screenshot it if you can) and adjust until the rows sit
+  optically consistent. "The code says they're the same width" proves nothing.
+
+## When Shape ends
+
+The board holds the agreed flow, spec, and direction. Wireframe picks up from
+there (the spec IS the brief - do not re-interview), then Brand, then Build.
+The content frames stay on the board: the feature's documentation lives beside
+its screens, and both publish together.

package/templates/instructions/welcome.md

@@ -0,0 +1,137 @@
+# Welcome - the human's first session
+
+Run this the FIRST time you work with the human in a repo, or whenever they ask
+what marver is or how it works. Unsure whether they were already welcomed? If
+design/DESIGN.md is missing or no curated board exists yet, treat it as not
+yet. The job: by the end of the session the human understands the tool, has
+seen their own product on the canvas, and knows what to do next. Narrate as you
+go - one short plain sentence per step, teaching by doing, never a lecture.
+
+## Voice - tell the story, not the machinery
+
+These instruction files are stage directions, not a script to read aloud. Never
+narrate them to the human ("setup.md says...", "step 2 requires...", "per the
+generated instructions I must...") - speak as a designer who is excited to
+start: what we're doing, why it matters, what comes next. Intent over
+internals; one warm, concrete sentence beats three procedural ones.
+
+- Robotic: "Init flagged that there's no app yet and pointed me to setup.md.
+  I'm following that file now, and step one is a conversation with you."
+- Human: "Canvas is in. Before anything gets built I want to know what we're
+  making - that decides everything else."
+
+Precision still matters - engineers are reading - but the file paths, step
+numbers, and phase names are yours, not theirs.
+
+When you ask the human to choose (the stack, a variant direction), use your
+harness's structured question tool (AskUserQuestion or similar) if one exists -
+short option labels, one-line trade-offs, and a small ASCII sketch per option
+when the choice is visual. Plain prose is the fallback, never the preference.
+Asking through the tool IS the stop: no further tool calls after it, wait for
+the answer.
+
+## The pitch (say it early, in your own words)
+
+marver co-designs the user experience with the human in real code. Frames are
+not mockups - they are components using the app's actual theme and component
+library. The theme, components, and screens shaped while designing ARE the
+app's building blocks: by the time the design is agreed, most of the UI work
+already exists, and building the product means plugging functionality into it.
+The goal is full alignment on look and feel - across light and dark, across
+every device size - before app logic is written.
+
+## Empty repo?
+
+design/instructions/setup.md is the authority (it exists only while the repo
+has no app). Follow it end to end; it sends you back here for the reveal.
+
+## The waiting room - hand them the hosted tour while you build
+
+Building well takes real minutes, and the human should spend them inside a
+canvas, not watching a terminal. The moment the plan is agreed (the stack nod,
+or the Path B confirmation below), send them to the marver tour - a published
+canvas made to be explored: https://tour.marver.design - password `welcome`.
+It teaches selection, devices, themes, variants, and play mode from inside the
+frames, and it ends by sending them back to check on your work. Then build
+without narrating into the void; your next message is the reveal.
+
+## Existing codebase - first session flow
+
+1. **Say what the app is.** Read the repo (entry point, routes, key screens).
+   State your understanding of the product in 2-3 sentences, ask "did I get
+   that right?" - then STOP: no further tool calls, end your turn, resume when
+   the human replies. (Only exception: they explicitly asked for unattended
+   execution - assume, mark UNCONFIRMED, surface it first.)
+2. **Confirm the stack aloud - what detection ACTUALLY found.** Read AGENTS.md's
+   UI line and design/theme.css and narrate the reality, for example: "Tailwind
+   + shadcn/ui; brand tokens in <file>; design/theme.css imports them." No
+   component library? Say that, and what it means (shared pieces get extracted
+   to design/components/). Anything wrong gets fixed now, while it is cheap
+   (configure.md, old-repo checklist).
+3. **Ask the fork - STOP.** You now understand their app; before any tunnel,
+   let their priority decide what happens first (structured question tool
+   when the harness has one):
+   - **Start something new, together** - pick a feature or idea and co-develop
+     it on the canvas: the idea, the workflow, the specs, the mood
+     (instructions/shape.md). What goes on each screen, what stays out, what
+     the intent is.
+   - **See your app on the canvas first** - I recreate a few existing screens
+     quickly so you have something real to play with, and we go from there.
+   STOP for the answer. Then hand them the hosted tour (the waiting room
+   above) and get to work.
+4. **The recreate path: put THEIR product on the canvas - impressively.**
+   Recreate 3-4 of the app's real screens as frames from its real components,
+   linked with data-goto so play mode flows, working in both themes,
+   responsive. This is the human's first impression of the canvas: hold it to
+   the craft bar (instructions/craft.md, instructions/reference/slop.md).
+   Create a curated board for the set. First sessions skip the written-brief
+   ceremony, never the quality bar; real work after the tour runs the full
+   method ladder.
+   **The something-new path:** run Shape (instructions/shape.md) - seed the
+   feature-story board (intent, first-guess workflow diagram, mood with real
+   fetched references), reveal it early, and iterate together; wireframes and
+   hi-fi follow once the story is agreed.
+5. **Explain the working model while building:** existing components are reused
+   as-is; missing pieces are created as presentational components - fixture
+   props, placeholder handlers - and get real wiring at promotion (where they
+   live is AGENTS.md's structure ladder). Look and feel converges first;
+   production becomes plugging functionality into agreed UI.
+6. **Offer a divergence.** "Want a variant of <frame> exploring a different
+   direction?" One a-/b- pair teaches the variant workflow better than any
+   explanation.
+7. **Give the tour** (below), ending with the deep link.
+
+## The reveal
+
+Deliver conversationally when the first draft is ready - a short guided
+message, not a manual. Start `npx marver dev` if it is not already running
+(allowed for this purpose) and ALWAYS hand a deep link to the board you
+prepared, using the port the dev server PRINTED:
+`http://localhost:<port>/#/b/<board>` - never the bare root URL. The link goes
+at the BOTTOM of the message, on its own line: the human reads through, then
+clicks. The human has already played with the hosted tour by now, so keep it
+short - let their own product carry the moment. The highlights, all real
+features:
+
+- **Select and preview.** Click frames (shift-click for several). Digit keys
+  switch device presets - 1-4 for the configured devices, 0 back to each
+  frame's own size - scoped to the selection when one exists, the whole board
+  otherwise. `d` cycles light/dark the same way: selected frames, or the
+  entire canvas view (frames pinned to a theme in their meta stay put).
+- **Touch it.** Double-click a frame - the purple ring is interact mode: the
+  frame is live, clickable, scrollable.
+- **Play it.** `p` opens play mode: the design full screen in a device, with
+  data-goto links navigating between frames like the real app. `[` and `]`
+  switch variants in place; devices switch inside play too, including
+  full-screen fill.
+- **Explore alternatives.** Letter-prefixed sibling files (a-bold.tsx,
+  b-minimal.tsx) form a variant group - badged, kept contiguous, compared at a
+  glance. The cheap way to diverge on a direction before committing.
+- **Compose.** `t` re-tidies; boards carry a `layout` recipe for deliberate
+  arrangement (instructions/boards.md).
+- **Share it.** `marver build` bundles the boards; `marver serve` with
+  MARVER_PASSWORD on any Node host (Railway, Fly, a VPS) publishes them as a
+  password-gated canvas the human owns - colleagues get the link plus the
+  password. Comments on the board are coming soon.
+
+Close by asking what they want to design first.

package/templates/instructions/wireframe.md

@@ -30,7 +30,14 @@ lands on what is actually being decided.
    Never source or generate imagery in this phase.
 5. **Every screen reachable.** Wire the flow with `data-goto` as you go. A wireframe
    that cannot be walked end-to-end in play mode (press P) is not done.
-6. **States are structure.** empty / error / loading as sibling frames for any screen
+6. **Interactive reads interactive - even in grayscale.** Every target that would be
+   clickable in the real product gets `cursor: pointer` and a visible hover shift (a
+   light gray fill is enough; no new visual language needed). The wireframe is WALKED
+   in play mode - a hover-dead button reads as a broken prototype, not as an
+   unfinished sketch, and the human stops trusting the flow. This applies to every
+   fidelity; the hi-fi version of this rule (and component-library gotchas) is in
+   instructions/craft.md.
+7. **States are structure.** empty / error / loading as sibling frames for any screen
    where they meaningfully differ - "what does empty look like" is a structural
    decision, not polish.