@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-design-consultation/sections/proposal-and-preview.md.tmpl

@@ -1,350 +0,0 @@
-<!-- The font-selection procedure and the three-looks calibration in this section are derived from pbakaus/impeccable reference/new-work.md (Apache-2.0), rewritten and modified. See NOTICE.md. -->
-## Phase 3: The Complete Proposal
-
-Read this section in full, then apply its design/font rules → draft independently → offer outside voices → synthesize for Q2. Preview and writes require their later approvals.
-
-### Your Design Knowledge (use to inform proposals — do NOT display as tables)
-
-**Calibration: the three looks.** Avoid predictable compositions: cream/serif/terracotta; near-black/neon/glowing edges; or broadsheet hairlines/italic serif/tiny tracked mono. Use one only when the brief specifically calls for it. Otherwise choose a direction grounded in these users, rather than the category stereotype or its obvious opposite. For example, a book product can draw color from jackets and cloth instead of defaulting to cream and serif.
-
-**Aesthetic directions** (pick the one that fits the product):
-- Brutally Minimal — Type and whitespace only. No decoration. Modernist.
-- Maximalist Chaos — Dense, layered, pattern-heavy. Y2K meets contemporary.
-- Retro-Futuristic — Vintage tech nostalgia. Phosphor palette, bitmap type, warm monospace for data (no glow halos, no grid-paper backgrounds).
-- Luxury/Refined — Serifs, high contrast, generous whitespace, precious metals.
-- Playful/Toy-like — Rounded, springy (no overshoot), bold primaries. Approachable and fun.
-- Editorial/Magazine — Strong typographic hierarchy, asymmetric grids, pull quotes.
-- Brutalist/Raw — Exposed structure, one utilitarian grotesk, visible grid, no polish (a system stack only when the user asks for it by name).
-- Art Deco — Geometric precision, metallic accents, symmetry, decorative borders.
-- Organic/Natural — Earth tones, rounded forms, hand-drawn texture, grain.
-- Industrial/Utilitarian — Function-first, data-dense, monospace accents, muted palette.
-
-**Decoration levels:** minimal (typography does all the work) / intentional (subtle texture, grain, or background treatment) / expressive (full creative direction, layered depth, patterns)
-
-**Layout approaches:** grid-disciplined (strict columns, predictable alignment) / creative-editorial (asymmetry, overlap, grid-breaking) / hybrid (grid for app, creative for marketing)
-
-**Color approaches:** Restrained (1 accent + neutrals, color is rare and meaningful) / Committed (one hue owns the page, neutrals derive from it) / Full palette (primary + secondary + semantic colors for hierarchy) / Drenched (color as the primary design tool, surfaces carry it)
-
-**Motion approaches:** minimal-functional (only transitions that aid comprehension) / intentional (subtle entrance animations, meaningful state transitions) / expressive (full choreography, scroll-driven, playful)
-
-**Choosing faces: a procedure, not a menu.** (1) Name the audience's world (publication, notation, identity or object they read) and mode: Persuade (marketing), Operate (tasks), Read (long content), Experience (immersive). Match its tone. (2) Shortlist three faces per display/body/label/mono role. (3) Apply role exclusions. (4) Check each proposed family's official Google Fonts/Fontshare listing via WebSearch/Aside for its exact name, required weights, license and loading URL; for a local face, inspect its files and license. Omit faces you cannot verify. (5) Specify the verified loading source and strategy.
-
-**Font-verification fallback:** Skipping competitive research does not waive font verification. Offline, check local files/licenses. Otherwise describe roles/weights/proportions; mark font selection as pending verification in DESIGN.md. Continue palette/layout; defer the preview until fonts can be verified, or honor a user skip. Invent no face or URL.
-
-{{OVERUSED_FONTS}}
-
-**Anti-convergence directive:** VARY aesthetic, faces and palette across project generations; justify repetition. Light vs dark is not one of the dials: fix it to the use scene (who, where, lighting) until that scene changes. Unjustified convergence is slop.
-
-**AI slop anti-patterns** (never include in your recommendations):
-{{DESIGN_SLOP_BULLETS}}
-
-### Coherence Validation
-
-After any override, gently flag mismatches and offer alternatives: Brutalist/Minimal + expressive motion → quieter motion or keep intentionally; Drenched + minimal decoration → supporting decoration; editorial + dense data → hybrid layout. Never block; accept the user's final choice and proceed.
-
-### Independent proposals, then synthesis
-
-Draft your own direction from the brief: fill Q2's aesthetic, palette, role-specific type, layout, spacing, motion and two deliberate risks before dispatching either voice. Keep that draft out of both reviewers' prompts; send the same brief, not your answer. Outside voices run only after user opt-in; `enabled` records that choice, and the second harness check guards the later spawn.
-
-{{DESIGN_OUTSIDE_VOICES}}
-
-Compare completed outside proposals: explain agreements, differences, and ideas adopted with attribution. Verify any newly suggested fonts before adopting them using the same procedure above. Tie the recommendation to the memorable-thing answer. Do not count agreement as a vote or invent a missing proposal. Q2 names completed, unavailable, or declined voices and presents the recommendation.
-
-**AskUserQuestion Q2 — present the full proposal with SAFE/RISK breakdown:**
-
-```
-Based on [product context] and [research findings / my design knowledge]:
-
-AESTHETIC: [direction] — [one-line rationale]
-DECORATION: [level] — [why this pairs with the aesthetic]
-LAYOUT: [approach] — [why this fits the product type]
-COLOR: [approach] + proposed palette (hex values) — [rationale]
-TYPOGRAPHY: [display, body, label, mono assignments; a face may serve multiple roles] — [why these fonts]
-SPACING: [base unit + density] — [rationale]
-MOTION: [approach] — [rationale]
-
-This system is coherent because [explain how choices reinforce each other].
-
-INDEPENDENT INPUT: [completed/unavailable/skipped voices; agreements, differences, ideas adopted and product-specific reasons — omit comparisons if none completed]
-
-SAFE CHOICES (category baseline — your users expect these):
-  - [2-3 decisions that match category conventions, with rationale for playing safe]
-
-RISKS (where your product gets its own face):
-  - [2-3 deliberate departures from convention]
-  - For each risk: what it is, why it works, what you gain, what it costs
-
-Safe choices meet category expectations; risks make the product memorable.
-Which risks appeal to you? Try others or adjust anything else?
-```
-
-Coherence alone can look generic. Propose at least 2 creative risks—type, accent, spacing, layout or motion—with rationale, benefit and cost alongside the category's safe choices.
-
-**Options:** A) Looks great — proceed to Phase 5 if fonts are verified. B) Adjust [section] — Phase 4, then Q2 again. C) Different risks — revise the proposal, then Q2 again. D) Start over — draft another direction using the same confirmed brief. E) Skip the preview — proceed to Phase 6's Q-final, not straight to writing.
-
-Revisions recheck fonts and coherence. If the product brief changes, label old proposals stale and offer fresh independent voices; do not claim they reviewed new context.
-
----
-
-## Phase 4: Drill-downs (only if user requests adjustments)
-
-Use one focused AskUserQuestion per requested drill-down: **Fonts:** 3-5 verified candidates with roles, rationale/evocation and preview offer; **Colors:** 2-3 hex palettes and color theory; **Aesthetic:** product-fit directions and why; **Layout/Spacing/Motion:** concrete product-specific tradeoffs. Carry the selected adjustment into the full Q2 proposal and re-check its font verification and coherence before asking Q2 again.
-
----
-
-## Phase 5: Design System Preview (default ON)
-
-After Q2 approval: pending fonts or a preview skip → Phase 6 with limitations. Generation unavailable/failed → offer Path B or skip, not unbounded retries.
-
-### Path A: AI Mockups (if DESIGN_READY)
-
-Apply the proposed system to realistic product screens:
-
-```bash
-SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
-GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
-_DESIGN_DIR="$GSTACK_STATE_ROOT/projects/$SLUG/designs/design-system-$(date +%Y%m%d)"
-mkdir -p "$_DESIGN_DIR"
-echo "DESIGN_DIR: $_DESIGN_DIR"
-```
-
-Brief: Phase 3 aesthetic/colors/type/spacing/layout plus Phase 1 product context, written into a private file:
-
-{{FREE_TEXT_FILE:BRIEF_FILE=brief}}
-
-Brief shape: `Product name: [name]. Product type: [type]. Aesthetic: [direction]. Colors: primary [hex], secondary [hex], neutrals [range]. Typography: display [font], body [font]. Layout: [approach]. Show a realistic [page type] screen with [specific content for this product].` Then substitute the printed name for `<brief-file-name>`:
-
-```bash
-BRIEF_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<brief-file-name>"
-[ -s "$BRIEF_FILE" ] || { echo "Not run: $BRIEF_FILE is missing or empty. Write the brief, then rerun this block." >&2; exit 1; }
-_OUT=$($D variants --brief "$(cat "$BRIEF_FILE")" --count 3 --output-dir "$_DESIGN_DIR/"); _RC=$?
-printf '%s\n' "$_OUT"; echo "EXIT: $_RC"
-```
-
-<!-- design:round-accounting -->
-**Round accounting:** names are never overwritten (a taken one is bumped), so use only the printed `saved` paths. Tell the user how many of `requested` paid images were saved and name each `failures` entry. Exit 2 means nothing was saved: report `failures` and stop here (offer Path B or skip); run no `$D check` or board.
-
-Run quality check on each saved path, starting with the first, against the same brief file; never include failed variants:
-
-```bash
-BRIEF_FILE="$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.gstack/tmp/<brief-file-name>"
-[ -s "$BRIEF_FILE" ] || { echo "Not run: $BRIEF_FILE is missing or empty. Write the brief, then rerun this block." >&2; exit 1; }
-$D check --image "<first path from the printed saved list>" --brief "$(cat "$BRIEF_FILE")"
-```
-
-Read JSON, not exit code: `pass: false` means regenerate addressing `issues`, then recheck. `pass: true` with an unavailable/skipped warning is missing automated coverage; disclose it and inspect visually.
-
-**Before presenting, self-gate:** Would a human designer be embarrassed to sign each variant? If yes, discard and regenerate. Hard rejects: purple gradient hero, 3-column SaaS grid, centered-everything, overused display face, generic stock photo, system-ui, gradient CTA, bubble-radius everything. Any trigger requires regeneration.
-
-Read each accepted PNG inline, then open the board with those paths before inviting choices/remix.
-
-{{DESIGN_SHOTGUN_LOOP}}
-
-After final image confirmation, `$D extract` would write DESIGN.md in a Git repo: run it only in a fresh non-repository scratch directory. Bind `$D` and `APPROVED_IMAGE` (the confirmed letter's `board-images.json` entry) to absolute paths:
-
-```bash
-_EXTRACT_DIR=$(mktemp -d "${TMPDIR:-/tmp}/gstack-design-extract-XXXXXXXX") || exit 1
-(
-  cd "$_EXTRACT_DIR" || exit 1
-  if git rev-parse --show-toplevel >/dev/null 2>&1; then
-    echo "Extraction refused: scratch directory resolves to a Git repository" >&2
-    exit 1
-  fi
-  "$D" extract --image "$APPROVED_IMAGE"
-)
-```
-
-Compare extracted tokens with the approved image and verified fonts; show discrepancies at Q-final. Empty arrays, an "Unable to extract" mood or command failure → disclose fallback to Phase 3 values, never invent measured tokens.
-
-Late visual changes return to the feedback loop: regenerate, recheck, reconfirm, then extract again. Only `generate` supplies `sessionFile` for `$D iterate --session "<returned sessionFile>" --feedback "$(cat "$FEEDBACK_FILE")" --output "$_DESIGN_DIR/refined.png"`; use its printed `outputPath`. Variants must regenerate.
-
-**Plan mode:** Carry the approved mockup paths/tokens into Phase 6's "## Proposed DESIGN.md" plan section. Its Q-final approval governs saving that content; defer the actual DESIGN.md to implementation.
-
-### Path B: HTML Preview Page (fallback if DESIGN_NOT_AVAILABLE)
-
-Create and open the HTML preview:
-
-```bash
-PREVIEW_FILE="/tmp/design-consultation-preview-$(date +%s).html"
-```
-
-Write the preview HTML to `$PREVIEW_FILE`, then open it:
-
-```bash
-open "$PREVIEW_FILE"
-```
-
-### Preview Page Requirements (Path B only)
-
-Write a **single, self-contained HTML file**, no frameworks:
-
-1. **Loads proposed fonts** via `<link>` from their step (4) verified Google Fonts/Fontshare/self-hosted source.
-2. **Uses the proposed palette** throughout.
-3. **Shows the product name**, not Lorem Ipsum, in the hero.
-4. **Font specimen section:**
-   - Each candidate in its hero/body/button/table role; compare same-role alternatives side by side using real domain content (e.g. civic tech: government data).
-5. **Color palette section:**
-   - Named hex swatches; primary/secondary/ghost buttons, cards, inputs, success/warning/error/info alerts; background/text contrast pairs.
-6. **Realistic product mockups:** Render 2-3 Phase 1 product-type layouts with the full system, product name, domain content and proposed spacing/layout/radii:
-   - **Dashboard/web app:** metrics table, sidebar nav, avatar header, stat cards.
-   - **Marketing:** real-copy hero, features, testimonials, CTA.
-   - **Settings/admin:** labeled inputs, toggles, dropdowns, save.
-   - **Auth/onboarding:** branded login, social buttons, validation states.
-7. **Light/dark toggle:** CSS custom properties plus a JS button.
-8. **Clean, professional layout.**
-9. **Responsive** at every width.
-
-Show how their product feels, beyond a font/color inventory.
-
-If `open` fails (headless environment), tell the user: *"I wrote the preview to [path] — open it in your browser to see the fonts and colors rendered."*
-
-If the user says skip the preview, go directly to Phase 6.
-
----
-
-## Phase 6: Write DESIGN.md & Confirm
-
-Only Path A invokes `$D extract`, isolated as above. For Path B, use the approved HTML preview's CSS values. No preview: approved Phase 3 values; mark only unverified fonts pending. Retain rationale and unchanged existing decisions.
-
-**Confirm before writing.** Prepare the complete DESIGN.md contents below, identify every token source (approved mockup extraction, approved HTML, or Phase 3 fallback), mark any unverified font pending, and show the exact CLAUDE.md guidance you would add or update. Show decisions and agent-selected defaults together with that preview. AskUserQuestion Q-final:
-- A) Approve — write DESIGN.md and CLAUDE.md; in plan mode, save Proposed DESIGN.md in the plan only
-- B) Revise — return to Phase 3, then confirm again
-- C) Start over — return to Phase 1
-
-Wait. Only A permits the writes below; B/C leave project files untouched. Honor prior explicit approval of these exact writes without re-asking. Any subsequent token, font or direction change invalidates that approval: update the proposal, reverify affected fonts/preview, and ask Q-final again. A changed product brief also invalidates prior independent proposals.
-
-**If in plan mode:** Write the DESIGN.md content into the plan file as a "## Proposed DESIGN.md" section. Do NOT write the actual file — that happens at implementation time.
-
-**If NOT in plan mode:** apply the approved Phase 0 format choice, then write root `DESIGN.md`. New, fresh and converted files use google-labs-code/design.md format below: all tokens belong in the five normative YAML groups; prose explains rationale/use without repeating values. Preserve the line-2 format marker. A kept-legacy or unknown-format Update instead retains its own shape; persist `legacy-keep` only for the chosen legacy path. Preserve the prior file in a backup before a fresh replacement.
-
-```markdown
----
-# gstack: design-md-format=spec
-name: [Project Name]
-description: [one sentence: mood, material, energy]
-colors:
-  primary: "#..."          # descriptive slugs; hex, or the project's canonical color space
-  on-primary: "#..."
-  surface: "#..."
-  text: "#..."
-  text-muted: "#..."
-  accent: "#..."
-  success: "#..."
-  warning: "#..."
-  error: "#..."
-typography:
-  display:
-    fontFamily: [face]
-    fontWeight: [weight]
-    fontSize: [clamp() or rem]
-    letterSpacing: [em]
-  body:
-    fontFamily: [face]
-    fontSize: 1rem
-    lineHeight: 1.5
-  label:
-    fontFamily: [face]
-    fontSize: 0.75rem
-    letterSpacing: 0.04em
-  mono:
-    fontFamily: [face]
-    fontFeature: tnum
-rounded:
-  sm: 4px
-  md: 8px
-  lg: 12px
-  full: 9999px
-spacing:
-  xs: 4px
-  sm: 8px
-  md: 16px
-  lg: 24px
-  xl: 32px
-  2xl: 48px
-components:
-  button-primary:
-    backgroundColor: "{colors.primary}"
-    textColor: "{colors.on-primary}"
-    rounded: "{rounded.md}"
-  button-primary-hover:
-    backgroundColor: "#..."
-  input:
-    borderColor: "{colors.text-muted}"
-    rounded: "{rounded.sm}"
-  card:
-    backgroundColor: "{colors.surface}"
-    rounded: "{rounded.lg}"
-  nav-link:
-    textColor: "{colors.text}"
----
-
-# [Project Name]
-
-## Overview
-
-**Creative North Star:** [one sentence: aesthetic + why it fits these users]
-**Product context:** [product, users, category/peers, project type]
-**Mode per surface:** [one line each: Persuade / Operate / Read / Experience]
-**Reference sites:** [URLs, if research was done]
-**Key characteristics:** [3-5 bullets: first-five-second impressions]
-
-## Colors
-
-**Strategy:** [Restrained / Committed / Full palette / Drenched] — [why]
-**Light or dark:** [decided by the use scene: who, where, under what light]
-[Explain which tokens signal interaction or emphasis, how neutrals derive from the palette, and how dark-mode surfaces preserve hierarchy rather than merely inverting lightness.]
-
-## Typography
-
-[Faces' source world, mode/register, roles and display boundaries; loading, scale rationale, justified overused-list exceptions]
-
-## Layout
-
-[Breakpoint grids, max width, density, large/small spacing rhythm, intentional grid breaks]
-
-## Elevation & Depth
-
-[Depth: offset + soft-blur shadows, tints, borders; no zero-offset glow]
-
-## Shapes
-
-[Radius hierarchy/uses; nested inner radius = outer radius − gap]
-
-## Components
-
-[Per component: hover/focus-visible/active/disabled states, invariants and adaptations]
-
-## Do's and Don'ts
-
-- Do: [3-5 specific, checkable rules]
-- Don't: [3-5 system-specific anti-patterns, including this category's tempting catalog entries]
-
-## Motion
-
-- **Approach:** [minimal-functional / intentional / expressive]
-- **Easing:** enter(ease-out) exit(ease-in) move(ease-in-out)
-- **Duration:** micro(50-100ms) short(150-250ms) medium(250-400ms) long(400-700ms)
-- **The one authored moment:** [what it is]
-
-## Decisions Log
-| Date | Decision | Rationale |
-|------|----------|-----------|
-| [today] | Initial design system created | Created by /design-consultation based on [product context / research] |
-```
-
-Use real token values, no placeholders; omit invented `components` entries and unverified fontFamily values. Describe pending font roles in prose instead. Outside plan mode, after writing DESIGN.md, run `bun --no-env-file run ~/.claude/skills/gstack/bin/gstack-design-md.ts check DESIGN.md`: require `DESIGN_MD_FORMAT: spec` for new/fresh/converted/spec files, `legacy` with `legacy-keep` for a kept legacy file, or the disclosed `unknown` format for a preserved unknown file. Never convert a kept file just to make validation say spec.
-
-**Outside plan mode, update CLAUDE.md** (or create it if it doesn't exist) — append this section:
-
-```markdown
-## Design System
-Read DESIGN.md before visual or UI work: it defines the fonts, colors, spacing, and
-aesthetic direction. Ask the user before departing from it. When reviewing or QA-ing
-UI, flag code that doesn't match DESIGN.md.
-```
-
-After shipping DESIGN.md, if the session produced screen-level mockups or page layouts
-(not just system-level tokens), suggest:
-"Want to see this design system as working Pretext-native HTML? Run /design-html."
-
----