# sw-prototypes — Claude Guide

This repo holds **static HTML/CSS/JS prototypes** and the **design style guide** for SmallWorld. It is intentionally not a build-tooled app — pages should open directly in a browser.

## What lives here

- `styleguide/` — canonical visual reference (HTML rendered + Markdown spec). The HTML is the source of truth for visual review; the Markdown captures rationale and tokens in human-readable form.
- `prototypes/<feature>/` — one folder per feature exploration. Multi-page prototypes have a sibling `shared/` directory with CSS, JS, and fixture data.

## What this repo is for

Rapid design exploration: laying out a screen, trying an interaction, or pinning down visual hierarchy *before* writing React. Prototypes are throwaway-grade in code quality but production-grade in visual fidelity — they are reviewed by stakeholders and used as the spec for the real implementation.

## Hosting

Deployed via **Cloudflare Pages** — `main` auto-deploys, PRs get preview deployments. No build step (vanilla static). Access is gated by Cloudflare Access (Zero Trust), and `_headers` sets `X-Robots-Tag: noindex` as defense-in-depth.

## What this repo is NOT for

- Production code. Nothing here ships. Do not import from this repo into the SmallWorld Rails/React app.
- Real data. Use fixtures in `shared/<feature>-data.js` for multi-page flows.
- Build tooling. No bundlers, no transpilers, no package.json unless absolutely necessary. Vanilla HTML/CSS/JS.

## Conventions

- **Visual fidelity matches the production app.** Use Montserrat as the font, the brand blue `#3f84e5`, and the patterns in `styleguide/style-guide.html`.
- **Multi-page flows use a `shared/` directory** for CSS/JS so each page can `<link>`/`<script>` to the same files. Don't duplicate styles per page.
- **Fixture data** for multi-page prototypes goes in `shared/<feature>-data.js` so we can edit one file and all pages reflect it.
- **Single-page prototypes** can keep all their CSS inline in `<style>` and all their JS inline in `<script>` — no shared dir needed.
- **Naming.** Files are `kebab-case.html`. Feature directories are `kebab-case/`.
- **Cross-page links** in multi-page prototypes use relative paths so the bundle is portable.
- **Versioned projects** (any project with more than one version) live under `prototypes/<feature>/v1/`, `v2/`, `v3/` … with the version qualifier dropped from filenames inside each version folder (e.g. `v1/dashboard.html`, not `v1/dashboard-v1.html`).

## Index page: versioned projects

When a project has more than one version, it MUST be rendered on `index.html` using the `.project` + `.version-track` pattern (see the **Connector Dashboard** section). The pattern:

- Wrap all of a project's versions in a single `<div class="project">` so the project reads as one unit.
- Each version is a `<div class="version-track">` with two children:
  - `<div class="version-label">` containing `<div class="version-num">v1</div>` and `<div class="version-desc">Stage</div>` (e.g. *Initial pass*, *Refinement*, *Build basis*).
  - `<div class="version-cards">` with the version's individual page cards.
- Card eyebrows describe the *page* (e.g. "Chrome + Target Companies", "Your Network tab"), not the version — the version is already conveyed by the track label.
- Use the existing CSS already defined in `index.html` — don't redefine the tokens per project.

Single-version projects continue to use the simple `<section>` + `<div class="grid">` of cards pattern.

## Working with prototypes

- Open a single file directly: `open prototypes/deal-team/deal-team.html`
- Serve the multi-page flows: `python3 -m http.server 8000` from repo root, then navigate to e.g. `http://localhost:8000/prototypes/settings/index.html`
- Use Chrome DevTools MCP for screenshotting / interaction testing if available.

## Editing the style guide

The style guide is the reference for the production app's visual language. If you change a token (color, spacing, font weight) here, the implication is that the React side should also change — flag this explicitly to the user. Don't silently drift.

## When the user asks to "build a prototype for X"

1. Decide single-page vs. multi-page based on scope. A list-and-detail flow is multi-page; a single screen is single-page.
2. Create `prototypes/<feature>/` (and `shared/` if multi-page).
3. Reference the style guide for visual decisions — don't invent tokens.
4. Use realistic but fake data. SmallWorld is a warm-intro platform; prospect/connector/requester roles are the core entities. See the SmallWorld Rails repo's `CLAUDE.md` for domain context.

## Future improvements (not yet built)

### Per-version frontmatter (`_meta.yml`)

Once the repo has enough volume that hand-curating `index.html` becomes friction, add a `_meta.yml` at the base of each version folder and **generate** the index from those files instead of editing it by hand. Sketch:

```yaml
# prototypes/<feature>/v2/_meta.yml
title: Dashboard v2
stage: refinement              # initial-pass | refinement | build-basis | shipped | archived
date: 2026-03-15
designer: Cameron
status: superseded             # current | superseded | shipped | archived
linked_pr: SmallWorld-io/small-world#3411
linked_ticket: SW-2163
notes: |
  Multi-line free-form notes about what changed and why.
pages:
  - { file: dashboard.html, label: Chrome + Target Companies }
  - { file: network.html,   label: Your Network tab }
```

Payoff:
- Adding a version becomes "drop a folder + `_meta.yml`," no `index.html` edits.
- Metadata becomes Claude-readable context for "what was the thinking behind v2?" questions.
- Designers/PMs get a queryable history without spelunking commits.

Trigger to actually build it: when there are 3+ versioned projects OR someone asks "who designed v2 of X?" and the answer requires `git blame`.