diff --git a/CHANGELOG.md b/CHANGELOG.md index 306f00b..7850000 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob Sections dated before 2026-09-19 predate the cycle and stay as they are. ## Unreleased +- new(design-artifacts, checkpoint-design): **the ui-ux-pro-max ideation library is now an explicit, opt-in interview question (D1) instead of a paragraph nobody acted on.** With no client brand, Step 0b now asks "where does the look come from?" as a `choice`: (a) fetch the public MIT dataset read-only at a pinned commit (`09170ee`) into a git-ignored `.ideation/` and propose three directions, safe to bold, or (b) Atlas defaults; recommendation (a) for demo/presales/POC, (b) for a like-for-like rebuild. Only a yes fetches; on no there is no network call. The brand question itself stays `user-only` and CAC-4 no longer offers "use Atlas defaults" as its default answer. The step names the commands (the repo's own `search.py --design-system -f markdown`, no toolkit wrapper per `skills-over-scripts.md`), what to keep and drop from its output, a contrast check before presenting, what never ports (`--persist`, CSS/Tailwind/React, landing patterns, chart colours, spacing), and the Decisions row that records direction + commit + source rows. Evidence: two full pipeline runs on the same source app used neither the library nor a deliberate direction, and the user picked the run they had pushed to "more 2027"; a test on that app produced three directions from three queries in 0.10–0.23 s each, ~3.1 KB (~800 tokens) per direction, and one of them ported to a `:root` token block + class-only px CSS and rendered. "Atlas defaults are usually right" becomes "Atlas defaults for a like-for-like rebuild; a showcase direction for a demo". — MendixMau, from two field builds - learn(bug-logs): **`BUG-DRAFT-module-close-never-surfaced`** — a whole build ran without the module close (LOOK, wiring sweep, design-audit) ever becoming the next action: the module brief declares it, but nothing on the build path asks for it. Toolkit-side, not mxcli; the closing rows and "LOOK owed" status from the recent build-loop changes cover part of it. — MendixMau, from a field build - process(research): **`process/context-cost-research-2026-09-30.md` — how much each session is made to read, file by file, and the plan to cut a build helper's start load from about 109k tokens of skills to about 15–20k.** The routing `agents` column filters only the agent stubs, so every Stage 5 helper loads the lead's, tester's and reviewer's rows too; the runbook alone is 24k of which a page helper needs at most 1.2k. Includes the per-file keep/trim/move table, the preflight and microflow probe results against mxcli v0.24.0, the page-preflight-versus-screenshot-loop question, and a four-variant test build to measure the cut before it ships. — MendixMau - process(project-bin/context-pack.sh): **context packs have an on/off switch, and a pack step is no longer a build-plan row.** PROJECT.md `Context packs: on | no-brain | off` (default on; `MXTK_CONTEXT_PACKS` overrides for one command). `no-brain` leaves out the `mxcli brain` section. `off` exits 3, and the dispatcher falls back to the reading list (`iterative-build-loop.md`), so a CLI change that breaks `DESCRIBE` or `brain brief` costs one register line, not a revert. The script header lists every file to touch if packs are ever removed. `module-brief.md` now says a Build step is one dispatch (one script) and must not size the build plan, which sizes rows by use case. Why: in a field build, "one row per dispatch" fed into a Stage 4 re-run that wrote 246 rows instead of 137. Pinned by `tests/wave2/test-context-pack.sh`, which replays DESCRIBE and impact output captured from mxcli v0.23.0 (both layouts, all four exit codes, every switch value). — field build, MendixMau diff --git a/skills/checkpoints/checkpoint-design.md b/skills/checkpoints/checkpoint-design.md index f403b4f..7e2b085 100644 --- a/skills/checkpoints/checkpoint-design.md +++ b/skills/checkpoints/checkpoint-design.md @@ -26,7 +26,9 @@ generic Atlas output that will need rework. Design direction is the checkpoint users most often want to *talk about*, not pick from a list. Open with a divergent conversation: show references (the source app's look, the client's brand, -2–3 mood directions described concretely or as quick HTML swatches) and discuss — what should +2–3 mood directions described concretely or as quick HTML swatches — with no client brand, +take them from the ideation library when the user says yes to it, `design-artifacts.md` Step 0b +question D1) and discuss — what should this app *feel* like, what must carry over from the brand, what should deliberately change? If the user says anything like "let's ideate on the design" at any point, this conversation IS the response — do not generate the design system or launch agents until it converges and the @@ -76,7 +78,12 @@ or desktop-first. Use that to set the recommended option. > "Do you have branding guidelines, a Figma file, or an existing design system? > > Drop a link, paste the key details (colors, fonts, logo), or describe the visual direction. -> If none — say 'use Atlas defaults' and we'll proceed with out-of-the-box Atlas styling." +> If there is none, say so — the next question is where the look comes from." + +This question is `user-only`: no default answer is offered in it. A "none" leads to +`design-artifacts.md` Step 0b question D1 (ideation-library directions vs Atlas defaults), a +`choice` with its own recommendation — Atlas defaults are one answer to D1, not the default +answer to this question. **What to do with the answer:** @@ -85,7 +92,7 @@ or desktop-first. Use that to set the recommended option. | Figma link | Add to `PROJECT.md` → `## Decisions` → `Design assets:`. Note which flows are designed vs wireframe-only. | | Brand doc / PDF | Same as above. Extract: primary color, font family, logo usage rules. | | Verbal description | Record key decisions (primary color, font, tone) in `design-artifacts.md` inputs. | -| "Atlas defaults" | Note it. No custom tokens needed. Skip Atlas customization in MDL layer. | +| "None" | Ask D1 (`design-artifacts.md` Step 0b). On "Atlas defaults": note it, no custom tokens, skip Atlas customization in the MDL layer. On "ideation library": fetch at the pinned commit, propose three directions, record the chosen one. | | Existing Mendix design system | Identify the theme module. Use its layout + widget naming conventions throughout. | --- @@ -96,5 +103,6 @@ or desktop-first. Use that to set the recommended option. PROJECT.md → ## Decisions: Atlas layout: [chosen layout] Platform target: [web / responsive / native / both] - Design assets: [Figma URL / brand doc link / 'Atlas defaults' / description] + Design assets: [Figma URL / brand doc link / 'none' / description] + Design direction: [brand / Atlas defaults / — ui-ux-pro-max @ + source rows] ``` diff --git a/skills/conversion-runbook.md b/skills/conversion-runbook.md index 3021fe7..e186eae 100644 --- a/skills/conversion-runbook.md +++ b/skills/conversion-runbook.md @@ -666,7 +666,7 @@ The biggest gap before this runbook existed. Module boundaries, wiring diagrams | | | |---|---| -| **User defines** | ① One Mendix app or several (if flagged at Stage 0). ② **Module boundaries** (agent proposes with `modularize-domain.md` criteria). ③ **Buy vs build vs stub, per fit-gap item** — the confirming step `brd-to-build-plan.md` assumed already happened. ④ **Target security / role model** — not just whether auth existed in the source, but what the target should be. ⑤ **Data volumes, concurrency, NFRs** — these decide indexing, pagination, datagrid-vs-paged-gallery, loop batch sizes. ⑥ **Integration contracts** — real or stub, endpoint, credentials, owner, test environment. ⑦ **Branding inputs** — logo, palette, type, spacing, per `design-artifacts.md`. | +| **User defines** | ① One Mendix app or several (if flagged at Stage 0). ② **Module boundaries** (agent proposes with `modularize-domain.md` criteria). ③ **Buy vs build vs stub, per fit-gap item** — the confirming step `brd-to-build-plan.md` assumed already happened. ④ **Target security / role model** — not just whether auth existed in the source, but what the target should be. ⑤ **Data volumes, concurrency, NFRs** — these decide indexing, pagination, datagrid-vs-paged-gallery, loop batch sizes. ⑥ **Integration contracts** — real or stub, endpoint, credentials, owner, test environment. ⑦ **Branding inputs** — logo, palette, type, spacing, per `design-artifacts.md`; with no brand, the design direction (Step 0b question D1: ideation-library directions or Atlas defaults). | | **Agent produces** | `.mx-brd.json`, `architecture/` (module defs, layer diagram, wiring diagram, `fit-gap.md`, `blueprint.html` checkpoint render — plus a workflow diagram and/or agent-wiring diagram in `blueprint.md`/`blueprint.html` when CAC-3's Q3 flags real scope for either, plus cross-persona journey diagrams + journey list — `architecture-blueprint.md` Step 3d — whenever the BRDs carry more than one persona; single-persona skip recorded as a one-line note, never silent), `design/` per `design-artifacts.md`'s full output list: `ds.css` + `design-system.html` + **`wireframes/*.html`, one annotated wireframe per screen** — the design system without the wireframes is half the deliverable and fails the gate. | | **Surface** | `module-design.html` · `architecture/blueprint.html` (generated render of `blueprint.md` — architecture-blueprint.md Step 7, never hand-edited) · `design-system.html` + `wireframes/*.html` | | **Gate ✋** | Boundaries approved. Marketplace calls made. Role model, volumes, integrations and branding **each asked and answered**: `CONFIRMED`, or explicitly delegated by the user ("you decide" → `ASSUMED` with risk). Never `ASSUMED` without the question having reached the user. Close-out block pasted before the ✋ decision is asked (§1b rule 7) — this stage has no closing checkpoint, so the gate is where the Stage-4 open (its approach, skills and optional artifacts) is shown. **No architecture/design artifact is produced before its checkpoint ran.** | diff --git a/skills/design-artifacts.md b/skills/design-artifacts.md index ac2c9de..55661da 100644 --- a/skills/design-artifacts.md +++ b/skills/design-artifacts.md @@ -66,19 +66,101 @@ Branding is an input, not an afterthought — and not a checkbox to tick silentl | Basis | When | Effort | |---|---|---| | **Client branding guidelines** (logo, palette, type, spacing) | Real project — request them as an analysis deliverable | depends | -| **Atlas defaults** | POC / no brand yet — matches the actual build target 1:1 | zero | +| **Atlas defaults** | No brand, like-for-like rebuild — matches the actual build target 1:1 | zero | +| **Ideation-library direction** (ui-ux-pro-max, question D1 below) | No brand, demo / presales / POC — a deliberate, current look | low | | **Neutral placeholder palette** (the `dataviz` reference palette) | Design-forward but brand-agnostic, swap later | low | -For a faithful rebuild POC, **Atlas defaults** are usually right — the wireframes then look like what Mendix will actually render, so coverage comparison is like-for-like. Record the choice; it cascades into every token below. +**Atlas defaults fit a like-for-like rebuild, not a demo.** When coverage comparison against the +source is the point, Atlas defaults are right: the wireframes look like what Mendix will render. +For a demo, presales or POC build, prefer a deliberate **showcase direction** instead — fidelity +covers behaviour, not looks. Measured on two runs of this pipeline over the same +source app (2026-10): the run that carried the source app's own look produced clean, generic, +dated wireframes; the run where the user demanded "more 2027, slick, modern" is the one they +picked side by side. Neither run used the ideation library below, which was then a passive +paragraph here. Record the choice; it cascades into every token below. + +### Two questions, asked in order — never merged into one + +1. **"Is there a brand guideline, a style guide or an existing design system?"** — `user-only` + (`interview-protocol.md`): asked on its own, with **no recommendation**, never as a line in a + batch. A yes ends here: the brand is the basis. +2. **If there is no brand: "Where does the look come from?"** — a `choice`, asked in the Step 0b + batch next to the navigation-layout question below, in the two-options-plus-recommendation + shape: + +> **D1 — Design direction (no client brand)** +> There is no brand guideline, so the look is ours to choose. Purpose on record: * Stage P purpose row from `PROJECT.md`>*. +> - **(a) Three directions from the ui-ux-pro-max ideation library.** I fetch a public, MIT-licensed +> design dataset (88 styles, 192 palettes, 74 font pairings, 119 UX rules) read-only, at a +> pinned commit, into `.ideation/` (git-ignored, ~30 MB, ~2 s). I search it for this domain and +> come back with three directions, safe to bold, as the next question. One more question; a +> deliberate, current look. +> - **(b) Atlas defaults.** No fetch, zero effort, and the wireframes look exactly like what +> Mendix renders, so coverage comparison is like-for-like. It also looks like every other +> Mendix app. +> +> **I recommend (a)** for a demo, presales or POC build; **(b)** when the purpose is a faithful +> rebuild judged on coverage. + +"Something else" is always open: a direction the user describes, or the neutral placeholder +palette. **Only a yes to (a) triggers the fetch. On (b) or anything else, nothing is fetched and +no network call is made.** + +### On (a): fetch, search, propose three + +The dataset is the fact source and its own search CLI is the instrument (Python 3 standard +library only, BM25 over the CSVs) — there is no toolkit wrapper. Fetch exactly the pinned commit, +from the project root: + +```bash +PIN=09170eec67eefd46a7ae85de61b40c194020f997 # ui-ux-pro-max-skill master, 2026-09-27 +git init -q .ideation/ui-ux-pro-max +git -C .ideation/ui-ux-pro-max fetch -q --depth 1 https://github.com/nextlevelbuilder/ui-ux-pro-max-skill "$PIN" +git -C .ideation/ui-ux-pro-max -c advice.detachedHead=false checkout -q FETCH_HEAD +grep -qxF '.ideation/' .gitignore 2>/dev/null || echo '.ideation/' >> .gitignore +cd .ideation/ui-ux-pro-max/src/ui-ux-pro-max/scripts +python3 search.py "" --design-system -p "" -f markdown # one bundle per seed +python3 search.py "" --domain ux -n 4 # UX rules for the key screens +``` -**No brand and no opinion? Borrow the ideation database.** When the client has neither guidelines -nor a preference, the public [ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) -repo (MIT) is a good input for this interview: clone it read-only and search its -`src/ui-ux-pro-max/data/` CSVs (styles, color palettes, font pairings, UX guidelines) for 2–3 -directions that fit the client's domain, then present those as the interview options. **Reuse -stops at the data.** Its implementation guidance targets CSS frameworks (React, Tailwind, etc.), -not Mendix — the chosen direction lands as `ds.css` tokens, the Atlas mapping table, and -StyleGallery choices per `learned-stylegallery.md`, never as its CSS or component code. +Moving the pin is a toolkit PR that changes this one line, never a per-project `git pull`. + +Then the judgement, which is yours: + +1. **Map the domain to rows yourself.** The dataset has no row for most enterprise back-office + domains (purchasing, ERP, claims, case handling): a bare domain query returns noise (a + purchasing query ranked "Food Delivery" second). Pick three seed queries that span safe to + bold: the nearest product row (e.g. `invoice billing finance back-office enterprise`), the + AI/agent row when the app has an agent (`AI agent copilot automation platform SaaS`), and a + bolder option (`financial dashboard dark data-dense analytics`, or a bento/soft-UI style). +2. **Run `--design-system -f markdown` once per seed.** Each is ~3 KB (~800 tokens) and returns in + under 0.3 s, so three directions cost ~2.5k tokens — cheap enough to run inside the interview. + Keep the Style name, the Colors table, the Typography pair and the Avoid list. Drop the + Pattern section (landing-page CTA advice such as "Contact Sales", wrong for a back-office + app), the font `@import` URLs (the font goes into the theme) and the pre-delivery checklist + (web/Tailwind items). +3. **Check every on-colour pair before you present it.** The palettes are mostly AA-adjusted + already, but a dark row can make the primary vanish: `#0F172A` on `#020617` is 1.13:1, so that + direction must use its accent as the action colour. Say so in the option, do not fix it + silently. +4. **Present the three as the follow-up question** (D1a), each with a name, a one-line feel, + five hex swatches, the font pair, one signature idea (what the agent or decision screen does + differently), and the source rows. Recommend one, with the reason. If the user wants to see + them, render quick HTML swatches — that is the CAC-4 brainstorm, not a design system yet. + +**Reuse stops at the data.** The chosen direction lands as `ds.css` tokens (three tiers per +`learned-stylegallery.md`), the Atlas mapping table and StyleGallery choices — class-only CSS in +px. What never ports: `search.py --persist` (it writes `design-system//MASTER.md`, a second +design spec that would compete with `ds.css`); any CSS, Tailwind, React or `--stack` guidance; +the landing-page patterns; its chart colours (chart series come from the `dataviz` palette); +its spacing scale (the toolkit's is `design-spacing.md`, 8/16/24/32/48). + +**Record it** as a Stage 3 row in the `PROJECT.md` Decisions table, with the commit and rows so +the direction can be reproduced: +`| 3 | Design direction: — ui-ux-pro-max @ 09170ee; colors.csv "", styles.csv "