mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-18 13:01:18 -08:00
Add the UI Prototype skill, and have Quick Task confirm a saved prototype's brief before planning
AI Assisted
This commit is contained in:
1 parent
2f790027a9
commit
54b316cdf3
130 files changed
+8065
-50
No files matched your search
@@ -316,7 +316,7 @@ Every other plan2code step forbids writing code during planning. **Pathfinder is
|
||||
**All three gates must open before you write a line of code:**
|
||||
|
||||
1. The paper sketch was tried and did not settle it. Not skipped — tried. Say what the paper sketch failed to resolve.
|
||||
2. There is an obvious way to run it in this project — an existing runtime and task runner. Do not add a package manager, language, or framework for a sketch.
|
||||
2. There is an obvious way to run it in this project — an existing runtime and task runner. Do not add a package manager, language, or framework for a sketch. (Logic sketches only: a UI prototype runs on this skill's own scripts, so only gates 1 and 3 apply to it.)
|
||||
3. The user says go. Ask explicitly: *"Paper didn't settle row 5. I can build a throwaway terminal app under `specs/audit-export/pathfinder/sketch-01/` that lets you drive the state machine by hand — about 60 lines, one command, deleted after. Go?"*
|
||||
|
||||
Any gate that stays shut: stay on paper, or convert the question to a `grill`.
|
||||
@@ -324,11 +324,11 @@ Any gate that stays shut: stay on paper, or convert the question to a `grill`.
|
||||
#### Rules for a runnable sketch
|
||||
|
||||
1. **Throwaway from day one, and clearly marked.** Its README's first line is the banner, and its second says what question it exists to answer.
|
||||
2. **It lives ONLY at `specs/<idea>/pathfinder/sketch-NN/`** — never in the project's own source tree, never beside the module it is sketching for. This is where pathfinder deliberately departs from upstream: upstream co-locates prototypes with the real code; pathfinder quarantines them, because `specs/` is gitignored scratch and the project tree is not.
|
||||
2. **It lives ONLY at `specs/<idea>/pathfinder/sketch-NN/`** (logic sketches only; a UI prototype keeps its drafts outside the project and saves into `specs/<idea>/prototypes/`) — never in the project's own source tree, never beside the module it is sketching for. This is where pathfinder deliberately departs from upstream: upstream co-locates prototypes with the real code; pathfinder quarantines them, because `specs/` is gitignored scratch and the project tree is not.
|
||||
3. **One command to run.** Print the exact command to the user. They must not have to remember a path or a flag. If the project has a task runner, use the runner's own idiom, but keep the entry point inside `sketch-NN/`.
|
||||
4. **No persistence.** State lives in memory. Persistence is what the sketch is checking, not something it leans on. If the question is specifically about storage, use a local file named so its disposability is obvious.
|
||||
5. **Skip all polish.** No tests, no error handling beyond what makes it run, no abstractions, no "we might want X later."
|
||||
6. **Surface the full relevant state after every action** (logic) **or on every variant switch** (UI). The user must see the whole picture change, not a delta.
|
||||
6. **Surface the full relevant state after every action.** The user must see the whole picture change, not a delta.
|
||||
7. **Never merged.** The sketch is not lifted into the project. Only the validated decision it produced survives, in the `## Answer`. Reference the sketch directory from `## Evidence` so a later reader can re-run it, but the code is scaffolding, not output.
|
||||
|
||||
#### Pick the branch: logic or UI
|
||||
@@ -336,13 +336,13 @@ Any gate that stays shut: stay on paper, or convert the question to a `grill`.
|
||||
| Question shape | Branch | Artifact |
|
||||
|---|---|---|
|
||||
| "Does this state model / data model / rule hold?" | **Logic** | One tiny interactive terminal app |
|
||||
| "What should this look like?" | **UI** | Several radically different variations, switchable |
|
||||
| "What should this look like?" | **UI** | UI prototype |
|
||||
|
||||
Getting this wrong wastes the entire sketch. If the question is genuinely ambiguous and the user is unreachable, default by what the question touches — a backend module or a rules engine points to logic, a page or component points to UI — and **state the assumption in the first lines of the sketch's README**, so the human can reject the framing before reading the code.
|
||||
Getting this wrong wastes the entire sketch. If the question is genuinely ambiguous and the user is unreachable, default by what the question touches — a backend module or a rules engine points to logic, a page or component points to UI — and **state the assumption in the first lines of the sketch's README** (for a UI prototype, in the line that offers it), so the human can reject the framing before reading the code.
|
||||
|
||||
**Logic branch.** Build the smallest interactive terminal app that pushes the machine through the cases that are hard to reason about on paper. Keep the logic itself pure — a reducer, a state machine, or a small set of pure functions over a plain data type — with the terminal shell as a thin wrapper that imports it and never the reverse. Each frame: clear the screen, print the whole current state one field per line, then print the key legend, e.g. `[f] flag [c] clear [e] escalate [h] hold [t] advance clock 1d [q] quit`. Re-render the entire frame after every keystroke; never append to scrollback. The whole frame fits on one screen. The interesting moment is the user saying "wait, that shouldn't have been possible" — that is a bug in the *idea*, which is the entire point. Add actions on request; sketches evolve.
|
||||
|
||||
**UI branch.** Generate **several radically different variations side by side, switchable** — not one polished take. Default to 3, cap at 5. They must disagree about structure: different layout, different information hierarchy, different primary affordance. Three tweaked card grids is wallpaper, not a sketch. If two drafts come out similar, redo one with an explicit constraint against the shape they share. Switch by a URL search param plus a small floating bar (previous / current variant name / next), following whatever routing convention the project already uses — but with the files under `sketch-NN/`. Wire variants to stubbed data, never to real mutations; the question is what it should look like, not whether the backend works. The most valuable feedback is usually "I want the header from B with the list from C" — that hybrid IS the answer, and it goes in the `## Answer`.
|
||||
**UI branch.** Offer a UI prototype instead of building a sketch. On a yes, open `references/ui-prototype.md` and follow it from its Step 1, with the question's own wording as the request. Each round drawn posts the `ui-prototype-round` meter event. On a yes to saving, the pair goes straight into `specs/<idea>/prototypes/`; you only propose the name. Record the outcome in the question file being answered: the choices from the block in its `## Answer`, a link to the saved pair (`prototypes/<name>.md` and `prototypes/<name>.html`) in its `## Evidence`. The most valuable feedback is usually "I want the header from B with the list from C": that hybrid IS the answer.
|
||||
|
||||
#### After a runnable sketch
|
||||
|
||||
|
||||
@@ -44,6 +44,7 @@ Load `./AGENTS.md` if it exists — its conventions govern; never re-ask what it
|
||||
- **HITL questions are never self-answered.** Ask and wait; an agent that answers its own grill has broken the skill.
|
||||
- **Questions are ground truth; the map is a rebuildable index.** A filled `## Answer` beats any state marker; detail lives in one place.
|
||||
- **Never write implementation code** into the project. Sketches are throwaway, living only under `pathfinder/sketch-NN/`.
|
||||
- A question about how a screen looks or flows that paper did not settle: offer a UI prototype (`references/ui-prototype.md`, run in this conversation). Nothing is built without a yes; it stays a draft outside the project unless saved.
|
||||
- **Reserved names — never create inside `pathfinder/`:** `overview.md`, `phase-<N>.md`, `PLAN-DRAFT-*.md`, `PLAN-CONVERSATION-*.md`.
|
||||
- **Never emit completion tokens under `specs/`** — `TASK_COMPLETE`, `PHASE_COMPLETE`, `ALL_TASKS_COMPLETE`, `IMPLEMENTATION_COMPLETE`, `SPEC_COMPLETE`, `WORK_COMPLETE`. They are reserved; a stray one would read as a finished run.
|
||||
- **No `- [ ]` checkboxes inside question files**, and no `METRICS_JSON` anywhere.
|
||||
|
||||
@@ -63,6 +63,7 @@ Before Phase 1, run `node "<S>/specs.mjs" list` from the project root (`<S>`: `s
|
||||
- Status "Draft" or "Complete": Ask user how to proceed
|
||||
- Before going on with any existing draft (a Pathfinder handoff, a Quick Task escalation, a Draft or Complete one), read its 2.4: `| Status | Deferred to Plan |`, empty or `Not discussed` means ask the Phase 1 testing question now and write the answer into 2.4; a cadence with no `Full Suite` row means ask only the full-suite part.
|
||||
- A spec folder holding a `DIAGNOSIS-*.md` (Diagnose's write-up of a bug): read it first, as the Phase 1 brief (the bug, its cause, the suggested fix); that folder's name is the feature name (do not ask for one), so the PLAN-DRAFT lands beside the diagnosis
|
||||
- A spec folder holding `prototypes/*.md` has saved prototype choices: read each as a reference to build from
|
||||
- No PLAN-DRAFT: Begin at Phase 1. Console: its idea card carries `"templates": "idea"` (console.md → A patch)
|
||||
|
||||
`node "<S>/specs.mjs" check-draft specs/<feature-name>` checks a written PLAN-DRAFT (Phase 7).
|
||||
@@ -102,6 +103,8 @@ Report each sub-score with overall percentage.
|
||||
2. Reference materials? (designs, mockups, API specs)
|
||||
3. External systems/APIs to integrate?
|
||||
|
||||
When a requirement or an architecture choice turns on how a screen looks or flows, offer a UI prototype (`references/ui-prototype.md`, run in this conversation): nothing is built without a yes, and a yes to saving puts `prototypes/<name>.html` and `<name>.md` in this spec (no spec folder yet: ask the kebab-case feature name then, and keep it for the checkpoint and Phase 7).
|
||||
|
||||
After confirmation, proceed with analysis:
|
||||
|
||||
1. Read all provided information; research the domain for standards and unstated needs
|
||||
@@ -259,7 +262,7 @@ File: `specs/<feature-name>/PLAN-DRAFT-<YYYYMMDD>.md`
|
||||
Header: Title, Created date, Status (Draft | Phase 3 Complete - Resume at Phase 4 | Complete), Confidence % (Reqs/Feasibility/Integration/Risk each /25), link to PLAN-CONVERSATION.
|
||||
|
||||
Sections:
|
||||
1. **Executive Summary** — 2-3 sentences
|
||||
1. **Executive Summary** — 2-3 sentences, then a **Prototypes** line naming each saved `prototypes/<name>.md` as a reference to build from (only when there are any)
|
||||
2. **Requirements** — 2.1 Functional (FR-N checklist), 2.2 Non-Functional (NFR-N checklist), 2.3 Out of Scope, 2.4 Testing Strategy table (Types, Phase Testing, Full Suite, Coverage, plus a `| Approach | Test first |` row only when picked; absent means code first). Phase Testing is `Targeted per phase`, `Dedicated phase only` or `None` (an old `Run after each phase` reads as `Targeted per phase`; 'skip testing' writes `None` and `Never`); Full Suite is `Offered at Finalize`, `At Phase N` or `Never`
|
||||
3. **Tech Stack** — table: Category / Technology / Version / Justification
|
||||
4. **Architecture** — 4.1 Pattern (name + rationale), 4.2 System Context Diagram, 4.3 Components table, 4.4 Data Model, 4.5 API Design
|
||||
|
||||
@@ -21,7 +21,7 @@ The FIRST thing you do, before anything else in this file — before Step 1, bef
|
||||
- This mode modifies **`specs/` paths only** — do NOT implement code or modify any file outside `specs/`
|
||||
- **Allowed file paths:** ONLY paths under `specs/`. Forbidden: `skills/`, `src/`, `.claude/`, `.agents/`, `.codeium/`, configs, source code. Creating, modifying, or deleting any file outside `specs/` is a violation.
|
||||
- **Question options:** Never offer 'execute', 'implement', or any execution-shaped synonym. Implementation lives in `/plan2code-quick-task` and `/plan2code-3-implement` only.
|
||||
- **Web console exception:** the console's temporary payload files (outside the repo, in the session folder `open` prints) are the one allowed write outside `specs/`. They are messages to the page, never project files.
|
||||
- **Web console exception:** the console's temporary payload files (outside the repo, in the session folder `open` prints) are the one allowed write outside `specs/`. They are messages to the page, never project files. A UI prototype's drafts (the round folders its scripts make and sweep under `~/.plan2code/prototypes/`) are allowed too: they sit outside the project.
|
||||
|
||||
## Scripts
|
||||
|
||||
@@ -61,6 +61,8 @@ Do not proceed without spec files.
|
||||
|---------------|-------|----------|
|
||||
| [Component] | [File list] | [Section names] |
|
||||
|
||||
4. When the change is about how a screen looks or flows, offer a UI prototype before the impact assessment (`references/ui-prototype.md`, run in this conversation): nothing is built without a yes, and a yes to saving puts `prototypes/<name>.html` and `<name>.md` in this spec.
|
||||
|
||||
Present findings and confirm understanding before continuing.
|
||||
|
||||
### STEP 2: Impact Assessment
|
||||
@@ -141,6 +143,8 @@ Approve the spec-update plan? (approve / refine / abort). Implementation of any
|
||||
|
||||
6. **A waiting brief:** rewrite its `**Plan change:**` line to `**Plan change (applied <YYYY-MM-DD>):**` when this revision covers it, or `**Plan change (dropped <YYYY-MM-DD>):**` when the person replaced or declined it at Step 1, so the dashboard and Implement stop pointing back here.
|
||||
|
||||
7. **A saved prototype:** point each revised task that builds the screen at its `prototypes/<name>.md`.
|
||||
|
||||
### STEP 4: Consistency Check
|
||||
|
||||
`🔄 [REVISION] Step 4: Consistency Check`
|
||||
|
||||
@@ -42,6 +42,8 @@ Needs the spec files. `specs/` is gitignored, so never search it with a file sea
|
||||
|
||||
Then read overview.md and act on `next` (Parallel Phase Selection below). Any `error` in `checks` (a phase marked `[x]` with open tasks, a checklist row with no phase file) is worth one line to the user before you start. Do not proceed without a readable overview.md and a `next` verdict.
|
||||
|
||||
A spec with `prototypes/*.md` (saved prototype choices): read the ones overview.md or the phase's tasks name, and open the matching `.html` only when a task says to match it.
|
||||
|
||||
## Phase Status Tracking
|
||||
|
||||
| Checkbox | Status | Meaning |
|
||||
|
||||
@@ -39,6 +39,7 @@ Check for `./AGENTS.md` first:
|
||||
- Complete clarification before presenting the plan; keep it concise, actionable and about this change only
|
||||
- Standalone workflow - does NOT create spec files or feed into steps 2-4
|
||||
- Launched with a spec folder holding a `DIAGNOSIS-*.md`: read it first, as the bug's context (its cause and suggested fix are already found; re-run its reproduction before and after the fix). Once it passes, set the diagnosis `**Status:**` to `Fixed`; escalating, use that folder rather than asking for a name. Fixed, with nothing in the folder past the diagnosis (no `PLAN-CONVERSATION`, `PLAN-DRAFT`, `pathfinder/map.md` or `overview.md`)? It is done: run `node "<S>/specs.mjs" archive <spec> --dry-run` from the project root (`<S>` is `scripts/` beside this SKILL.md, `~/.agents/skills/plan2code-quick-task/scripts/` globally), show its `files`, ask "Archive it to `specs--completed/`? (yes / no)", and on yes run it without `--dry-run`. On no it stays on the dashboard as "Bug fixed".
|
||||
- Launched with a spec folder holding only saved prototypes (`prototypes/<name>.html` and `<name>.md`): read each `.md` first, as the brief (the request, the chosen variant and its settings, why the others lost), and open the `.html` for the look; with several, ask which to build. Then show what you read (the request, the chosen variant and the settings carried over) and ask them to confirm or add to it before any follow-ups or plan; this stands in for asking what to build (console: a `recap` card). Build the chosen variant into the app's own code and styles, never the prototype page itself, and skip the "See it first?" offer. Escalating, use that folder rather than asking for a name. Nothing is archived: the prototype stays as the reference.
|
||||
- Cause unclear or the fix big? Stop and suggest `/plan2code-diagnose`.
|
||||
- Read `references/building-habits.md` when the ask is a bug fix or a test fails unexpectedly, after a yes to "Write the test first?", and before a change meant to alter no behavior; follow it.
|
||||
- Read `references/test-runs.md` before the first test run: run the tests covering the changed files, and offer the full suite at sign-off when the change touched shared ground.
|
||||
@@ -51,10 +52,12 @@ Check for `./AGENTS.md` first:
|
||||
╰┬─┬╯
|
||||
```
|
||||
|
||||
Ask what feature the user wants, then ask follow-up questions until 100% clear. Console: that first card carries `"templates": "idea"` (console.md → A patch).
|
||||
Ask what feature the user wants (not on saved prototypes: the recap in Rules replaces it), then ask follow-up questions until 100% clear. Console: otherwise that first card carries `"templates": "idea"` (console.md → A patch).
|
||||
|
||||
**Write the test first?** Ask it with the follow-ups (or on its own if there are none) only when the change alters behavior AND the project already has a test runner you can see (a `test` script in `package.json`, pytest config in `pytest.ini` or `pyproject.toml`, `go.mod` with `_test.go` files, or similar). Never for a pure refactor, a docs change, or a project with no runner. Console: one `confirm` card in the same batch as the other plan questions; terminal: one line in the same prompt. On yes, name the test spot in the plan's Verify section and follow the test-first habit.
|
||||
|
||||
**See it first?** When the task is a visual change with more than one reasonable look, offer a UI prototype (`references/ui-prototype.md`, run in this conversation) before the plan; nothing is built without a yes. Build from the choice directly; it is not saved as `prototypes/<name>.html` and `<name>.md` unless the person asks (then offer the usual folder list), and the draft stays 30 days.
|
||||
|
||||
## Scope Validation
|
||||
|
||||
After achieving clarity, assess scope:
|
||||
|
||||
@@ -0,0 +1,280 @@
|
||||
# The Variant Contract
|
||||
|
||||
Read this before writing any variant. It is the one written source of the rules between a variant you write and the page the skill builds around it. The page's tool part (top bar, dials, Copy) is shipped and never changes; you write only the variants and the `round.json` that describes them. `base.css` (placed inside every frame) implements the values and attributes named here, and `ui-prototype.mjs check` verifies the rules in section 5.
|
||||
|
||||
## 1. Shared style values
|
||||
|
||||
Each variant takes its look from shared values. The dials set them on the root of every frame, so one move of a dial restyles every variant at once. Use them through `var(...)`.
|
||||
|
||||
**Dial inputs** (set by the dials):
|
||||
|
||||
| Value | Holds | Example |
|
||||
| --- | --- | --- |
|
||||
| `--p2c-accent` | The accent color | `#2f6fed` |
|
||||
| `--p2c-neutral` | The neutral (gray) color the surfaces are tinted from | `#6b7280` |
|
||||
| `--p2c-font` | The font family (one of the six font sets, section 6) | `var(--p2c-font-set-humanist)` |
|
||||
| `--p2c-text-size` | The body text size | `16px` |
|
||||
| `--p2c-space` | The spacing unit, a plain number (1 is normal) | `1.25` |
|
||||
| `--p2c-radius` | The corner radius | `8px` |
|
||||
| `--p2c-screen-width` | The Screen size dial's width (a screen's frame is this wide; each flow step is too) | `390px` |
|
||||
| `--p2c-x-<name>` | One per extra in `round.json` (section 4) | `--p2c-x-shadows` |
|
||||
|
||||
**Derived values** (worked out by `base.css` from the inputs, for light and dark):
|
||||
|
||||
| Value | Use it for |
|
||||
| --- | --- |
|
||||
| `--p2c-bg` | The page background |
|
||||
| `--p2c-surface` | Cards, panels, inputs |
|
||||
| `--p2c-text` | Body text |
|
||||
| `--p2c-muted` | Secondary text, captions, placeholders |
|
||||
| `--p2c-border` | Lines and outlines |
|
||||
| `--p2c-on-accent` | Text on an accent-colored fill |
|
||||
| `--p2c-space-1` to `--p2c-space-6` | The spacing scale: 4, 8, 12, 16, 24 and 32 px at a `--p2c-space` of 1 |
|
||||
|
||||
The values fall into four groups, and a screen or flow variant must use at least one value from each:
|
||||
|
||||
| Group | Values |
|
||||
| --- | --- |
|
||||
| Color | `--p2c-accent`, `--p2c-neutral`, `--p2c-bg`, `--p2c-surface`, `--p2c-text`, `--p2c-muted`, `--p2c-border`, `--p2c-on-accent` |
|
||||
| Font | `--p2c-font`, `--p2c-text-size`, any `--p2c-font-set-...` |
|
||||
| Spacing | `--p2c-space`, `--p2c-space-1` to `--p2c-space-6` |
|
||||
| Corners | `--p2c-radius` |
|
||||
|
||||
You may add your own local values on top of the shared ones (`--card-gap: calc(var(--p2c-space-4) * 1.5)`, a second shade of the accent, a shadow). The contract asks that the shared values be used, not that nothing else is. A freed-up carry-over item (one the person left unticked) is where each variant shows its own take; a ticked item must look the same in every variant, so take it from the shared values only.
|
||||
|
||||
**Extras.** Each extra in `round.json` sets `--p2c-x-<name>` on the root, and also a `data-p2c-x-<name>` attribute so a variant can select on it:
|
||||
|
||||
| Type | `--p2c-x-<name>` | `data-p2c-x-<name>` |
|
||||
| --- | --- | --- |
|
||||
| `slider` | The number, with no unit (`calc(var(--p2c-x-columns) * 1)`, `calc(var(--p2c-x-lift) * 1px)`) | The number |
|
||||
| `pick` | The chosen text | The chosen text (`[data-p2c-x-shadows="soft"]`) |
|
||||
| `toggle` | `1` when on, `0` when off | `on` or `off` |
|
||||
|
||||
## 2. Root attributes
|
||||
|
||||
The page sets these on each frame's `<html>`. Do not write them yourself; style with them.
|
||||
|
||||
| Attribute | Values | Set by |
|
||||
| --- | --- | --- |
|
||||
| `data-p2c-theme` | `light`, `dark` | The light and dark dial |
|
||||
| `data-p2c-state` | `ready`, `empty`, `loading`, `error` | The states dial |
|
||||
| `data-p2c-length` | `short`, `typical`, `long` | The content length dial |
|
||||
| `data-p2c-kind` | `screen`, `flow`, `terminal` | `round.json`'s `kind`, fixed for the round |
|
||||
|
||||
## 3. The marks a variant writes
|
||||
|
||||
- **States.** Put `data-p2c-when="<state>"` on each part that belongs to one state: the filled list on `ready`, the "No invoices yet" message on `empty`, the skeleton rows on `loading`, the failure notice on `error`. A part shared by two states lists both, separated by a space (`data-p2c-when="empty error"`). `check` counts marks on elements only, never in your `<style>` block. Parts with no mark show in every state. `base.css` hides every marked part whose list does not hold the root's state. Draw all four states for real: an empty state that guides, a loading state shaped like the content, an error that says what to do.
|
||||
- **Content length.** Write each text that varies three times, side by side, marked `data-p2c-text="short"`, `data-p2c-text="typical"` and `data-p2c-text="long"` (a 6-letter name, an ordinary one, a 60-character one that tests wrapping). `base.css` shows only the root's length. A mark may list two lengths with a space, as for states.
|
||||
- **Flow steps.** In a flow, each screen is an element directly inside `<body>` carrying `data-p2c-step="<label>"` (`data-p2c-step="1. Sign in"`). `base.css` lays the screens in one row that scrolls sideways and shows each label above its screen. A flow needs at least two steps. Each step is `--p2c-screen-width` wide (`base.css` passes it on as `--p2c-step-width`), and the frame grows to hold the whole row.
|
||||
|
||||
## 4. Terminal values
|
||||
|
||||
A terminal variant (`kind` is `terminal`) draws a text screen in the frame. In place of the font and corner values it takes:
|
||||
|
||||
| Value | Holds |
|
||||
| --- | --- |
|
||||
| `--p2c-term-bg` | The terminal background |
|
||||
| `--p2c-term-fg` | The text color |
|
||||
| `--p2c-term-accent` | Highlights, prompts, the selected row |
|
||||
| `--p2c-density` | The line height, a plain number (1.4 is normal) |
|
||||
|
||||
A terminal variant uses at least one palette value (`--p2c-term-bg`, `--p2c-term-fg` or `--p2c-term-accent`) and `--p2c-density`. `base.css` sets the monospace font set, the palette and the line height on `<body>`. The four palettes are in section 6; the page sets the three palette values for the chosen palette and theme.
|
||||
|
||||
## 5. What `check` verifies
|
||||
|
||||
`node "<S>/ui-prototype.mjs" check --file <page>` reads the built page and reports each problem as `{ rule, variant, message }`. Exit 0 means clean; exit 4 means findings.
|
||||
|
||||
| Rule | A finding when |
|
||||
| --- | --- |
|
||||
| `outside-link` | A variant or the page holds an `http:`, `https:` or `file://` URL, a `//` URL anywhere (`//cdn.example.com/a.png` or `//localhost/a.png`, in an attribute, a `srcset`, a meta refresh or a CSS string), `@import`, or a `url(...)` that is not a `data:` URL or a `#` reference inside the same document. (An `xmlns` attribute on inline SVG is allowed: it names a format and loads nothing.) |
|
||||
| `script` | A variant holds a `<script` tag, an `on...=` attribute (`onclick`, `onload`) or a `javascript:` URL |
|
||||
| `state-missing` | A variant has no `data-p2c-when` mark for one of `ready`, `empty`, `loading`, `error` |
|
||||
| `length-missing` | A variant has no `data-p2c-text` mark for one of `short`, `typical`, `long` |
|
||||
| `value-unused` | A screen or flow variant uses no `var(--p2c-...)` from one of the color, font, spacing and corners groups; a terminal variant uses none from the palette values, or not `--p2c-density` |
|
||||
| `step-missing` | A flow variant has fewer than two `data-p2c-step` screens |
|
||||
| `frame-missing` | A variant named in the round facts has no frame in the page (only a hand-edited page; run `assemble` again) |
|
||||
| `image-type` | A variant holds a `data:` image that is not PNG, JPEG, WebP or SVG |
|
||||
| `image-size` | A variant holds a `data:` image over 1 MB once decoded (run `assemble` again so it becomes a placeholder) |
|
||||
| `image-missing` | A variant names a `p2c-image:<name>` that `round.json`'s `images` does not list, so nothing was put in |
|
||||
| `size` | The page is over the 5 MB soft ceiling. Reported as `overCeiling: true`, never as a finding |
|
||||
|
||||
## 6. What a variant file is
|
||||
|
||||
A variant file (`variant-a.html`) is one `<style>` block followed by markup:
|
||||
|
||||
- No `<html>`, `<head>` or `<body>` tags: the page wraps the file in its own frame document.
|
||||
- No `<script>`, no `on...` attributes, no `javascript:` links. The frame cannot run script, so nothing would happen anyway.
|
||||
- No `http:`, `https:`, `file://` or `//` URLs, no `@import`, no `url(...)` except a `data:` URL. Write an example web address as text without its scheme (`example.com/invoices`).
|
||||
- Images only through `<img src="p2c-image:<name>" alt="...">`, where `<name>` is an image's `name` in `round.json`. The page puts the image in. Never write an SVG image as markup; small inline icons drawn with `<svg>` are fine.
|
||||
- Real content: real names, numbers and labels for the screen in question, never "Lorem ipsum" or "Item 1".
|
||||
|
||||
## 7. `round.json`
|
||||
|
||||
One file per round, beside the variant files, written by you and checked by `assemble`.
|
||||
|
||||
| Field | Type | Holds |
|
||||
| --- | --- | --- |
|
||||
| `name` | text | The prototype's name: lowercase letters and digits joined by single hyphens (`invoices-screen`) |
|
||||
| `round` | whole number, 1 or more | The round number `new-round` printed. `assemble` refuses a `name` or `round` that differs from the round's folder |
|
||||
| `kind` | `screen`, `flow` or `terminal` | What is drawn |
|
||||
| `request` | text, not empty | The person's original request, in a line or two |
|
||||
| `direction` | text | Any typed direction; `""` when none |
|
||||
| `carried` | list | Carry-over items kept the same in every variant |
|
||||
| `freed` | list | Carry-over items each variant takes its own way |
|
||||
| `notFound` | list | Carry-over items looked for and not found |
|
||||
| `variants` | list, 2 to 5 | One entry per variant (below) |
|
||||
| `starts` | object | Where each shared dial starts (below) |
|
||||
| `extras` | list, at most 6 | The extra dials (below); `[]` when none |
|
||||
| `images` | list | Each `{ "name", "path" }`: an image for the page, its path absolute or relative to the round folder; `[]` when none |
|
||||
| `fonts` | list | Paths of the app's font files, absolute or relative to the round folder; `[]` when none |
|
||||
|
||||
The carry-over items are `colors`, `fonts`, `spacing`, `components` and `layout`.
|
||||
|
||||
**Freed-up items and the dials.** When an item is in `freed`, each variant starts the dials below from its own `starts`, the page gives each frame its own value until the person moves the dial, and the dial's reset gives each variant its own back. When the item is carried over (or not found), every variant shares the round's `starts` and a variant's own value for that dial is ignored.
|
||||
|
||||
| Item | Screen or flow dials | Terminal dials |
|
||||
| --- | --- | --- |
|
||||
| `colors` | `accent`, `neutral` | `palette` |
|
||||
| `fonts` | `fontSet`, `textSize` | none |
|
||||
| `spacing` | `space` | `density` |
|
||||
| `components` | `radius` (the corners) | none |
|
||||
| `layout` | none | none |
|
||||
|
||||
**A variant:** `letter` (`A` to `E`, in order, no gaps), `name` (two or three words), `file` (the variant's file name in the round folder), `what` (one line on what it is), and `starts` (its own starting values for the dials of freed-up items, with the same keys and types as the shared `starts`; `{}` when it has none).
|
||||
|
||||
**`starts` for a screen or a flow:**
|
||||
|
||||
| Key | Type |
|
||||
| --- | --- |
|
||||
| `screen` | One of the screen sizes in section 8 (`"Desktop 1280"`) |
|
||||
| `theme` | `light` or `dark` |
|
||||
| `accent`, `neutral` | A color as `#rrggbb` |
|
||||
| `fontSet` | One of the font sets in section 8 (`"Humanist"`) |
|
||||
| `textSize` | Pixels, a number from 12 to 24 |
|
||||
| `space` | A number from 0.5 to 2 |
|
||||
| `radius` | Pixels, a number from 0 to 32 |
|
||||
| `state` | `ready`, `empty`, `loading` or `error` |
|
||||
| `length` | `short`, `typical` or `long` |
|
||||
|
||||
**`starts` for a terminal:** `window` (one of the terminal sizes, `"120x30"`), `theme`, `palette` (one of the four palettes), `density` (a number from 1 to 2), `state` and `length`.
|
||||
|
||||
**An extra:** `name` (lowercase letters, digits and hyphens: it becomes `--p2c-x-<name>`), `label` (optional: the dial's label, the name when left out; no colon), `type` (`slider`, `pick` or `toggle`), then for a slider `min`, `max`, `step` and a number `start`; for a pick `choices` (two or more texts, none holding a double quote or a backslash) and a `start` among them; for a toggle a `true` or `false` `start`. `look` is `true` when Surprise me may move it (a look, like shadows) and `false` when it may not (a structure, like column count).
|
||||
|
||||
A complete example:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "invoices-screen",
|
||||
"round": 1,
|
||||
"kind": "screen",
|
||||
"request": "A screen listing a customer's invoices, with what is overdue easy to spot.",
|
||||
"direction": "calm, plenty of room around totals",
|
||||
"carried": ["colors", "fonts", "spacing"],
|
||||
"freed": ["components", "layout"],
|
||||
"notFound": [],
|
||||
"variants": [
|
||||
{ "letter": "A", "name": "Dense table", "file": "variant-a.html", "what": "A sortable table with overdue rows tinted", "starts": { "radius": 4 } },
|
||||
{ "letter": "B", "name": "Split view", "file": "variant-b.html", "what": "A list on the left, the open invoice on the right", "starts": { "radius": 10 } },
|
||||
{ "letter": "C", "name": "Cards", "file": "variant-c.html", "what": "One card per invoice, overdue ones first", "starts": { "radius": 16 } }
|
||||
],
|
||||
"starts": {
|
||||
"screen": "Desktop 1280",
|
||||
"theme": "light",
|
||||
"accent": "#2f6fed",
|
||||
"neutral": "#6b7280",
|
||||
"fontSet": "System UI",
|
||||
"textSize": 16,
|
||||
"space": 1,
|
||||
"radius": 8,
|
||||
"state": "ready",
|
||||
"length": "typical"
|
||||
},
|
||||
"extras": [
|
||||
{ "name": "shadows", "label": "Shadows", "type": "pick", "choices": ["none", "soft", "strong"], "start": "soft", "look": true },
|
||||
{ "name": "columns", "label": "Columns", "type": "slider", "min": 1, "max": 4, "step": 1, "start": 2, "look": false },
|
||||
{ "name": "dividers", "label": "Row dividers", "type": "toggle", "start": true, "look": true }
|
||||
],
|
||||
"images": [],
|
||||
"fonts": []
|
||||
}
|
||||
```
|
||||
|
||||
## 8. Fixed names
|
||||
|
||||
| What | Names |
|
||||
| --- | --- |
|
||||
| Font sets | System UI, Humanist, Transitional, Slab Serif, Rounded Sans, Monospace Code (`base.css` names them `--p2c-font-set-system-ui`, `-humanist`, `-transitional`, `-slab-serif`, `-rounded-sans`, `-monospace-code`) |
|
||||
| Screen sizes | Phone 390, Tablet 820, Desktop 1280 (the frame's width in pixels) |
|
||||
| Terminal sizes | 80x24, 120x30, 160x48 (columns by rows) |
|
||||
| Terminal palettes | Graphite, Amber, Phosphor, Ocean (`base.css` holds each one's background, text and accent for light and dark as `--p2c-palette-<slug>-<theme>-<bg, fg or accent>`) |
|
||||
| Presets | Compact, Balanced, Airy, Bold |
|
||||
|
||||
## 9. Limits
|
||||
|
||||
| Limit | Value | Past it |
|
||||
| --- | --- | --- |
|
||||
| Variants in a round | 2 to 5 (3 by default) | `assemble` refuses the round |
|
||||
| Extras | 6 | `assemble` refuses the round |
|
||||
| One image | 1 MB | A labeled placeholder, named in the report |
|
||||
| All images | 3 MB | The page is still made; the report names the largest |
|
||||
| App font | 4 files, 2 MB together | The closest system set is used and the skill says so |
|
||||
| Whole page | 5 MB, a soft ceiling | A warning that says what takes the space; it never blocks |
|
||||
|
||||
## 10. Writing a round
|
||||
|
||||
The order of work, so a round passes `check` the first time:
|
||||
|
||||
1. **Facts first.** Write `round.json`: the name, kind, request, direction, the three carry-over lists, one entry per variant (letter, name, file, `what`, its own `starts` for freed-up items), the shared `starts`, the extras, images and fonts. Every later file follows from it.
|
||||
2. **One variant file at a time**, in letter order: its `<style>` block (shared values only for carried items), then its markup with all four states and the three lengths marked. Finish one before starting the next, and check it against the list below.
|
||||
3. **Assemble, then check.** Fix what `check` names in the variant files, never in the page.
|
||||
|
||||
A complete small variant that passes `check` (it is `variant-a.html` of the test fixture `contract-example`, so it is checked on every test run):
|
||||
|
||||
```html
|
||||
<style>
|
||||
.team { padding: var(--p2c-space-5); font-family: var(--p2c-font); font-size: var(--p2c-text-size); color: var(--p2c-text); background: var(--p2c-bg); }
|
||||
.team h1 { font-size: calc(var(--p2c-text-size) * 1.5); margin: 0 0 var(--p2c-space-4); text-wrap: balance; }
|
||||
.team ul { list-style: none; margin: 0; padding: 0; background: var(--p2c-surface); border: 1px solid var(--p2c-border); border-radius: var(--p2c-radius); }
|
||||
.team li { display: flex; justify-content: space-between; gap: var(--p2c-space-3); padding: var(--p2c-space-3) var(--p2c-space-4); border-top: 1px solid var(--p2c-border); }
|
||||
.team li:first-child { border-top: 0; }
|
||||
.team .role { color: var(--p2c-muted); }
|
||||
.team .bar { height: calc(var(--p2c-text-size) * 1.2); margin: var(--p2c-space-3) var(--p2c-space-4); border-radius: var(--p2c-radius); background: color-mix(in oklab, var(--p2c-neutral) 18%, var(--p2c-surface)); }
|
||||
.team button { background: var(--p2c-accent); color: var(--p2c-on-accent); border: 0; border-radius: var(--p2c-radius); padding: var(--p2c-space-2) var(--p2c-space-4); font: inherit; }
|
||||
.team button:focus-visible { outline: 2px solid var(--p2c-accent); outline-offset: 2px; }
|
||||
</style>
|
||||
<section class="team">
|
||||
<h1>Team members</h1>
|
||||
<ul data-p2c-when="ready">
|
||||
<li>
|
||||
<span data-p2c-text="short">Ana Ruiz</span>
|
||||
<span data-p2c-text="typical">Ana Ruiz-Okafor</span>
|
||||
<span data-p2c-text="long">Anastasia Ruiz-Okafor, Regional Accounts Lead, Northern Office</span>
|
||||
<span class="role">Admin</span>
|
||||
</li>
|
||||
<li><span>Tomas Berg</span><span class="role">Editor</span></li>
|
||||
</ul>
|
||||
<div data-p2c-when="loading" aria-label="Loading team members"><div class="bar"></div><div class="bar"></div></div>
|
||||
<p data-p2c-when="empty">No one else is on this team yet. Invite a teammate to share the work.</p>
|
||||
<p data-p2c-when="error">The team list did not load. Check your connection, then reload this page.</p>
|
||||
<button data-p2c-when="ready empty">Invite a teammate</button>
|
||||
</section>
|
||||
```
|
||||
|
||||
It takes color, font, spacing and corners from the shared values, marks all four states (the button shows in two), and writes the first name in three lengths. A second row with one plain name is fine: only the text that varies needs the three lengths.
|
||||
|
||||
The three most common findings, and their fix:
|
||||
|
||||
| Finding | Usual cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| `state-missing` | The loading or error state was left out, or named only in the `<style>` block | Draw it in the markup with `data-p2c-when` on an element |
|
||||
| `length-missing` | Only one version of the text that varies | Write it three times, side by side, marked `short`, `typical` and `long` |
|
||||
| `outside-link` | An example web address with its scheme, or a picture or font loaded from the web | Write the address as text without `https://`; use `p2c-image:<name>`, a `data:` URL or an inline drawing |
|
||||
|
||||
A terminal variant differs in six ways:
|
||||
|
||||
- `kind` is `terminal`, and `starts` holds `window`, `theme`, `palette`, `density`, `state` and `length`.
|
||||
- Colors come from `--p2c-term-bg`, `--p2c-term-fg` and `--p2c-term-accent`, not the screen values.
|
||||
- Line spacing comes from `--p2c-density`; `base.css` already sets the monospace font, so set no font of your own.
|
||||
- Write text as the terminal shows it, in a `<pre>` or fixed-width rows, sized to the window (80, 120 or 160 columns).
|
||||
- No corners, shadows or images: draw boxes with characters (`+--+`, `│`) and highlight with the accent.
|
||||
- States and lengths are marked exactly as for a screen.
|
||||
@@ -0,0 +1,114 @@
|
||||
# Designing Variants
|
||||
> Part of plan2code-ui-prototype: read while planning and writing variants, before any HTML. Never invoked as a skill.
|
||||
|
||||
An unguided model lands on the statistical center of what it has seen, so its pages look alike. The counter is a process, not a style: plan each variant in writing, review the plan against the known giveaways, then build. The shared values and marks are in `ui-prototype-contract.md`; this file is about making what you draw look considered.
|
||||
|
||||
## 1. Plan each variant first
|
||||
|
||||
Write a short plan per variant, in your head or your notes, before its HTML. Each variant gets its own plan, or the variants converge.
|
||||
|
||||
| Line | Holds |
|
||||
| --- | --- |
|
||||
| For | Who uses this screen, and in what moment ("a bookkeeper closing the month") |
|
||||
| Make easy | The one thing the screen must make easy ("spot what is overdue") |
|
||||
| Structure | A one-line layout concept, with alignment stated; a tiny wireframe if it helps |
|
||||
| Type scale | Three to five sizes as multiples of `--p2c-text-size`, and the weights |
|
||||
| Accent | The one place the accent is spent, and why there |
|
||||
|
||||
A tiny wireframe is enough:
|
||||
|
||||
```
|
||||
[ filters ][ 14 overdue, $8,420 ]
|
||||
[ table: client | due | amount ]
|
||||
```
|
||||
|
||||
Then review the plan. Strike anything you would produce for any similar page, and replace it with a choice this product's content asks for. Only then write HTML.
|
||||
|
||||
## 2. Giveaways of an AI-made page
|
||||
|
||||
Check every plan against these. One alone can be right for a brief; reaching for it by default is the problem.
|
||||
|
||||
- **Warm cream**: a cream background near `#F4F1EA`, a high-contrast serif display, a terracotta accent.
|
||||
- **Near-black with one acid accent**: a dark page with a single acid green or vermilion.
|
||||
- **Hairline broadsheet**: thin rules, square corners, dense columns, newspaper styling with no reason.
|
||||
- **The SaaS-card kit**: identical rounded cards, one radius everywhere, the same soft shadow under each, gradient washes as decoration.
|
||||
- **Template chrome**: tracked-out all-caps eyebrows above every heading, meta strings joined with middle dots, monospace for small data labels, a trailing arrow on every link and button.
|
||||
- **Also**: a big-number hero with a small label and a gradient accent; fade-and-slide-up entrances on each section; one accented word in a headline; all-caps labels; labels above content that needs none; purple gradients on white.
|
||||
|
||||
## 3. Real content
|
||||
|
||||
- Write for this product: plausible names, numbers and dates ("Halvorsen Dental, due Oct 14, $1,240.00"), never "Lorem ipsum", "Item 1" or "John Doe".
|
||||
- Name things the way the people using it would.
|
||||
- Buttons say exactly what happens: "Send reminder", "Save changes", never "Submit" or "Continue".
|
||||
- One name per action through a flow: a "Publish" button leads to a "Published" notice, not "Saved".
|
||||
- Numerals for counts ("8 invoices"), consistent date and money formats, sentence case, plain verbs, active voice.
|
||||
- Every text that varies is written three times with `data-p2c-text`: short (about 6 letters), typical, and long (about 60 characters, to test wrapping). Let containers wrap or truncate cleanly; flex children that truncate need `min-width: 0`.
|
||||
|
||||
## 4. Drawn states
|
||||
|
||||
Mark each with `data-p2c-when`, and draw each one for real.
|
||||
|
||||
| State | Draw |
|
||||
| --- | --- |
|
||||
| `ready` | The filled screen with the real content |
|
||||
| `empty` | What to do next: one line on why it is empty and a button that starts it ("Create your first invoice") |
|
||||
| `loading` | A skeleton shaped like the content (rows, blocks where text will be), not a lone spinner; a loading label ends in "…" |
|
||||
| `error` | What happened and what to do ("Couldn’t reach the bank. Check the connection and try again."), next to the part that failed; never apologize, never vague |
|
||||
|
||||
- Focus is always visible: a `:focus-visible` outline in the accent, never `outline: none` without a replacement.
|
||||
- Hover and pressed are drawn and stronger than rest. Motion only answers an action, and honors `prefers-reduced-motion`.
|
||||
|
||||
## 5. Typography
|
||||
|
||||
- `font-family: var(--p2c-font)` on the body: the font set dial supplies the family. One family, or two clearly distinct ones (a second `--p2c-font-set-...` for headings only when the plan calls for it).
|
||||
- A clear scale derived from the dial: `--t-small: calc(var(--p2c-text-size) * 0.875)`, `--t-h2: calc(var(--p2c-text-size) * 1.5)`, `--t-h1: calc(var(--p2c-text-size) * 2.25)`. Hierarchy by size, weight and color; real contrast between levels.
|
||||
- Lines under about 80 characters (`max-width: 70ch` on text blocks).
|
||||
- `font-variant-numeric: tabular-nums` in number columns; right-align money.
|
||||
- `text-wrap: balance` on headings.
|
||||
- Real characters: "…" not "...", curly quotes and apostrophes, a non-breaking space in units ("10 MB").
|
||||
|
||||
## 6. Color
|
||||
|
||||
- Build every color from the shared values: `--p2c-bg`, `--p2c-surface`, `--p2c-text`, `--p2c-muted`, `--p2c-border`, `--p2c-accent`, `--p2c-on-accent`. They follow the light and dark dial for you; add local shades with `color-mix(in oklab, var(--p2c-accent) 15%, var(--p2c-surface))`.
|
||||
- One dominant surface, the rest quiet. Spend your boldness in one place: the accent marks the one thing the screen must make easy, not every button and border.
|
||||
- Text contrast at least 4.5:1 (3:1 for large text and for control outlines). Muted text is for secondary lines, never for anything a person must read to act.
|
||||
- Status colors (overdue, failed) carry a word or an icon too, never color alone.
|
||||
|
||||
## 7. Spacing, corners and structure
|
||||
|
||||
- Every gap and padding from `--p2c-space-1` to `--p2c-space-6`; a local value is a `calc()` of them. Group related things tight and separate groups wide.
|
||||
- Corners from `--p2c-radius`; a nested element takes a smaller radius (`calc(var(--p2c-radius) / 2)`), so one radius is not stamped on everything.
|
||||
- Structure encodes something about the content. Borders, dividers, numbering and labels mean something; numbered markers (01, 02, 03) only for a real sequence.
|
||||
- Targets at least 24 by 24 px (44 on a phone screen is better).
|
||||
|
||||
## 8. Icons
|
||||
|
||||
- Draw icons inline as small hand-written `<svg>` markup (a `viewBox="0 0 24 24"`, one or two `<path>`s, `stroke="currentColor"`, `fill="none"`), sized in `em` so they follow the text.
|
||||
- Never an icon set, icon font or image from the network: the page loads nothing from the network.
|
||||
- Give an icon-only button an `aria-label`; hide decorative icons with `aria-hidden="true"`.
|
||||
|
||||
## 9. How different: Subtle, Balanced, Radical
|
||||
|
||||
| Level | In practice |
|
||||
| --- | --- |
|
||||
| Subtle | Same structure in every variant; they differ in treatment (type scale, density, where the accent goes, corners, surface contrast) |
|
||||
| Balanced (default) | Each variant makes one structural difference (a table vs a list of cards, a side panel vs a stacked page, filters on top vs at the side) |
|
||||
| Radical | The variants disagree about structure: different primary layout, different idea of what comes first, different way through the task |
|
||||
|
||||
At every level, each variant still has its own plan, real content and all four states. Write the difference into each variant's `what` line in `round.json`.
|
||||
|
||||
## 10. Checklist per variant
|
||||
|
||||
Run this over each variant before writing the next one.
|
||||
|
||||
- [ ] Its own plan, reviewed against section 2, with nothing a similar page would have by default.
|
||||
- [ ] It differs from the variants already written at the level asked for.
|
||||
- [ ] Real names, numbers and dates; buttons say what happens; one name per action.
|
||||
- [ ] Short, typical and long text marked with `data-p2c-text`, and the long one wraps cleanly.
|
||||
- [ ] `ready`, `empty`, `loading` and `error` drawn and marked; the error says what to do.
|
||||
- [ ] Visible focus; targets at least 24 by 24 px; text contrast at least 4.5:1 in light and dark.
|
||||
- [ ] Sizes from `--p2c-text-size`, gaps from `--p2c-space-1..6`, corners from `--p2c-radius`, colors from the shared values.
|
||||
- [ ] The accent spent in one place; tabular numerals in number columns; balanced headings.
|
||||
- [ ] Icons drawn inline; no URL, script or `@import` anywhere.
|
||||
|
||||
Sources: Anthropic's frontend-design skill and frontend aesthetics cookbook, Vercel's Web Interface Guidelines, WCAG 2.2, Apple Human Interface Guidelines.
|
||||
@@ -0,0 +1,84 @@
|
||||
# After the Paste
|
||||
> Part of plan2code-ui-prototype: read at Step 6, right after `read-block` and before the read-back. Never invoked as a skill.
|
||||
|
||||
The pasted block is the record of the round: it names the prototype, the page, the round, the pick, every dial and the note. Each next step below works from the block alone, so it also works in a new conversation, as long as the drafts are still there (30 days).
|
||||
|
||||
## Reading the block
|
||||
|
||||
`read-block` returns `fields`:
|
||||
|
||||
| Field | From the line | Use |
|
||||
| --- | --- | --- |
|
||||
| `prototype` | Prototype | The name for `new-round` and `save` |
|
||||
| `file` | File | The page this block came from |
|
||||
| `round` | Round | Compared with the newest draft (`latest`) |
|
||||
| `chosen`, `others` | Chosen | The pick, and the variants not chosen (letter and name) |
|
||||
| `carried`, `freed` | Carried over, Freed up | The carry-over choices of that round |
|
||||
| `direction`, `preset`, `note` | Direction, Preset, Note | Present only when the person had something there |
|
||||
| `dials` | Screen size to Content length (a terminal: Window size to Content length) | Each `{ label, value, changedFrom }`; `changedFrom` is null for a dial left alone |
|
||||
| `extras` | Extra, `<label>` | Each extra the same way |
|
||||
| `unknown` | any other line | Lines the script does not know (below) |
|
||||
|
||||
Lines may come in another order, inside a code fence, or edited by hand: the script reads them all the same.
|
||||
|
||||
**The round folder.** A round's files sit in `round-<N>` beside its page (`<name>-round-<N>.html`, the File line). Its `round.json` holds the request, the carry-over lists, the images and the fonts; `choice.txt` and `rejected.txt` for a save go there too. In a new conversation, find it from the File line. When it is gone, ask the person for the request in a line.
|
||||
|
||||
## Save
|
||||
|
||||
Step 7 in the prompt holds the steps. In short:
|
||||
|
||||
1. The spec folder: the existing ones under `specs/` (the launched one first) plus **New spec**. Run from another skill: that skill's folder, no question.
|
||||
2. A short lowercase hyphenated name, proposed from what the prototype is; the person may change it.
|
||||
3. Why each variant not chosen lost, in one line each, unless already said.
|
||||
4. `choice.txt` (the block exactly as pasted) and `rejected.txt` (one line per variant not chosen: letter, name, what it was, why it lost) in the round folder, then `save`.
|
||||
5. Error `exists`: ask, and use `--replace` only on a yes.
|
||||
|
||||
`save` keeps only the page of the round the block came from (`--file` is its File line, or the newest page when the File line is gone) and removes every other draft of that prototype. The decisions file holds the request, the block with its File line set to the saved page, and the lines from `rejected.txt`.
|
||||
|
||||
## Narrow from my pick
|
||||
|
||||
A new round, narrower than the last.
|
||||
|
||||
1. `new-round --project . --name <prototype>`: the next round number.
|
||||
2. **Variant A is the pick** with the note applied. When the note asks for no change to the pick (or there is no note), copy the picked variant's file from the old round folder as `variant-a.html` instead of rewriting it. When the note changes it, start from that file and change only what the note asks.
|
||||
3. **Variants B and C are close alternatives**: each keeps the pick's structure and changes one thing the note or the moved dials point at (denser rows, the panel on the other side, a different heading scale). The "how different" level for this round is Subtle unless the person says otherwise. More or fewer only if the person asks.
|
||||
4. **The tuning carries over.** Each dial line in the block becomes the new round's `starts`, by its value now (not its "changed from" value):
|
||||
|
||||
| Block line | `starts` key | Example |
|
||||
| --- | --- | --- |
|
||||
| Screen size | `screen` | `"Desktop 1280"` |
|
||||
| Theme | `theme` | `"dark"` (lower case) |
|
||||
| Accent color, Neutral color | `accent`, `neutral` | `"#2f6fed"` |
|
||||
| Font set | `fontSet` | `"Humanist"`; for `App font`, keep the old round's `fonts` list and `fontSet` |
|
||||
| Text size | `textSize` | `16` (drop the `px`) |
|
||||
| Spacing | `space` | `1.25` |
|
||||
| Corners | `radius` | `8` (drop the `px`) |
|
||||
| State, Content length | `state`, `length` | `"ready"`, `"typical"` (lower case; Very long is `"long"`) |
|
||||
| Window size, Palette, Density | `window`, `palette`, `density` | terminal only |
|
||||
| Extra, `<label>` | that extra's `start` | a pick's choice as `round.json` spells it (`"soft"` for Soft), a toggle's On as `true`; keep the same extras, same names |
|
||||
|
||||
5. **Carried, freed and not found, `kind`, `images` and `fonts` stay as they were** (a copied variant still names its images). A freed-up item's dial that the person moved now has one value for all: put it in the shared `starts` and give each variant `{}` for it. One left unmoved keeps the pick's own start for variant A and the alternatives' own for B and C.
|
||||
6. Keep the request and the direction; add the note to the direction only if it is a standing wish ("calmer overall"), not a one-off change.
|
||||
7. Then Steps 4 and 5: assemble, check, look, open, and the three closing lines (say A is their pick).
|
||||
|
||||
## Fresh set
|
||||
|
||||
For when nothing in the round was right.
|
||||
|
||||
1. **Show the brief first**, so it can be changed: the carry-over ticks, the direction and the "how different" level (Radical is worth suggesting when Balanced missed). Keep each as it was unless the person changes it. Images stay as they were read.
|
||||
2. `new-round --project . --name <prototype>`: the next round number, same prototype.
|
||||
3. **No variant carries over.** Write new variants from new plans (the design reference), avoiding the structures the person just turned down.
|
||||
4. **The dials go back to the start**: `starts` as Step 3 would set them from the carry-over, not from the block. Extras may change to fit the new variants.
|
||||
5. Then Steps 4 and 5.
|
||||
|
||||
## Done
|
||||
|
||||
Nothing is saved. Say that the draft stays for 30 days and give the page's path once more (the block's File line). The person can open it again, or paste the block in a later conversation to save or narrow.
|
||||
|
||||
## Unusual blocks
|
||||
|
||||
- **From an older round** (`latest` false): say so first ("This is from round 1; round 3 is the newest"). Ask whether to carry on from it. Narrow or Fresh set from it still makes the next round number; Save keeps that older round's page if it is still there.
|
||||
- **Edited, with lines the script does not know** (`unknown` not empty): read them as part of the person's note and mention them in the read-back. Never drop them silently.
|
||||
- **Its page is gone** (`fileExists` false): say so. Narrow and Fresh set still work from the block (when the round folder is gone too, the pick is drawn again from its name, the dial lines and the note). Save needs a page: offer to draw the pick again as a new round and save that one.
|
||||
- **From a saved page** (`saved` true, the File line under `specs/`): say it is already saved there. Save again only from a new round (Narrow or Fresh set), whose save asks before replacing. Its drafts are gone, so Narrow draws the pick again from its name, the dial lines and the note, and takes the request from the saved decisions file beside the page.
|
||||
- **Missing lines** (no Chosen, no Prototype): ask the person to press Copy again and paste the whole block.
|
||||
@@ -0,0 +1,170 @@
|
||||
/* Plan2Code UI prototype: the base stylesheet placed inside every variant frame.
|
||||
It implements the shared values, root attributes and marks named in
|
||||
ui-prototype-contract.md. The page's dials set the inputs on each frame's
|
||||
<html>; everything below derives from them. No rule here loads anything. */
|
||||
|
||||
/* ------------------------------------------------------------ dial inputs */
|
||||
|
||||
:root {
|
||||
/* Font sets, verbatim from Modern Font Stacks (fetched 2026-11-11). */
|
||||
--p2c-font-set-system-ui: system-ui, sans-serif;
|
||||
--p2c-font-set-humanist: Seravek, 'Gill Sans Nova', Ubuntu, Calibri, 'DejaVu Sans', source-sans-pro, sans-serif;
|
||||
--p2c-font-set-transitional: Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif;
|
||||
--p2c-font-set-slab-serif: Rockwell, 'Rockwell Nova', 'Roboto Slab', 'DejaVu Serif', 'Sitka Small', serif;
|
||||
--p2c-font-set-rounded-sans: ui-rounded, 'Hiragino Maru Gothic ProN', Quicksand, Comfortaa, Manjari, 'Arial Rounded MT', 'Arial Rounded MT Bold', Calibri, source-sans-pro, sans-serif;
|
||||
--p2c-font-set-monospace-code: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace;
|
||||
|
||||
/* Terminal palettes: background, text and accent for each theme. */
|
||||
--p2c-palette-graphite-dark-bg: #1e1f22;
|
||||
--p2c-palette-graphite-dark-fg: #d7dae0;
|
||||
--p2c-palette-graphite-dark-accent: #6cb6ff;
|
||||
--p2c-palette-graphite-light-bg: #fafafa;
|
||||
--p2c-palette-graphite-light-fg: #24292f;
|
||||
--p2c-palette-graphite-light-accent: #0969da;
|
||||
--p2c-palette-amber-dark-bg: #1a1408;
|
||||
--p2c-palette-amber-dark-fg: #ffcc66;
|
||||
--p2c-palette-amber-dark-accent: #ff9e3d;
|
||||
--p2c-palette-amber-light-bg: #fff8e8;
|
||||
--p2c-palette-amber-light-fg: #4a3200;
|
||||
--p2c-palette-amber-light-accent: #b35c00;
|
||||
--p2c-palette-phosphor-dark-bg: #0b140d;
|
||||
--p2c-palette-phosphor-dark-fg: #9ef0a8;
|
||||
--p2c-palette-phosphor-dark-accent: #3fd96b;
|
||||
--p2c-palette-phosphor-light-bg: #f2fbf3;
|
||||
--p2c-palette-phosphor-light-fg: #1d4d27;
|
||||
--p2c-palette-phosphor-light-accent: #1a7f37;
|
||||
--p2c-palette-ocean-dark-bg: #0f1b2a;
|
||||
--p2c-palette-ocean-dark-fg: #cfe3f7;
|
||||
--p2c-palette-ocean-dark-accent: #4fc1e9;
|
||||
--p2c-palette-ocean-light-bg: #f3f8fd;
|
||||
--p2c-palette-ocean-light-fg: #16324f;
|
||||
--p2c-palette-ocean-light-accent: #0b6fa4;
|
||||
|
||||
/* Defaults for every dial input; the page overrides them on the root. */
|
||||
--p2c-accent: #2f6fed;
|
||||
--p2c-neutral: #6b7280;
|
||||
--p2c-font: var(--p2c-font-set-system-ui);
|
||||
--p2c-text-size: 16px;
|
||||
--p2c-space: 1;
|
||||
--p2c-radius: 8px;
|
||||
--p2c-density: 1.4;
|
||||
/* The Screen size dial's width; a flow's screens each take it. */
|
||||
--p2c-screen-width: 390px;
|
||||
--p2c-step-width: var(--p2c-screen-width);
|
||||
|
||||
/* The spacing scale. */
|
||||
--p2c-space-1: calc(var(--p2c-space) * 4px);
|
||||
--p2c-space-2: calc(var(--p2c-space) * 8px);
|
||||
--p2c-space-3: calc(var(--p2c-space) * 12px);
|
||||
--p2c-space-4: calc(var(--p2c-space) * 16px);
|
||||
--p2c-space-5: calc(var(--p2c-space) * 24px);
|
||||
--p2c-space-6: calc(var(--p2c-space) * 32px);
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------- light and dark */
|
||||
|
||||
:root,
|
||||
:root[data-p2c-theme="light"] {
|
||||
color-scheme: light;
|
||||
--p2c-bg: color-mix(in srgb, var(--p2c-neutral) 5%, #ffffff);
|
||||
--p2c-surface: color-mix(in srgb, var(--p2c-neutral) 1%, #ffffff);
|
||||
--p2c-text: color-mix(in srgb, var(--p2c-neutral) 20%, #0d0e10);
|
||||
--p2c-muted: color-mix(in srgb, var(--p2c-neutral) 85%, #000000);
|
||||
--p2c-border: color-mix(in srgb, var(--p2c-neutral) 28%, #ffffff);
|
||||
--p2c-on-accent: color-mix(in srgb, var(--p2c-accent) 4%, #ffffff);
|
||||
--p2c-term-bg: var(--p2c-palette-graphite-light-bg);
|
||||
--p2c-term-fg: var(--p2c-palette-graphite-light-fg);
|
||||
--p2c-term-accent: var(--p2c-palette-graphite-light-accent);
|
||||
}
|
||||
|
||||
:root[data-p2c-theme="dark"] {
|
||||
color-scheme: dark;
|
||||
--p2c-bg: color-mix(in srgb, var(--p2c-neutral) 12%, #0b0c0e);
|
||||
--p2c-surface: color-mix(in srgb, var(--p2c-neutral) 18%, #121316);
|
||||
--p2c-text: color-mix(in srgb, var(--p2c-neutral) 10%, #f4f5f7);
|
||||
--p2c-muted: color-mix(in srgb, var(--p2c-neutral) 70%, #ffffff);
|
||||
--p2c-border: color-mix(in srgb, var(--p2c-neutral) 35%, #17181b);
|
||||
--p2c-on-accent: color-mix(in srgb, var(--p2c-accent) 4%, #ffffff);
|
||||
--p2c-term-bg: var(--p2c-palette-graphite-dark-bg);
|
||||
--p2c-term-fg: var(--p2c-palette-graphite-dark-fg);
|
||||
--p2c-term-accent: var(--p2c-palette-graphite-dark-accent);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------- body */
|
||||
|
||||
*,
|
||||
*::before,
|
||||
*::after {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
margin: 0;
|
||||
font-family: var(--p2c-font);
|
||||
font-size: var(--p2c-text-size);
|
||||
line-height: 1.5;
|
||||
background: var(--p2c-bg);
|
||||
color: var(--p2c-text);
|
||||
}
|
||||
|
||||
img {
|
||||
max-width: 100%;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------- states and text length */
|
||||
|
||||
/* A mark holds one value or several separated by spaces; only the parts whose
|
||||
list holds the root's value show. Unmarked parts always show. */
|
||||
:root[data-p2c-state="ready"] [data-p2c-when]:not([data-p2c-when~="ready"]),
|
||||
:root[data-p2c-state="empty"] [data-p2c-when]:not([data-p2c-when~="empty"]),
|
||||
:root[data-p2c-state="loading"] [data-p2c-when]:not([data-p2c-when~="loading"]),
|
||||
:root[data-p2c-state="error"] [data-p2c-when]:not([data-p2c-when~="error"]),
|
||||
:root[data-p2c-length="short"] [data-p2c-text]:not([data-p2c-text~="short"]),
|
||||
:root[data-p2c-length="typical"] [data-p2c-text]:not([data-p2c-text~="typical"]),
|
||||
:root[data-p2c-length="long"] [data-p2c-text]:not([data-p2c-text~="long"]) {
|
||||
display: none !important;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------- flow */
|
||||
|
||||
:root[data-p2c-kind="flow"] body {
|
||||
display: flex;
|
||||
flex-wrap: nowrap;
|
||||
align-items: flex-start;
|
||||
gap: var(--p2c-space-6);
|
||||
padding: var(--p2c-space-5);
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
:root[data-p2c-kind="flow"] [data-p2c-step] {
|
||||
flex: 0 0 auto;
|
||||
width: var(--p2c-step-width);
|
||||
position: relative;
|
||||
margin-top: calc(var(--p2c-text-size) * 2);
|
||||
}
|
||||
|
||||
:root[data-p2c-kind="flow"] [data-p2c-step]::before {
|
||||
content: attr(data-p2c-step);
|
||||
position: absolute;
|
||||
bottom: 100%;
|
||||
left: 0;
|
||||
padding-bottom: var(--p2c-space-2);
|
||||
font-size: 0.8em;
|
||||
font-weight: 600;
|
||||
color: var(--p2c-muted);
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- terminal */
|
||||
|
||||
:root[data-p2c-kind="terminal"] {
|
||||
--p2c-font: var(--p2c-font-set-monospace-code);
|
||||
}
|
||||
|
||||
:root[data-p2c-kind="terminal"] body {
|
||||
font-family: var(--p2c-font-set-monospace-code);
|
||||
background: var(--p2c-term-bg);
|
||||
color: var(--p2c-term-fg);
|
||||
line-height: var(--p2c-density);
|
||||
padding: 0.5ch 1ch;
|
||||
}
|
||||
@@ -0,0 +1,582 @@
|
||||
/* Plan2Code UI prototype: the tool's own look (top bar, backdrop, frames,
|
||||
floating panel). It never styles a variant: each variant lives in its own
|
||||
frame with base.css, and every value here is a --tool- one. Long-supported
|
||||
features only (no nesting, no @scope, no light-dark()): the page is checked
|
||||
by hand in Firefox and Safari. */
|
||||
|
||||
:root {
|
||||
--tool-bar-h: 48px;
|
||||
--tool-backdrop: #d5d8dd;
|
||||
--tool-bar-bg: #ffffff;
|
||||
--tool-surface: #ffffff;
|
||||
--tool-surface-2: #f3f4f6;
|
||||
--tool-text: #1f2328;
|
||||
--tool-muted: #5c6370;
|
||||
--tool-line: #c9cdd3;
|
||||
--tool-line-soft: #e3e5e9;
|
||||
--tool-focus: #1d5fd1;
|
||||
--tool-pick: #1f2328;
|
||||
--tool-on-pick: #ffffff;
|
||||
--tool-shadow: 0 1px 2px rgba(15, 18, 24, 0.12), 0 8px 24px rgba(15, 18, 24, 0.14);
|
||||
--tool-frame-shadow: 0 1px 3px rgba(15, 18, 24, 0.18), 0 6px 18px rgba(15, 18, 24, 0.1);
|
||||
--tool-font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
|
||||
--tool-mono: ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
|
||||
--tool-radius: 8px;
|
||||
--tool-panel-w: 300px;
|
||||
}
|
||||
|
||||
html,
|
||||
body {
|
||||
margin: 0;
|
||||
height: 100%;
|
||||
overflow: hidden;
|
||||
background: var(--tool-backdrop);
|
||||
color: var(--tool-text);
|
||||
font-family: var(--tool-font);
|
||||
font-size: 13px;
|
||||
line-height: 1.4;
|
||||
}
|
||||
|
||||
*,
|
||||
*::before,
|
||||
*::after {
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
[hidden] {
|
||||
display: none !important;
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- controls */
|
||||
|
||||
.tool-button {
|
||||
font: inherit;
|
||||
color: var(--tool-text);
|
||||
background: var(--tool-surface);
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: 6px;
|
||||
padding: 5px 12px;
|
||||
cursor: pointer;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.tool-button:hover {
|
||||
background: var(--tool-surface-2);
|
||||
}
|
||||
|
||||
.tool-button[aria-pressed="true"] {
|
||||
background: var(--tool-pick);
|
||||
border-color: var(--tool-pick);
|
||||
color: var(--tool-on-pick);
|
||||
}
|
||||
|
||||
.tool-primary {
|
||||
background: var(--tool-pick);
|
||||
border-color: var(--tool-pick);
|
||||
color: var(--tool-on-pick);
|
||||
}
|
||||
|
||||
.tool-primary:hover {
|
||||
background: #3a3f47;
|
||||
}
|
||||
|
||||
.tool-small {
|
||||
padding: 2px 8px;
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
button:focus-visible,
|
||||
input:focus-visible,
|
||||
select:focus-visible,
|
||||
[role="tab"]:focus-visible {
|
||||
outline: 2px solid var(--tool-focus);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------- the top bar */
|
||||
|
||||
#p2c-bar {
|
||||
position: fixed;
|
||||
top: 0;
|
||||
left: 0;
|
||||
right: 0;
|
||||
z-index: 30;
|
||||
height: var(--tool-bar-h);
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 12px;
|
||||
padding: 0 16px;
|
||||
background: var(--tool-bar-bg);
|
||||
border-bottom: 1px solid var(--tool-line);
|
||||
}
|
||||
|
||||
.tool-name {
|
||||
font-weight: 650;
|
||||
font-size: 14px;
|
||||
max-width: 220px;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
white-space: nowrap;
|
||||
flex: 0 1 auto;
|
||||
}
|
||||
|
||||
.tool-tabs {
|
||||
display: flex;
|
||||
gap: 4px;
|
||||
min-width: 0;
|
||||
flex: 0 1 auto;
|
||||
overflow-x: auto;
|
||||
}
|
||||
|
||||
.tool-tab {
|
||||
font: inherit;
|
||||
color: var(--tool-muted);
|
||||
background: transparent;
|
||||
border: 1px solid transparent;
|
||||
border-radius: 6px;
|
||||
padding: 5px 10px;
|
||||
cursor: pointer;
|
||||
white-space: nowrap;
|
||||
max-width: 200px;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.tool-tab:hover {
|
||||
background: var(--tool-surface-2);
|
||||
color: var(--tool-text);
|
||||
}
|
||||
|
||||
.tool-tab[aria-selected="true"] {
|
||||
color: var(--tool-text);
|
||||
background: var(--tool-surface-2);
|
||||
border-color: var(--tool-line);
|
||||
}
|
||||
|
||||
.tool-tab-letter {
|
||||
font-weight: 700;
|
||||
margin-right: 6px;
|
||||
}
|
||||
|
||||
.tool-spacer {
|
||||
flex: 1 1 0;
|
||||
}
|
||||
|
||||
/* --------------------------------------------------- the backdrop and frames */
|
||||
|
||||
#p2c-stage {
|
||||
position: fixed;
|
||||
top: var(--tool-bar-h);
|
||||
left: 0;
|
||||
right: 0;
|
||||
bottom: 0;
|
||||
overflow: auto;
|
||||
background: var(--tool-backdrop);
|
||||
}
|
||||
|
||||
.tool-sizer {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
left: 0;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.p2c-frame {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
left: 0;
|
||||
display: block;
|
||||
/* The width set on a frame is its inside: what a variant's @media sees. */
|
||||
box-sizing: content-box;
|
||||
border: 1px solid var(--tool-line);
|
||||
background: #ffffff;
|
||||
box-shadow: var(--tool-frame-shadow);
|
||||
transform-origin: 0 0;
|
||||
}
|
||||
|
||||
.p2c-frame.tool-away {
|
||||
visibility: hidden;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.p2c-frame.tool-current-frame {
|
||||
border-color: #8a9099;
|
||||
}
|
||||
|
||||
.tool-compare .p2c-frame {
|
||||
/* In the row a click picks the variant, so the frame does not take it. */
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.tool-compare #p2c-stage {
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.tool-compare .p2c-frame.tool-current-frame {
|
||||
outline: 3px solid var(--tool-focus);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
.tool-label {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
left: 0;
|
||||
font: inherit;
|
||||
font-size: 12px;
|
||||
color: var(--tool-text);
|
||||
background: transparent;
|
||||
border: 0;
|
||||
padding: 2px 0;
|
||||
cursor: pointer;
|
||||
text-align: left;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.tool-label[aria-current="true"] {
|
||||
font-weight: 700;
|
||||
color: var(--tool-focus);
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------- the floating panel */
|
||||
|
||||
.tool-panel {
|
||||
position: fixed;
|
||||
top: calc(var(--tool-bar-h) + 16px);
|
||||
left: 16px;
|
||||
z-index: 20;
|
||||
width: var(--tool-panel-w);
|
||||
max-width: 320px;
|
||||
max-height: calc(100vh - var(--tool-bar-h) - 24px);
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
background: var(--tool-surface);
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: var(--tool-radius);
|
||||
box-shadow: var(--tool-shadow);
|
||||
}
|
||||
|
||||
.tool-panel-head {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
padding: 8px 10px;
|
||||
border-bottom: 1px solid var(--tool-line-soft);
|
||||
cursor: grab;
|
||||
user-select: none;
|
||||
touch-action: none;
|
||||
}
|
||||
|
||||
.tool-panel-head.tool-dragging {
|
||||
cursor: grabbing;
|
||||
}
|
||||
|
||||
.tool-grip {
|
||||
width: 10px;
|
||||
height: 14px;
|
||||
border-left: 2px dotted var(--tool-muted);
|
||||
border-right: 2px dotted var(--tool-muted);
|
||||
}
|
||||
|
||||
.tool-panel-title {
|
||||
flex: 1 1 auto;
|
||||
margin: 0;
|
||||
font-size: 13px;
|
||||
font-weight: 650;
|
||||
}
|
||||
|
||||
.tool-panel-body {
|
||||
overflow-y: auto;
|
||||
padding: 6px 12px 12px;
|
||||
}
|
||||
|
||||
.tool-dials-tab {
|
||||
position: fixed;
|
||||
z-index: 20;
|
||||
box-shadow: var(--tool-shadow);
|
||||
}
|
||||
|
||||
/* --------------------------------------------------------------- dial rows */
|
||||
|
||||
.tool-row {
|
||||
display: grid;
|
||||
grid-template-columns: 1fr auto;
|
||||
align-items: center;
|
||||
gap: 4px 8px;
|
||||
padding: 7px 0;
|
||||
border-bottom: 1px solid var(--tool-line-soft);
|
||||
}
|
||||
|
||||
.tool-row:last-child {
|
||||
border-bottom: 0;
|
||||
}
|
||||
|
||||
.tool-row-label {
|
||||
font-weight: 600;
|
||||
color: var(--tool-text);
|
||||
}
|
||||
|
||||
.tool-row-side {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 6px;
|
||||
color: var(--tool-muted);
|
||||
font-family: var(--tool-mono);
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
.tool-row-control {
|
||||
grid-column: 1 / -1;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.tool-row-control input[type="range"] {
|
||||
flex: 1 1 auto;
|
||||
min-width: 0;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.tool-row-control input[type="color"] {
|
||||
width: 40px;
|
||||
height: 26px;
|
||||
padding: 0 2px;
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: 4px;
|
||||
background: var(--tool-surface);
|
||||
}
|
||||
|
||||
.tool-row-control input[type="text"],
|
||||
.tool-row-control select {
|
||||
flex: 1 1 auto;
|
||||
min-width: 0;
|
||||
font: inherit;
|
||||
padding: 4px 6px;
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: 4px;
|
||||
background: var(--tool-surface);
|
||||
color: var(--tool-text);
|
||||
}
|
||||
|
||||
.tool-seg {
|
||||
display: flex;
|
||||
flex: 1 1 auto;
|
||||
min-width: 0;
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: 6px;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.tool-seg button {
|
||||
flex: 1 1 0;
|
||||
min-width: 0;
|
||||
font: inherit;
|
||||
font-size: 12px;
|
||||
padding: 4px 4px;
|
||||
border: 0;
|
||||
border-right: 1px solid var(--tool-line);
|
||||
background: var(--tool-surface);
|
||||
color: var(--tool-text);
|
||||
cursor: pointer;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.tool-seg button:last-child {
|
||||
border-right: 0;
|
||||
}
|
||||
|
||||
.tool-seg button[aria-pressed="true"] {
|
||||
background: var(--tool-pick);
|
||||
color: var(--tool-on-pick);
|
||||
}
|
||||
|
||||
.tool-switch {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.tool-switch input {
|
||||
margin: 0;
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
}
|
||||
|
||||
.tool-scale {
|
||||
color: var(--tool-muted);
|
||||
}
|
||||
|
||||
.tool-reset {
|
||||
display: inline-flex;
|
||||
}
|
||||
|
||||
.tool-reset-button {
|
||||
font: inherit;
|
||||
font-family: var(--tool-font);
|
||||
font-size: 11px;
|
||||
color: var(--tool-focus);
|
||||
background: transparent;
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: 4px;
|
||||
padding: 0 6px;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.tool-reset-button:hover {
|
||||
background: var(--tool-surface-2);
|
||||
}
|
||||
|
||||
.tool-own {
|
||||
font-family: var(--tool-font);
|
||||
font-size: 11px;
|
||||
color: var(--tool-muted);
|
||||
background: var(--tool-surface-2);
|
||||
border: 1px solid var(--tool-line-soft);
|
||||
border-radius: 999px;
|
||||
padding: 0 6px;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------- presets, extras, foot */
|
||||
|
||||
.tool-presets {
|
||||
display: flex;
|
||||
gap: 4px;
|
||||
padding: 6px 0 8px;
|
||||
border-bottom: 1px solid var(--tool-line-soft);
|
||||
}
|
||||
|
||||
.tool-presets .tool-button {
|
||||
flex: 1 1 0;
|
||||
min-width: 0;
|
||||
padding-left: 4px;
|
||||
padding-right: 4px;
|
||||
}
|
||||
|
||||
.tool-dials .tool-row:last-child {
|
||||
border-bottom: 1px solid var(--tool-line-soft);
|
||||
}
|
||||
|
||||
.tool-extras {
|
||||
padding: 4px 0;
|
||||
border-bottom: 1px solid var(--tool-line-soft);
|
||||
}
|
||||
|
||||
.tool-extras-title {
|
||||
font-weight: 650;
|
||||
padding: 6px 0;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
.tool-panel-foot {
|
||||
display: flex;
|
||||
gap: 8px;
|
||||
padding-top: 10px;
|
||||
}
|
||||
|
||||
.tool-panel-foot .tool-button {
|
||||
flex: 1 1 0;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------- the Copy popover */
|
||||
|
||||
.tool-pop {
|
||||
position: fixed;
|
||||
top: calc(var(--tool-bar-h) + 8px);
|
||||
right: 16px;
|
||||
z-index: 40;
|
||||
width: 420px;
|
||||
max-width: calc(100vw - 32px);
|
||||
max-height: calc(100vh - var(--tool-bar-h) - 24px);
|
||||
overflow-y: auto;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 6px;
|
||||
padding: 12px;
|
||||
background: var(--tool-surface);
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: var(--tool-radius);
|
||||
box-shadow: var(--tool-shadow);
|
||||
}
|
||||
|
||||
.tool-pop-label {
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.tool-pop-hint {
|
||||
font-weight: 400;
|
||||
color: var(--tool-muted);
|
||||
}
|
||||
|
||||
.tool-pop textarea {
|
||||
width: 100%;
|
||||
font: inherit;
|
||||
color: var(--tool-text);
|
||||
background: var(--tool-surface);
|
||||
border: 1px solid var(--tool-line);
|
||||
border-radius: 4px;
|
||||
padding: 6px 8px;
|
||||
resize: vertical;
|
||||
}
|
||||
|
||||
#p2c-block {
|
||||
font-family: var(--tool-mono);
|
||||
font-size: 12px;
|
||||
background: var(--tool-surface-2);
|
||||
white-space: pre;
|
||||
}
|
||||
|
||||
.tool-pop-foot {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
}
|
||||
|
||||
.tool-pop-status {
|
||||
flex: 1 1 auto;
|
||||
color: var(--tool-muted);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------- the terminal window */
|
||||
|
||||
.tool-term-title {
|
||||
position: absolute;
|
||||
top: 0;
|
||||
left: 0;
|
||||
height: 24px;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 8px;
|
||||
padding: 0 10px;
|
||||
background: #2b2d31;
|
||||
color: #d7dae0;
|
||||
font-family: var(--tool-mono);
|
||||
font-size: 12px;
|
||||
border-radius: 6px 6px 0 0;
|
||||
overflow: hidden;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
.tool-term-title.tool-away {
|
||||
visibility: hidden;
|
||||
}
|
||||
|
||||
.tool-term-dots {
|
||||
flex: 0 0 auto;
|
||||
width: 34px;
|
||||
height: 10px;
|
||||
background: radial-gradient(circle at 5px 5px, #ff5f57 4px, transparent 4.5px), radial-gradient(circle at 17px 5px, #febc2e 4px, transparent 4.5px), radial-gradient(circle at 29px 5px, #28c840 4px, transparent 4.5px);
|
||||
}
|
||||
|
||||
.tool-term-name {
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
<!doctype html>
|
||||
<!--
|
||||
Plan2Code UI prototype page shell. ui-prototype.mjs assemble fills three
|
||||
placeholders, each a comment alone on its line:
|
||||
p2c:tool-styles the tool styles (shell.css) in a <style>
|
||||
p2c:frames one sandboxed iframe per variant
|
||||
p2c:script the round facts (JSON) and the tool script (shell.js)
|
||||
Everything else here is the tool part of the page, the same for every round.
|
||||
-->
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; img-src data:; font-src data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>UI prototype</title>
|
||||
<!-- p2c:tool-styles -->
|
||||
</head>
|
||||
<body>
|
||||
<header id="p2c-bar">
|
||||
<span id="p2c-name" class="tool-name">UI prototype</span>
|
||||
<div id="p2c-tabs" class="tool-tabs" role="tablist" aria-label="Variants"></div>
|
||||
<span class="tool-spacer"></span>
|
||||
<button type="button" id="p2c-compare" class="tool-button" aria-pressed="false">Compare all</button>
|
||||
<button type="button" id="p2c-copy" class="tool-button tool-primary">Copy</button>
|
||||
</header>
|
||||
<div id="p2c-copy-pop" class="tool-pop" role="dialog" aria-label="Copy your choice" hidden>
|
||||
<label for="p2c-note" class="tool-pop-label">Note <span class="tool-pop-hint">(optional)</span></label>
|
||||
<textarea id="p2c-note" rows="2" placeholder="For example: the header from A with these cards"></textarea>
|
||||
<label for="p2c-block" class="tool-pop-label">What gets copied</label>
|
||||
<textarea id="p2c-block" rows="12" readonly spellcheck="false"></textarea>
|
||||
<div class="tool-pop-foot">
|
||||
<span id="p2c-copy-status" class="tool-pop-status" role="status" aria-live="polite"></span>
|
||||
<button type="button" id="p2c-copy-block" class="tool-button tool-primary">Copy block</button>
|
||||
<button type="button" id="p2c-copy-close" class="tool-button">Close</button>
|
||||
</div>
|
||||
</div>
|
||||
<main id="p2c-stage" aria-label="Variants">
|
||||
<!-- p2c:frames -->
|
||||
</main>
|
||||
<aside id="p2c-panel" class="tool-panel" aria-labelledby="p2c-panel-title">
|
||||
<div id="p2c-panel-handle" class="tool-panel-head">
|
||||
<span class="tool-grip" aria-hidden="true"></span>
|
||||
<h2 id="p2c-panel-title" class="tool-panel-title">Dials</h2>
|
||||
<button type="button" id="p2c-hide" class="tool-button tool-small">Hide</button>
|
||||
</div>
|
||||
<div id="p2c-panel-body" class="tool-panel-body"></div>
|
||||
</aside>
|
||||
<button type="button" id="p2c-dials-tab" class="tool-button tool-dials-tab" hidden>Dials</button>
|
||||
<!-- p2c:script -->
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,145 @@
|
||||
# 🎨 UI PROTOTYPE MODE
|
||||
|
||||
Start all UI PROTOTYPE MODE responses with '🎨 [UI PROTOTYPE]'
|
||||
|
||||
## Role
|
||||
|
||||
Product designer who shows several real options instead of describing them. Draws two to five variants of a screen, a flow or a terminal screen on one page the person opens in their browser, tunes with live dials and hands back with Copy and a paste. **Never builds production code**: a prototype is a reference that Plan and Implement build from.
|
||||
|
||||
## Interface
|
||||
|
||||
The FIRST thing you do, before anything else in this file, before running a script: ask **web console** (browser page, suggested) or **terminal**? Console → run `node "<D>/console.mjs" open --workflow ui-prototype` before reading (<D>: references/web-console/ beside this SKILL.md (~/.agents/skills/plan2code-ui-prototype/references/web-console/ globally) or the dir in ~/.plan2code/console/console-dir), then read <D>/console.md and <D>/notes/ui-prototype.md. The starting screen, the paste, the next steps and the save questions all go through it; the prototype itself always opens as its own browser tab. Switchable anytime. If the argument already says which (`--web` or `Use the web console for this session.`), take it and do not ask; drop the flag. Launched by the dashboard? Its session is already open: resume it (console-launches.md), then Project Context.
|
||||
|
||||
## Run from another skill
|
||||
|
||||
When this file is `references/ui-prototype.md` inside Pathfinder, Plan, Revise plan or Quick Task (the host), run Steps 1 to 7 in the same conversation, with these changes:
|
||||
|
||||
- `<S>` is the host's `scripts/` folder (`../scripts/` from this file); the references below are the files beside this one.
|
||||
- Skip Interface (use the host's console session, or its terminal), Project Context's `AGENTS.md` read (the host has done it) and Step 7's folder list.
|
||||
- On the console, read `<D>/notes/ui-prototype.md` once for its cards (the host's `<D>`); its finish is the host's, not yours.
|
||||
- A save goes into the host's spec folder. Quick Task has none: it saves only when the person asks, and then offers the folder list.
|
||||
- When the person picks Done, or after a save, return to the host at the step that made the offer, handing it the read-back of the block and, when saved, the two paths (`html`, `md`). The host records the choice in its own place.
|
||||
|
||||
## Project Context
|
||||
|
||||
Read `./AGENTS.md` when it exists: its stack, its style files and its conventions help Step 1 find the look. Its absence does not block this skill.
|
||||
|
||||
## Scripts
|
||||
|
||||
`<S>` is `scripts/` beside this SKILL.md (`~/.agents/skills/plan2code-ui-prototype/scripts/` globally). Run from the project root. Each prints one JSON object; on a non-zero exit read `message` and do what `next` says. Exit codes: 0 ok, 3 not found, 4 invalid (or `check` findings), 5 refused.
|
||||
|
||||
- `node "<S>/ui-prototype.mjs" sweep --project .`: deletes this project's drafts older than 30 days. Prints `draftsDir`, `removed`.
|
||||
- `node "<S>/ui-prototype.mjs" new-round --project . --name <name>`: the next round's folder in the drafts. Prints `round`, `folder`, `page`.
|
||||
- `node "<S>/ui-prototype.mjs" assemble --round <folder>`: builds the page from `round.json` and the variant files. Prints `file`, `bytes`, `parts` (largest first), `warnings`. Exit 3 a file missing, 4 a field malformed (the message names it).
|
||||
- `node "<S>/ui-prototype.mjs" check --file <page>`: checks the page. Prints `findings` (`rule`, `variant`, `message`), `bytes`, `overCeiling`. Exit 4 with findings.
|
||||
- `node "<S>/ui-prototype.mjs" open --file <page>`: opens it in the default browser. Prints `opened`, `path`, `reason`. Exit 5 for a page outside the drafts and `specs/`.
|
||||
- `node "<S>/ui-prototype.mjs" read-block --project .` (the block on stdin): prints `fields`, `latest`, `fileExists`, `saved`. Exit 3 when the first line is not `Plan2Code UI prototype choice`.
|
||||
- `node "<S>/ui-prototype.mjs" save --file <page> --spec specs/<name> --name <name> --block <file> --request <text> --rejected <file> [--replace]`: writes `specs/<name>/prototypes/<name>.html` and `.md` and removes that prototype's drafts. Prints `html`, `md`, `removedDrafts`. Exit 5 for a target outside `specs/`, a page outside the drafts, or (error `exists`) a saved pair already there.
|
||||
|
||||
## References
|
||||
|
||||
- `references/ui-prototype-design.md`: how to make each variant look designed. Read it at Step 3.
|
||||
- `references/ui-prototype-contract.md`: the rules a variant file and `round.json` follow. Read it at Step 4.
|
||||
- `references/ui-prototype-rounds.md`: the four next steps after a paste. Read it at Step 6, right after `read-block`.
|
||||
|
||||
## Rules
|
||||
|
||||
- **Nothing is built into the project.** Before a save the only files you write are in the round folder `new-round` gives (outside the project); a save writes only under `specs/`.
|
||||
- **The page loads nothing from the network**: no web fonts, icon sets, scripts, styles or remote images. Icons are small inline drawings.
|
||||
- **Never edit the page's tool part** (the top bar, dials, Copy) or the assembled page. Fix a variant file and assemble again.
|
||||
- **No round before the starting screen is answered.**
|
||||
- **Read the app, never run it**: source files and the person's screenshots only; no build, no start.
|
||||
- Plain words for product and design people: say variant, dial, carry over, freed up. Never use developer words for the page's parts.
|
||||
- US English. No em dashes in anything you write.
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Start
|
||||
|
||||
1. Run `sweep --project .` silently.
|
||||
2. **The kind.** From the request: a **screen**, a **flow** (several screens of one journey, shown side by side, not linked) or a **terminal** screen. Ask only when it cannot be told.
|
||||
3. **What can be carried over.** Read source files only: stylesheets, theme and config files (a Tailwind or theme config, CSS custom properties, design files), and component files. For each of the five items (colors, fonts, spacing, components, layout) note what you found and where (`src/styles/theme.css`: accent #0f766e, gray #64748b), or "none found". Note the app's own font files when it ships some (at most 4, 2 MB together). A project with no screens yet skips the checklist: say you found no existing look and start fresh.
|
||||
|
||||
### Step 2: The starting screen
|
||||
|
||||
Ask one screen, answered together:
|
||||
|
||||
1. **Carry over from your app.** The five items, each with what was found, all ticked to start. An item not found shows unticked and marked "none found", so the person knows the variants invent it. Skipped for a project with no screens.
|
||||
2. **How different should the variants be?** Subtle, **Balanced** (when left alone), Radical.
|
||||
3. **A direction** (optional): one box for anything all variants stay inside ("calmer colors, bigger type").
|
||||
4. **Images** (optional): attach them (console: the card's Attach file control; terminal: file paths in the reply).
|
||||
|
||||
Three variants unless the person asks for more or fewer: up to 5, never fewer than 2. Raise the count only if they do.
|
||||
|
||||
After the answer, say in one line per image what you took it for: **in the page** (a logo, a photo) or **a look to match** (a screenshot of their app). They may correct it before you draw. A look to match is read, never kept or placed in the page. In-page images: PNG, JPEG, WebP or SVG; name and skip any other type.
|
||||
|
||||
### Step 3: Plan the round
|
||||
|
||||
Read `references/ui-prototype-design.md` now; without it: give each variant a different structure, real content, and all four states.
|
||||
|
||||
- **Ticked items** look the same in every variant: they set where their dials start, and every variant takes them from the shared values only.
|
||||
- **An unticked item** is where each variant tries its own take, steered by the direction and the "how different" level, each with its own dial starts.
|
||||
- **A "none found" item**: you pick one shared start for its dials, and each variant invents the rest.
|
||||
- With no existing look, every item is unticked.
|
||||
|
||||
Choose up to about four extras that fit this screen (shadows, motion, column count, row dividers, and the like), each a slider, a pick or a toggle, and say in one line which you added. Name each variant with a letter and two or three plain words ("A Dense table"). Write each variant's plan as the design reference says before any HTML.
|
||||
|
||||
### Step 4: Write the round
|
||||
|
||||
Read `references/ui-prototype-contract.md` before writing any variant (its "Writing a round" section is the order of work).
|
||||
|
||||
1. Pick the prototype's name: lowercase words joined by hyphens (`invoices-screen`).
|
||||
2. `new-round --project . --name <name>`. Write `round.json` (images and app fonts by absolute path) and one `variant-<letter>.html` per variant into the `folder` it returns, with `round.json`'s `name` and `round` as it printed them (a copied `round.json` gets the new number). This is the only place you write.
|
||||
3. `assemble --round <folder>`, then `check --file <file>`.
|
||||
4. **Findings:** fix only the named variant files, then assemble and check again, once, without asking. Still findings: keep the page and prepare one plain line saying what is wrong with it ("Variant B has no error state drawn"). Never a second silent retry.
|
||||
5. **Size:** when `assemble` warns or `overCeiling` is true, say how big the page is and what takes the space (its `parts`, largest first). It never blocks.
|
||||
|
||||
### Step 5: Look, then show
|
||||
|
||||
1. **Look first.** When you have a browser tool: say you are looking at the page first (it adds a wait), open the page with it, press Hide on the Dials panel so it covers nothing, look at each variant once (its tab), and fix what is plainly wrong (text spilling out, a state that does not show, unreadable contrast) through the variant files and a new `assemble` and `check`, never the page itself. Without one: say in one line that you could not look at the page yourself.
|
||||
2. **Open it:** `open --file <page>`. Always give the page's path. When `opened` is false, say why (`reason`: a remote session, no browser, browsers switched off) and that the file can be opened by hand.
|
||||
3. **Close with three lines:** what each variant is; which extras were added; how to hand the choice back: "Tune it, press Copy, and paste the block here." Add the plain line from Step 4 when a page still has findings.
|
||||
4. On the console, put up a card to paste into.
|
||||
|
||||
### Step 6: The paste
|
||||
|
||||
Any message whose first line is `Plan2Code UI prototype choice` is a block (on the console it arrives after the paste card's title: drop that prefix and the indent, `notes/ui-prototype.md`). Pipe it to `read-block --project .`, then read `references/ui-prototype-rounds.md` before you answer (its "Unusual blocks" covers lines it does not know, a missing line, a saved page).
|
||||
|
||||
1. When `latest` is false, say first that it is from an older round (its Round line) and ask whether to carry on from it. When `fileExists` is false, say the page it names is gone; the block alone is still enough to go on.
|
||||
2. **Read it back** in a line or two: the chosen variant, what was changed (each line marked "changed from"), the note.
|
||||
3. Offer four next steps:
|
||||
1. **Save**: keep the page and a decisions file in a spec folder
|
||||
2. **Narrow from my pick**: your pick with the note applied, plus two close alternatives
|
||||
3. **Fresh set**: new variants, same brief
|
||||
4. **Done**: keep nothing; the draft stays for 30 days
|
||||
|
||||
Do nothing before the person picks. Narrow and Fresh set go back to Step 4 with a new round, as the rounds reference says.
|
||||
|
||||
### Step 7: Save
|
||||
|
||||
1. **Where.** List the existing spec folders (the folders under `specs/`, the launched one first) plus **New spec**, which asks for a short name. Run from another skill: that skill's spec folder, no list.
|
||||
2. **The name.** Propose a short lowercase hyphenated name from what the prototype is (`invoices-screen`); the person may change it.
|
||||
3. **Why the others lost.** Ask in one line why each variant not chosen lost, unless they already said.
|
||||
4. **Write and save.** In the round folder (`round-<N>` beside the page the block's File line names; the rounds reference) write the pasted block as `choice.txt` and one line per variant not chosen as `rejected.txt` (`A "Dense table": a table with overdue rows tinted; too crowded for a phone`). Run `save --file <page> --spec specs/<folder> --name <name> --block <round folder>/choice.txt --request "<the request from round.json>" --rejected <round folder>/rejected.txt`, where `<page>` is the page of the round the block came from.
|
||||
5. **Exit 5 with error `exists`:** ask whether to replace the saved pair; run again with `--replace` only on a yes, otherwise ask for another name.
|
||||
|
||||
## Session End
|
||||
|
||||
Work summary: what was prototyped, how many rounds, the variant chosen, and the files saved (or that nothing was kept, with the draft's path).
|
||||
|
||||
After a save, give the two saved paths, and one line that a project ignoring `specs/` in git will not commit them. Next step, whichever fits:
|
||||
|
||||
- The prototype settles what to build → "Next (NEW conversation): `/plan2code-1-plan` with `specs/<folder>/` as its brief."
|
||||
- Much is still open → "Next (NEW conversation): `/plan2code-0-pathfinder` with `specs/<folder>/` as its notes."
|
||||
|
||||
Done without a save: "Prototype done. The draft stays for 30 days at `<page>`."
|
||||
|
||||
On the console this is the `finish`.
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
╲│ ★ │╱
|
||||
│ ◡ │ Prototype done!
|
||||
╰┬─┬╯
|
||||
```
|
||||
+8
-7
@@ -36,7 +36,7 @@ The page draws the cards itself — you never send the list. It also knows the r
|
||||
- `building` ("Building"): Implement is next.
|
||||
- `built` ("Ready to finalize"): Finalize is next.
|
||||
- A `documented` or `building` spec whose `[/]` phase file holds a waiting `**Plan change:**` line in its Notes (Implement paused for a revision; `(applied <date>):` or `(dropped <date>):` means done): recommend Revise the plan instead, `details` "Plan change waiting from Phase N". The Revise card is lit on a `built` spec too (a change found in the last manual checks): recommend it there only for a waiting brief, and say so in `note`; otherwise Finalize stays the next step.
|
||||
- A spec that scans `unrecognized` ("files on disk") is input, not progress: its folder rides along on a Pathfinder or Plan launch as reference, and those are the only pipeline cards it lights. Read the files and recommend the fit — a settled design doc the person wrote is Plan's brief, loose notes are Pathfinder's. No skill generates such a doc; see the table below for what each one does write. Never flag Document or anything downstream of it for such a spec.
|
||||
- A spec that scans `unrecognized` ("files on disk") is input, not progress: its folder rides along on a Pathfinder or Plan launch as reference, and those are the only pipeline cards it lights. Read the files and recommend the fit — a settled design doc the person wrote is Plan's brief, loose notes are Pathfinder's. No skill generates such a doc; see the table below for what each one does write. Never flag Document or anything downstream of it for such a spec. A spec holding only saved prototypes is such input, and its folder also rides along on a Quick Task launch: Plan when the prototype settles what to build, Quick Task when what it shows is a small change, Pathfinder when much is still open.
|
||||
- A `diagnosed` spec ("Bug diagnosed") is a bug Diagnose wrote up: recommend Quick Task, or Plan when its `DIAGNOSIS-<date>.md` sizes the fix as big; its folder rides along on either launch.
|
||||
- A `fixed` spec ("Bug fixed") is a diagnosed bug Quick Task fixed but did not archive: finished, so never recommend for it or name it in the note; the picker never pre-selects one and hides it while unavailable workflows are hidden. The person archives it (Quick Task offers that once the bug is fixed) or deletes it with the picker's ✕.
|
||||
- Nothing on disk, or only `fixed` specs → `recommend: "plan2code-0-pathfinder"`; the note invites the first idea.
|
||||
@@ -54,10 +54,10 @@ Ground truth for menu notes and Ask-tab answers. For anything beyond this table,
|
||||
| --- | --- | --- |
|
||||
| init | codebase, README, agent rule files | `AGENTS.md`, `.agents-docs/AGENTS-<section>.md`; points CLAUDE.md etc. at AGENTS.md |
|
||||
| init-update | `AGENTS.md`, codebase | `AGENTS.md`, `.agents-docs/` |
|
||||
| 0-pathfinder | the idea, loose notes | `pathfinder/map.md`, `pathfinder/questions/NN-<slug>.md`; cleared → `PLAN-DRAFT-<date>.md` |
|
||||
| 1-plan | idea or `PLAN-DRAFT` | `PLAN-DRAFT-<date>.md`, `PLAN-CONVERSATION-<date>.md` |
|
||||
| 1b-revise-plan | `overview.md`, `phase-X.md`, a waiting `**Plan change:**` brief | the same, revised; the brief marked applied or dropped |
|
||||
| quick-task | the ask; a `DIAGNOSIS-*.md` when launched on one | code; the diagnosis set to `Fixed`, then the folder moved to `specs--completed/` on a yes; escalated → `PLAN-DRAFT-<date>.md` |
|
||||
| 0-pathfinder | the idea, loose notes | `pathfinder/map.md`, `pathfinder/questions/NN-<slug>.md`; cleared → `PLAN-DRAFT-<date>.md`; a UI prototype's `prototypes/<name>.html` and `<name>.md` on a yes |
|
||||
| 1-plan | idea or `PLAN-DRAFT` | `PLAN-DRAFT-<date>.md`, `PLAN-CONVERSATION-<date>.md`; a UI prototype's `prototypes/<name>.html` and `<name>.md` on a yes |
|
||||
| 1b-revise-plan | `overview.md`, `phase-X.md`, a waiting `**Plan change:**` brief | the same, revised; the brief marked applied or dropped; a UI prototype's `prototypes/<name>.html` and `<name>.md` on a yes |
|
||||
| quick-task | the ask; a `DIAGNOSIS-*.md` when launched on one; a saved prototype's `.md` and `.html` when launched on its folder | code; the diagnosis set to `Fixed`, then the folder moved to `specs--completed/` on a yes; escalated → `PLAN-DRAFT-<date>.md`; a UI prototype's `prototypes/<name>.html` and `<name>.md` only when asked |
|
||||
| 2-document | `PLAN-DRAFT`, `PLAN-CONVERSATION` (optional) | `overview.md`, `phase-X.md` |
|
||||
| 3-implement(-review) | `overview.md`, `phase-X.md` | code; `[x]` marks + completion summary in `phase-X.md`; paused for a revision, a `**Plan change:**` brief in its Notes |
|
||||
| review | spec, diff | the fixes picked; no spec writes |
|
||||
@@ -70,12 +70,13 @@ Ground truth for menu notes and Ask-tab answers. For anything beyond this table,
|
||||
| pr-prep | git diff and status, the `AGENTS.md` test map, the project's config files, the PR template | the page report and description; `PR-READINESS-<date>.md` on a yes; the `AGENTS.md` test map on a yes; no commits, no push |
|
||||
| test | the codebase, the `AGENTS.md` test map, nearby tests, coverage output when offered | new test files; the `AGENTS.md` test map on a yes; `PLAN-DRAFT-<date>.md` when escalated; no source changes |
|
||||
| dead-code | the project's source, its own dead-code tool's output, the `AGENTS.md` test map, `.plan2code-dead-code/keep.md` | code removals the person picks; `.plan2code-dead-code/keep.md`; `.plan2code-dead-code/reports/DEAD-CODE-<date>.md` and the `.gitignore` line on a yes; no commits, no staging |
|
||||
| ui-prototype | the request, the project's style and component source files, attached images | draft pages under ~/.plan2code/prototypes/; `prototypes/<name>.html` and its `.md` on a yes; no code changes |
|
||||
|
||||
## A pick arrives
|
||||
|
||||
A card click is a send whose action is `__launch`, carrying `skill`, `workflow` and, when a spec was picked, `spec`; the send also names `resume` (the command to run) and `skillFile`.
|
||||
|
||||
`__launch` names no question; like `__stop` it is about the session. `spec` is the picker's selected spec dir — present only when the launched skill takes a spec (or is Quick Task on a `diagnosed` spec) and the person picked one; absent means "start from scratch".
|
||||
`__launch` names no question; like `__stop` it is about the session. `spec` is the picker's selected spec dir — present only when the launched skill takes a spec (or is Quick Task on a `diagnosed` spec or a folder of only saved prototypes) and the person picked one; absent means "start from scratch".
|
||||
|
||||
> **Never hand this to a skill-invocation tool. Open its `SKILL.md` with your own file-read tool instead.** Every Plan2Code skill below the dashboard ships `disable-model-invocation: true` on purpose — it exists to be read and followed inline, not launched as a sub-skill — and calling one through a skill-invocation tool errors out and strands the hand-off mid-launch.
|
||||
|
||||
@@ -106,7 +107,7 @@ If `skill` is not in the table below, say so on the page and stay the dashboard.
|
||||
| plan2code-git | git | | plan2code-changelog | changelog |
|
||||
| plan2code-xray | xray | | plan2code-diagnose | diagnose |
|
||||
| plan2code-pr-prep | pr-prep | | plan2code-test | test |
|
||||
| plan2code-dead-code | dead-code | | | |
|
||||
| plan2code-dead-code | dead-code | | plan2code-ui-prototype | ui-prototype |
|
||||
|
||||
## A pick-up arrives
|
||||
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
// ui-prototype-block.mjs: read a pasted UI prototype choice block (the text
|
||||
// the page's Copy button gives, ui-prototype-contract.md) into fields.
|
||||
//
|
||||
// parseBlock(text) -> { ok: true, fields } or { ok: false } when the first line
|
||||
// is not the fixed one. A person may edit the block before pasting it, so a
|
||||
// label this file does not know is kept in fields.unknown, never refused.
|
||||
|
||||
export const FIRST_LINE = "Plan2Code UI prototype choice";
|
||||
|
||||
// The dial lines, in the order the page writes them (screen, flow and terminal).
|
||||
export const DIAL_LABELS = [
|
||||
"Screen size",
|
||||
"Window size",
|
||||
"Theme",
|
||||
"Accent color",
|
||||
"Neutral color",
|
||||
"Font set",
|
||||
"Text size",
|
||||
"Spacing",
|
||||
"Corners",
|
||||
"Palette",
|
||||
"Density",
|
||||
"State",
|
||||
"Content length",
|
||||
];
|
||||
|
||||
const CHANGED_RE = /^(.*?)\s*\(changed from (.*)\)$/;
|
||||
const PICK_RE = /^([A-E])\s+"(.*)"$/;
|
||||
|
||||
/** "value (changed from old)" -> { value, changedFrom } (changedFrom null when unchanged). */
|
||||
function changed(text) {
|
||||
const m = text.match(CHANGED_RE);
|
||||
return m ? { value: m[1], changedFrom: m[2] } : { value: text, changedFrom: null };
|
||||
}
|
||||
|
||||
/** `B "Split view"` -> { letter, name }; anything else keeps its text as the name. */
|
||||
function pick(text) {
|
||||
const m = text.trim().match(PICK_RE);
|
||||
return m ? { letter: m[1], name: m[2] } : { letter: null, name: text.trim() };
|
||||
}
|
||||
|
||||
/** "colors, fonts" -> ["colors", "fonts"]; "none" or "" -> []. */
|
||||
function list(text) {
|
||||
const t = text.trim();
|
||||
return !t || t.toLowerCase() === "none" ? [] : t.split(/\s*,\s*/).filter(Boolean);
|
||||
}
|
||||
|
||||
/** The pasted text's lines, with surrounding white space and code-fence lines taken off. */
|
||||
function blockLines(text) {
|
||||
const lines = String(text ?? "").replace(/\r\n?/g, "\n").trim().split("\n");
|
||||
while (lines.length && /^\s*(```|~~~)/.test(lines[0])) lines.shift();
|
||||
while (lines.length && /^\s*(```|~~~)/.test(lines[lines.length - 1])) lines.pop();
|
||||
while (lines.length && !lines[0].trim()) lines.shift();
|
||||
while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
|
||||
return lines;
|
||||
}
|
||||
|
||||
/** The block's text as it should be stored: fences and surrounding white space taken off. */
|
||||
export function cleanBlock(text) {
|
||||
return blockLines(text).join("\n");
|
||||
}
|
||||
|
||||
export function parseBlock(text) {
|
||||
const lines = blockLines(text);
|
||||
if (!lines.length || lines[0].trim() !== FIRST_LINE) return { ok: false };
|
||||
const fields = {
|
||||
prototype: null,
|
||||
file: null,
|
||||
round: null,
|
||||
chosen: null,
|
||||
others: [],
|
||||
carried: [],
|
||||
freed: [],
|
||||
direction: null,
|
||||
preset: null,
|
||||
dials: [],
|
||||
extras: [],
|
||||
note: null,
|
||||
unknown: [],
|
||||
};
|
||||
let last = null;
|
||||
for (const raw of lines.slice(1)) {
|
||||
const line = raw.trim();
|
||||
if (!line) continue;
|
||||
const at = line.indexOf(":");
|
||||
if (at <= 0) {
|
||||
// A line with no label: the Note carries on onto it, otherwise it is kept as is.
|
||||
if (last === "note") fields.note += `\n${line}`;
|
||||
else fields.unknown.push({ label: null, value: line });
|
||||
continue;
|
||||
}
|
||||
const label = line.slice(0, at).trim();
|
||||
const value = line.slice(at + 1).trim();
|
||||
last = null;
|
||||
if (label === "Prototype") fields.prototype = value;
|
||||
else if (label === "File") fields.file = value;
|
||||
else if (label === "Round") fields.round = /^\d+$/.test(value) ? Number(value) : value;
|
||||
else if (label === "Chosen") {
|
||||
const m = value.match(/^(.*?)\s*\(others:\s*(.*)\)$/);
|
||||
fields.chosen = pick(m ? m[1] : value);
|
||||
fields.others = m ? m[2].split(/,\s*(?=[A-E]\s+")/).map(pick) : [];
|
||||
} else if (label === "Carried over") fields.carried = list(value);
|
||||
else if (label === "Freed up") fields.freed = list(value);
|
||||
else if (label === "Direction") fields.direction = value;
|
||||
else if (label === "Preset") fields.preset = value;
|
||||
else if (label === "Note") {
|
||||
fields.note = value;
|
||||
last = "note";
|
||||
} else if (DIAL_LABELS.includes(label)) fields.dials.push({ label, ...changed(value) });
|
||||
else if (/^Extra,\s*/.test(label)) fields.extras.push({ label: label.replace(/^Extra,\s*/, ""), ...changed(value) });
|
||||
else fields.unknown.push({ label, value });
|
||||
}
|
||||
return { ok: true, fields };
|
||||
}
|
||||
@@ -0,0 +1,61 @@
|
||||
// ui-prototype-drafts.mjs: where a project's prototype drafts live.
|
||||
//
|
||||
// ~/.plan2code/prototypes/<project key>/<name>/round-N/ the round's files
|
||||
// ~/.plan2code/prototypes/<project key>/<name>/<name>-round-N.html its page
|
||||
//
|
||||
// The project key has the same shape as the web console's notepadKey(): the
|
||||
// folder's base name as a slug, then the first 12 hex characters of the SHA-256
|
||||
// of the resolved path (lowercased on Windows and Mac). It is computed here
|
||||
// because a built skill has no console source beside it to import.
|
||||
|
||||
import crypto from "node:crypto";
|
||||
import os from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
const FOLDS_CASE = process.platform === "win32" || process.platform === "darwin";
|
||||
|
||||
/** A resolved path, lowercased where the file system ignores case. */
|
||||
export const fold = (p) => {
|
||||
const resolved = path.resolve(String(p || ""));
|
||||
return FOLDS_CASE ? resolved.toLowerCase() : resolved;
|
||||
};
|
||||
|
||||
/** <home>/.plan2code/prototypes */
|
||||
export function draftsRoot() {
|
||||
return path.join(os.homedir(), ".plan2code", "prototypes");
|
||||
}
|
||||
|
||||
/** The project's folder name under the drafts root: `<slug>-<12 hex>`. */
|
||||
export function projectKey(root) {
|
||||
const slug =
|
||||
path
|
||||
.basename(path.resolve(String(root || "")))
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]+/g, "-")
|
||||
.replace(/^-+|-+$/g, "")
|
||||
.slice(0, 40)
|
||||
.replace(/-+$/, "") || "folder";
|
||||
const hash = crypto.createHash("sha256").update(fold(root)).digest("hex").slice(0, 12);
|
||||
return `${slug}-${hash}`;
|
||||
}
|
||||
|
||||
/** This project's drafts folder. */
|
||||
export function projectDrafts(root) {
|
||||
return path.join(draftsRoot(), projectKey(root));
|
||||
}
|
||||
|
||||
/** <projectDrafts>/<name>/round-<N> */
|
||||
export function roundFolder(root, name, round) {
|
||||
return path.join(projectDrafts(root), name, `round-${round}`);
|
||||
}
|
||||
|
||||
/** <projectDrafts>/<name>/<name>-round-<N>.html */
|
||||
export function pagePath(root, name, round) {
|
||||
return path.join(projectDrafts(root), name, `${name}-round-${round}.html`);
|
||||
}
|
||||
|
||||
/** True only when the resolved child is the parent or sits under it. */
|
||||
export function isInside(parent, child) {
|
||||
const rel = path.relative(fold(parent), fold(child));
|
||||
return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
|
||||
}
|
||||
@@ -0,0 +1,352 @@
|
||||
// ui-prototype-page.mjs: build a prototype page from a round and the shipped
|
||||
// shell, and unpack a built page back into its round facts and variants.
|
||||
//
|
||||
// buildPage(round, shell, media) -> { html, parts: [{ what, bytes }] }
|
||||
// round: readRound()'s result; shell: { html, css, js, base } (the text of
|
||||
// shell.html, shell.css, shell.js and base.css); media (optional): the
|
||||
// variants and images from embedImages() and the rules from embedFonts().
|
||||
// parts come largest first.
|
||||
// unpackPage(html) -> { facts, frames: { <letter>: { doc, content } }, outside }
|
||||
// or null when the text is not a prototype page. `outside` is the page with
|
||||
// every frame and the round facts taken out: the shell's own text.
|
||||
// embedImages(round) and embedFonts(round) read only the files round.json
|
||||
// lists, and turn them into data: URLs within LIMITS.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { FONT_SETS } from "./ui-prototype-round.mjs";
|
||||
|
||||
const MB = 1024 * 1024;
|
||||
|
||||
// The limits, in one place: Finalize revisits the font numbers against a real project.
|
||||
export const LIMITS = {
|
||||
image: 1 * MB, // one image; past it, a labeled placeholder
|
||||
allImages: 3 * MB, // every embedded image together; past it, a warning
|
||||
fontFiles: 4, // app font files; past either font limit, the fallback set
|
||||
fonts: 2 * MB, // app font files together
|
||||
ceiling: 5 * MB, // the whole page, a soft ceiling: a warning, never a stop
|
||||
};
|
||||
|
||||
export const IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp", "image/svg+xml"];
|
||||
export const APP_FONT = "App font";
|
||||
const APP_FAMILY = "P2C App Font";
|
||||
|
||||
const PLACEHOLDERS = {
|
||||
styles: "<!-- p2c:tool-styles -->",
|
||||
frames: "<!-- p2c:frames -->",
|
||||
script: "<!-- p2c:script -->",
|
||||
};
|
||||
|
||||
const FRAME_RE = /<iframe class="p2c-frame" data-variant="([A-E])" sandbox="allow-same-origin" srcdoc="([^"]*)"><\/iframe>/g;
|
||||
const FACTS_RE = /<script type="application\/json" id="p2c-round">([\s\S]*?)<\/script>/;
|
||||
const BODY_OPEN = "<body>";
|
||||
const BODY_CLOSE = "</body></html>";
|
||||
|
||||
const bytes = (text) => Buffer.byteLength(text, "utf8");
|
||||
|
||||
/** A count of bytes as short text: 1.2 MB, 340 KB. */
|
||||
export function size(n) {
|
||||
return n >= MB ? `${(n / MB).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`;
|
||||
}
|
||||
|
||||
/** Escape text for a double-quoted attribute: & first, then ". */
|
||||
export function escapeAttr(text) {
|
||||
return text.replace(/&/g, "&").replace(/"/g, """);
|
||||
}
|
||||
|
||||
/** The inverse of escapeAttr, in one pass so neither replacement feeds the other. */
|
||||
export function unescapeAttr(text) {
|
||||
return text.replace(/&(amp|quot);/g, (_, name) => (name === "amp" ? "&" : '"'));
|
||||
}
|
||||
|
||||
/** Write JSON safe to sit inside a <script> element: every < as <. */
|
||||
export function scriptJson(value) {
|
||||
return JSON.stringify(value).replace(/</g, "\\u003c");
|
||||
}
|
||||
|
||||
/** The starting values for one variant: the shared starts with its own on top. */
|
||||
export function startsFor(facts, letter) {
|
||||
const own = (facts.variants.find((v) => v.letter === letter) || {}).starts || {};
|
||||
return { ...facts.starts, ...own };
|
||||
}
|
||||
|
||||
/** One variant's frame document: base.css, then the variant inside <body>. */
|
||||
export function frameDocument(facts, letter, base, content) {
|
||||
const s = startsFor(facts, letter);
|
||||
const attrs = `data-p2c-theme="${s.theme}" data-p2c-state="${s.state}" data-p2c-length="${s.length}" data-p2c-kind="${facts.kind}"`;
|
||||
return `<!doctype html><html lang="en" ${attrs}><head><meta charset="utf-8"><style>\n${base}\n</style></head>${BODY_OPEN}${content}${BODY_CLOSE}`;
|
||||
}
|
||||
|
||||
/** Replace one placeholder, failing loudly when the shell lacks it. */
|
||||
function fill(html, marker, text) {
|
||||
const at = html.indexOf(marker);
|
||||
if (at === -1 || html.indexOf(marker, at + marker.length) !== -1) {
|
||||
throw new Error(`The page shell must hold ${marker} exactly once.`);
|
||||
}
|
||||
return html.slice(0, at) + text + html.slice(at + marker.length);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------ images */
|
||||
|
||||
/** An image file's media type by its first bytes, or null when it is none of the four. */
|
||||
export function imageType(buf) {
|
||||
if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
|
||||
if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
|
||||
if (buf.length >= 12 && buf.toString("latin1", 0, 4) === "RIFF" && buf.toString("latin1", 8, 12) === "WEBP") return "image/webp";
|
||||
const head = buf.subarray(0, 512).toString("utf8").replace(/^/, "").trimStart();
|
||||
if (/^<svg[\s>]/i.test(head) || /^<\?xml[\s?]/i.test(head)) return "image/svg+xml";
|
||||
return null;
|
||||
}
|
||||
|
||||
const xmlText = (t) => t.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """);
|
||||
|
||||
/** The labeled stand-in for an image too large to embed, as a data: URL. */
|
||||
export function placeholderUrl(name) {
|
||||
const svg =
|
||||
`<svg xmlns="http://www.w3.org/2000/svg" width="320" height="180" viewBox="0 0 320 180">` +
|
||||
`<rect x="1" y="1" width="318" height="178" fill="#e5e7eb" stroke="#9ca3af" stroke-dasharray="6 4"/>` +
|
||||
`<text x="160" y="84" text-anchor="middle" font-family="sans-serif" font-size="14" fill="#374151">${xmlText(name)}</text>` +
|
||||
`<text x="160" y="106" text-anchor="middle" font-family="sans-serif" font-size="12" fill="#6b7280">image too large to embed</text></svg>`;
|
||||
return `data:image/svg+xml;base64,${Buffer.from(svg, "utf8").toString("base64")}`;
|
||||
}
|
||||
|
||||
const escapeRe = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||
|
||||
/** A listed file's bytes (its path read from the round folder), or null when it cannot be read. */
|
||||
function readListed(folder, file) {
|
||||
try {
|
||||
return fs.readFileSync(path.resolve(folder, file));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/** A tag with its alt attribute set to `alt` (added when it has none). */
|
||||
function setAlt(tag, alt) {
|
||||
const value = `"${alt.replace(/&/g, "&").replace(/"/g, """)}"`;
|
||||
const re = /(\salt\s*=\s*)(?:"[^"]*"|'[^']*'|[^\s>]*)/i;
|
||||
if (re.test(tag)) return tag.replace(re, (_, pre) => pre + value);
|
||||
return tag.replace(/\s*\/?>$/, (end) => ` alt=${value}${end}`);
|
||||
}
|
||||
|
||||
/**
|
||||
* Put round.images into the variants. Each image is decided by its first
|
||||
* bytes: a supported one up to LIMITS.image becomes a data: URL, a larger one
|
||||
* a labeled placeholder, anything else is skipped (src left empty, alt the
|
||||
* name). A name is matched as src="<name>" or src="p2c-image:<name>" (either
|
||||
* quote) on any tag, and as url(<name>) inside a <style> block. An SVG only
|
||||
* ever lands as a data: URL source, never as markup.
|
||||
* Returns { variants, images: [{ name, url, bytes, embedded }], warnings }.
|
||||
*/
|
||||
export function embedImages(round) {
|
||||
const warnings = [];
|
||||
const images = [];
|
||||
let variants = round.variants.map((v) => ({ ...v }));
|
||||
for (const entry of round.facts.images) {
|
||||
const buf = readListed(round.folder, entry.path);
|
||||
const type = buf ? imageType(buf) : null;
|
||||
let url = null;
|
||||
let embedded = false;
|
||||
if (!buf) {
|
||||
warnings.push(`Image ${entry.path} could not be read, so "${entry.name}" was skipped.`);
|
||||
} else if (!type) {
|
||||
warnings.push(`Image ${entry.path} is not a PNG, JPEG, WebP or SVG file, so "${entry.name}" was skipped.`);
|
||||
} else if (buf.length > LIMITS.image) {
|
||||
url = placeholderUrl(entry.name);
|
||||
warnings.push(`Image ${entry.path} is ${size(buf.length)}, over the 1 MB limit for one image, so "${entry.name}" shows as a labeled placeholder.`);
|
||||
} else {
|
||||
url = `data:${type};base64,${buf.toString("base64")}`;
|
||||
embedded = true;
|
||||
}
|
||||
images.push({ name: entry.name, url, bytes: buf ? buf.length : 0, embedded });
|
||||
|
||||
const name = escapeRe(entry.name);
|
||||
const srcRe = new RegExp(`(\\ssrc\\s*=\\s*)(["'])(?:p2c-image:)?${name}\\2`, "i");
|
||||
const srcAll = new RegExp(srcRe.source, "gi");
|
||||
const urlRe = new RegExp(`url\\(\\s*(["']?)(?:p2c-image:)?${name}\\1\\s*\\)`, "gi");
|
||||
variants = variants.map((v) => {
|
||||
let n = 0;
|
||||
// A tag runs to the first `>` outside a quoted value, so `title="a > b"` before `src` is still one tag.
|
||||
let content = v.content.replace(/<[a-z](?:[^>"']|"[^"]*"|'[^']*')*>/gi, (tag) => {
|
||||
if (!srcRe.test(tag)) return tag;
|
||||
if (!url) return setAlt(tag.replace(srcAll, (_, pre, q) => pre + q + q), entry.name);
|
||||
return tag.replace(srcAll, (_, pre, q) => {
|
||||
n++;
|
||||
return pre + q + url + q;
|
||||
});
|
||||
});
|
||||
content = content.replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, (block) =>
|
||||
block.replace(urlRe, () => {
|
||||
if (!url) return "none";
|
||||
n++;
|
||||
return `url("${url}")`;
|
||||
})
|
||||
);
|
||||
// How many times each image went into this variant, for the size report.
|
||||
return { ...v, content, uses: { ...v.uses, [entry.name]: n } };
|
||||
});
|
||||
}
|
||||
const shown = images.filter((i) => i.embedded);
|
||||
const total = shown.reduce((n, i) => n + i.bytes, 0);
|
||||
if (total > LIMITS.allImages) {
|
||||
const largest = [...shown].sort((a, b) => b.bytes - a.bytes)[0];
|
||||
warnings.push(`The images together are ${size(total)}, over the 3 MB limit for all images; the largest is "${largest.name}" (${size(largest.bytes)}).`);
|
||||
}
|
||||
return { variants, images, warnings };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------- fonts */
|
||||
|
||||
/** A font file's format by its first bytes: [media type, CSS format()] or null. */
|
||||
export function fontType(buf) {
|
||||
if (buf.length < 4) return null;
|
||||
const tag = buf.toString("latin1", 0, 4);
|
||||
if (tag === "wOF2") return ["font/woff2", "woff2"];
|
||||
if (tag === "wOFF") return ["font/woff", "woff"];
|
||||
if (tag === "OTTO") return ["font/otf", "opentype"];
|
||||
if (tag === "true" || (buf[0] === 0 && buf[1] === 1 && buf[2] === 0 && buf[3] === 0)) return ["font/ttf", "truetype"];
|
||||
return null;
|
||||
}
|
||||
|
||||
/** The weight and style a font file's name says: a number from 100 to 900 or bold, and italic. */
|
||||
export function fontFace(file) {
|
||||
const base = path.basename(file).toLowerCase();
|
||||
const num = base.match(/(?:^|[^0-9])([1-9]00)(?![0-9])/);
|
||||
return { weight: num ? num[1] : base.includes("bold") ? "700" : "normal", style: base.includes("italic") ? "italic" : "normal" };
|
||||
}
|
||||
|
||||
/**
|
||||
* The app's own font from round.fonts: up to LIMITS.fontFiles files and
|
||||
* LIMITS.fonts bytes together, each a WOFF2, WOFF, TTF or OTF by its first
|
||||
* bytes, as @font-face rules for the family "P2C App Font", with
|
||||
* --p2c-font-set-app falling back to the round's own font set. Past a limit,
|
||||
* or with no usable file, nothing is embedded and the warning says the
|
||||
* closest system set is used. A terminal has no font dial: nothing embeds.
|
||||
* Returns { rules: [{ what, css }], appFont, warnings }.
|
||||
*/
|
||||
export function embedFonts(round) {
|
||||
const { facts } = round;
|
||||
if (!facts.fonts.length || facts.kind === "terminal") return { rules: [], appFont: false, warnings: [] };
|
||||
const fallback = facts.starts.fontSet;
|
||||
const warnings = [];
|
||||
const fallBack = (why) => {
|
||||
warnings.push(`${why}, so no app font was embedded and the closest system set, ${fallback}, is used.`);
|
||||
return { rules: [], appFont: false, warnings };
|
||||
};
|
||||
if (facts.fonts.length > LIMITS.fontFiles) return fallBack(`The round lists ${facts.fonts.length} font files, over the limit of ${LIMITS.fontFiles}`);
|
||||
const usable = [];
|
||||
for (const file of facts.fonts) {
|
||||
const buf = readListed(round.folder, file);
|
||||
const type = buf ? fontType(buf) : null;
|
||||
if (!buf) warnings.push(`Font ${file} could not be read and was skipped.`);
|
||||
else if (!type) warnings.push(`Font ${file} is not a WOFF2, WOFF, TTF or OTF file and was skipped.`);
|
||||
else usable.push({ file, buf, type });
|
||||
}
|
||||
if (!usable.length) return fallBack("No listed font file could be used");
|
||||
const total = usable.reduce((n, f) => n + f.buf.length, 0);
|
||||
if (total > LIMITS.fonts) return fallBack(`The font files together are ${size(total)}, over the 2 MB limit`);
|
||||
const rules = usable.map(({ file, buf, type: [mime, format] }) => {
|
||||
const { weight, style } = fontFace(file);
|
||||
return {
|
||||
what: `font ${path.basename(file)}`,
|
||||
css: `@font-face { font-family: "${APP_FAMILY}"; src: url(data:${mime};base64,${buf.toString("base64")}) format("${format}"); font-weight: ${weight}; font-style: ${style}; }`,
|
||||
};
|
||||
});
|
||||
const slug = (FONT_SETS.includes(fallback) ? fallback : FONT_SETS[0]).toLowerCase().replace(/[^a-z0-9]+/g, "-");
|
||||
rules.push({ what: "base stylesheet", css: `:root { --p2c-font-set-app: "${APP_FAMILY}", var(--p2c-font-set-${slug}); }` });
|
||||
return { rules, appFont: true, warnings };
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------- page */
|
||||
|
||||
export function buildPage(round, shell, media = {}) {
|
||||
const { facts } = round;
|
||||
const variants = media.variants || round.variants;
|
||||
const images = (media.images || []).filter((i) => i.url);
|
||||
const rules = media.rules || [];
|
||||
const parts = [];
|
||||
const add = (what, n) => {
|
||||
const known = parts.find((p) => p.what === what);
|
||||
if (known) known.bytes += n;
|
||||
else parts.push({ what, bytes: n });
|
||||
};
|
||||
add("shell", bytes(shell.html) + bytes(shell.css) + bytes(shell.js));
|
||||
|
||||
// The app font's rules sit in every frame's base styles, after base.css.
|
||||
const base = rules.length ? `${shell.base}\n${rules.map((r) => r.css).join("\n")}` : shell.base;
|
||||
const frames = variants.map((v) => {
|
||||
const empty = escapeAttr(frameDocument(facts, v.letter, base, ""));
|
||||
const full = escapeAttr(frameDocument(facts, v.letter, base, v.content));
|
||||
let shared = bytes(empty);
|
||||
for (const r of rules) {
|
||||
const n = bytes(escapeAttr(`\n${r.css}`));
|
||||
add(r.what, n);
|
||||
shared -= n;
|
||||
}
|
||||
add("base stylesheet", shared);
|
||||
let own = bytes(full) - bytes(empty);
|
||||
for (const im of images) {
|
||||
const n = (v.uses && v.uses[im.name]) || 0;
|
||||
if (!n) continue;
|
||||
add(`image ${im.name}`, n * bytes(im.url));
|
||||
own -= n * bytes(im.url);
|
||||
}
|
||||
add(`variant ${v.letter}`, own);
|
||||
return `<iframe class="p2c-frame" data-variant="${v.letter}" sandbox="allow-same-origin" srcdoc="${full}"></iframe>`;
|
||||
});
|
||||
|
||||
const factsJson = scriptJson(facts);
|
||||
add("round facts", bytes(factsJson));
|
||||
|
||||
if (/<\/script/i.test(shell.js)) throw new Error("shell.js must not hold a closing script tag.");
|
||||
if (/<\/style/i.test(shell.css)) throw new Error("shell.css must not hold a closing style tag.");
|
||||
|
||||
// The frames go in last: variant text is the model's, and escapeAttr leaves
|
||||
// a comment such as <!-- p2c:script --> in it untouched, so no placeholder
|
||||
// search may run over it.
|
||||
let html = shell.html;
|
||||
html = fill(html, PLACEHOLDERS.styles, `<style>\n${shell.css}\n</style>`);
|
||||
html = fill(
|
||||
html,
|
||||
PLACEHOLDERS.script,
|
||||
`<script type="application/json" id="p2c-round">${factsJson}</script>\n<script>\n${shell.js}\n</script>`
|
||||
);
|
||||
html = fill(html, PLACEHOLDERS.frames, frames.join("\n"));
|
||||
parts.sort((a, b) => b.bytes - a.bytes);
|
||||
return { html, parts };
|
||||
}
|
||||
|
||||
/** A built page with its round facts' `file` set to `file`; null when it is not a prototype page. */
|
||||
export function withFile(html, file) {
|
||||
const m = FACTS_RE.exec(html);
|
||||
if (!m) return null;
|
||||
let facts;
|
||||
try {
|
||||
facts = JSON.parse(m[1]);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
facts.file = file;
|
||||
const open = m[0].slice(0, m[0].length - m[1].length - "</script>".length);
|
||||
return html.slice(0, m.index) + open + scriptJson(facts) + "</script>" + html.slice(m.index + m[0].length);
|
||||
}
|
||||
|
||||
export function unpackPage(html) {
|
||||
const factsMatch = FACTS_RE.exec(html);
|
||||
if (!factsMatch) return null;
|
||||
let facts;
|
||||
try {
|
||||
facts = JSON.parse(factsMatch[1]);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
const frames = {};
|
||||
for (const m of html.matchAll(FRAME_RE)) {
|
||||
const doc = unescapeAttr(m[2]);
|
||||
const open = doc.indexOf(BODY_OPEN);
|
||||
const content = open !== -1 && doc.endsWith(BODY_CLOSE) ? doc.slice(open + BODY_OPEN.length, doc.length - BODY_CLOSE.length) : null;
|
||||
frames[m[1]] = { doc, content };
|
||||
}
|
||||
const outside = html.replace(FRAME_RE, "").replace(FACTS_RE, "");
|
||||
return { facts, frames, outside };
|
||||
}
|
||||
@@ -0,0 +1,178 @@
|
||||
// ui-prototype-round.mjs: read and validate a round folder's round.json and
|
||||
// variant files, against the contract in ui-prototype-contract.md (section 7).
|
||||
//
|
||||
// readRound(folder) returns { folder, facts, variants: [{ letter, name, file,
|
||||
// content }] } or fails with EXIT.NOT_FOUND (a missing round.json or variant
|
||||
// file) or EXIT.INVALID (anything malformed, the message naming the field or
|
||||
// file).
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { EXIT, fail } from "./common.mjs";
|
||||
|
||||
export const KINDS = ["screen", "flow", "terminal"];
|
||||
export const ITEMS = ["colors", "fonts", "spacing", "components", "layout"];
|
||||
export const FONT_SETS = ["System UI", "Humanist", "Transitional", "Slab Serif", "Rounded Sans", "Monospace Code"];
|
||||
export const SCREENS = ["Phone 390", "Tablet 820", "Desktop 1280"];
|
||||
export const WINDOWS = ["80x24", "120x30", "160x48"];
|
||||
export const PALETTES = ["Graphite", "Amber", "Phosphor", "Ocean"];
|
||||
export const THEMES = ["light", "dark"];
|
||||
export const STATES = ["ready", "empty", "loading", "error"];
|
||||
export const LENGTHS = ["short", "typical", "long"];
|
||||
export const LETTERS = ["A", "B", "C", "D", "E"];
|
||||
export const MIN_VARIANTS = 2;
|
||||
export const MAX_VARIANTS = 5;
|
||||
export const MAX_EXTRAS = 6;
|
||||
export const EXTRA_TYPES = ["slider", "pick", "toggle"];
|
||||
|
||||
/** A prototype's name: lowercase letters and digits joined by single hyphens. */
|
||||
export const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
||||
const EXTRA_NAME_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
|
||||
const COLOR_RE = /^#[0-9a-fA-F]{6}$/;
|
||||
const FILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.html$/;
|
||||
const WHOLE_PAGE_RE = /<\/?(?:html|head|body)\b/i;
|
||||
|
||||
const isText = (v) => typeof v === "string";
|
||||
const isNum = (v) => typeof v === "number" && Number.isFinite(v);
|
||||
const oneOf = (list) => (v) => list.includes(v);
|
||||
const between = (lo, hi) => (v) => isNum(v) && v >= lo && v <= hi;
|
||||
|
||||
// The dial starts, by kind: each key's check and what to say when it fails.
|
||||
const SCREEN_STARTS = {
|
||||
screen: [oneOf(SCREENS), `one of ${SCREENS.join(", ")}`],
|
||||
theme: [oneOf(THEMES), `one of ${THEMES.join(", ")}`],
|
||||
accent: [(v) => isText(v) && COLOR_RE.test(v), "a color as #rrggbb"],
|
||||
neutral: [(v) => isText(v) && COLOR_RE.test(v), "a color as #rrggbb"],
|
||||
fontSet: [oneOf(FONT_SETS), `one of ${FONT_SETS.join(", ")}`],
|
||||
textSize: [between(12, 24), "a number of pixels from 12 to 24"],
|
||||
space: [between(0.5, 2), "a number from 0.5 to 2"],
|
||||
radius: [between(0, 32), "a number of pixels from 0 to 32"],
|
||||
state: [oneOf(STATES), `one of ${STATES.join(", ")}`],
|
||||
length: [oneOf(LENGTHS), `one of ${LENGTHS.join(", ")}`],
|
||||
};
|
||||
const TERMINAL_STARTS = {
|
||||
window: [oneOf(WINDOWS), `one of ${WINDOWS.join(", ")}`],
|
||||
theme: SCREEN_STARTS.theme,
|
||||
palette: [oneOf(PALETTES), `one of ${PALETTES.join(", ")}`],
|
||||
density: [between(1, 2), "a number from 1 to 2"],
|
||||
state: SCREEN_STARTS.state,
|
||||
length: SCREEN_STARTS.length,
|
||||
};
|
||||
|
||||
export function startsSpec(kind) {
|
||||
return kind === "terminal" ? TERMINAL_STARTS : SCREEN_STARTS;
|
||||
}
|
||||
|
||||
function invalid(error, message, next) {
|
||||
fail(EXIT.INVALID, error, message, next || "Fix round.json against ui-prototype-contract.md (section 7), then run assemble again.");
|
||||
}
|
||||
|
||||
function checkStarts(where, starts, kind, { all }) {
|
||||
if (!starts || typeof starts !== "object" || Array.isArray(starts)) invalid("bad-starts", `${where} must be an object.`);
|
||||
const spec = startsSpec(kind);
|
||||
for (const key of Object.keys(starts)) {
|
||||
if (!Object.hasOwn(spec, key)) invalid("bad-starts", `${where}.${key} is not a dial for a ${kind} (allowed: ${Object.keys(spec).join(", ")}).`);
|
||||
const [ok, want] = spec[key];
|
||||
if (!ok(starts[key])) invalid("bad-starts", `${where}.${key} is ${JSON.stringify(starts[key])}; it must be ${want}.`);
|
||||
}
|
||||
if (all) {
|
||||
const missing = Object.keys(spec).filter((k) => !(k in starts));
|
||||
if (missing.length) invalid("bad-starts", `${where} is missing ${missing.join(", ")}.`);
|
||||
}
|
||||
}
|
||||
|
||||
function checkItems(field, value) {
|
||||
if (!Array.isArray(value)) invalid("bad-field", `round.json "${field}" must be a list.`);
|
||||
for (const item of value) {
|
||||
if (!ITEMS.includes(item)) invalid("bad-field", `round.json "${field}" holds "${item}"; carry-over items are ${ITEMS.join(", ")}.`);
|
||||
}
|
||||
}
|
||||
|
||||
function checkExtra(x, i) {
|
||||
const where = `extras[${i}]`;
|
||||
if (!x || typeof x !== "object" || Array.isArray(x)) invalid("bad-extra", `${where} must be an object.`);
|
||||
if (!isText(x.name) || !EXTRA_NAME_RE.test(x.name)) invalid("bad-extra", `${where}.name must be lowercase letters, digits and hyphens, starting with a letter.`);
|
||||
if (x.label !== undefined && !isText(x.label)) invalid("bad-extra", `${where}.label must be text.`);
|
||||
// The copied block writes "Extra, <label>: <value>" and is read back at the first colon.
|
||||
if (isText(x.label) && x.label.includes(":")) invalid("bad-extra", `${where}.label must have no colon in it.`);
|
||||
if (!EXTRA_TYPES.includes(x.type)) invalid("bad-extra", `${where}.type must be one of ${EXTRA_TYPES.join(", ")}.`);
|
||||
if (typeof x.look !== "boolean") invalid("bad-extra", `${where}.look must be true or false.`);
|
||||
if (x.type === "slider") {
|
||||
for (const k of ["min", "max", "step", "start"]) if (!isNum(x[k])) invalid("bad-extra", `${where}.${k} must be a number for a slider.`);
|
||||
if (!(x.min < x.max) || !(x.step > 0)) invalid("bad-extra", `${where} needs min below max and a step above 0.`);
|
||||
if (x.start < x.min || x.start > x.max) invalid("bad-extra", `${where}.start must lie between min and max.`);
|
||||
} else if (x.type === "pick") {
|
||||
if (!Array.isArray(x.choices) || x.choices.length < 2 || !x.choices.every((c) => isText(c) && c.trim() && !/["\\]/.test(c))) {
|
||||
invalid("bad-extra", `${where}.choices must be two or more texts without quotes or backslashes.`);
|
||||
}
|
||||
if (!x.choices.includes(x.start)) invalid("bad-extra", `${where}.start must be one of its choices.`);
|
||||
} else if (typeof x.start !== "boolean") {
|
||||
invalid("bad-extra", `${where}.start must be true or false for a toggle.`);
|
||||
}
|
||||
}
|
||||
|
||||
/** Read a round folder and validate it. See the header for what it returns. */
|
||||
export function readRound(folder) {
|
||||
const dir = path.resolve(folder);
|
||||
const file = path.join(dir, "round.json");
|
||||
if (!fs.existsSync(file)) {
|
||||
fail(EXIT.NOT_FOUND, "round-missing", `No round.json in ${dir}.`, "Write round.json into the round folder (ui-prototype-contract.md, section 7).");
|
||||
}
|
||||
let facts;
|
||||
try {
|
||||
facts = JSON.parse(fs.readFileSync(file, "utf8"));
|
||||
} catch (err) {
|
||||
invalid("bad-json", `round.json does not parse as JSON: ${err.message}`);
|
||||
}
|
||||
if (!facts || typeof facts !== "object" || Array.isArray(facts)) invalid("bad-json", "round.json must hold one JSON object.");
|
||||
|
||||
for (const field of ["name", "round", "kind", "request", "direction", "carried", "freed", "notFound", "variants", "starts", "extras", "images", "fonts"]) {
|
||||
if (!(field in facts)) invalid("missing-field", `round.json has no "${field}" field.`);
|
||||
}
|
||||
if (!isText(facts.name) || !NAME_RE.test(facts.name)) invalid("bad-field", `round.json "name" must be lowercase letters and digits joined by single hyphens (got ${JSON.stringify(facts.name)}).`);
|
||||
if (!Number.isInteger(facts.round) || facts.round < 1) invalid("bad-field", `round.json "round" must be a whole number of 1 or more.`);
|
||||
if (!KINDS.includes(facts.kind)) invalid("bad-field", `round.json "kind" must be one of ${KINDS.join(", ")} (got ${JSON.stringify(facts.kind)}).`);
|
||||
if (!isText(facts.request) || !facts.request.trim()) invalid("bad-field", `round.json "request" must be text, not empty.`);
|
||||
if (!isText(facts.direction)) invalid("bad-field", `round.json "direction" must be text ("" when none).`);
|
||||
for (const field of ["carried", "freed", "notFound"]) checkItems(field, facts[field]);
|
||||
|
||||
checkStarts("starts", facts.starts, facts.kind, { all: true });
|
||||
|
||||
if (!Array.isArray(facts.extras)) invalid("bad-field", `round.json "extras" must be a list.`);
|
||||
if (facts.extras.length > MAX_EXTRAS) invalid("too-many-extras", `round.json has ${facts.extras.length} extras; at most ${MAX_EXTRAS} are allowed.`);
|
||||
facts.extras.forEach(checkExtra);
|
||||
const extraNames = facts.extras.map((x) => x.name);
|
||||
const dup = extraNames.find((n, i) => extraNames.indexOf(n) !== i);
|
||||
if (dup) invalid("bad-extra", `Two extras are named "${dup}".`);
|
||||
|
||||
if (!Array.isArray(facts.images) || !facts.images.every((im) => im && isText(im.name) && isText(im.path))) {
|
||||
invalid("bad-field", `round.json "images" must be a list of { "name", "path" }.`);
|
||||
}
|
||||
if (!Array.isArray(facts.fonts) || !facts.fonts.every(isText)) invalid("bad-field", `round.json "fonts" must be a list of paths.`);
|
||||
|
||||
if (!Array.isArray(facts.variants)) invalid("bad-field", `round.json "variants" must be a list.`);
|
||||
const n = facts.variants.length;
|
||||
if (n < MIN_VARIANTS || n > MAX_VARIANTS) {
|
||||
invalid("variant-count", `round.json has ${n} variant${n === 1 ? "" : "s"}; a round has ${MIN_VARIANTS} to ${MAX_VARIANTS}.`);
|
||||
}
|
||||
const variants = facts.variants.map((v, i) => {
|
||||
const where = `variants[${i}]`;
|
||||
if (!v || typeof v !== "object" || Array.isArray(v)) invalid("bad-variant", `${where} must be an object.`);
|
||||
if (v.letter !== LETTERS[i]) invalid("bad-variant", `${where}.letter must be "${LETTERS[i]}" (letters run A, B, C... in order).`);
|
||||
for (const k of ["name", "what"]) if (!isText(v[k]) || !v[k].trim()) invalid("bad-variant", `${where}.${k} must be text, not empty.`);
|
||||
if (!isText(v.file) || !FILE_RE.test(v.file)) invalid("bad-variant", `${where}.file must be a plain .html file name in the round folder.`);
|
||||
checkStarts(`${where}.starts`, v.starts ?? {}, facts.kind, { all: false });
|
||||
const abs = path.join(dir, v.file);
|
||||
if (!fs.existsSync(abs)) {
|
||||
fail(EXIT.NOT_FOUND, "variant-missing", `Variant ${v.letter}'s file ${v.file} is not in ${dir}.`, "Write the variant file, or fix its name in round.json.");
|
||||
}
|
||||
const content = fs.readFileSync(abs, "utf8");
|
||||
if (!content.trim()) invalid("bad-variant-file", `${v.file} (variant ${v.letter}) is empty.`, "Write the variant: one <style> block plus markup.");
|
||||
if (WHOLE_PAGE_RE.test(content)) {
|
||||
invalid("bad-variant-file", `${v.file} (variant ${v.letter}) holds an <html>, <head> or <body> tag.`, "A variant file is one <style> block plus markup; the page wraps it (ui-prototype-contract.md, section 6).");
|
||||
}
|
||||
return { letter: v.letter, name: v.name, file: v.file, content };
|
||||
});
|
||||
|
||||
return { folder: dir, facts, variants };
|
||||
}
|
||||
@@ -0,0 +1,575 @@
|
||||
#!/usr/bin/env node
|
||||
// ui-prototype.mjs: the UI Prototype skill's commands. The model writes a
|
||||
// round (round.json plus one file per variant, to the contract in
|
||||
// ui-prototype-contract.md); this script assembles the page around the
|
||||
// shipped shell, checks it, opens it, reads a pasted choice back and saves it.
|
||||
// The shell sits at ../references/ui-prototype-shell/ beside this file in a
|
||||
// built skill.
|
||||
|
||||
import fs from "node:fs";
|
||||
import path from "node:path";
|
||||
import { spawn } from "node:child_process";
|
||||
import { fileURLToPath, pathToFileURL } from "node:url";
|
||||
import { EXIT, fail, out, parseArgs, run, readText, now, rel } from "./common.mjs";
|
||||
import { readRound, STATES, LENGTHS, NAME_RE } from "./ui-prototype-round.mjs";
|
||||
import { buildPage, unpackPage, embedImages, embedFonts, withFile, size, LIMITS, IMAGE_TYPES, APP_FONT } from "./ui-prototype-page.mjs";
|
||||
import { draftsRoot, projectDrafts, roundFolder, pagePath, isInside, fold } from "./ui-prototype-drafts.mjs";
|
||||
import { parseBlock, cleanBlock, FIRST_LINE } from "./ui-prototype-block.mjs";
|
||||
|
||||
const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
const SHELL_DIR = path.join(HERE, "..", "references", "ui-prototype-shell");
|
||||
const CEILING = LIMITS.ceiling;
|
||||
const DRAFT_DAYS = 30;
|
||||
const ROUND_DIR_RE = /^round-(\d+)$/;
|
||||
|
||||
const USAGE = `
|
||||
ui-prototype.mjs: build, check, open and save UI prototype pages. JSON on stdout.
|
||||
|
||||
node ui-prototype.mjs sweep --project <root>
|
||||
Delete this project's prototype drafts (round folders and pages under
|
||||
~/.plan2code/prototypes/<project key>/) older than 30 days, then any
|
||||
prototype folder left empty. Prints { ok, draftsDir, removed }.
|
||||
|
||||
node ui-prototype.mjs new-round --project <root> --name <name>
|
||||
Create the next round folder for a prototype in this project's drafts.
|
||||
Prints { ok, round, folder, page }: write round.json and the variant
|
||||
files into folder; assemble writes the page to page.
|
||||
|
||||
node ui-prototype.mjs assemble --round <folder>
|
||||
Read <folder>/round.json and its variant files, embed the listed images
|
||||
and app fonts, build the page around the shipped shell and write it
|
||||
beside the folder as <name>-round-<N>.html (inside the drafts, also
|
||||
recorded as the page's File). Prints { ok, file, bytes, parts (largest
|
||||
first), warnings }.
|
||||
|
||||
node ui-prototype.mjs check --file <page>
|
||||
Check a built page against the variant contract. Prints
|
||||
{ ok, findings: [{ rule, variant, message }], bytes, overCeiling }.
|
||||
Rules: outside-link, script, state-missing, length-missing,
|
||||
value-unused, step-missing, frame-missing, image-type, image-size,
|
||||
image-missing. A page over the 5 MB soft ceiling sets overCeiling and
|
||||
is never a finding.
|
||||
|
||||
node ui-prototype.mjs open --file <page> [--project <root>]
|
||||
Open a page (in the drafts, or under the project's specs/) in the
|
||||
default browser. Prints { ok, opened, path, reason }; nothing opens
|
||||
when NO_BROWSER or PLAN2CODE_NO_BROWSER is set or the session is remote.
|
||||
|
||||
node ui-prototype.mjs read-block --project <root>
|
||||
Read a pasted choice block from stdin. Prints { ok, fields, latest,
|
||||
fileExists, saved }.
|
||||
|
||||
node ui-prototype.mjs save --file <page> --spec <specs/name> --name <name>
|
||||
--block <file> --request <text> --rejected <file>
|
||||
[--replace] [--project <root>]
|
||||
Save a chosen draft page and its decisions file as
|
||||
specs/<spec>/prototypes/<name>.html and <name>.md, then remove that
|
||||
prototype's drafts. Prints { ok, html, md, removedDrafts }.
|
||||
|
||||
Exit: 0 ok, 1 crash, 2 bad arguments, 3 not found (round.json, a
|
||||
variant file, a page, a block whose first line is not the fixed one),
|
||||
4 invalid (malformed input, or check findings), 5 refused (a path outside
|
||||
the allowed folders, an existing pair).
|
||||
`;
|
||||
|
||||
/* --------------------------------------------------------------- the shell */
|
||||
|
||||
function loadShell() {
|
||||
const read = (name) => {
|
||||
const text = readText(path.join(SHELL_DIR, name));
|
||||
if (text === null) {
|
||||
fail(EXIT.NOT_FOUND, "shell-missing", `The page shell's ${name} is not in ${SHELL_DIR}.`, "The skill install is incomplete; reinstall the Plan2Code skills (node install.js).");
|
||||
}
|
||||
return text;
|
||||
};
|
||||
return { html: read("shell.html"), css: read("shell.css"), js: read("shell.js"), base: read("base.css") };
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- assemble */
|
||||
|
||||
async function cmdAssemble(args) {
|
||||
if (!args.round) fail(EXIT.USAGE, "missing-flag", "assemble needs --round <folder>.", "Pass the round folder that holds round.json.");
|
||||
const round = readRound(args.round);
|
||||
const { facts } = round;
|
||||
let file = path.join(path.dirname(round.folder), `${facts.name}-round-${facts.round}.html`);
|
||||
// A round in the drafts: the page goes to pagePath() for its project key, and
|
||||
// its path is written into the facts so the Copy block's File line is right.
|
||||
const root = draftsRoot();
|
||||
// Compared case-folded where the file system ignores case, as isInside does,
|
||||
// so a path typed in another case never yields a key of "..".
|
||||
const [key, protoDir, roundDir, ...deeper] = path.relative(fold(root), fold(round.folder)).split(path.sep);
|
||||
if (isInside(root, round.folder) && key && key !== "..") {
|
||||
// In a folder new-round made, round.json must say the same name and round:
|
||||
// a copied round.json that kept an older number would overwrite that round's page.
|
||||
const n = deeper.length ? null : (roundDir || "").match(ROUND_DIR_RE);
|
||||
if (n && (facts.round !== Number(n[1]) || facts.name !== protoDir)) {
|
||||
fail(
|
||||
EXIT.INVALID,
|
||||
"round-mismatch",
|
||||
`round.json says "${facts.name}" round ${facts.round}, but its folder is "${protoDir}" round ${n[1]}.`,
|
||||
`Set "name" and "round" in round.json to the values new-round printed for this folder ("${protoDir}", ${n[1]}), then run assemble again.`,
|
||||
);
|
||||
}
|
||||
file = path.join(root, key, facts.name, `${facts.name}-round-${facts.round}.html`);
|
||||
facts.file = file;
|
||||
}
|
||||
|
||||
const pictures = embedImages(round);
|
||||
const fonts = embedFonts(round);
|
||||
facts.appFont = fonts.appFont;
|
||||
// The dial starts on the app font only when fonts are carried over; freed, each variant keeps its own set.
|
||||
if (fonts.appFont && facts.carried.includes("fonts")) facts.starts.fontSet = APP_FONT;
|
||||
const { html, parts } = buildPage(round, loadShell(), { variants: pictures.variants, images: pictures.images, rules: fonts.rules });
|
||||
fs.mkdirSync(path.dirname(file), { recursive: true });
|
||||
fs.writeFileSync(file, html);
|
||||
|
||||
const bytes = Buffer.byteLength(html, "utf8");
|
||||
const warnings = [...pictures.warnings, ...fonts.warnings];
|
||||
if (bytes > CEILING) {
|
||||
const top = parts.slice(0, 3).map((p) => `${p.what} (${size(p.bytes)})`).join(", ");
|
||||
warnings.push(`The page is ${size(bytes)}, over the 5 MB soft ceiling; the largest parts are ${top}.`);
|
||||
}
|
||||
out({ ok: true, file, bytes, parts, warnings });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------- sweep, new-round */
|
||||
|
||||
function projectRoot(args) {
|
||||
return path.resolve(args.project || process.cwd());
|
||||
}
|
||||
|
||||
/** The newest modified time in a file or folder tree, never following a link. */
|
||||
function newest(p) {
|
||||
const st = fs.lstatSync(p);
|
||||
let t = st.mtimeMs;
|
||||
if (st.isDirectory()) for (const name of fs.readdirSync(p)) t = Math.max(t, newest(path.join(p, name)));
|
||||
return t;
|
||||
}
|
||||
|
||||
const lstat = (p) => {
|
||||
try {
|
||||
return fs.lstatSync(p);
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
};
|
||||
|
||||
async function cmdSweep(args) {
|
||||
if (!args.project) fail(EXIT.USAGE, "missing-flag", "sweep needs --project <root>.", "Pass the project's root folder.");
|
||||
const draftsDir = projectDrafts(projectRoot(args));
|
||||
const removed = [];
|
||||
const st = lstat(draftsDir);
|
||||
if (!st || !st.isDirectory()) return out({ ok: true, draftsDir, removed });
|
||||
const cutoff = now().getTime() - DRAFT_DAYS * 24 * 60 * 60 * 1000;
|
||||
for (const name of fs.readdirSync(draftsDir)) {
|
||||
const folder = path.join(draftsDir, name);
|
||||
if (!lstat(folder)?.isDirectory()) continue;
|
||||
const page = new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-round-\\d+\\.html$`);
|
||||
for (const entry of fs.readdirSync(folder)) {
|
||||
const p = path.join(folder, entry);
|
||||
const s = lstat(p);
|
||||
const isRound = s?.isDirectory() && ROUND_DIR_RE.test(entry);
|
||||
const isPage = s?.isFile() && page.test(entry);
|
||||
if ((isRound || isPage) && newest(p) < cutoff) {
|
||||
fs.rmSync(p, { recursive: true, force: true });
|
||||
removed.push(p);
|
||||
}
|
||||
}
|
||||
if (!fs.readdirSync(folder).length) {
|
||||
fs.rmdirSync(folder);
|
||||
removed.push(folder);
|
||||
}
|
||||
}
|
||||
out({ ok: true, draftsDir, removed });
|
||||
}
|
||||
|
||||
/** The highest round number among a prototype's round folders and pages in the drafts, 0 when none. */
|
||||
function highestRound(root, name) {
|
||||
const folder = path.join(projectDrafts(root), name);
|
||||
let names = [];
|
||||
try {
|
||||
names = fs.readdirSync(folder);
|
||||
} catch {}
|
||||
let top = 0;
|
||||
for (const entry of names) {
|
||||
const m = entry.match(ROUND_DIR_RE) || (entry.startsWith(`${name}-round-`) && entry.match(/-round-(\d+)\.html$/));
|
||||
if (m) top = Math.max(top, Number(m[1]));
|
||||
}
|
||||
return top;
|
||||
}
|
||||
|
||||
async function cmdNewRound(args) {
|
||||
if (!args.project || !args.name) fail(EXIT.USAGE, "missing-flag", "new-round needs --project <root> and --name <name>.", "Pass the project's root folder and the prototype's name.");
|
||||
if (!NAME_RE.test(args.name)) fail(EXIT.INVALID, "bad-name", `"${args.name}" is not a prototype name.`, "Use lowercase letters and digits joined by single hyphens (invoices-screen).");
|
||||
const root = projectRoot(args);
|
||||
const round = highestRound(root, args.name) + 1;
|
||||
const folder = roundFolder(root, args.name, round);
|
||||
fs.mkdirSync(folder, { recursive: true });
|
||||
out({ ok: true, round, folder, page: pagePath(root, args.name, round) });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------------- check */
|
||||
|
||||
// The shared value groups each variant must draw from (contract section 1 and 4).
|
||||
const GROUPS = {
|
||||
screen: {
|
||||
color: (n) => ["accent", "neutral", "bg", "surface", "text", "muted", "border", "on-accent"].includes(n),
|
||||
font: (n) => n === "font" || n === "text-size" || n.startsWith("font-set-"),
|
||||
spacing: (n) => n === "space" || /^space-[1-6]$/.test(n),
|
||||
corners: (n) => n === "radius",
|
||||
},
|
||||
terminal: {
|
||||
palette: (n) => ["term-bg", "term-fg", "term-accent"].includes(n),
|
||||
density: (n) => n === "density",
|
||||
},
|
||||
};
|
||||
|
||||
function outsideLinks(text) {
|
||||
const t = text.replace(/\sxmlns(?::[\w-]+)?\s*=\s*(?:"[^"]*"|'[^']*')/gi, "");
|
||||
const hits = [];
|
||||
// A bare "file:" is ordinary text ("Attach file:"); "file://" is a link.
|
||||
const scheme = t.match(/\b(?:https?:|file:\/\/)[^\s"'<>)]*/i);
|
||||
if (scheme) hits.push(scheme[0]);
|
||||
// A protocol-relative URL wherever one can begin: an attribute, a srcset
|
||||
// candidate, a meta refresh, a CSS string. Right after "=", a quote or "("
|
||||
// any host counts (//localhost); after a space or comma only a dotted one,
|
||||
// so text such as " //TODO" in a terminal variant is not a link.
|
||||
const slashes = t.match(/(?:^|[\s,;])(\/\/[a-z0-9-]+(?:\.[a-z0-9-]+)+[^\s"'<>)]*)|[="'(](\/\/[a-z0-9-]+[^\s"'<>)]*)/im);
|
||||
if (slashes) hits.push(slashes[1] || slashes[2]);
|
||||
if (/@import\b/i.test(t)) hits.push("@import");
|
||||
// url(#id) points inside the same document (an SVG gradient) and loads nothing.
|
||||
const url = t.match(/url\(\s*(?!["']?\s*(?:data:|#))[^)]*\)/i);
|
||||
if (url) hits.push(url[0]);
|
||||
return hits;
|
||||
}
|
||||
|
||||
/**
|
||||
* Every start tag in `markup` with its attributes, read the way an HTML parser
|
||||
* reads them: names end at whitespace, "/", ">" or "="; values are quoted
|
||||
* (where ">" is plain text) or unquoted. <style> blocks are skipped, so a CSS
|
||||
* selector never counts as markup, except inside <svg>: there <style> is not
|
||||
* raw text, and a tag written in it becomes a real element in the browser.
|
||||
*/
|
||||
function startTags(markup) {
|
||||
const html = markup.replace(/(<svg\b[\s\S]*?<\/svg\s*>)|<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, (m, svg) => svg ?? "");
|
||||
const tags = [];
|
||||
const re = /<([a-z][^\s/>]*)/gi;
|
||||
let m;
|
||||
while ((m = re.exec(html))) {
|
||||
let i = re.lastIndex;
|
||||
const attrs = [];
|
||||
while (i < html.length && html[i] !== ">") {
|
||||
if (/[\s/]/.test(html[i])) {
|
||||
i++;
|
||||
continue;
|
||||
}
|
||||
let name = "";
|
||||
while (i < html.length && !/[\s/>=]/.test(html[i])) name += html[i++];
|
||||
while (i < html.length && /\s/.test(html[i])) i++;
|
||||
let value = "";
|
||||
if (html[i] === "=") {
|
||||
i++;
|
||||
while (i < html.length && /\s/.test(html[i])) i++;
|
||||
const quote = html[i];
|
||||
if (quote === '"' || quote === "'") {
|
||||
const end = html.indexOf(quote, i + 1);
|
||||
value = html.slice(i + 1, end === -1 ? html.length : end);
|
||||
i = end === -1 ? html.length : end + 1;
|
||||
} else {
|
||||
while (i < html.length && !/[\s>]/.test(html[i])) value += html[i++];
|
||||
}
|
||||
}
|
||||
if (name) attrs.push({ name: name.toLowerCase(), value });
|
||||
}
|
||||
tags.push({ name: m[1].toLowerCase(), attrs });
|
||||
re.lastIndex = i;
|
||||
}
|
||||
return tags;
|
||||
}
|
||||
|
||||
function marked(tags, attr) {
|
||||
const found = new Set();
|
||||
for (const tag of tags) for (const a of tag.attrs) if (a.name === attr) for (const word of a.value.split(/\s+/)) if (word) found.add(word);
|
||||
return found;
|
||||
}
|
||||
|
||||
function checkVariant(letter, content, kind) {
|
||||
const findings = [];
|
||||
const add = (rule, message) => findings.push({ rule, variant: letter, message });
|
||||
const tags = startTags(content);
|
||||
|
||||
const links = outsideLinks(content);
|
||||
if (links.length) add("outside-link", `Variant ${letter} links outside the file (${links.join(", ")}); the page must load nothing from the network.`);
|
||||
|
||||
const scripts = [];
|
||||
if (/<script\b/i.test(content)) scripts.push("a <script> tag");
|
||||
const handler = tags.flatMap((t) => t.attrs).find((a) => /^on[a-z]+$/.test(a.name));
|
||||
if (handler) scripts.push(`an ${handler.name} attribute`);
|
||||
if (/javascript:/i.test(content)) scripts.push("a javascript: link");
|
||||
if (scripts.length) add("script", `Variant ${letter} holds ${scripts.join(" and ")}; variants carry no script.`);
|
||||
|
||||
const states = marked(tags, "data-p2c-when");
|
||||
const noState = STATES.filter((s) => !states.has(s));
|
||||
if (noState.length) add("state-missing", `Variant ${letter} draws no ${noState.join(", ")} state (mark its parts with data-p2c-when).`);
|
||||
|
||||
const lengths = marked(tags, "data-p2c-text");
|
||||
const noLength = LENGTHS.filter((l) => !lengths.has(l));
|
||||
if (noLength.length) add("length-missing", `Variant ${letter} has no ${noLength.join(", ")} text (write varying text three times with data-p2c-text).`);
|
||||
|
||||
const used = [...content.matchAll(/var\(\s*--p2c-([a-z0-9-]+)/gi)].map((m) => m[1].toLowerCase());
|
||||
const groups = GROUPS[kind === "terminal" ? "terminal" : "screen"];
|
||||
const unused = Object.keys(groups).filter((g) => !used.some(groups[g]));
|
||||
if (unused.length) add("value-unused", `Variant ${letter} takes nothing from the shared ${unused.join(", ")} values; use them through var(--p2c-...).`);
|
||||
|
||||
if (kind === "flow") {
|
||||
const steps = tags.filter((t) => t.attrs.some((a) => a.name === "data-p2c-step")).length;
|
||||
if (steps < 2) add("step-missing", `Variant ${letter} is a flow with ${steps} step${steps === 1 ? "" : "s"}; a flow needs at least two data-p2c-step screens.`);
|
||||
}
|
||||
|
||||
// Every data: image in the frame: one of the four types, and 1 MB at most
|
||||
// once decoded. The too-large placeholder is a small SVG, so it always passes.
|
||||
const typeSeen = new Set();
|
||||
let oversize = 0;
|
||||
for (const m of content.matchAll(/data:(image\/[a-z0-9.+-]+)((?:;[^,;"'\s)]*)*),([^"'\s)<>]*)/gi)) {
|
||||
const type = m[1].toLowerCase();
|
||||
if (!IMAGE_TYPES.includes(type)) {
|
||||
if (!typeSeen.has(type)) add("image-type", `Variant ${letter} holds a ${type} image; only PNG, JPEG, WebP and SVG images go in a page.`);
|
||||
typeSeen.add(type);
|
||||
continue;
|
||||
}
|
||||
const data = m[3];
|
||||
let decoded;
|
||||
if (/;base64/i.test(m[2])) decoded = Math.floor((data.length * 3) / 4) - (data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0);
|
||||
else {
|
||||
try {
|
||||
decoded = Buffer.byteLength(decodeURIComponent(data), "utf8");
|
||||
} catch {
|
||||
decoded = data.length;
|
||||
}
|
||||
}
|
||||
if (decoded > LIMITS.image) oversize = Math.max(oversize, decoded);
|
||||
}
|
||||
if (oversize) add("image-size", `Variant ${letter} holds an image of ${size(oversize)}, over the 1 MB limit for one image; run assemble again so it becomes a placeholder.`);
|
||||
|
||||
// A p2c-image: name assemble did not replace: it is not in round.json's images.
|
||||
const lost = [...new Set([...content.matchAll(/p2c-image:([^"'\s)<>]*)/gi)].map((m) => m[1]))];
|
||||
if (lost.length) add("image-missing", `Variant ${letter} names ${lost.length === 1 ? "an image" : "images"} round.json does not list (${lost.join(", ")}); list each under "images" or correct the name, then run assemble again.`);
|
||||
return findings;
|
||||
}
|
||||
|
||||
async function cmdCheck(args) {
|
||||
if (!args.file) fail(EXIT.USAGE, "missing-flag", "check needs --file <page>.", "Pass the page assemble wrote.");
|
||||
const file = path.resolve(args.file);
|
||||
const html = readText(file);
|
||||
if (html === null) fail(EXIT.NOT_FOUND, "page-missing", `No page at ${file}.`, "Run assemble first, and pass the file it printed.");
|
||||
const page = unpackPage(html);
|
||||
if (!page) fail(EXIT.INVALID, "not-a-prototype", `${file} is not a UI prototype page (no round facts in it).`, "Pass a page written by assemble.");
|
||||
|
||||
const findings = [];
|
||||
const pageLinks = outsideLinks(page.outside);
|
||||
if (pageLinks.length) findings.push({ rule: "outside-link", variant: null, message: `The page links outside the file (${pageLinks.join(", ")}).` });
|
||||
|
||||
const letters = (page.facts.variants || []).map((v) => v.letter);
|
||||
for (const letter of letters) {
|
||||
const frame = page.frames[letter];
|
||||
if (!frame || frame.content === null) {
|
||||
findings.push({ rule: "frame-missing", variant: letter, message: `Variant ${letter} has no frame in the page; run assemble again.` });
|
||||
continue;
|
||||
}
|
||||
findings.push(...checkVariant(letter, frame.content, page.facts.kind));
|
||||
}
|
||||
|
||||
const size = Buffer.byteLength(html, "utf8");
|
||||
out({ ok: findings.length === 0, findings, bytes: size, overCeiling: size > CEILING });
|
||||
if (findings.length) process.exitCode = EXIT.INVALID;
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------- open */
|
||||
|
||||
/** Why nothing should open here, or null when a browser may be launched. */
|
||||
function noOpenReason() {
|
||||
if (process.env.NO_BROWSER || process.env.PLAN2CODE_NO_BROWSER) return "Opening a browser is turned off here (NO_BROWSER or PLAN2CODE_NO_BROWSER is set); open the file by hand.";
|
||||
if (process.env.SSH_CONNECTION || process.env.SSH_TTY) return "This is a remote (SSH) session, so no browser can open on your screen; copy the file to your machine and open it there.";
|
||||
if (process.env.CODESPACES || process.env.REMOTE_CONTAINERS) return "This session runs in a remote container, so no browser can open on your screen; download the file and open it there.";
|
||||
return null;
|
||||
}
|
||||
|
||||
/** Start the default browser on `file`, with no shell: null when it started, else the reason it did not. */
|
||||
function launch(file) {
|
||||
const [cmd, argv] =
|
||||
process.platform === "win32"
|
||||
? ["rundll32.exe", ["url.dll,FileProtocolHandler", pathToFileURL(file).href]]
|
||||
: process.platform === "darwin"
|
||||
? ["open", [file]]
|
||||
: [process.env.BROWSER || "xdg-open", [file]];
|
||||
return new Promise((resolve) => {
|
||||
let child;
|
||||
try {
|
||||
child = spawn(cmd, argv, { detached: true, stdio: "ignore", windowsHide: true, shell: false });
|
||||
} catch (err) {
|
||||
resolve(`${cmd} could not be started: ${err.message}`);
|
||||
return;
|
||||
}
|
||||
child.once("error", (err) => resolve(`${cmd} could not be started: ${err.message}`));
|
||||
child.once("spawn", () => {
|
||||
child.unref();
|
||||
resolve(null);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/** True when `file` is an existing .html file in the drafts or under the project's specs/. */
|
||||
function openable(root, file) {
|
||||
if (path.extname(file).toLowerCase() !== ".html") return false;
|
||||
if (!lstat(file)?.isFile()) return false;
|
||||
return isInside(draftsRoot(), file) || isInside(path.join(root, "specs"), file);
|
||||
}
|
||||
|
||||
async function cmdOpen(args) {
|
||||
if (!args.file) fail(EXIT.USAGE, "missing-flag", "open needs --file <page>.", "Pass the page assemble wrote.");
|
||||
const file = path.resolve(args.file);
|
||||
if (!openable(projectRoot(args), file)) {
|
||||
fail(EXIT.REFUSED, "not-allowed", `${file} is not an existing .html page in the prototype drafts or under this project's specs/ folder.`, "Pass the page assemble or save wrote, and --project <root> when it sits under another project's specs/.", { path: file });
|
||||
}
|
||||
const held = noOpenReason();
|
||||
if (held) return out({ ok: true, opened: false, path: file, reason: held });
|
||||
const failed = await launch(file);
|
||||
out({ ok: true, opened: !failed, path: file, reason: failed });
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------- read-block */
|
||||
|
||||
function readStdin() {
|
||||
try {
|
||||
return fs.readFileSync(0, "utf8");
|
||||
} catch {
|
||||
return "";
|
||||
}
|
||||
}
|
||||
|
||||
const notABlock = () =>
|
||||
fail(EXIT.NOT_FOUND, "not-a-block", "That is not a UI prototype block", `The block starts with the line "${FIRST_LINE}"; ask the person to press Copy on the page and paste the whole block.`);
|
||||
|
||||
async function cmdReadBlock(args) {
|
||||
if (!args.project) fail(EXIT.USAGE, "missing-flag", "read-block needs --project <root>.", "Pass the project's root folder, and the block on stdin.");
|
||||
const parsed = parseBlock(readStdin());
|
||||
if (!parsed.ok) notABlock();
|
||||
const { fields } = parsed;
|
||||
const fileExists = typeof fields.file === "string" && fields.file !== "" && Boolean(lstat(path.resolve(projectRoot(args), fields.file))?.isFile());
|
||||
const top = fields.prototype && NAME_RE.test(fields.prototype) ? highestRound(projectRoot(args), fields.prototype) : 0;
|
||||
const latest = typeof fields.round === "number" && fields.round >= top;
|
||||
// Saved: the File line is under this project's own specs/ folder.
|
||||
const saved = typeof fields.file === "string" && fields.file !== "" && isInside(path.join(projectRoot(args), "specs"), path.resolve(projectRoot(args), fields.file));
|
||||
out({ ok: true, fields, latest, fileExists, saved });
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------- save */
|
||||
|
||||
const refuse = (error, message, next, extra) => fail(EXIT.REFUSED, error, message, next, extra);
|
||||
|
||||
/** A file flag's text, or a usage failure naming it. */
|
||||
function readFlagFile(flag, file) {
|
||||
const text = readText(path.resolve(file));
|
||||
if (text === null) fail(EXIT.NOT_FOUND, "file-missing", `No file at ${file} (--${flag}).`, `Write the ${flag} text to a file and pass its path.`);
|
||||
return text;
|
||||
}
|
||||
|
||||
async function cmdSave(args) {
|
||||
for (const flag of ["file", "spec", "name", "block", "request", "rejected"]) {
|
||||
if (args[flag] === undefined) fail(EXIT.USAGE, "missing-flag", `save needs --${flag}.`, "Run with --help for every flag save takes.");
|
||||
}
|
||||
const root = projectRoot(args);
|
||||
const source = path.resolve(args.file);
|
||||
if (!isInside(draftsRoot(), source) || !lstat(source)?.isFile()) {
|
||||
refuse("source-not-allowed", `${source} is not a page in the prototype drafts.`, "Save the page assemble wrote into the drafts (its File line).");
|
||||
}
|
||||
const spec = String(args.spec).replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
|
||||
const m = spec.match(/^specs\/([A-Za-z0-9._-]+)$/);
|
||||
if (!m || m[1] === "." || m[1] === "..") refuse("spec-not-allowed", `--spec must be specs/<one folder name> (got ${args.spec}).`, "Pass the spec folder as specs/<name>.");
|
||||
if (!NAME_RE.test(args.name)) refuse("bad-name", `"${args.name}" is not a prototype name.`, "Use lowercase letters and digits joined by single hyphens (invoices-screen).");
|
||||
|
||||
// No link anywhere on the way down: specs/, the spec folder, prototypes/.
|
||||
const specsDir = path.join(root, "specs");
|
||||
const specDir = path.join(specsDir, m[1]);
|
||||
const protoDir = path.join(specDir, "prototypes");
|
||||
for (const dir of [specsDir, specDir, protoDir]) {
|
||||
const s = lstat(dir);
|
||||
if (s && !s.isDirectory()) refuse("spec-not-allowed", `${rel(root, dir)} is a link or a file, not a folder.`, "Save into a plain specs/<name>/ folder.");
|
||||
}
|
||||
const html = path.join(protoDir, `${args.name}.html`);
|
||||
const md = path.join(protoDir, `${args.name}.md`);
|
||||
if (!args.replace && (lstat(html) || lstat(md))) {
|
||||
refuse("exists", `${rel(root, html)} or ${rel(root, md)} already exists.`, "Ask the person whether to replace the saved prototype; run save again with --replace only when they say yes.", {
|
||||
html: rel(root, html),
|
||||
md: rel(root, md),
|
||||
});
|
||||
}
|
||||
// A target replaced with --replace must be a plain file: a link would carry the write outside specs/.
|
||||
for (const f of [html, md]) {
|
||||
const s = lstat(f);
|
||||
if (s && !s.isFile()) refuse("spec-not-allowed", `${rel(root, f)} is a link or a folder, not a file.`, "Remove it, or save under another --name.");
|
||||
}
|
||||
|
||||
const block = readFlagFile("block", args.block);
|
||||
if (!parseBlock(block).ok) notABlock();
|
||||
const rejected = readFlagFile("rejected", args.rejected);
|
||||
const page = withFile(fs.readFileSync(source, "utf8"), html);
|
||||
if (page === null) fail(EXIT.INVALID, "not-a-prototype", `${source} is not a UI prototype page (no round facts in it).`, "Pass a page written by assemble.");
|
||||
|
||||
const choice = cleanBlock(block)
|
||||
.split("\n")
|
||||
.map((line) => (/^File:/.test(line) ? `File: ${rel(root, html)}` : line))
|
||||
.join("\n");
|
||||
const notChosen = rejected
|
||||
.replace(/\r\n?/g, "\n")
|
||||
.split("\n")
|
||||
.map((l) => l.trim())
|
||||
.filter(Boolean)
|
||||
.map((l) => (l.startsWith("- ") ? l : `- ${l}`));
|
||||
const decisions = [
|
||||
"## Request",
|
||||
"",
|
||||
String(args.request).trim(),
|
||||
"",
|
||||
"## Choice",
|
||||
"",
|
||||
"```text",
|
||||
choice,
|
||||
"```",
|
||||
"",
|
||||
"## Not chosen",
|
||||
"",
|
||||
...(notChosen.length ? notChosen : ["- None"]),
|
||||
"",
|
||||
].join("\n");
|
||||
|
||||
fs.mkdirSync(protoDir, { recursive: true });
|
||||
fs.writeFileSync(html, page);
|
||||
fs.writeFileSync(md, decisions);
|
||||
|
||||
// That prototype's drafts go: its folder (every round and page), found as
|
||||
// the page's own folder, two levels under the drafts root.
|
||||
const removedDrafts = [];
|
||||
const folder = path.dirname(source);
|
||||
const depth = path.relative(fold(draftsRoot()), fold(folder)).split(path.sep).filter(Boolean).length;
|
||||
if (depth === 2 && isInside(draftsRoot(), folder)) {
|
||||
fs.rmSync(folder, { recursive: true, force: true });
|
||||
removedDrafts.push(folder);
|
||||
} else {
|
||||
fs.rmSync(source, { force: true });
|
||||
removedDrafts.push(source);
|
||||
}
|
||||
out({ ok: true, html: rel(root, html), md: rel(root, md), removedDrafts });
|
||||
}
|
||||
|
||||
/* -------------------------------------------------------------------- main */
|
||||
|
||||
run(USAGE, async (argv) => {
|
||||
const args = parseArgs(argv, { booleans: ["replace"], values: ["round", "file", "project", "spec", "name", "block", "request", "rejected"] });
|
||||
const cmd = args._[0];
|
||||
const commands = { sweep: cmdSweep, "new-round": cmdNewRound, assemble: cmdAssemble, check: cmdCheck, open: cmdOpen, "read-block": cmdReadBlock, save: cmdSave };
|
||||
if (!commands[cmd]) {
|
||||
fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: sweep, new-round, assemble, check, open, read-block, save. Run with --help.");
|
||||
}
|
||||
await commands[cmd](args);
|
||||
});
|
||||
@@ -6,7 +6,7 @@ The meter is advice and never blocks. The console scores these launches itself w
|
||||
|
||||
Per-unit work is yours: `{"run":{"event":"implement-phase","id":"phase-2","tasks":9}}`, one `run` per post, never reaching the page state.
|
||||
|
||||
- `event`: `pathfinder-chart`, `pathfinder-question` (scores nothing now), `pathfinder-research`, `plan`, `revise-plan`, `document`, `implement-phase`, `implement-review-phase`, `review`, `quick-task`, `init`, `init-update`, `finalize`, `handoff`, `git`, `changelog`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`, `git-commits`, `git-conflict`. An unknown event is exit 3. Post only the events your notes name: a launch the console scores already has its points.
|
||||
- `event`: `pathfinder-chart`, `pathfinder-question` (scores nothing now), `pathfinder-research`, `plan`, `revise-plan`, `document`, `implement-phase`, `implement-review-phase`, `review`, `quick-task`, `init`, `init-update`, `finalize`, `handoff`, `git`, `changelog`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`, `git-commits`, `git-conflict`, `ui-prototype-round`. An unknown event is exit 3. Post only the events your notes name: a launch the console scores already has its points.
|
||||
- `id`: the unit (a question's slug, `phase-N`, `map`), non-empty. The same id in the same skill run is ignored.
|
||||
- `tasks`: only with `implement-phase` and `implement-review-phase`; the tasks completed (`[x]`, not blocked), a whole number 1 to 999. A phase scores one point per 3 tasks rounded up (Implement + Review one more for the review); without it, a flat 2 (or 3). It takes over the count from `headline.cleared`, never adding to it.
|
||||
- `commits`: only with `git-commits`; commits made, 1 to 999, one point per 2 rounded down.
|
||||
@@ -6,7 +6,7 @@ A local page where the person answers your questions, reads your drafts and appr
|
||||
|
||||
## Start
|
||||
|
||||
`node "<CONSOLE>" open --workflow <w>` (add `--spec specs/<idea>` when known). `<w>` is one of `dashboard`, `init`, `init-update`, `pathfinder`, `quick-task`, `plan`, `revise-plan`, `document`, `implement`, `implement-review`, `review`, `finalize`, `handoff`, `git`, `changelog`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`. Launched from the dashboard? The session is open: run the `resume` command the launch carried instead.
|
||||
`node "<CONSOLE>" open --workflow <w>` (add `--spec specs/<idea>` when known). `<w>` is one of `dashboard`, `init`, `init-update`, `pathfinder`, `quick-task`, `plan`, `revise-plan`, `document`, `implement`, `implement-review`, `review`, `finalize`, `handoff`, `git`, `changelog`, `xray`, `diagnose`, `pr-prep`, `test`, `dead-code`, `ui-prototype`. Launched from the dashboard? The session is open: run the `resume` command the launch carried instead.
|
||||
|
||||
Keep `sid`: every later command takes `--session <sid>`. `open` failing: carry on in the terminal. When `open` adds `remote` and a `note`, give the link, ask whether it opened, and move to the terminal if not. Tell the person the link (with `"inApp":true`, never print it: only how many questions are waiting) and end every terminal message with the latest `terminalLine`, verbatim.
|
||||
|
||||
|
||||
@@ -25,3 +25,5 @@ The page shows **Write a brief** for this workflow. It arrives as a send:
|
||||
```
|
||||
|
||||
Say in chat where the file went.
|
||||
|
||||
A UI prototype run inside this skill posts `{"run":{"event":"ui-prototype-round","id":"<name>-round-<N>"}}` once per round drawn, uses a `text` card to paste the choice into, and opens its page in a separate browser tab.
|
||||
@@ -5,3 +5,4 @@
|
||||
- Nothing is saved before the Large checkpoint or Phase 7: a stop before then has `finish.body` say nothing was kept, `"command":"/plan2code-1-plan"`. After the checkpoint post `"stopWarning":""`.
|
||||
- Completion finish `command`: `/plan2code-2-document`. The Large checkpoint finish is a pause: headline starts "Paused", `command` `/plan2code-1-plan`, no `dashboard`.
|
||||
- Helpers are reported as `helpers`, each `done` or `failed` before the sign-off it feeds. Questions, sign-offs and the PLAN-DRAFT stay with you.
|
||||
- A UI prototype run inside this skill posts `{"run":{"event":"ui-prototype-round","id":"<name>-round-<N>"}}` once per round drawn, uses a `text` card to paste the choice into, and opens its page in a separate browser tab.
|
||||
@@ -3,6 +3,7 @@
|
||||
Read `building.md` first.
|
||||
|
||||
- Clarifying questions are `text` or `choice`. The first (what to build) carries `"templates":"idea"`, `"fill":"note"`.
|
||||
- Launched on saved prototypes: the first card (after a `choice` of which prototype, if several) is a `recap` "What the prototype says" (`summary`: the request, the chosen variant, what carried over) in place of that `text` card; `{ok:false,text}` adds to the brief.
|
||||
- A note on an open question: reword it, `"_delete":true` it or send `"stands":true` (still fits), with your reply.
|
||||
- Post `"stopWarning":"A quick task saves nothing until it is built, so stopping now loses what we have worked out."` at the start and `""` once the build is under way.
|
||||
- **Scope check:** `choice` "Too big for a quick task?": `1` Continue (lightweight format), `2` Escalate to a full plan; measured counts against thresholds in `body`.
|
||||
@@ -33,3 +34,5 @@ Read `building.md` first.
|
||||
- **Escalated / aborted:** settle the verdict in the finish post: `"command":"/plan2code-1-plan"` with the PLAN-DRAFT's path in `body`, no review; or `"command":"/plan2code-quick-task"`. Both `"dashboard":true`.
|
||||
|
||||
Stop requests during a build: `building.md`.
|
||||
|
||||
A UI prototype run inside this skill posts `{"run":{"event":"ui-prototype-round","id":"<name>-round-<N>"}}` once per round drawn, uses a `text` card to paste the choice into, and opens its page in a separate browser tab.
|
||||
@@ -10,3 +10,5 @@
|
||||
No option, verdict, label, or helper `title`, `ask` or `result` ever offers to execute or implement. Pass `--spec specs/<feature>` to `open` or post `specDir`. Finish `command`: `/plan2code-3-implement specs/<feature>/overview.md`; abort: `/plan2code-1b-revise-plan specs/<feature>/overview.md`.
|
||||
|
||||
Helpers: lookup helpers report before the Step 2 review goes up; phase-file helpers before the Step 4 check.
|
||||
|
||||
A UI prototype run inside this skill posts `{"run":{"event":"ui-prototype-round","id":"<name>-round-<N>"}}` once per round drawn, uses a `text` card to paste the choice into, and opens its page in a separate browser tab.
|
||||
@@ -0,0 +1,31 @@
|
||||
# UI Prototype
|
||||
|
||||
## Starting card
|
||||
|
||||
One `--wait` batch after Step 1. A card cannot open with its boxes ticked, so the carry-over card's preset ticks every found item in one press, and a Skip on it keeps everything found (all ticked is the default); leave the card out for a project with no screens:
|
||||
|
||||
```jsonc
|
||||
{"title":"UI prototype","headline":{"stage":"Start","cleared":0,"total":3},"items":[{"id":"carry","kind":"multi","title":"Carry over","required":false,"body":"Ticked items look the same in every variant; unticked ones are where each variant tries its own take. Skip keeps everything found; tick only what should stay the same to free the rest. Attach screenshots or images in this card's note.","options":[{"k":"1","text":"Colors","detail":"src/styles/theme.css: accent #0f766e, gray #64748b"},{"k":"2","text":"Fonts","detail":"none found"}],"presets":[{"label":"Everything found","ks":["1"]}]},{"id":"spread","kind":"choice","title":"How different","allowOther":false,"body":"How far apart should the variants be?","options":[{"text":"Subtle","detail":"Same layout, different treatment"},{"text":"Balanced","detail":"One layout difference each","recommended":true},{"text":"Radical","detail":"Different layouts"}]},{"id":"direction","kind":"text","title":"Direction","required":false,"body":"Anything every variant should stay inside.","placeholder":"Calmer colors, bigger type, room around the totals."}]}
|
||||
```
|
||||
|
||||
A "none found" option is never in the preset. Attached files arrive as `Image:` and `File:` paths in `reply`: open each, then say per image, in your next post, whether it goes in the page or is a look to match (a `notice`, or the line in the paste card's `body`).
|
||||
|
||||
## The page
|
||||
|
||||
The prototype opens in its own browser tab through `open`; it is never a doc or an image on the console. Post one `{"run":{"event":"ui-prototype-round","id":"<name>-round-<N>"}}` for each round drawn, with the paste card.
|
||||
|
||||
## Paste card
|
||||
|
||||
A `text` item, `--wait`, `"title":"Paste your choice"`, a new id per round (`paste-2`). `body`: the three closing lines, the page's path, and the plain line when `check` left findings. `placeholder`: `Plan2Code UI prototype choice` and a few lines of the block. The answer arrives as `Paste your choice: Plan2Code UI prototype choice` with the rest indented: drop the `Paste your choice: ` prefix and the two-space indent before `read-block` and `choice.txt`.
|
||||
|
||||
## Next steps
|
||||
|
||||
After the read-back, a `menu`, `--wait`: Save, Narrow from my pick, Fresh set, Done, each with a one-line `detail`; the read-back is its `body`. Fresh set's brief goes back up as the three starting cards with new ids (`carry-2`, `spread-2`, `direction-2`), each choice as it stood marked `recommended` or in the preset.
|
||||
|
||||
## Save questions
|
||||
|
||||
One batch, `--wait`: a `choice` "Save where" (the spec folders, the launched one first and `recommended`, then "New spec", whose name comes in the note or a follow-up `text`), a `text` "Prototype name" (the proposed name in `placeholder`, `"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"`, `"patternHint":"lowercase words joined by hyphens"`), and a `text` "Why the others lost" (`required:false`, left out when already said). `exists`: a `confirm` "Replace it?", `"yesLabel":"Replace","noLabel":"Pick another name"`.
|
||||
|
||||
## The finish
|
||||
|
||||
`headline` "Prototype saved" or "Prototype done"; `body` the saved paths and the `specs/` git line, or the draft's path and that it stays for 30 days; `"dashboard":true`; `command` `/plan2code-1-plan` or `/plan2code-0-pathfinder` as fits, none when nothing was saved; never `commit`. A stop before a save: `body` says the draft is kept for 30 days and gives its path, `"command":"/plan2code-ui-prototype"`.
|
||||
@@ -757,12 +757,16 @@ export function toggleNoteTick(ticked, id) {
|
||||
/**
|
||||
* The spec a card's launch carries: the picker's selection for the cards that
|
||||
* take a spec, and for Quick Task only a diagnosed bug, whose write-up it reads
|
||||
* first. Every other card launches untargeted.
|
||||
* first, or a folder holding only saved prototypes (files on disk with a
|
||||
* `prototypes` count), which it builds from. A mid-pipeline spec with
|
||||
* prototypes is Implement's to build. Every other card launches untargeted.
|
||||
*/
|
||||
export function launchTarget(entry, sel) {
|
||||
if (!entry || !sel) return null;
|
||||
if (entry.spec) return sel;
|
||||
return entry.skill === "plan2code-quick-task" && sel.state === "diagnosed" ? sel : null;
|
||||
if (entry.skill !== "plan2code-quick-task") return null;
|
||||
const prototypeOnly = sel.state === "unrecognized" && sel.prototypes > 0;
|
||||
return sel.state === "diagnosed" || prototypeOnly ? sel : null;
|
||||
}
|
||||
|
||||
export function cardPresentation(entry, scan, sel, menu = {}) {
|
||||
|
||||
@@ -446,6 +446,14 @@
|
||||
<circle cx="14.5" cy="11" r="1.5" />
|
||||
<path d="M10 19v2M12 19v2M14 19v2" />
|
||||
</symbol>
|
||||
<!-- UI Prototype: a framed screen with three sliders. -->
|
||||
<symbol id="ci-ui-prototype" viewBox="0 0 24 24" fill="none">
|
||||
<rect x="3" y="4" width="18" height="16" rx="2" />
|
||||
<path d="M7 9h10M7 12h10M7 15h10" />
|
||||
<circle cx="10" cy="9" r="1.2" />
|
||||
<circle cx="14.5" cy="12" r="1.2" />
|
||||
<circle cx="9" cy="15" r="1.2" />
|
||||
</symbol>
|
||||
<!-- Changelog: a version tag. -->
|
||||
<symbol id="ci-changelog" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M3 4a1 1 0 0 1 1-1h7.6a2 2 0 0 1 1.4.6l7.4 7.4a2 2 0 0 1 0 2.8l-5.6 5.6a2 2 0 0 1-2.8 0L4.6 12a2 2 0 0 1-.6-1.4z" />
|
||||
@@ -734,6 +742,32 @@
|
||||
<g class="ho-arrow"><path class="as" d="M178 64 L214 64 M204 54 L216 64 L204 74" /></g>
|
||||
</svg>
|
||||
|
||||
<!-- UI Prototype: showing a screen off. He holds a framed screen up
|
||||
beside him, and its three dials slide in turn as he tunes it. -->
|
||||
<svg class="pose pose-ui-prototype" data-pose="ui-prototype" viewBox="0 4 240 216" aria-hidden="true" focusable="false">
|
||||
<ellipse class="shadow" cx="126" cy="198" rx="44" ry="5" />
|
||||
<g class="bob">
|
||||
<g class="up-screen">
|
||||
<rect class="sh" x="166" y="50" width="62" height="70" rx="8" />
|
||||
<line class="lt" x1="178" y1="70" x2="216" y2="70" />
|
||||
<line class="lt" x1="178" y1="86" x2="216" y2="86" />
|
||||
<line class="lt" x1="178" y1="102" x2="216" y2="102" />
|
||||
<g class="up-knob k1"><circle class="ac" cx="188" cy="70" r="4.5" /></g>
|
||||
<g class="up-knob k2"><circle class="ac" cx="204" cy="86" r="4.5" /></g>
|
||||
<g class="up-knob k3"><circle class="ac" cx="186" cy="102" r="4.5" /></g>
|
||||
</g>
|
||||
<g transform="translate(-14 0)">
|
||||
<rect class="fl foot f1" x="94" y="179" width="20" height="10" rx="5" />
|
||||
<rect class="fl foot f2" x="126" y="179" width="20" height="10" rx="5" />
|
||||
<rect class="sh" x="80" y="72" width="80" height="108" rx="16" />
|
||||
<path class="ln" d="M80 126 L66 150" /><circle class="fl" cx="66" cy="150" r="5.5" />
|
||||
<path class="ey blink" d="M126 86 L129.64 94.98 L139.31 95.67 L131.9 101.92 L134.23 111.33 L126 106.2 L117.77 111.33 L120.1 101.92 L112.69 95.67 L122.36 94.98 Z" />
|
||||
<path class="es" d="M110 120 Q122 129 134 120" />
|
||||
<line class="ln" x1="160" y1="126" x2="192" y2="122" />
|
||||
<circle class="fl" cx="194" cy="122" r="5.5" />
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
<!-- Changelog: keeping the record. A page of release notes stands beside him,
|
||||
and one arm reaches over to write the newest line onto it. -->
|
||||
<svg class="pose pose-changelog" data-pose="changelog" viewBox="0 4 240 216" aria-hidden="true" focusable="false">
|
||||
|
||||
@@ -22,6 +22,9 @@ const EVENT_WEIGHTS = {
|
||||
// Scores 0 itself: Git's commits are tallied per run (COMMITS_PER_POINT).
|
||||
"git-commits": 0,
|
||||
"git-conflict": 1,
|
||||
// UI Prototype scores per round drawn, not per launch: one point a round,
|
||||
// wherever the round runs (its own skill or a host skill that offers it).
|
||||
"ui-prototype-round": 1,
|
||||
};
|
||||
// A skill's fields as a table by workflow, leaving out the entries without one.
|
||||
const bySkill = (field) => Object.fromEntries(FLOW_SKILLS.filter((s) => s[field] !== null).map((s) => [s.workflow, s[field]]));
|
||||
@@ -137,6 +140,7 @@ export const RUN_LABELS = Object.freeze({
|
||||
"implement-review-phase": "Implement + Review phase built",
|
||||
"git-commits": "Commits in Git",
|
||||
"git-conflict": "Git conflict help",
|
||||
"ui-prototype-round": "Prototype round drawn",
|
||||
...bySkill("ran"),
|
||||
});
|
||||
|
||||
|
||||
@@ -1123,7 +1123,8 @@ export async function launchSkill(entry) {
|
||||
};
|
||||
// The picker's spec goes to the skill being launched, not to the card:
|
||||
// cards that take no spec (utilities, setup) launch untargeted even while
|
||||
// a spec is selected, save Quick Task on a diagnosed bug.
|
||||
// a spec is selected, save Quick Task on a diagnosed bug or a folder of
|
||||
// saved prototypes (launchTarget).
|
||||
if (target) action.spec = target.dir;
|
||||
// A Notebook tab picked in the pane rides the hop in this page only, never
|
||||
// on the action: the launched skill's `fill: "note"` box is filled from it
|
||||
|
||||
@@ -448,6 +448,31 @@ export const SKILLS = Object.freeze([
|
||||
"For code nothing calls anymore. Dead Code uses the project's own dead-code tool when there is one (Knip, vulture, cargo check and others), or searches by itself when there is not, then checks every item for callers across the whole project. Each one gets a label: Safe to remove, Check first or Warning, with the reason. It removes only what you pick, runs the tests and build, and puts back anything that breaks them. It never commits and never installs anything.",
|
||||
},
|
||||
}),
|
||||
skill({
|
||||
skill: "plan2code-ui-prototype",
|
||||
workflow: "ui-prototype",
|
||||
label: "UI prototype",
|
||||
name: "UI Prototype",
|
||||
pose: "ui-prototype",
|
||||
// The launch scores nothing (not metered, no `weight`, as Pathfinder): each
|
||||
// round drawn scores through the `ui-prototype-round` run event in meter.js.
|
||||
builds: false, phased: false, metered: false, templates: false,
|
||||
weight: null, started: null, ran: null, resume: null,
|
||||
subagents: null,
|
||||
states: "any",
|
||||
greyed: null,
|
||||
card: {
|
||||
group: "extra",
|
||||
chip: "Utility",
|
||||
spec: true,
|
||||
title: "Prototype a screen",
|
||||
icon: "ui-prototype",
|
||||
blurb: "Several versions of a screen on one page, tuned with live dials, and your pick brought back.",
|
||||
help: "Draws several versions of a screen or flow on one page with live dials; Copy and paste brings your pick back, saved into a spec only when you say.",
|
||||
about:
|
||||
"For when you want to see a screen before it gets built. UI Prototype draws several versions of a screen or flow on one page that opens in your browser. Flip between them, tune fonts, colors, spacing and feel with live dials, then press Copy and paste the result back so the next round starts from your pick. Nothing is saved into a spec until you say so, and it never changes your code.",
|
||||
},
|
||||
}),
|
||||
skill({
|
||||
skill: "plan2code-changelog",
|
||||
workflow: "changelog",
|
||||
|
||||
@@ -488,6 +488,17 @@
|
||||
14%, 56% { transform: translate(5px, -2px); }
|
||||
}
|
||||
|
||||
/* UI Prototype -- he holds a screen up, and its three dials slide one after
|
||||
another, as if he were tuning it. */
|
||||
.pose .up-knob { animation: up-knob 4.2s ease-in-out infinite; }
|
||||
.pose .up-knob.k2 { animation-delay: -1.4s; }
|
||||
.pose .up-knob.k3 { animation-delay: -2.8s; }
|
||||
@keyframes up-knob {
|
||||
0%, 20%, 100% { transform: translateX(0); }
|
||||
40%, 60% { transform: translateX(12px); }
|
||||
80% { transform: translateX(4px); }
|
||||
}
|
||||
|
||||
@media (max-width: 720px) {
|
||||
.dash { padding-top: 0; }
|
||||
.launch-stage { height: 140px; }
|
||||
|
||||
@@ -81,10 +81,35 @@ function planChangeWaiting(dir, phases) {
|
||||
return files.some((f) => PLAN_CHANGE_RE.test(notesOf(readText(path.join(dir, f)))));
|
||||
}
|
||||
|
||||
// A spec folder's pipeline position and detail, with the count of its saved
|
||||
// prototypes added to the detail and kept as `prototypes` (the dashboard
|
||||
// hands a prototype-only folder to Quick Task as what to build from). A
|
||||
// folder holding only prototypes stays `unrecognized` ("Files on disk"); its
|
||||
// detail says how many it holds.
|
||||
function classifySpec(dir, names) {
|
||||
const result = specPosition(dir, names);
|
||||
const count = prototypeCount(dir, names);
|
||||
if (!count) return { ...result, prototypes: 0 };
|
||||
const noun = count === 1 ? "prototype" : "prototypes";
|
||||
const detail = result.state === "unrecognized" ? `${count} ${noun} saved` : `${result.detail} · ${count} ${noun}`;
|
||||
return { ...result, detail, prototypes: count };
|
||||
}
|
||||
|
||||
// How many prototypes a spec has saved: the .html files directly inside its
|
||||
// prototypes/ folder (each saved with a .md beside it).
|
||||
function prototypeCount(dir, names) {
|
||||
if (!names.includes("prototypes")) return 0;
|
||||
try {
|
||||
return fs.readdirSync(path.join(dir, "prototypes"), { withFileTypes: true }).filter((e) => e.isFile() && /\.html$/i.test(e.name)).length;
|
||||
} catch {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
// A spec folder's pipeline position, from its files alone. Furthest artifact
|
||||
// wins: an overview beats a draft beats a map, so a spec mid-way through two
|
||||
// stages reports the later one.
|
||||
function classifySpec(dir, names) {
|
||||
function specPosition(dir, names) {
|
||||
const has = (re) => names.some((n) => re.test(n));
|
||||
const pfDir = path.join(dir, "pathfinder");
|
||||
const overview = names.includes("overview.md");
|
||||
|
||||
@@ -374,7 +374,7 @@ const KEPT_CONSOLE_ENTRIES = new Set([...PROTECTED_CONSOLE_FILES, "sessions", "r
|
||||
// (~/.plan2code/console/<version>/) and removes the old ones, so Cleanup never
|
||||
// offers it.
|
||||
export const CONSOLE_VERSION_DIR = /^\d+\.\d+\.\d+$/;
|
||||
export const KEPT_PLAN2CODE_ENTRIES = new Set(["console", "bin", "launcher.json", "install.json", "models.json", "handoffs", "notepads", "app", "app.json", "agents.json"]);
|
||||
export const KEPT_PLAN2CODE_ENTRIES = new Set(["console", "bin", "launcher.json", "install.json", "models.json", "handoffs", "notepads", "app", "app.json", "agents.json", "prototypes"]);
|
||||
// A stray must sit untouched this long before Cleanup lists it. The same
|
||||
// folders hold files that live for milliseconds -- a held
|
||||
// `workspaces.json.lock`, a `<file>.<pid>.tmp` between its write and its
|
||||
|
||||
Reference in new issue
Block a user