Jev Design

Jev design

Each part of the work goes to whoever does it best:

Jev only picks from lists: a component from the catalog's candidates and a recipe from its styles. It does not write layout, copy, or code. The agent does all open-ended work. Everything below is a default. Override any step when you have a stated reason, and write the reason in your summary.

1. Brief

Turn the user's request into brief.json. Read references/brief-writing.md for the procedure and a worked example.

jsonCopy code
{"brief":"Support agents triage 200+ cases a day on desktop; calm, dense, keyboard-first.",
 "style_traits":["dense","calm","professional"],
 "requirements":[
  {"id":"results","role":"Compare, filter, and act on open cases","capabilities":["tabular-data","filter","row-actions"]},
  {"id":"details","role":"Inspect one case without leaving the list","capabilities":["overlay","details"]}
]}

• List capabilities, style traits, recipes, and limits with --list-capabilities. Use only listed names.
• Keep the brief to audience, task, and tone, 1,500 characters at most. Layout and copy notes stay with you for phase 3.
• Add "primitives": "radix" | "base" | "aria" when the project already uses one primitive set.
• Ask the user only when the surface type (landing page or app) or the audience is unknown. Otherwise decide, and record the assumption.

Deriving a brief from an existing screen

The planner has no vision input and picks components, not layout. Read the screen (DOM, a screenshot) yourself and write the brief from it: one requirement per region, each with 1 or 2 capabilities and a role written as a verb plus an object. Three capabilities per requirement abstained with no_compatible_component; vague roles abstained with low_fitness, and verb-plus-object roles selected (data-table 0.94). Layout stays with you in phase 3.

2. Pick

bashCopy code
python3 skills/frontend/jev-design/scripts/plan.py \
  --input brief.json --output /tmp/design-plan.json \
  --receipt /tmp/jev-design-receipt.json --css /tmp/design-theme.css

The planner filters the catalog by capability in code: each requirement gets at most six candidates, tightest fit first. It packs requests to 3,500 tokens or fewer and refuses to send any request over 4,500. It sends through the selectable Jev transport (Vercel AI Gateway when configured), which retries 429, 503, and 529 with jittered backoff. It validates every answer and accepts a pick only when its fitness is 0.62 or higher. It never installs anything or edits code.

When the plan is selected, implementation holds:

• install: the exact npx shadcn@latest add ... command, plus npm for extra dependencies.
• css: paste-ready @theme inline, :root, and .dark blocks.
• fonts: the families to load.
• layout_tokens: radius, density classes, and shadow.
• contrast: every checked WCAG pair and its ratio.

When the plan abstains, the output still holds baseline and candidates:

Run the planner at most three times per screen.

3. Compose and build

Use the frontend skill. Follow this order:

1. Run init (if needed), install, and npm exactly as the plan gives them.
2. Paste css into the app's global stylesheet, replacing the existing theme variables. Load fonts.
3. Write the layout. Apply layout_tokens everywhere: the same control height, row height, gap, and section spacing on every part of the screen.
4. Write real copy: a headline that names the task, labels as nouns, buttons as verbs with objects ("Assign case", not "Submit").
5. When no catalog component fits, compose from catalog parts first (item + dropdown-menu, card + chart). Write new markup only when that fails, and reuse the recipe's variables.

4. Review

Build with UI design judgment and its recipes. Render the screen and review it with references/visual-review.md. Use the harness's screenshot tool (Playwright or chrome-devtools MCP). Capture 375, 768, and 1280 px widths in light and dark mode (set deviceScaleFactor 2 for the 375 px shots you send to Jev).

• Send the desktop and mobile screenshots to Jev, one Noul per trait, with the rated reference in the same state. Load references/jev-images.md for captures, question set, and code. Image answers steer the review. They do not replace the checklist.
• Report each finding as a fact with a location: "Primary button in the dialog footer is below the fold at 375 px", not "spacing feels off".
• Fix code-level findings in code. Put requirement-level findings (a wrong component, the wrong tone) back into brief.json, and rerun phase 2.
• Stop after three review rounds. Report what remains.
• If the harness has no screenshot tool, say so. Give the user the checklist from visual-review.md to check by eye, and do not claim visual quality.

Rules for changing the planner

Apply the Jev production rules to any change in how requests are built or sent. They cover request size, retries by status, and budget checks. Keep the worst-case size test passing: too much context is the most common failure. The planner picks among catalog candidates, and Jev leans toward the first option on some inputs: keep candidate order out of the signal (tightest fit first is a code ordering, so test a reversed order on labeled requirements before trusting a pick). Pin a versioned model ID for planner calibration; jev-latest moves between versions. Read references/decision-card.md before you change the model, catalog, rubric, threshold, bounds, failure policy, or promotion status. references/catalog-v1.json is kept for reference only.