diff --git a/README.md b/README.md index da69476..153f839 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ # FixMap -Know where to edit before the first edit. +Tell AI coding tools which files to check first. -Paste a GitHub issue URL, describe a task, or point at a diff. FixMap returns ranked context, an evidence-backed Impact Graph, reachable test commands, risks, and explicit uncertainty—without an account, API key, or model call. +Describe what is broken. FixMap checks the project and gives tools like Codex, Claude Code, and Cursor a short list of files to open, tests to run, and other code to review. It includes reasons and says when it is unsure—without an account, API key, or model call. [![CI](https://github.com/aryamthecodebreaker/FixMap/actions/workflows/ci.yml/badge.svg)](https://github.com/aryamthecodebreaker/FixMap/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/%40aryam%2Ffixmap)](https://www.npmjs.com/package/@aryam/fixmap) @@ -12,13 +12,15 @@ Paste a GitHub issue URL, describe a task, or point at a diff. FixMap returns ra [![Marketplace](https://img.shields.io/badge/GitHub_Marketplace-FixMap-2ea44f?logo=github)](https://github.com/marketplace/actions/fixmap) [![MIT](https://img.shields.io/badge/license-MIT-74f0ba)](LICENSE) -[Website](https://usefixmap.vercel.app) · [Live demo](https://usefixmap.vercel.app/demo) · [Documentation](https://usefixmap.vercel.app/docs) · [Evidence](https://usefixmap.vercel.app/evidence) · [Changelog](CHANGELOG.md) +[Website](https://usefixmap.vercel.app) · [Use cases](https://usefixmap.vercel.app/use-cases) · [Live demo](https://usefixmap.vercel.app/demo) · [Documentation](https://usefixmap.vercel.app/docs) · [Evidence](https://usefixmap.vercel.app/evidence) · [Changelog](CHANGELOG.md) -[![FixMap v0.9.0: two coding agents work the same issue, with FixMap supplying ranked context, an Impact Graph, Watch feedback, and Verify evidence](docs/assets/fixmap-v0.9.0-agent-comparison.gif)](https://usefixmap.vercel.app/fixmap-launch.mp4) +[![FixMap workflow video opening frame: req.fresh returns false for QUERY requests, so 304 Not Modified is never set](apps/web/public/fixmap-launch-poster.jpg)](https://usefixmap.vercel.app/fixmap-launch.mp4) -

Watch the 32-second launch film with sound

+

Watch the 31-second FixMap workflow video with sound

+ +Try a task in the [homepage sample](https://usefixmap.vercel.app). It runs the real FixMap Plan engine in the tab against the bundled `sample-api` project. It does not inspect your repository or upload the task text. Use [Get started](https://usefixmap.vercel.app/get-started) for your own repository, or open the [full browser demo](https://usefixmap.vercel.app/demo) for advanced workflows. ![A generated FixMap CLI report showing ranked context files, test routes, risks, analysis, and diagnostics](docs/assets/fixmap-cli-demo.svg) @@ -172,7 +174,8 @@ Use `--working-tree` for staged and unstaged tracked edits, `--include-untracked - The MCP server exposes `fixmap_plan`, `fixmap_context`, `fixmap_graph`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor` over local stdio and is published in the official MCP Registry. - The GitHub Action runs Plan or Verify on pull requests, appends within the job summary's remaining 1 MiB budget, bounds its report output and comment, and creates or updates one FixMap comment instead of posting duplicates. - The Action accepts explicit task input or pull-request context, uses the same report validator as the CLI and MCP server, and fails clearly when a requested diff cannot be resolved. -- The browser demo runs the real core Plan, Explain, Compare, and Verify logic against a sample repository without uploading the task. +- The homepage task mapper runs real Plan logic against the bundled `sample-api` repository and preserves the engine's uncertainty state instead of inventing fallback results. +- The full browser demo runs the real core Plan, Explain, Compare, and Verify logic against the same sample repository without uploading the task. ### TypeScript library diff --git a/apps/web/.impeccable/design.json b/apps/web/.impeccable/design.json new file mode 100644 index 0000000..47d535f --- /dev/null +++ b/apps/web/.impeccable/design.json @@ -0,0 +1,243 @@ +{ + "schemaVersion": 2, + "generatedAt": "2026-08-20T20:23:55.4435764+05:30", + "title": "Design System: FixMap", + "extensions": { + "colorMeta": { + "paper": { + "role": "neutral", + "displayName": "Warm Paper", + "canonical": "#f7f4ec", + "tonalRamp": ["#0d1117", "#111821", "#161d26", "#405064", "#736e66", "#d9d3c6", "#eee9dc", "#fffdf8"] + }, + "ink": { + "role": "neutral", + "displayName": "Navy Ink", + "canonical": "#0a213b", + "tonalRamp": ["#071523", "#071d35", "#0a213b", "#405064", "#656e79", "#aab5bf", "#c4ced6", "#edf3f7"] + }, + "navy": { + "role": "secondary", + "displayName": "Evidence Navy", + "canonical": "#071d35", + "tonalRamp": ["#071523", "#071d35", "#0a213b", "#23394d", "#405064", "#74818c", "#aab5bf", "#edf3f7"] + }, + "green": { + "role": "primary", + "displayName": "Repository Green", + "canonical": "#0a5a43", + "tonalRamp": ["#04261d", "#074433", "#0a5a43", "#2f805d", "#589774", "#75c99a", "#9bddb7", "#dff2e7"] + }, + "mint": { + "role": "tertiary", + "displayName": "Signal Mint", + "canonical": "#75c99a", + "tonalRamp": ["#074433", "#0a5a43", "#2f805d", "#589774", "#75c99a", "#9bddb7", "#dff2e7", "#f0f3e8"] + }, + "line": { + "role": "neutral", + "displayName": "Rule", + "canonical": "#d9d3c6", + "tonalRamp": ["#161d26", "#394651", "#656e79", "#736e66", "#aab5bf", "#d9d3c6", "#eee9dc", "#fffdf8"] + }, + "warning": { + "role": "tertiary", + "displayName": "Review Amber", + "canonical": "#9b521b", + "tonalRamp": ["#2f1708", "#5b2d0d", "#794014", "#9b521b", "#bd7138", "#db9562", "#ffc184", "#ffe8d1"] + }, + "dark-paper": { + "role": "neutral", + "displayName": "Night Paper", + "canonical": "#0d1117", + "tonalRamp": ["#071523", "#0d1117", "#111821", "#161d26", "#394651", "#74818c", "#c4ced6", "#edf3f7"] + } + }, + "typographyMeta": { + "display": { + "displayName": "Display", + "purpose": "Plain-language homepage and subpage statements." + }, + "headline": { + "displayName": "Headline", + "purpose": "Section claims and featured use-case headings." + }, + "body": { + "displayName": "Body", + "purpose": "Explanations and supporting prose." + }, + "label": { + "displayName": "Evidence Label", + "purpose": "Compact capability, step, and proof labels." + }, + "technical": { + "displayName": "Technical Evidence", + "purpose": "Paths, commands, ranks, and report metadata." + } + }, + "shadows": [ + { + "name": "ambient-panel", + "value": "0 14px 38px rgba(10, 33, 59, 0.08)", + "purpose": "Dropdowns and established raised containers." + }, + { + "name": "live-report", + "value": "0 18px 50px rgba(10, 33, 59, 0.08)", + "purpose": "The homepage interactive sample report only." + }, + { + "name": "dark-ambient-panel", + "value": "0 20px 55px rgba(0, 0, 0, 0.36)", + "purpose": "Theme-equivalent lift on dark surfaces." + } + ], + "motion": [ + { + "name": "state-standard", + "value": "180ms ease", + "purpose": "Color and border changes on buttons, links, and compact controls." + }, + { + "name": "progress-reveal", + "value": "450ms cubic-bezier(0.2, 0.75, 0.25, 1)", + "purpose": "A short directional reveal for report progress only." + }, + { + "name": "reduced-motion", + "value": "0.01ms", + "purpose": "Near-instant fallback for animations and transitions when reduced motion is requested." + } + ], + "breakpoints": [ + { + "name": "phone", + "value": "620px" + }, + { + "name": "compact-editorial", + "value": "820px" + }, + { + "name": "mobile-navigation", + "value": "900px" + }, + { + "name": "stacked-feature", + "value": "1120px" + } + ] + }, + "components": [ + { + "name": "Primary Button", + "kind": "button", + "refersTo": "button-primary", + "description": "The single strongest action in a section.", + "html": "", + "css": ".ds-btn-primary { min-height: 44px; padding: 0 18px; border: 1px solid transparent; border-radius: 6px; background: var(--green); color: var(--paper-light); font: 620 14px/1 var(--font-body), Arial, sans-serif; cursor: pointer; transition: background 180ms ease, border-color 180ms ease; } .ds-btn-primary:hover { background: var(--green-dark); } .ds-btn-primary:active { background: var(--ink); } .ds-btn-primary:focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 3px; }" + }, + { + "name": "Secondary Button", + "kind": "button", + "refersTo": "button-secondary", + "description": "A bounded alternative action that remains visually subordinate.", + "html": "", + "css": ".ds-btn-secondary { min-height: 44px; padding: 0 18px; border: 1px solid var(--ink); border-radius: 6px; background: transparent; color: var(--ink); font: 620 14px/1 var(--font-body), Arial, sans-serif; cursor: pointer; transition: background 180ms ease, color 180ms ease; } .ds-btn-secondary:hover, .ds-btn-secondary:active { background: var(--ink); color: var(--paper-light); } .ds-btn-secondary:focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 3px; }" + }, + { + "name": "Task Input", + "kind": "input", + "refersTo": "task-input", + "description": "A readable task-description field for the interactive report.", + "html": "", + "css": ".ds-task-field { display: grid; gap: 6px; color: var(--ink-soft); font: 680 11px/1.4 var(--font-body), Arial, sans-serif; } .ds-task-field textarea { min-height: 82px; padding: 11px 12px; resize: vertical; border: 1px solid var(--line-strong); border-radius: 6px; background: var(--paper); color: var(--ink); font: 600 16px/1.38 var(--font-body), Arial, sans-serif; } .ds-task-field small { color: var(--ink-faint); font-size: 10.5px; font-weight: 400; } .ds-task-field textarea:focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 3px; border-color: var(--green); }" + }, + { + "name": "Preset Chip", + "kind": "chip", + "refersTo": "preset-chip", + "description": "A compact example-task selector with an explicit pressed state.", + "html": "", + "css": ".ds-preset-chip { min-height: 31px; padding: 5px 9px; border: 1px solid var(--line); border-radius: 5px; background: transparent; color: var(--ink-soft); font: 620 10.5px/1.3 var(--font-body), Arial, sans-serif; cursor: pointer; } .ds-preset-chip:hover, .ds-preset-chip[aria-pressed=\"true\"] { border-color: var(--green); background: var(--mint-soft); color: var(--green-dark); } .ds-preset-chip:focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 3px; }" + }, + { + "name": "Primary Navigation", + "kind": "nav", + "description": "Compact text navigation with green interaction states.", + "html": "", + "css": ".ds-nav { display: flex; align-items: center; gap: 26px; color: var(--ink); font: 560 13px/1.4 var(--font-body), Arial, sans-serif; } .ds-nav a { color: inherit; text-decoration: none; transition: color 180ms ease; } .ds-nav a:hover, .ds-nav a[aria-current=\"page\"] { color: var(--green); } .ds-nav a:focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 3px; }" + }, + { + "name": "Live Report", + "kind": "custom", + "description": "The signature task-to-evidence product preview.", + "html": "
Try FixMap on a sample project
3. FIXMAP SHOWSWhere to start
File to check first
src/auth/reset.tsDefines the task identifier.
Test to run
npm test -- reset
", + "css": ".ds-live-report { overflow: hidden; border: 1px solid var(--line-strong); border-radius: 10px; background: var(--paper-light); color: var(--ink); box-shadow: 0 18px 50px rgba(10, 33, 59, 0.08); font-family: var(--font-body), Arial, sans-serif; } .ds-live-report header, .ds-live-report footer { padding: 12px 16px; background: var(--paper-deep); color: var(--ink-faint); font-size: 11px; } .ds-live-report > div { padding: 24px 26px; } .ds-live-report > div > span { color: var(--green-dark); font: 650 10px/1.3 var(--font-mono), monospace; letter-spacing: 0.08em; } .ds-live-report strong { display: block; margin-top: 4px; font-size: 18px; } .ds-live-report dl { margin: 18px 0 0; border-top: 1px solid var(--line); } .ds-live-report dl > div { padding: 15px 0; display: grid; grid-template-columns: 124px 1fr; gap: 16px; border-bottom: 1px solid var(--line); } .ds-live-report dt { color: var(--green-dark); font-size: 12px; font-weight: 720; } .ds-live-report dd { margin: 0; } .ds-live-report code { color: var(--ink); font: 680 12.5px/1.4 var(--font-mono), monospace; } .ds-live-report small { display: block; margin-top: 3px; color: var(--ink-faint); font-size: 10.5px; } .ds-live-report:focus-within { outline: 3px solid var(--focus-ring); outline-offset: 3px; }" + }, + { + "name": "Use-Case Output Panel", + "kind": "custom", + "description": "A dark proof panel for genuine sample output.", + "html": "

Real output from the sample project

File to check first
src/auth/reset.ts
Test to run
npm test -- reset
This is genuine FixMap output.
", + "css": ".ds-use-case-output { padding: 28px 30px; border: 1px solid var(--line-strong); border-radius: 10px; background: var(--navy); color: var(--on-dark); font-family: var(--font-body), Arial, sans-serif; } .ds-use-case-output > p { margin: 0 0 18px; color: var(--mint); font-size: 13px; font-weight: 700; } .ds-use-case-output dl { margin: 0; border-top: 1px solid rgba(255, 255, 255, 0.2); } .ds-use-case-output dl > div { padding: 14px 0; display: grid; grid-template-columns: 180px 1fr; gap: 20px; border-bottom: 1px solid rgba(255, 255, 255, 0.15); } .ds-use-case-output dt { color: var(--mint); font-size: 12px; font-weight: 680; } .ds-use-case-output dd { margin: 0; } .ds-use-case-output code { color: var(--on-dark); font: 600 13px/1.45 var(--font-mono), monospace; } .ds-use-case-output small { display: block; margin-top: 17px; color: #adbac5; font-size: 11px; line-height: 1.5; }" + } + ], + "narrative": { + "northStar": "The Evidence Ledger", + "overview": "FixMap feels like a clear technical record, not an abstract AI promise. Warm paper surfaces, dark navy proof bands, disciplined rules, and compact report artifacts make the product approachable while keeping its repository-grounded character visible.\n\nThe visual system is restrained, legible, and evidence-first. Large plain-language headings establish the story; genuine files, tests, commands, and uncertainty appear in denser mono-set structures. Decoration stays subordinate to comprehension, and every expressive treatment should strengthen trust in what FixMap can actually show.", + "keyCharacteristics": [ + "Warm paper foundation with a navy-and-mint identity.", + "Editorial hierarchy paired with compact technical evidence.", + "Rules and tonal bands organize content more often than floating cards.", + "Real product output is the signature visual proof.", + "Light and dark themes preserve the same semantic roles and contrast hierarchy." + ], + "rules": [ + { + "name": "The Proof Band Rule", + "body": "Use navy as a deliberate evidence surface, not as a general decorative background.", + "section": "colors" + }, + { + "name": "The Mint Signal Rule", + "body": "Mint marks confirmed structure, progress, or action; it does not become a broad page wash.", + "section": "colors" + }, + { + "name": "The Two-Voice Rule", + "body": "Use Geist for the explanation and Geist Mono for the evidence; do not set long explanatory paragraphs in mono.", + "section": "typography" + }, + { + "name": "The Explanation-Then-Evidence Rule", + "body": "Lead with the plain-language claim, then place the denser report or proof beside it on wide screens and immediately after it on narrow screens.", + "section": "layout" + }, + { + "name": "The Flat-By-Default Rule", + "body": "A new section begins with rules, spacing, and tonal contrast; add shadow only when the surface is interactive, transient, or meaningfully raised.", + "section": "elevation" + }, + { + "name": "The Bounded Utility Rule", + "body": "Rounded shapes identify controls and discrete evidence surfaces; editorial rows remain mostly open and are separated by rules.", + "section": "shapes" + } + ], + "dos": [ + "Do explain the product in plain Geist copy before introducing compact mono-set evidence.", + "Do use genuine paths, tests, commands, and uncertainty as the primary visual proof.", + "Do use ruled editorial lists for repeated workflows and use cases.", + "Do preserve visible focus, reduced-motion behavior, semantic headings, and a no-overflow layout at a 390px viewport.", + "Do keep light and dark themes semantically aligned: paper, ink, green action, mint signal, and structural rules." + ], + "donts": [ + "Don't turn every section into a floating card or add shadow to static editorial content.", + "Don't use navy or mint as unbounded decoration; both colors carry specific proof and signal roles.", + "Don't present unmeasured outcomes, invented customers, or generic AI imagery as product evidence.", + "Don't let technical vocabulary or mono typography precede the plain-language explanation on first-contact surfaces.", + "Don't replace honest empty or uncertain states with fabricated confident output." + ] + } +} diff --git a/apps/web/DESIGN.md b/apps/web/DESIGN.md new file mode 100644 index 0000000..70eea64 --- /dev/null +++ b/apps/web/DESIGN.md @@ -0,0 +1,271 @@ +--- +version: alpha +name: FixMap +description: An evidence-led product interface that helps developers and AI coding tools see where to start. +colors: + paper: "#f7f4ec" + paper-deep: "#eee9dc" + paper-light: "#fffdf8" + on-dark: "#fffdf8" + ink: "#0a213b" + ink-soft: "#405064" + ink-faint: "#656e79" + navy: "#071d35" + green: "#0a5a43" + green-dark: "#074433" + mint: "#75c99a" + mint-soft: "#dff2e7" + line: "#d9d3c6" + line-strong: "#736e66" + focus-ring: "#589774" + warning: "#9b521b" + dark-paper: "#0d1117" + dark-paper-deep: "#111821" + dark-paper-light: "#161d26" + dark-on-dark: "#edf3f7" + dark-ink-soft: "#c4ced6" + dark-ink-faint: "#aab5bf" + dark-navy: "#071523" + dark-green: "#75c99a" + dark-green-emphasis: "#9bddb7" + dark-mint-soft: "#203b31" + dark-line: "#394651" + dark-line-strong: "#74818c" + dark-focus-ring: "#8ddfb0" + dark-warning: "#ffc184" +typography: + display: + fontFamily: "Geist, Arial, sans-serif" + fontSize: "76px" + fontWeight: 660 + lineHeight: 0.98 + letterSpacing: "-0.04em" + headline: + fontFamily: "Geist, Arial, sans-serif" + fontSize: "54px" + fontWeight: 640 + lineHeight: 1.03 + letterSpacing: "-0.045em" + title: + fontFamily: "Geist, Arial, sans-serif" + fontSize: "21px" + fontWeight: 600 + lineHeight: 1.25 + letterSpacing: "-0.02em" + body: + fontFamily: "Geist, Arial, sans-serif" + fontSize: "16px" + fontWeight: 400 + lineHeight: 1.55 + lede: + fontFamily: "Geist, Arial, sans-serif" + fontSize: "19px" + fontWeight: 400 + lineHeight: 1.55 + label: + fontFamily: "Geist Mono, monospace" + fontSize: "12px" + fontWeight: 700 + lineHeight: 1 + letterSpacing: "0.08em" + technical: + fontFamily: "Geist Mono, monospace" + fontSize: "12px" + fontWeight: 600 + lineHeight: 1.45 +rounded: + chip: "5px" + control: "6px" + standard: "8px" + panel: "10px" + full: "999px" +spacing: + micro: "6px" + compact: "12px" + control: "18px" + card: "24px" + desktop-gutter: "32px" + tablet-gutter: "20px" + mobile-gutter: "14px" + section: "88px" + section-roomy: "96px" +components: + button-primary: + backgroundColor: "{colors.green}" + textColor: "{colors.paper-light}" + rounded: "{rounded.control}" + padding: "0 18px" + height: "44px" + button-primary-hover: + backgroundColor: "{colors.green-dark}" + textColor: "{colors.paper-light}" + button-secondary: + backgroundColor: "transparent" + textColor: "{colors.ink}" + rounded: "{rounded.control}" + padding: "0 18px" + height: "44px" + task-input: + backgroundColor: "{colors.paper}" + textColor: "{colors.ink}" + rounded: "{rounded.control}" + padding: "11px 12px" + preset-chip: + backgroundColor: "transparent" + textColor: "{colors.ink-soft}" + rounded: "{rounded.chip}" + padding: "5px 9px" +--- + +# Design System: FixMap + +## Overview + +**Creative North Star: "The Evidence Ledger"** + +FixMap feels like a clear technical record, not an abstract AI promise. Warm paper surfaces, dark navy proof bands, disciplined rules, and compact report artifacts make the product approachable while keeping its repository-grounded character visible. + +The visual system is restrained, legible, and evidence-first. Large plain-language headings establish the story; genuine files, tests, commands, and uncertainty appear in denser mono-set structures. Decoration stays subordinate to comprehension, and every expressive treatment should strengthen trust in what FixMap can actually show. + +**Key Characteristics:** + +- Warm paper foundation with a navy-and-mint identity. +- Editorial hierarchy paired with compact technical evidence. +- Rules and tonal bands organize content more often than floating cards. +- Real product output is the signature visual proof. +- Light and dark themes preserve the same semantic roles and contrast hierarchy. + +## Colors + +The palette combines warm archival neutrals with deep technical navy and a restrained green-to-mint accent family. + +### Primary + +- **Repository Green** (`#0a5a43`): Primary actions, meaningful icons, active states, and evidence labels. +- **Deep Repository Green** (`#074433`): Hover states, text links, and small labels that need stronger contrast on paper. + +### Secondary + +- **Evidence Navy** (`#071d35`): Dark proof bands, code surfaces, and the use-case output panel. +- **Signal Mint** (`#75c99a`): Positive emphasis, selected text, dark-surface labels, and connective marks. + +### Neutral + +- **Warm Paper** (`#f7f4ec`): Default page background. +- **Inset Paper** (`#eee9dc`): Toolbars and restrained tonal separation. +- **Clean Paper** (`#fffdf8`): Raised or bounded content surfaces and text on dark backgrounds. +- **Navy Ink** (`#0a213b`): Primary text and the strongest secondary-button border. +- **Slate Ink** (`#405064`): Supporting copy and technical descriptions. +- **Quiet Slate** (`#656e79`): Metadata, helper text, and trust facts. +- **Rule** (`#d9d3c6`) and **Strong Rule** (`#736e66`): Structural dividers and bounded controls. + +Dark mode remaps the same roles to near-black paper (`#0d1117`), deep raised surfaces (`#161d26`), cool white text (`#edf3f7`), mint-led actions (`#75c99a`), and stronger slate rules (`#394651` / `#74818c`). It is a semantic inversion, not a separate visual identity. + +**The Proof Band Rule.** Use navy as a deliberate evidence surface, not as a general decorative background. + +**The Mint Signal Rule.** Mint marks confirmed structure, progress, or action; it does not become a broad page wash. + +## Typography + +**Display Font:** Geist (with Arial and sans-serif fallbacks) +**Body Font:** Geist (with Arial and sans-serif fallbacks) +**Label/Mono Font:** Geist Mono (with monospace fallback) + +**Character:** Geist keeps public explanations contemporary and plain-spoken. Geist Mono distinguishes paths, commands, indices, labels, and engine evidence without turning the whole site into a developer console. + +### Hierarchy + +- **Display** (weight `660`, up to `76px`, line-height `0.98`): Homepage and major subpage statements; responsive sizing may step down to `45–50px` on small screens. +- **Headline** (weight `640`, up to `54px`, line-height `1.03`): Section claims and featured use-case headings. +- **Title** (weight around `600`, `21px`, line-height `1.25`): Card, workflow, and use-case titles. +- **Body** (weight `400`, `16px`, line-height `1.55`): Explanations and supporting prose. Important ledes use `19px` with the same open line height. +- **Label** (weight `700`, `12px`, `0.08em` tracking, uppercase when naming evidence roles): Compact capability, step, and proof labels. +- **Technical** (weight around `600`, typically `10.5–12.5px`, line-height near `1.45`): Paths, commands, ranks, and report metadata. + +**The Two-Voice Rule.** Use Geist for the explanation and Geist Mono for the evidence; do not set long explanatory paragraphs in mono. + +## Layout + +The site uses a fixed-max-width fluid shell (`1240px`) with `32px` desktop side gutters, `20px` tablet gutters below `900px`, and `14px` phone gutters below `620px`. Major sections breathe vertically at roughly `88–96px`; internal report and card spacing is tighter, usually `12–24px`. + +Desktop compositions often pair a shorter explanatory column with a larger evidence or list column. At `1120px`, hero and featured use-case pairs stack. At `820px`, editorial two-column sections and use-case rows simplify. At `620px`, controls and calls to action become full width, report definitions collapse to one column, and all content must wrap without horizontal overflow. + +Long lists favor ruled rows and aligned columns over repeated floating cards. A row's index, story, and result create the reading order; on small screens they become one linear narrative. + +**The Explanation-Then-Evidence Rule.** Lead with the plain-language claim, then place the denser report or proof beside it on wide screens and immediately after it on narrow screens. + +## Elevation & Depth + +The system is flat by default. Borders, dark bands, paper tones, and whitespace create most hierarchy. Shadows are reserved for overlays and the primary live report artifact, where a shallow ambient lift distinguishes an interactive product surface from editorial content. + +### Shadow Vocabulary + +- **Ambient Panel** (`0 14px 38px rgba(10, 33, 59, 0.08)`): Dropdowns and established raised containers. +- **Live Report** (`0 18px 50px rgba(10, 33, 59, 0.08)`): The homepage's interactive sample report only. +- **Dark Ambient Panel** (`0 20px 55px rgba(0, 0, 0, 0.36)`): Theme-equivalent lift on dark surfaces. + +**The Flat-By-Default Rule.** A new section begins with rules, spacing, and tonal contrast; add shadow only when the surface is interactive, transient, or meaningfully raised. + +## Shapes + +Corners are gently engineered rather than bubbly. Compact controls and buttons use `5–6px` radii; ordinary cards and media use `8px`; report and proof panels use `10px`. Pills and circles are reserved for state, status, or numbered steps. Thin borders are structural and recur more often than filled containers. + +**The Bounded Utility Rule.** Rounded shapes identify controls and discrete evidence surfaces; editorial rows remain mostly open and are separated by rules. + +## Components + +### Buttons + +- **Shape:** Compact and rectangular with gently curved corners (`6px`) and a minimum height of `44px`. +- **Primary:** Repository Green on Clean Paper text, with horizontal padding of `18px`. +- **Hover / Focus:** Deepen to Deep Repository Green. Keep the global visible three-pixel focus outline and do not rely on movement alone. +- **Secondary:** Transparent paper surface with Navy Ink text and border; invert to Navy Ink on hover. On phone layouts, calls to action span the available width. + +### Chips + +- **Style:** Small transparent preset controls with a fine Rule border, `5px` corners, compact padding, and Slate Ink labels. +- **State:** Hover and selected states use Mint Soft with Repository Green borders and Deep Repository Green text. Selection remains explicit through `aria-pressed`. + +### Cards / Containers + +- **Corner Style:** Ordinary bounded surfaces use `8px`; report and proof panels use `10px`. +- **Background:** Clean Paper for bounded content, Warm Paper for inset areas, and Evidence Navy for proof panels. +- **Shadow Strategy:** Flat at rest except for the live report and transient navigation overlays. +- **Border:** One-pixel Rule or Strong Rule borders carry most separation. +- **Internal Padding:** Usually `24px`; compact report rows use approximately `12–16px`. + +### Inputs / Fields + +- **Style:** Warm Paper fill, Strong Rule border, `6px` radius, `11px 12px` padding, and a readable `16px` input size. +- **Focus:** Preserve the global three-pixel visible focus ring with offset. Interactive variants may also shift the border to Repository Green. +- **Error / Disabled:** Use explicit warning copy and the Warning token; do not communicate uncertainty by color alone. + +### Navigation + +The header is sticky, compact, and lightly translucent over the page. Desktop links use small Geist text with green hover/open states. Below `900px`, a bordered `44px` menu control opens a Clean Paper panel; every mobile navigation target is at least `44px` tall. The theme toggle remains a separately bounded control. + +### Live Report + +The homepage report is the canonical product-preview component. It follows a visible sequence—task input, repository check, evidence output—and uses a tonal toolbar, compact labels, ruled definition rows, mono-set paths, plain-language reasons, and an explicit uncertainty state. Preserve its privacy footnote and do not restyle it as a generic analytics dashboard. + +### Use-Case Output Panel + +The featured use case presents genuine sample output on Evidence Navy. Mint labels name the evidence roles, Clean Paper carries the values, and thin translucent rules separate rows. The panel stacks each label above its value on phones to keep long paths readable. + +## Do's and Don'ts + +### Do: + +- **Do** explain the product in plain Geist copy before introducing compact mono-set evidence. +- **Do** use genuine paths, tests, commands, and uncertainty as the primary visual proof. +- **Do** use ruled editorial lists for repeated workflows and use cases. +- **Do** preserve visible focus, reduced-motion behavior, semantic headings, and a no-overflow layout at a `390px` viewport. +- **Do** keep light and dark themes semantically aligned: paper, ink, green action, mint signal, and structural rules. + +### Don't: + +- **Don't** turn every section into a floating card or add shadow to static editorial content. +- **Don't** use navy or mint as unbounded decoration; both colors carry specific proof and signal roles. +- **Don't** present unmeasured outcomes, invented customers, or generic AI imagery as product evidence. +- **Don't** let technical vocabulary or mono typography precede the plain-language explanation on first-contact surfaces. +- **Don't** replace honest empty or uncertain states with fabricated confident output. diff --git a/apps/web/PRODUCT.md b/apps/web/PRODUCT.md new file mode 100644 index 0000000..c835550 --- /dev/null +++ b/apps/web/PRODUCT.md @@ -0,0 +1,51 @@ +# Product + + + +## Platform + +web + +## Users + +The primary user is an individual developer who works with AI coding tools such as Codex, Claude Code, Cursor, or GitHub Copilot. First-time website visitors may not know terms such as repository context, impact graph, or coding agent, so public pages must explain the product without requiring that vocabulary. + +## Product Purpose + +FixMap checks a software task and a code project together. It gives people and AI coding tools a short, evidence-backed starting list: files to inspect, tests or checks to run, nearby code to review, risks, and explicit uncertainty. Success means a visitor can understand that mechanism within seconds and can choose to try a sample or install FixMap for a real project. + +## Positioning + +FixMap is deterministic and repository-grounded. It uses project paths, symbols, imports, related tests, and bounded Git history rather than a hosted model. It shows why it surfaced an item and declines unsupported certainty. + +## Operating Context + +FixMap can run in a terminal, inside supported AI coding tools through `/fixmap`, over local stdio through MCP, in GitHub Actions, and in a browser against the bundled sample project. Plan is used before an edit; Explain, Compare, Verify, Watch, Context, Graph, and Benchmark support later investigation and review workflows. + +## Capabilities and Constraints + +- The homepage and browser demo run against the bundled `sample-api` project; they do not inspect a visitor's repository or upload task text. +- Public copy may describe files to inspect, tests to run, related code, risks, and uncertainty. It must not describe pre-edit suggestions as files that were changed. +- Token, cost, time, tool-call, and task-success improvements have not been measured and must not be claimed. +- Use cases may explain genuine product mechanisms but must not invent customers, testimonials, success rates, or guaranteed outcomes. +- FixMap runs without an account, API key, or model call. + +## Brand Commitments + +Keep the FixMap name, logo, existing navy-and-mint identity, and direct evidence-led tone. Public-facing copy should use plain language, short sentences, and familiar examples. Prefer “AI coding tool” over unexplained insider terms on first-contact surfaces. + +## Evidence on Hand + +The repository contains checked-in baseline, held-out, adversarial, and performance records, plus a real browser demo and a 31-second workflow video. Repository retrieval has measured results. No completed controlled-agent runs, customer testimonials, or downstream-efficiency evidence exist. + +## Product Principles + +- Explain the product before asking visitors to learn its vocabulary. +- Show genuine engine output and honest uncertainty. +- Make the next action obvious: try a sample or use FixMap on a project. +- Keep evidence and unmeasured outcomes clearly separated. +- Preserve advanced detail for people who ask for it. + +## Accessibility & Inclusion + +Public pages must remain keyboard accessible, use semantic headings and links, preserve visible focus, support reduced motion, and avoid horizontal overflow at a 390px viewport. Copy should be understandable without specialist repository-analysis knowledge. diff --git a/apps/web/app/_components/interactive-map-stage.tsx b/apps/web/app/_components/interactive-map-stage.tsx index c04c07d..1b9734b 100644 --- a/apps/web/app/_components/interactive-map-stage.tsx +++ b/apps/web/app/_components/interactive-map-stage.tsx @@ -1,3 +1,8 @@ +"use client"; + +import Link from "next/link"; +import { useMemo, useState } from "react"; +import type { FormEvent } from "react"; import { ArrowRight, CheckCircle, @@ -5,83 +10,169 @@ import { GitBranch, ShieldCheck, Warning -} from "@phosphor-icons/react/ssr"; -import { buildReportFromRepo } from "@aryam/fixmap-core/browser"; -import { sampleRepo } from "../sample-repo"; - -const task = "TOKEN_TTL_MINUTES is ignored and reset links expire immediately."; -const command = `fixmap plan --issue "${task}" --format agent`; -const report = buildReportFromRepo(sampleRepo, { issueText: task, limit: 3 }); - -function homepageExample() { - const editCandidate = report.contextFiles[0]; - const impactFile = (report.impact?.files ?? []).find((file) => !file.path.includes("test/")); - const testRoute = report.testRoutes[0]; - const risk = report.risks[0]; - - if (!editCandidate || !impactFile || !testRoute || !risk) { - throw new Error("The homepage example no longer contains the file, test, impact, and risk evidence it is designed to explain."); - } +} from "@phosphor-icons/react"; +import { quoteCliValue } from "@aryam/fixmap-core/browser"; +import { + buildHomepageReport, + homepageDefaultReport, + homepageDefaultTask, + homepagePresets, + selectHomepageEvidence +} from "../_lib/homepage-demo"; - return { editCandidate, impactFile, testRoute, risk }; +function candidateReason(reasons: string[]): string | undefined { + return ( + reasons.find((reason) => reason.startsWith("defines task identifiers")) ?? + reasons[0] + ); } -const { editCandidate, impactFile, testRoute, risk } = homepageExample(); +export function InteractiveMapStage() { + const [draftTask, setDraftTask] = useState(homepageDefaultTask); + const [submittedTask, setSubmittedTask] = useState(homepageDefaultTask); + const [runCount, setRunCount] = useState(0); + const report = useMemo( + () => submittedTask === homepageDefaultTask ? homepageDefaultReport : buildHomepageReport(submittedTask), + [submittedTask] + ); + const { editCandidate, impactFile, testRoute, risk, diagnostic } = useMemo( + () => selectHomepageEvidence(report), + [report] + ); + const command = `fixmap plan --issue ${quoteCliValue(submittedTask, "posix")} --format agent`; + const editCandidateReason = editCandidate ? candidateReason(editCandidate.reasons) : undefined; + const impactReason = impactFile?.evidence[0]?.reason; + const status = runCount === 0 + ? "" + : editCandidate + ? `FixMap run ${runCount} complete. ${report.contextFiles.length} file candidates surfaced. First candidate: ${editCandidate.path}.` + : `FixMap run ${runCount} complete. No grounded file candidates surfaced.`; -const candidateReason = - editCandidate.reasons.find((reason) => reason.startsWith("defines task identifiers")) ?? - editCandidate.reasons[0] ?? "ranked repository evidence"; -const impactReason = impactFile.evidence[0]?.reason ?? "related repository evidence"; + function runFixMap(event: FormEvent) { + event.preventDefault(); + setSubmittedTask(draftTask.trim()); + setRunCount((count) => count + 1); + } -export function InteractiveMapStage() { return (
- Real FixMap output - sample-api · local checkout + Try FixMap on a sample project + Runs in this tab
- You provide - Your coding task -
{task}
-
Repository sample-api
- {command} + 1. Tell FixMap + What is broken? + +
+ +