Repository navigation
Conversation
Workspace Sync Dry-Run CompleteDry-run completed successfully - no changes were made Dry-Run Results |
lucaslyl
marked this pull request as draft
September 28, 2026 08:25
lucaslyl
changed the title
Interviews the user and writes a buildable brief as a software-factory Wiki card, with no design decisions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lucaslyl
force-pushed
the
eco-579-domain-interview-skill
branch
from
September 28, 2026 09:13
095e47e to
ba2f1a1
Compare
Decides how a unit looks, moves and responds before it is built, and records it as a DESIGN-DIRECTION.md. SKILL.md routes to one reference file per phase. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The direction is a `## Design direction` section on the unit's brief card, never a markdown file. The skill stops after the hand-off summary; build order and the after-build gate belong to the builder and design-review. Adds a Reads / Writes / Stops-when contract. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Refining a brief keeps the sections later stages added to the same card. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
lucaslyl
commented
Sep 28, 2026
lucaslyl
left a comment
lucaslyl
left a comment
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Focused on the new domain-interview skill's own internal consistency and its consistency with the sibling skills it tells the reader to load (source-code-editing, catalog-reuse, boxel-environment's tool-selection docs) — not on the Wiki/software-factory contract itself, which lives outside this repo and isn't checkable here.
Bottom line: no blocking issues. One non-blocking finding below — the create-then-patch-fields recipe conflicts with the platform's documented tool-selection rule, though the skill's own "check it landed" step recovers from it.
Adjacent, out of scope: none noticed.
Bring design-direction's history into this branch so domain-interview can hand off to it directly, resolving the follow-up noted in this PR's description. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Offer design-direction as the next stage when the brief is done, instead of stopping with no next-step guidance. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
lucaslyl
changed the title
Add a single-surface / multi-object fork at Phase 1, decided from the schema's link calls: a unit whose CardDefs are only ever read through one screen gets one screen with tabs and filters as interaction rows, and skips the nav and set-acceptance machinery. Multi-object units still get real screens, but only the first is written out in full before the build. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Layout and interaction were two passes over the same screen, and the hand-off was four bullets of reporting on the end of the write. Merge them into a first-screen phase and a write-and-hand-off phase, renumbering the references that named the old six. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The direction ended by reporting and stopping, which dead-ends a pipeline whose first stage now offers its next step. Offer build, motion-authoring or adjust as a choice, gated on the motion line it just wrote. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Both were written against a file-based pipeline, where each stage dropped a markdown file beside the last. The brief card replaced that, so their output is retargeted: motion-authoring appends a Motion section to the same card with patch-fields, and design-review reads the card's acceptance lines and writes nothing, since a review scores rather than decides. Brings the scroll reveal/scrub pattern with them — motion-authoring's engine rows start from it rather than rewriting the observer. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lucaslyl
changed the title
The software-factory Wiki card held every stage in one content blob, so each stage had to read the whole brief back and resend all of it to add its own section — 14k+ characters per patch, and the field every stage could accidentally truncate. BriefCard gives spec, designDirection and motion their own MarkdownField: a stage replaces only its own field, and a change to one block inside it is an apply-markdown-edit, not a resend. The definition ships as a reference file and is written into a realm that lacks it, so nothing crosses realms. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The definition belongs with the other shared CardDefs, not as a file the skill copies into each realm — one definition, nothing to drift. The skills now adopt from @cardstack/catalog/cards/projects/brief. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
1 of 2 tasks
A marketing screen is judged against the best of its kind, so the style phase names three to five real sites first, and says whether it looked or recalled — the Boxel assistant cannot fetch pages, only whitelisted APIs and Google image search. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Questions typed as prose made a non-expert compose answers from scratch, and a four-question batch written up front went wrong all at once: "spa" was read as a medical spa before anyone checked. Each round is now a choice-UI call of at most two questions, and the first call asks what the thing is and who it's for, with ambiguous readings offered as answers. Depth (Quick, Standard, Deep) is never asked. Every interview starts Quick and goes deeper only where the answers, or "Not sure, suggest for me" picks, show gaps; call counts are ceilings, and the brief records which depth it was written at. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
"Where the environment supports it" let the model type questions as prose. Every ask (feeling, interaction fork, style directions, revision scope, hand-off) is now one choice-UI call: single-select by default, recommended first, each option saying what it commits the build to, and lettered options in chat only when no choice tool exists. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A one-word feeling answer gets the default it usually produces: "calm" becomes a pale grey page. Phase 0b turns the brief and the feeling into `## Story` (one image, a named reader, a voice, a scene per screen or band with what they feel and what must never happen), and every later phase argues from it. The feeling question now offers scenes, never adjectives, alongside a question about the reader's moment. The story is not put to the user as text; each Phase 3 style direction shows its reading of the story next to a palette whose colours each have a role in the story's image, so picking a direction is picking a reading. The skill opens on the art-director bar Phase 3 already used, so the story is written to it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
"Create me a landing page" matched both domain-interview ("even when
the user sounds confident") and design-direction ("even when nobody
asks"), so the model guessed. The index now asks once: just build it
(the default, since most users want to see something first), plan it
first (recommended only for specialist domains), or build from an
existing brief. The two skills' descriptions no longer claim the same
request.
"Just build it" still asks what it is and who it's for in one call,
researches real examples where a browsing tool exists, and writes a
two-sentence story the mockup is argued from.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Included here for testing alongside the design pipeline only. This belongs in its own PR and will be moved to a separate branch before this one merges. The assistant had no build-time way to fill sample instances' image fields. host-commands-reference now declares generate-thumbnail (any OpenRouter image, not only thumbnails) and download-file-to-realm, both with approval, and boxel-file-def/references/sample-images.md picks a source by scenario (the user's own, AI-generated, stock, or a placeholder) and links each without breaking the realm. Never guess an image URL: a made-up Pexels ID loads an unrelated photo. asset-selection-guidelines drops the guessing advice and the dead source.unsplash.com, via.placeholder.com, unDraw and SVGBackgrounds patterns. attach-remote-image imported ImageDef from @cardstack/base/image, whose default is ImageCard; it now uses @cardstack/base/image-file-def. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Resolves the glossary conflict with the screenshot-to-captures rename (#150): main's renamed entries kept, with this branch's Sample images entry added after GenerateThumbnailCommand. Follows the rename in this branch's own text: design-review's capture table and pattern link now name CaptureCardTool, POST /_capture-card and integrate-capture-card-format, and motion-authoring and the scroll-reveal pattern say capture rather than screenshot service. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…very media slot
Three gaps found in real Claude Code builds (a rider app, a cinema app)
and in Chuan's review:
- Look check. "Plan it with me" (domain-interview) makes no design
decisions on purpose, and since design-direction was retired nothing
after it asked the user about the look, so the careful route gave less
say than the shortcut. boxel-design now runs a Look check at build
entry: the shortcut's feel and real-details questions, asked once and
only when unanswered ("Use what's in the brief" when the spec already
holds facts), recorded as Look: and Real details: lines in the brief's
designDirection. The shortcut points at the same block, so nothing is
asked twice. domain-interview's hand-off, the glossary and
design-review say the same.
- Review from a terminal. Both rider sessions skipped the automatic
design review because no skill named a capture tool outside the app.
capture.md and the index name `npx boxel screenshot` (with a tall
--viewport for cards that scroll inside their root), a blank region
is re-captured once and then reported, and Home lists use embedded
rows, fitted only for tile grids, since fitted tiles hid the data.
- Media slots. Builds shipped gradients or initials where photos belong,
or random picsum photos as film posters. Every media slot now ships
with an image: real photos from Openverse when the session can run
curl (Unsplash and Pexels search pages refuse non-browser requests),
each URL load-checked, else a labelled placeholder in theme colours
sized to the slot; named fictional people and real copyrighted
subjects always get placeholders; in the Boxel app, AI images are
offered after the build as one batched question. The file's own
contradictions (a solid-colour fallback as the default, dead hosts in
the style table) are removed.
Tested: the plan route asked the Look check once and changed only
designDirection; two cinema simulations filled every media slot (real
photos where the load check passed); a real staging build had no empty
section and placed 2nd of 5 against four real cinema sites in a judged
comparison, with its design review run through the CLI.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ound A real "kid swimming course app" build still shipped no photos: it followed the playbook's pointer to sample-images.md, whose source table still offered "Placeholder (Lorem Picsum, placehold.co)" and never mentioned Openverse, which lived only in asset-selection-guidelines.md. It drew CSS boxes where photos belong. - sample-images.md now holds the Openverse recipe (one query per subject, 20 results so a refused host has fallbacks, title match, load check, thumbnail only for small tiles), a source table led by Openverse photos and labelled placeholders, and the rule that every media slot of every sample instance gets an image (a gradient, initials or CSS box is not one). It drops a duplicated paragraph and the advice to open Unsplash or Pexels pages, which refuse a terminal. - asset-selection-guidelines.md keeps the policy and points at the recipe; the playbook and boxel-design's reference list say the same. From the e2e cinema build and its review: - critical-rules: a marked slot never removes the main action; Book, Buy, Enrol or Sign up stays on screen and points at a slot until the link is known (the judge found no Book button anywhere). - capture.md: a fitted capture on its own can come back without the card's theme; check it inside its parent before reporting it (the review spent a fix round on this). - motion-baseline: set --i with the cssVar helper; a literal style='--i: 2' fails no-inline-styles. - index step 1: the call asks up to four questions; domain-interview's two-per-call limit is for its own rounds. - check-palette.mjs reads a StructuredTheme JSON's rootVariables, so it finds every role without flags. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Both judged end-to-end builds lost points on the same defect: the user could not see what to do. The cinema build had no Book button; the swim school build (an internal app) showed no Add swimmer or Take attendance. The rule added last commit named only public verbs, so an internal app read as exempt. - critical-rules: a standalone "Main action always on screen" rule. Every app names one main action for its primary user (one per audience view when there are two), shown as a button on Home without scrolling at desktop and phone widths and repeated on the cards it applies to. An external target with no link opens a marked slot and is never replaced by a home-made booking system; an internal target works in the first build as an @operation, since a "coming soon" button there is an unfinished feature, not a missing input. Only the main action must work; others wait in a "Next to add" note, never as live-looking dead buttons; a blocked operation shows disabled with its reason. "Never invent proof" keeps a one-line pointer. - index (app branch): name the main action and give it one working @operation before polishing layout. - design-playbook: one primary-styled button on Home, in reach on a phone, repeated where it applies. - design-review (constraints): a main-action check with blocker, major and minor severities, and "not exercised" when the session cannot run it. - card-operations-authoring: the first build's main action as the common reason to declare one create-and-link operation. Decided by a council run (2 of 3 for a working operation over a stub, 2 of 3 for a standalone rule); not yet exercised in a real build. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…iew-skill # Conflicts: # skills/glossary.md
Contributor
|
This PR shud be split up for easy review. it's too big |
…sible control work - design-review/references/build-check.md: the builder captures its own work and fixes every pass/fail line (names, fill, media, phone, colour roles, type, controls, one signature, job first, same facts) before the review, and again after the fix round. No score. - The automatic review runs one fix round, then offers another as a choice; the re-score gets the gap list so a fresh reviewer does not reverse it. Flaky captures are re-checked once; a gap is a cause, not an instance. - critical-rules: a first build is Home plus at most four card types; every visible control works (main action plus up to three cheap ones via the host's viewCard side stack, edit view, tabs or links), or it is not drawn; a card the main action creates takes the app's theme. - Placeholder labels are quieter and sized for the largest display; sample data carries the longest realistic name. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…iew-skill # Conflicts: # skills/glossary.md
- catalog-reuse: "Reuse the model, own the look". Adopting a catalog card binds the build to its fields, computeds and operations, never its templates. Four routes, lightest first: the theme (only when the stock layout already fits), its fields in the parent's own markup (one placement), extend it and override isolated/embedded/fitted (an app entity or several placements), refuse only for a model or behaviour mismatch. The disposition records the route. - build-check: a catalog card shown through its stock template fails the one-signature line. - critical-rules: the three cheap controls count kinds, not instances; linked cards and real links do not count. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
- The boxel search check writes `cardInfo.name`: the CLI adds the `item.` prefix itself, so `item.cardInfo.name` went out doubled and matched nothing (checked against a realm with boxel-cli 0.8.0-unstable.0; the 0.7.0 source prefixes the same way). - A whole-file rewrite through `boxel file write` has no version check, so it is safe only while this stage is the card's only writer: read right before writing, carry every attribute, cardInfo key and relationship, change `spec` alone, and confirm `designDirection` and `motion` after. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Step 1 sent a terminal agent to the refine paragraph, which uses apply-markdown-edit, a tool the terminal section says it does not have; it now points at the whole-file rewrite. The landed check says to write again from a terminal instead of patching. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…rove - Look for an earlier brief (another slug, a Wiki card, a markdown file) before creating one, so an upgrade is not started as a new interview. - Branch on the read's status: 404 create, 200 refine, anything else stop. - Rewrite by parsing the JSON read and setting data.attributes.spec, so meta and every other key go back as they were. - Correct the concurrency guard: a read after an unconditional write cannot show a write that landed in between, so the path is for when no other stage is editing; the read-back only shows whether someone wrote after. - Compare the stored spec exactly, match the search result's exact id, and allow for indexing lag before calling it a failure. - A schema that differs from an old brief is raised with the user, not folded in silently; numbered options where an agent has no choice tool. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…e-and-cli domain-interview: terminal-agent write path, and upgrading older briefs
…iew-skill # Conflicts: # index.md # skills/domain-interview/SKILL.md
Takes #184's tested image guidance (sample-images, asset-selection, host commands, the Images-in-templates section) and keeps this branch's own sections around it: never invent proof, main action, visible controls and first-build size in critical-rules, and the boxel-design reference list. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A labelled placeholder image is an honest gap, like a marked slot for a review the business has not given yet: the build puts one where no photo may be used or none could be found. The review scores the slot's space, crop and shape as if a fitting photo stood there, and never the placeholder's colours, label or count. The build check's label rule exempts a small avatar that shares the panel's URL. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…and #189's interview record Brings in main (including #184's sample images), takes #188's versions of layout-vocabulary.md and layout-gravity.md, and #189's interview record in domain-interview, its brief template and glossary entry, and its routing skip sentence in index.md. Conflicts keep #151's fuller text and add the newer lines into it. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ayout token fix Main now carries #188 and #189 and the layered-surface / edge-overlap token fix. The layout files and their glossary and SKILL.md lines take main's wording; index.md and the domain-interview field table keep this branch's fuller text, which names the Look check and motion-authoring. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
lucaslyl
commented
Oct 9, 2026
lucaslyl
left a comment
lucaslyl
left a comment
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] This review runs the boxel-ui-guidelines UI review procedure (contract tokens, guaranteed pairs, typography roles, ladders, components, markup) over show-scroll-reveal-and-scrub/example.gts and the CSS snippets in the skills, and the pr-review correctness pass over all 27 files. It reads each file whole and checks every named path, API, flag and token against boxel and boxel-catalog main. Almost all of this PR's content landed after the last reviewed commit, so this pass covers the whole diff. Contrast was not computed for the example, because its colours are literals (see the inline comment). Nothing was rendered, so hover, motion timing, sticky behaviour inside a live card and hit sizes are unverified.
3 blocking: the example card renders @model.title, which CardDef doesn't have; the example pins literal colours; check-palette.mjs reports contrast: pass when it could not check a pair.
- (blocking)
@model.title: see the comment on the<h1>inexample.gts. - (blocking) Literal colours: see the comment on the
.pieceroot inexample.gts(UI review §2). - (blocking) False pass: see the comment on the pair loop in
check-palette.mjs. .card-bodyis read as the page background: seecheck-palette.mjs.- Rules that only a full direction can satisfy (Views table, Width line, Interaction rows, build order) are read unconditionally: see
design-review/SKILL.md. - The Source order link points at a section that doesn't exist: see
untrusted-content.md(the same link is indesign-review/SKILL.md). - The glossary's routing question still says a web research pass runs: see
glossary.md. - A terminal has no documented way to write
motionor the Look check lines: seemotion-authoring/SKILL.md. - The focus ring uses
currentColorinstead of--ring: seemotion-baseline.md(UI review §2). - Journey wording in several files: see
signature-treatments.md. - The description is out of date. It still names the retired
design-directionskill as thedesignDirectionwriter. It says the catalogBriefPR must merge first, but that PR has merged, andcards/projects/brief.gtson catalogmainhasspec/designDirection/motion. It also saysdesign-reviewhas three modes, and it has four.
Addressed since the last review: the create-then-patch-fields thread on domain-interview. Step 2 now reads the instance back before patching, and the terminal path writes the whole card.
The request to split this PR is covered by the description's do-not-merge banner and its split plan.
Pre-existing, not caused by this change: in the catalog Brief card, the Design direction empty state still says "design-direction writes this", naming the retired skill. The writer is now boxel-design's Look check. That is a boxel-catalog follow-up.
| <template> | ||
| <section class='piece' data-motion-root> | ||
| <header class='intro' data-reveal {{this.reveal}}> | ||
| <h1>{{@model.title}}</h1> |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] CardDef has no title field. Base declares cardTitle, cardDescription and cardInfo, and this class doesn't declare one either. So the <h1> renders empty, and Component<typeof ScrollMotionExample> won't type-check under glint. motion-authoring tells builders to start from this file, so every copy inherits the bug. Use {{@model.cardTitle}}, or declare @field title = contains(StringField) if the pattern should have its own. Regression in new code; blocking.
Comment on lines
+264
to
+265
| background: #0e0f12; | ||
| color: #f2f0ea; |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] UI review §1/§2 Colors: the root pins #0e0f12 / #f2f0ea, and the subject's gradient further down pins #cfe8ff / #37506b. The pattern therefore looks the same under every theme, and it teaches builders to hardcode colours. CardContainer already gives the isolated root the --background/--foreground pair, so these two lines can go. For the subject, use a tint taken from the contract, for example radial-gradient(circle at 35% 30%, color-mix(in oklch, var(--primary) 30%, var(--background)), var(--primary)). Blocking under the UI review (literal colours in a template).
|
|
||
| console.log('\ncontrast'); | ||
| for (const [fg, bg, min, what] of PAIRS) { | ||
| if (!roles[fg] || !roles[bg]) continue; |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] When a role is missing or can't be parsed, its pair is skipped with continue, and the run still ends with contrast: pass and exit 0. A theme written in hsl(), or in bare shadcn triples like 0 0% 100%, parses to nothing. I ran it on :root { --background: hsl(0 0% 100%); --foreground: #111; --muted-foreground: #999; }: it printed no contrast lines, then contrast: pass, exit 0. The skills present this script as the gate that fails a build ("exits 1 when a pair fails"), so a palette it couldn't read passes the gate. Either track the skipped pairs and exit non-zero (for example 2, with could not check: …) whenever any of the five goes unchecked, or add hsl() parsing and still report what was skipped. Regression in the new script. Blocking, because it turns an accessibility check into a false pass.
| } | ||
| } | ||
| // The body's own background beats a guessed token when it is a literal colour. | ||
| const bodyBg = text.match(/body\s*\{[^}]*background(?:-color)?\s*:\s*([^;}]+)/i); |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] /body\s*\{/ has no boundary, so .card-body { background: #000 } matches and replaces the canvas. On :root { --background: #fff; --foreground: #111 } .card-body { background: #000 } the script reports ink on canvas 1.11:1 FAIL from body background. Anchor the match to the element selector, for example /(?:^|[\s,}])body\s*\{[^}]*background(?:-color)?\s*:\s*([^;}]+)/im. Non-blocking: it's a false FAIL, and the report names where the colour came from.
Comment on lines
+18
to
+23
| Everywhere below, `## Design direction` means the brief card's `designDirection` field and | ||
| `## Motion` its `motion` field. `boxel-design`'s Look check writes only a `Look:` and a `Real details:` line into | ||
| `designDirection`: score the colour against the first and check that no proof was invented beyond the | ||
| second. A brief from earlier work, or one written by hand, may carry a full direction. Every rule below | ||
| that reads `## Design direction` acceptance lines applies only when that field holds them. With it empty, what was decided is the brief's `spec` (or, with no | ||
| brief, the build's own hand-off line). |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] This guard covers acceptance lines only. Several rules below read parts of a full direction that nothing in this pipeline writes any more, because the Look check writes only Look: and Real details::
- Card mode step 5 compares
prefersWideFormatagainst the direction's Width line. - The Media row reads its Views table.
- The Motion row scores a unit without
## Motion"on its Interaction rows alone". - Reviewing hardcoded work points at "the build order in
## Design direction".
On current briefs, the reviewer is told to check against rows that don't exist. Either widen this sentence to cover every ## Design direction read ("…applies only when the field holds it; otherwise skip that check and say so"), or drop those clauses. The same dependency shows up in motion-authoring's triggers (Interaction row marked JS, Narrative arc, spatial model) and in the "Phase 2" / "Phase 3" references in signature-treatments.md. Non-blocking.
|
|
||
| - **Brief card** — a unit's one source of truth: a catalog `Brief` (`@cardstack/catalog/cards/projects/brief`) at `Brief/<slug>.json` with one MarkdownField per stage — `spec` from `domain-interview`, `designDirection` (`boxel-design`'s Look check), then `motion`. No stage writes a markdown file or another stage's field. | ||
| - **Interview depth (Quick / Standard / Deep)** — how far `domain-interview` goes, never asked: every interview starts Quick (at most 3 calls) and goes to Standard (6) or Deep (10) only when the answers show gaps, or "Not sure, suggest for me" picks. Counts are ceilings; the interview stops once it could build. → `domain-interview/SKILL.md` "Size the interview from the answers" | ||
| - **Routing question** — the one single-select question the index asks before loading a skill for a short build request ("create me a landing page"): just build it (`boxel-design`, the default recommendation, after one purpose question and a web research pass), plan it first (`domain-interview`, recommended only for specialist domains), or build from an existing brief. Each stage then offers the next as its own hand-off question. → `index.md` Pre-flight |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] "after one purpose question and a web research pass" contradicts the index's step 2 and untrusted-content.md → When to research. Both make research opt-in and skip it for common categories. Suggest "after one call (purpose, audience, feel, real details)". Non-blocking.
| One line per beat: name · engine · trigger · the one number that defines its feel. The build then | ||
| proceeds from the brief, with `## Design direction` when there is one, and `## Motion` together. | ||
|
|
||
| **Writing it onto the brief card.** Read the card back first so it has resolved, then |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] This write path only exists in the assistant. The same goes for the brief-card create earlier in this file, and for boxel-design's Record it on the brief, which names no mechanism at all. From a terminal, patch-fields and apply-markdown-edit aren't available. domain-interview covers that case with its own terminal path (boxel file read → script → boxel file write --file → read back). The index runs terminal builds through this pipeline too (npx boxel screenshot for design-review), so a Claude Code run has no documented way to save motion. Add a terminal paragraph that reuses domain-interview's steps (read the card, set the one field in a script, write it with --file, read it back and compare), or link to them. Non-blocking.
| .control:hover { transform: translateY(-2px); } | ||
| } | ||
| .control:active { transform: translateY(0) scale(0.98); } | ||
| .control:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; } |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] UI review §2 Colors: focus outlines use --ring, not currentColor, so this should be outline: 2px solid var(--ring). This recipe goes into every build's controls. A Pret UI Button already draws this ring, so the line only belongs on non-Button controls. Non-blocking.
|
|
||
| ## Spatial model — the control that was never defined | ||
|
|
||
| `spatial model` is the style control for depth, and until now it had |
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Some wording describes how these files got here, and it will read wrong once merged:
- "until now it had no vocabulary" here, and "Upstream's" / "Upstream ships" in this file and in
design-review/SKILL.md - "the one this list used to miss" and "it used to appear in neither the build gate nor this list" in
design-review/SKILL.md - "The earlier rules in this skill described only that look" in
style-families.md - "Today
boxel-design's Look check writes…" inglossary.md
State each rule as it is now. Non-blocking.
…light Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The section now carries #196's exact text: the one call of four questions and the never-invent rule scoped to the user's own business, with sample records still realistic. This branch keeps its extras around it: the page-colour hint, the Look check and Never invent proof links, and the research and page-or-app steps after the call. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…s final wording Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Drop motion-authoring, motion-baseline and the scroll reveal-and-scrub pattern: card-motion (glimmer-motion and Choreo) is now the one way to animate a card, and a build animates only when the user or the design asks for it. Review no longer marks down a still page. Never invent proof gains demo mode's guardrails and the two contradiction fixes from #205; the app rules gain the free catalog-button row, the viewCard guard and the hand-off note. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This was referenced Oct 12, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Background and Goal
The design pipeline, from a vague request to a scored build. Four skills, one artifact: a catalog
BriefatBrief/<slug>.jsonwith one MarkdownField per stage, so a stage only ever replaces its own field. No stage writes a markdown file.The definition is the catalog's
Briefcard — cardstack/boxel-catalog#771, adopted as@cardstack/catalog/cards/projects/brief. That PR has to merge before this one, or the alias resolves to nothing for anyone running the skill.The stages
domain-interview(ECO-579) — interviews the user in rounds and writesspec: domain primer, schema, element coverage matrix from a realcatalog-reusesearch, per-screen content contracts, flows, sample data. Makes no design decisions.design-direction(ECO-576) — decides how the unit looks before it is built and writesdesignDirection. Asks only the feeling and the style; decides layout itself with reasons recorded, and writes acceptance lines a reviewer can tick without taste.motion-authoring— opt-in, only when the direction recorded an arc, a scrubbed subject or a library way. Writesmotion: one motion system, the engine per beat, the load-bearing CSS, an exhaustive effect table, and the three capture points.design-review— scores what was built, from captures only, against the card's acceptance lines and an aesthetic bar whose gate is 8.5. Three modes: one screen,setacross an app,cardacross a CardDef's formats.Each stage ends by offering the next as a structured choice and never starts it itself.
Key decisions
contentblob. A stagepatch-fieldsonly its own field, after reading the card back so it has indexed; a change to one block inside a field is anapply-markdown-edit, never a resend of the whole field.design-directionruns in four phases: inventory → first screen (layout + interaction) → style → write and hand off.design-reviewwrites nothing. The brief card records decisions, not scores.Also brings the
show-scroll-reveal-and-scrubpattern, whichmotion-authoring's engine rows start from rather than rewriting the observer.Testing-only commit — to be split out
e965ea7(Source sample images by scenario) is here for testing alongside the pipeline only and belongs in its own PR. It will be moved to a separate branch offmainand dropped from this one before this PR merges. It covers: declaringgenerate-thumbnailanddownload-file-to-realminhost-commands-reference, the newboxel-file-def/references/sample-images.md, removing the dead stock/placeholder URLs fromasset-selection-guidelines, and theImageDefimport fix inattach-remote-image. Please review it separately.🤖 Generated with Claude Code