JudgmentKit

JudgmentKit is a fresh activity-first kernel for AI-generated interface work.

It is not a beautifier, generic design-system linter, prompt library, schema browser, or MCP reference surface. Design-system provenance is now enforced after activity judgment through the implementation contract; the core job remains helping an agent generate or critique UI that is relevant, succinct, and appropriate to the activity it supports.

Product Thesis

AI-generated UI fails when the implementation model becomes the user experience. Tables become screens, schemas become forms, tool calls become buttons, and internal prompts become product vocabulary.

JudgmentKit catches when AI-generated UI turns implementation mechanics into UX, then gives the agent repair instructions before the work ships.

The shippable value path is the public /value/ page: it shows what JudgmentKit prevents with concrete before/after cases for implementation-language leakage, unsafe approval boundaries, and missing accessibility evidence. Eval reports remain supporting evidence for audit and reproduction, not the primary product story.

JudgmentKit gives the agent a better order of operations:

1. Understand the activity.
2. Translate the activity into interaction responsibilities.
3. Decide what implementation detail should stay hidden, be translated, or appear only as diagnostics.
4. Bind generation to approved implementation primitives and verification checks.
5. Generate or critique the UI.
6. Apply visual system choices only after the activity and interaction model are sound.

Aesthetics are adapter-layer work. They should refine a relevant UI, not rescue a broken one.

Kernel

• ActivityModel: the activity system the UI enters.
• InteractionContract: the specific user actions, decisions, state changes, and success criteria the UI must support.
• DisclosurePolicy: the vocabulary and visibility rules that prevent implementation leakage.
• JudgmentExample: a before/after case that calibrates what good and bad generated UI look like.

Architecture

JudgmentKit keeps the core deterministic and lets model assistance enter through explicit seams:

1. Deterministic analyzer: extracts activity evidence, implementation terms, review questions, and disclosure risks from a brief.
2. Deterministic review packet: turns that evidence into a reviewable activity model candidate with guardrails.
3. Model-assisted candidate review seam: accepts a model-proposed candidate through dependency injection or MCP and runs the same guardrails.
4. Provider-neutral proposer adapter: builds a serializable activity-model request for an injected model caller and returns the proposed candidate to the review seam.
5. Surface-type recommendation: classifies activity purpose as marketing, workbench, operator review, artifact inspector, form flow, dashboard monitor, content/report, setup/debug tool, or conversation before workflow or frontend implementation guidance.
6. UI workflow candidate review seam: accepts a model- or agent-proposed workflow candidate and checks grounding, action support, handoff clarity, and disclosure containment before UI implementation.
7. UI implementation contract gate: creates or accepts the repo authority for approved primitives, control semantics, required states, static checks, and browser QA.
8. UI generation handoff gate: turns only ready workflow reviews plus an implementation contract into compact handoffs for the next UI generation pass.
9. Frontend generation context adapter: combines a ready handoff, selected surface type, frontend context, and verification expectations, then applies governed presentation guidance such as the supported default Workbench operational profile or the proposed Artifact Inspector profile contract without making styling or component inventory part of the kernel contract.
10. Frontend implementation skill context: compiles repo-local frontend skill guidance into a gated MCP packet for agents that cannot read local skills directly, including the active implementation_contract.design_system_source for tokens, typography, icons, and component contracts.
11. Optional provider adapters: provider configuration and network calls stay outside the kernel and feed proposed candidates back through the same review contract.

Structure

• AGENTS.md: operating rules for agents working in this repository.
• DESIGN.md: activity-first judgment contract.
• specs/: product and interface specs for the kernel.
• contracts/: machine-readable activity and disclosure contracts.
• docs/: daily workflow guidance for agents and local usage.
• examples/: copyable briefs and candidate fixtures for CLI and MCP checks.
• tests/: checks that protect the kernel from drifting back to aesthetic-first or implementation-first work.

First Workflow

The first workflow is AI UI generation. It starts with one contract:

• contracts/ai-ui-generation.activity-contract.json

First 10 Minutes

Start with a short activity brief in any client that can load the JudgmentKit skill, including Codex or Claude Code. For example:

Use JudgmentKit to plan an interface for a support lead reviewing refund requests during daily triage. They decide whether to recommend support, send a case to policy review, or return it for missing evidence. The outcome is a clear handoff with the next action and reason.

The default experience is inference-first: the agent proposes and briefly shows its best-current activity case, keeps reversible assumptions visible, and continues. It asks at most one targeted question only when a consequential fork would materially change the design and be costly to reverse. It stops when a protected action needs an authoritative source. A field-by-field interview is never the default.

The portable path is the same across clients:

1. Infer and review the activity case from the short brief.
2. Classify the surface and review the proposed workflow.
3. Pass the exact brief and attributed context through handoff, frontend generation, and portable frontend skill compilation.
4. Apply the selected design-system adapter and implementation contract.
5. Review implementation evidence before acceptance.

For direct MCP integrations, the corresponding sequence is create_activity_model_review, review_activity_model_candidate, recommend_surface_types, review_ui_workflow_candidate, create_ui_implementation_contract, create_ui_generation_handoff, create_frontend_generation_context, and create_frontend_implementation_skill_context; generate the UI in the client, then call review_ui_implementation_candidate before acceptance. Resupply the exact current brief and attributed context_items at every validating boundary; integrity receipts prove continuity, not action authority.

Use the first-use fixture when you want to inspect the later implementation acceptance loop without reading an eval report:

• examples/ai-native-design-system/first-use.json

The fixture contains one brief, one implementation contract input, one failing candidate, one repaired candidate, and a two-attempt transcript. That later loop is:

1. Create the implementation contract.
2. Review the failing candidate.
3. Read next_agent_action and grouped repair_instructions.
4. Repair the candidate.
5. Resubmit and expect accept.

The canonical examples live beside it:

• examples/ai-native-design-system/canonical-examples.json

They cover setup/onboarding, an operational dashboard, and a high-stakes review/refund workflow. These examples still prove contract and repair behavior rather than runtime rendering.

JudgmentKit also contains an unreleased optional React adapter candidate at judgmentkit/react, with styles imported explicitly from judgmentkit/react/styles.css. All 17 canonical component contracts have local implementation candidates and all 65 required-state scenarios are represented. The React subpath exposes 18 named symbols because CheckboxField is a supporting primitive in addition to the 17 canonical contract exports. Implementation availability, scenario representation, and current verification remain separate claims; the exported component registry is the evidence authority. The root package, CLI, and MCP remain framework-neutral and do not load React or component CSS.

The Simple Design System (Community) file is JudgmentKit's component-and-variant reference denominator: 122 public families with 336 masters and six hidden families with 18 masters. Standalone icons and Simple Design System styling are excluded. JudgmentKit accounts for all 128 families and 354 masters, classifies every family, normalizes the 304 masters in documented variant sets across 105 semantic axes, and records the remaining 50 as singleton masters. Reference accounting, family disposition, variant semantics, runtime availability, and current evidence are reported separately.

By default, implementation_contract.design_system_source.mode is judgmentkit_default: tokens, font roles, icon catalog policy, component contracts, the component implementation registry, and supported surface-presentation profiles come from JudgmentKit /design-system/ exports. A sufficiently grounded or explicitly selected Workbench receives judgmentkit.workbench.operational-v1 in frontend-generation context by default. A grounded Artifact Inspector receives judgmentkit.artifact-inspector.v1, which keeps one rendered artifact primary while applying JudgmentKit guidance only to declared chrome and overlay scopes. surface_profile: "none" opts out without changing either interaction contract. If a complete design_system_adapter is supplied to create_ui_implementation_contract, the mode becomes external_design_system and that adapter owns tokens, typography, icons, and renderer components. Incomplete external adapters fail instead of falling back to JudgmentKit defaults, and neither JudgmentKit surface profiles nor the unreleased React adapter candidate cross that boundary implicitly.

Artifact Inspector uses an explicit mixed-authority contract: inspector_chrome and inspection_overlay are JudgmentKit-owned, while primary_artifact remains external_not_reviewed. Its profile component roles are semantic contract guidance, not implemented component-registry exports. This release has no trusted interactive-attestation producer or verifier; candidate-authored evidence and the existing static browser-composition runtime cannot satisfy the authority gate, so an otherwise valid implementation remains review_required.

The default field-select composition contract is source-backed and documented in docs/select-field-composition.md. It separates selected-value spacing, the reserved trailing indicator slot, and the indicator's placement inside that slot instead of treating a field's content padding as the chevron's physical edge inset.

The JudgmentKit default source does not load a font CDN, runtime icon CDN, or external runtime icon package. Font guidance uses system stacks, and icon guidance points to the committed Lucide catalog exposed through list_icon_catalog, search_icon_catalog, and get_icon_svg.

A generated UI that fails the active design-system source, visual-token, component-contract, local-component-authority, accessibility, or browser-QA gate is repair evidence only. Do not publish it as a UI artifact, gallery snapshot, screenshot artifact, or release proof until a repaired candidate passes.

The first validation command is:

npm test

Retained visual-composition media checks require ffmpeg on PATH.

For daily local use:

npm run mcp:smoke
judgmentkit review --input examples/refund-triage.brief.txt

For JudgmentKit slide deck planning and local PPTX export from Codex Desktop, use the receipt-backed MCP workflow in docs/slide-deck-mcp.md.

For a hosted MCP install:

curl -fsSL https://judgmentkit.ai/install | bash
curl -fsSL https://judgmentkit.ai/install | bash -s -- --client claude
curl -fsSL https://judgmentkit.ai/install | bash -s -- --client cursor

From a checkout, the same installer can be dry-run locally:

npm run install:mcp -- --client codex --dry-run
npm run install:mcp -- --client claude --dry-run
npm run install:mcp -- --client cursor --dry-run

Optional OpenAI Responses smoke checks are opt-in:

JUDGMENTKIT_OPENAI_SMOKE=1 \
OPENAI_API_KEY=... \
JUDGMENTKIT_OPENAI_MODEL=... \
npm run smoke:openai-ui-workflow

For a deterministic one-shot before/after demo:

npm run demo:one-shot

That command also writes examples/demo/one-shot-demo.html for visual review.

For the modal action evidence demo:

npm run demo:modal-actions

That command prints deterministic reviewUiImplementationCandidate modal-action outcomes and writes examples/demo/modal-actions-evidence-demo.html, including the current evidence-driven reviewed: 0 caveat.

For an early standalone comparison harness:

npm run demo:comparison

That command writes two independently runnable apps plus a manifest under examples/comparison/. Use it for qualitative paired comparisons of the raw brief baseline versus the JudgmentKit handoff path. The checked-in comparison is historical evidence and explicitly opts out of the Workbench presentation profile so the accepted artifact does not change during profile promotion.

For a music-app standalone comparison:

npm run demo:comparison:music

That command writes a dinner-playlist brief, two independently runnable apps, a manifest, and a facilitator scorecard under examples/comparison/music/. This checked-in comparison also preserves its historical visual evidence with surface_profile: "none".

To score the committed comparison artifacts as a deterministic paired UI-generation eval:

npm run eval:ui

That command writes immutable JSON and HTML reports plus archived screenshots under evals/reports/<date>/mcp-<version>/run-NNN/ and updates the catalog at evals/reports/index.html. It is qualitative paired-artifact evidence, not a statistically powered benchmark, and the historical opt-out fixtures do not serve as Workbench-profile evidence. Screenshot capture requires local Chrome or Chromium; set JUDGMENTKIT_UI_EVAL_CHROME_PATH if the executable is not on the default path.

To run the full live UI-generation refresh for the same paired cases:

npm run eval:ui:live

That command calls the configured live provider, writes dated generated HTML artifacts under the run directory, screenshots those artifacts, and reports provider/model provenance. It remains qualitative paired evidence; it is not a statistically powered benchmark.

For the system-map model UI matrix:

npm run demo:model-ui

That command writes static 5x4 model UI matrices under examples/model-ui/ for support refund triage, field service dispatch, clinical intake review, and B2B renewal risk review. Each use case includes a fixture-rendered baseline, Gemma 4 local LLM, GPT-5.5 xhigh, GPT-5.6 Sol Light, and GPT-5.6 Sol Ultra paths across raw brief, JudgmentKit skill context, Material UI only, and JudgmentKit skill plus Material UI columns. The fixture-rendered baseline is scripted from fixed fixtures and local renderer code; it is not model-generated and is isolated from provider-connected captures. The refund route at examples/model-ui/refund-system-map/ remains the stable compatibility path. The matrix writes accepted artifacts plus diagnostic records; design-system-failed cells stay in diagnostic_candidates and are excluded from manifest.artifacts, live artifact routes, screenshots, and release evidence. The website build copies committed accepted artifacts, records provenance in each manifest, and does not call live providers.

To refresh the committed Gemma 4, GPT-5.5, and GPT-5.6 Sol transcripts for that matrix:

npm run capture:model-ui

That command uses LM Studio's lms CLI for Gemma 4 and the codex CLI for GPT-5.5 and GPT-5.6 Sol. Sol Light runs with low reasoning effort; Sol Ultra runs with ultra reasoning effort. Light and Ultra receive identical model-facing input for each use-case column; their row identity stays in capture provenance instead of the prompt. The command writes capture transcripts under each examples/model-ui/<use-case>/captures/ directory and regenerates the static matrices from those committed files. Add -- --fresh to force recapturing every model cell instead of reusing matching transcripts.

Pass one or more --row <comparison-row-id> arguments to refresh selected model rows without recapturing other committed rows. Use --captures-only when model rows are captured in separate use-case chunks, then run npm run demo:model-ui and npm run capture:model-ui:screenshots once after every chunk finishes. Gemma captures explicitly load the local model with a minimum 16k LM Studio context window before lms chat; override with MODEL_UI_LMS_CONTEXT_LENGTH only to request a larger window.

To refresh only the committed gallery screenshots after regenerating the matrix:

npm run capture:model-ui:screenshots

For the replacement website build:

npm run site:build

That command publishes static paths for /, /value/, /docs/, /examples/, and /install under site/dist/. The public /mcp and /mcp/ routes are served by the hosted Streamable HTTP MCP function and return metadata for browser GET requests.

The visual-composition film is temporarily retired from the public homepage. Its light and dark recordings, posters, dormant player implementation, and authoring source remain available for a bounded restoration; the default site build emits no film markup or player behavior on /. The retained media continues to receive integrity checks, but no separate visual-composition release or demo route ships.

For local site review with the same /mcp behavior:

npm run site:dev -- --host 127.0.0.1 --port 4173

That command rebuilds site/dist, serves static routes locally, and routes localhost /mcp and /mcp/ through the same Streamable HTTP handler used in production.