Skip to content

feat(design): sketch-and-critique designer with mockup mode and M3E strict mode - #8

Merged
Conava merged 11 commits into
mainfrom
feat/designer-web
Nov 17, 2026
Merged

Conava merged 11 commits into
mainfrom
feat/designer-web

Conversation

@Conava

@Conava Conava commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Description

Replaces devline's designer. The old one was a port of a catalogue-based design skill: CSV catalogues of styles, palettes and fonts, picked by BM25 search. Its output had the generic AI look. The new designer sketches cheaply, has a separate critic judge rendered captures, and refines only what survives. We ran a blind comparison against two prototypes, and the sketch-and-critique approach won on every subject. It also adds a mockup mode for iterating on a single change, and a Material 3 Expressive strict mode backed by a new kb-m3e knowledge base.

Exploration loop. Seeds and cheap sketches run on sketch_model. Each sketch is a finished first screen plus a storyboard of its signature motion. A fresh critic culls them, the user picks from a screenshot gallery, and only the picks become full builds. Each build goes through capture, critique and refine, scored for Wow and Craft. A design is done when both scores reach 8 or higher, or after at most 2 refine rounds. A critic never scores work it built itself and judges only from captures. The signature rules require every design to have one screenshot-worthy moment, and every exploration includes at least one ambitious 3D or interactive sketch.

Phone design. Web pages are always designed for desktop and phone, and app UIs and widgets too when the product runs on phones. references/phone.md treats the phone as its own composition: what leads the first screen, one idea per screen, thumb reach, no hover-only affordances, safe areas and svh/dvh. The signature has to work on the phone too, adapted for touch and lighter 3D; a desktop-only signature counts as half, and a shrunk desktop caps Craft at 6. Sketches include their phone first screen. capture.mjs adds --phone-sheet (stills along a touch-scrolled 390x844 page) and --phone-video, and the gallery shows the phone strip.

Mockup mode (/devline:design mockup <what>). It mocks only the surface the change touches, in the project's own tokens, fonts, icons and wording. A separate control section holds only the inputs that can't be changed inside the mock. A feedback log keeps later rounds from undoing earlier decisions, and a demo script (<slug>.demo.json) drives the scripted captures.

M3E strict mode and kb-m3e. Strict mode turns on when the project uses Material 3 Expressive, when design_mode says so, or when the user asks for it. In strict mode every value comes from kb-m3e, which is built from m3.material.io and the androidx Compose and Material Web token sources. The designer may decide things only where the knowledge base marks a line Room for choice:. The critic runs the compliance checklist and fails anything off-spec. If kb-m3e is missing, strict mode stops instead of falling back to values from memory.

Living design system. When a design is approved it is written to docs/design-system/MASTER.md, with tokens, components, rules, an acceptance checklist and an append-only Corrections log. Planner, implementer and reviewer treat it as binding. Only tokens are allowed: a literal colour, size, radius, shadow or duration is a review finding.

Settings. New keys: design_model, sketch_model, mockup_model, design_sketches, design_pick and design_mode. They are documented in the README and in the setup template.

Captures. Captures need playwright-core and Chromium in ~/.cache/devline/capture. The skill asks before installing them. Without them, the critic judges from the HTML only.

Removed. The kb-design knowledge base, the frontend-planner agent and its output templates.

Credits and licences. skills/design/CREDITS.md lists every source and its licence. The Modern Web Guidance guides are copied unchanged into references/web/, with the Apache-2.0 text in references/LICENSE-APACHE.

Verification

python3 -m unittest discover -s skills/design/tests
python3 -m unittest discover -s skills/kb-m3e/tests

Then, in a project, try /devline:design mockup <something> (for example, a dialog or settings screen) and open the HTML it writes.

…d-critique designer

The old designer ranked a fixed CSV catalogue and produced the same generic look for every subject. The new designer agent works one step per launch (seeds, sketch, cull, build, refine, critique, mockup) and is judged only from rendered captures by a launch that didn't build the design.

- skills/design: exploration and mockup flows, references, CREDITS.md and the Apache-2.0 licence for the unchanged Modern Web Guidance copies
- capture.mjs: --stills-only for sketches and --video script --demo to replay a demo script with a still after each step; the fixed keyboard mode is gone
- gallery.py: card gallery over items and their captures, servable with http.server
- slop-scan.mjs: reflex-font is a medium hint, not a blocking finding
- remove kb-design, frontend-planner and its output templates
…tages to MASTER.md

The pipeline still launched the removed frontend-planner and pointed planner, implementer and reviewer at a design file that no longer exists.

- Stage 1.5 runs the design skill's exploration loop, asks for picks with AskUserQuestion, accepts an existing mockup as design input and writes docs/design-system/MASTER.md on approval
- planner, plan format, implementer and reviewer read MASTER.md and enforce tokens over literal values
- README and the setup template describe the designer, its two modes, the design_* settings and the capture prerequisite
Guards against dangling reference paths, private strings and unattributed sources in a public skill, and exercises gallery.py, slop-scan.mjs and (when Playwright is installed) capture.mjs on small fixtures. CI runs the suite; the capture tests skip there.
The pick gallery showed culled sketches, and the private-name test published the very words it guards against.

- gallery.py --only <file> keeps the stems a cull.md marks keep (or a plain stem list), in that order; the pick step uses it
- the private-word test compares SHA-256 hashes of lowercase word tokens and scans its own directory too
- signature.md examples and the first worked pattern are generic instead of tracing specific subjects
The designer's strict mode and implementers in M3E projects need exact
spec values and a clear line between fixed values and the choices the
spec leaves open.

kb-m3e covers motion springs, shape and morphing, colour roles, type
scale, layout and window size classes, and 22 components, each with its
motion. Values come from the m3.material.io spec, androidx Compose and
Material Web tokens; conflicts between them are noted. Every permitted
decision is marked "Room for choice", and checklist.md is the critic's
compliance pass.
One exploration run was about 25-30 opus launches. Seeds, sketch and cull
now launch with the new sketch_model setting (default sonnet); build,
refine and critique keep design_model (opus). Refine rounds drop from 3
to 2.
# Conflicts:
#	.github/workflows/validate.yml
#	README.md
#	agents/implementer.md
#	agents/reviewer.md
#	skills/devline/SKILL.md
The designer treated phones as an afterthought: one phone still and a
"works at 375" line, so phone layouts ended up as shrunk desktops and
signatures silently dropped off on touch devices.

- references/phone.md: phone composition (first screen, reading order,
  thumb reach, touch not hover, safe areas, svh/dvh, landscape) and how
  the signature adapts (touch/scroll-driven, lighter 3D, fallback).
- Targets: web pages always desktop + phone; app UIs and widgets get a
  phone layout when the product runs on phones.
- Sketches include the phone first screen; storyboards say how the
  signature works on the phone; build and refine cover the phone.
- Critic: Craft covers the phone, a shrunk desktop or missing phone
  signature caps Craft at 6, findings name phone captures.
- capture.mjs: --phone-sheet (touch-scrolled 390x844 stills) and
  --phone-video; gallery shows the phone strip.
@Conava
Conava merged commit 3bab3e1 into main Nov 17, 2026
1 check passed
@Conava
Conava deleted the feat/designer-web branch November 17, 2026 18:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants