mikeylong · mikeylong · Jun 28, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- Preserved no-config UI implementation contracts with the JudgmentKit package-default design-system source while validating malformed explicit `design_system_source` values as failures.
+- Retired public `/design-system` pages in favor of the canonical Surfaces contract without removing JudgmentKit's built-in package default.
+
 ## 0.5.0 - 2026-06-20
 
 - Added `review_cognitive_dimensions_candidate` as a library and MCP tool for reviewing UI workflow or implementation candidates against activity mapping, evidence visibility, hidden dependencies, premature commitment, progressive evaluation, change cost, mental operations, role expressiveness, and disclosure discipline.

diff --git a/README.md b/README.md
@@ -82,7 +82,7 @@ The canonical examples live beside it:
 
 They cover setup/onboarding, an operational dashboard, and a high-stakes review/refund workflow. The renderer package is still deferred; these examples prove the contract and repair behavior before visual rendering.
 
-By default, `implementation_contract.design_system_source.mode` is `judgmentkit_default`: tokens, font roles, icon catalog policy, and component contracts come from JudgmentKit `/design-system/` exports. 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.
+By default, `implementation_contract.design_system_source.mode` is `judgmentkit_default`: tokens, font roles, icon catalog policy, and component contracts come from the JudgmentKit package default. Public `/design-system/` routes are retired and are not the source of truth for this default. If a complete `design_system_source` or `design_system_adapter` is supplied to `create_ui_implementation_contract`, the mode becomes `external_design_system` and that source owns tokens, typography, icons, and renderer components. Incomplete external sources or adapters fail instead of falling back to JudgmentKit defaults.
 
 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`.
 

diff --git a/api/design-system-retired.js b/api/design-system-retired.js
@@ -0,0 +1,47 @@
+const CANONICAL_SURFACES_DESIGN_SYSTEM_URL =
+  "https://surfaces.systems/design-system";
+const DESIGN_SYSTEM_MIGRATION_CODE = "judgmentkit_design_system_retired";
+
+function requestedPath(req) {
+  const queryPath = req.query?.requestedPath;
+
+  if (Array.isArray(queryPath)) {
+    return queryPath[0] ?? "/design-system";
+  }
+
+  if (typeof queryPath === "string" && queryPath.length > 0) {
+    return queryPath;
+  }
+
+  return req.url ?? "/design-system";
+}
+
+export default function handler(req, res) {
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    res.statusCode = 405;
+    res.setHeader("Allow", "GET, HEAD");
+    res.end("Method not allowed.\n");
+    return;
+  }
+
+  const payload = {
+    code: DESIGN_SYSTEM_MIGRATION_CODE,
+    message:
+      "judgmentkit.ai/design-system is retired. Use the canonical Surfaces design-system contract.",
+    canonicalUrl: CANONICAL_SURFACES_DESIGN_SYSTEM_URL,
+    requestedPath: requestedPath(req),
+  };
+  const body = `${JSON.stringify(payload, null, 2)}\n`;
+
+  res.statusCode = 410;
+  res.setHeader("Content-Type", "application/json; charset=utf-8");
+  res.setHeader("Cache-Control", "public, max-age=300");
+  res.setHeader("Content-Length", Buffer.byteLength(body));
+
+  if (req.method === "HEAD") {
+    res.end();
+    return;
+  }
+
+  res.end(body);
+}
diff --git a/contracts/ai-ui-generation.activity-contract.json b/contracts/ai-ui-generation.activity-contract.json
@@ -1586,7 +1586,7 @@
       "mode": "judgmentkit_default",
       "name": "JudgmentKit",
       "package": "judgmentkit",
-      "definition_point": "implementation_contract",
+      "definition_point": "package_default",
       "required_authorities": [
         "tokens",
         "fonts",
@@ -1596,13 +1596,13 @@
       "fallback_policy": "fail_incomplete",
       "provenance_required": true,
       "source_exports": {
-        "overview": "/design-system/",
-        "manifest": "/design-system/manifest.json",
-        "visual_token_adapter": "/design-system/visual-token-adapter.json",
-        "component_contracts": "/design-system/component-contracts.json",
-        "pattern_contracts": "/design-system/pattern-contracts.json",
-        "accessibility_policy": "/design-system/accessibility-policy.json",
-        "icon_catalog": "/design-system/icons/",
+        "overview": "package://judgmentkit/design-system/",
+        "manifest": "package://judgmentkit/design-system/manifest.json",
+        "visual_token_adapter": "package://judgmentkit/design-system/visual-token-adapter.json",
+        "component_contracts": "package://judgmentkit/design-system/component-contracts.json",
+        "pattern_contracts": "package://judgmentkit/design-system/pattern-contracts.json",
+        "accessibility_policy": "package://judgmentkit/design-system/accessibility-policy.json",
+        "icon_catalog": "package://judgmentkit/design-system/icons/",
         "icon_tools": [
           "list_icon_catalog",
           "search_icon_catalog",
@@ -1658,9 +1658,9 @@
       ],
       "component_contract_source": "implementation_contract.default_ai_native_design_system.component_contracts",
       "provenance_rules": [
-        "visual tokens, fonts, icons, and renderer components must come from this active design-system source",
+        "visual tokens, fonts, icons, and renderer components come from the JudgmentKit package default when no design system is supplied",
         "local CSS may define layout and UI structure but must not become the source of visual tokens, typography, icon assets, or renderer components",
-        "external design systems must be supplied as complete contract-time adapters; missing authorities do not fall back to JudgmentKit defaults"
+        "external design systems must be supplied as complete contract-time adapters or complete design-system sources; missing authorities do not fall back to JudgmentKit defaults"
       ]
     },
     "visual_token_adapter": {

diff --git a/contracts/judgmentkit-kernel.schema.json b/contracts/judgmentkit-kernel.schema.json
@@ -334,19 +334,25 @@
         "default_include_svg"
       ],
       "properties": {
-        "source": { "type": "string" },
-        "library": { "type": "string" },
-        "package": { "type": "string" },
-        "version": { "type": "string" },
+        "source": { "type": "string", "minLength": 1 },
+        "library": { "type": "string", "minLength": 1 },
+        "package": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
         "icon_count": { "type": "number", "minimum": 1 },
-        "license": { "type": "string" },
-        "notice": { "type": "string" },
-        "style_system": { "type": "string" },
+        "license": { "type": "string", "minLength": 1 },
+        "notice": { "type": "string", "minLength": 1 },
+        "style_system": { "type": "string", "minLength": 1 },
         "style_attributes": {
           "type": "object",
+          "minProperties": 1,
           "additionalProperties": { "type": "string" }
         },
-        "mcp_tools": { "type": "array", "items": { "type": "string" } },
+        "mcp_tools": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
         "default_include_svg": { "type": "boolean" }
       }
     },
@@ -502,16 +508,18 @@
         "provenance_rules"
       ],
       "properties": {
-        "id": { "type": "string" },
+        "id": { "type": "string", "minLength": 1 },
         "mode": {
           "type": "string",
           "enum": ["judgmentkit_default", "external_design_system"]
         },
-        "name": { "type": "string" },
-        "package": { "type": "string" },
-        "definition_point": { "type": "string" },
+        "name": { "type": "string", "minLength": 1 },
+        "package": { "type": "string", "minLength": 1 },
+        "definition_point": { "type": "string", "minLength": 1 },
         "required_authorities": {
           "type": "array",
+          "minItems": 4,
+          "uniqueItems": true,
           "items": {
             "type": "string",
             "enum": ["tokens", "fonts", "icons", "components"]
@@ -524,26 +532,36 @@
         "provenance_required": { "type": "boolean" },
         "source_exports": {
           "type": "object",
+          "minProperties": 1,
           "additionalProperties": {
             "oneOf": [
-              { "type": "string" },
-              { "type": "array", "items": { "type": "string" } }
+              { "type": "string", "minLength": 1 },
+              {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string", "minLength": 1 }
+              }
             ]
           }
         },
         "token_prefixes": {
           "type": "array",
-          "items": { "type": "string" }
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
         },
         "icon_catalog": { "$ref": "#/$defs/iconCatalog" },
         "renderer_components": {
           "type": "array",
-          "items": { "type": "string" }
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
         },
-        "component_contract_source": { "type": "string" },
+        "component_contract_source": { "type": "string", "minLength": 1 },
         "provenance_rules": {
           "type": "array",
-          "items": { "type": "string" }
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
         }
       }
     },

diff --git a/docs/agent-usage-contract.md b/docs/agent-usage-contract.md
@@ -10,7 +10,7 @@ Use JudgmentKit before UI generation, UI critique, implementation planning, or h
 4. Call `recommend_surface_types` to classify the activity purpose before workflow or frontend implementation guidance.
 5. If a model or agent proposes a UI workflow, call `review_ui_workflow_candidate` before treating it as acceptable.
 6. Call `review_cognitive_dimensions_candidate` when a workflow or implementation candidate needs Cognitive Dimensions review for mapping, visibility, hidden dependencies, premature commitment, progressive evaluation, change cost, mental operations, or disclosure.
-7. Call `create_ui_implementation_contract`. Use the default JudgmentKit design-system source, or pass a complete `design_system_adapter` when an external design system should own tokens, typography, icons, and renderer components.
+7. Call `create_ui_implementation_contract`. Omit design-system fields to use the JudgmentKit package default, or pass a complete `design_system_source` or `design_system_adapter` when an external design system should own tokens, typography, icons, and renderer components.
 8. Call `create_ui_generation_handoff` on the reviewed workflow with the implementation contract before generating UI. Pass the Cognitive Dimensions review when it should block handoff until ready.
 9. Call `create_frontend_generation_context` when frontend implementation guidance needs a selected surface type, project frontend context, and verification expectations.
 10. Call `create_frontend_implementation_skill_context` when the implementing agent needs a compiled frontend skill packet that is portable across MCP clients.
@@ -24,7 +24,7 @@ Use JudgmentKit before UI generation, UI critique, implementation planning, or h
 - Treat `needs_source_context` as a prompt to gather source context or ask the packet's targeted questions.
 - Treat surface type as activity-purpose guidance, not visual styling.
 - Treat the implementation contract as the authority for allowed primitives, control semantics, states, static checks, browser QA, visual asset handling, and accessibility evidence.
-- Treat `implementation_contract.design_system_source` as the active authority for visual tokens, typography, icon assets, and renderer components. `judgmentkit_default` uses JudgmentKit `/design-system/` exports; `external_design_system` requires a complete adapter and has no implicit JudgmentKit fallback. `external_authority` is trace metadata unless paired with `design_system_adapter`.
+- Treat `implementation_contract.design_system_source` as the active authority for visual tokens, typography, icon assets, and renderer components. When no external source is supplied, JudgmentKit uses its package default. `external_design_system` requires a complete source or adapter and has no implicit JudgmentKit fallback. `external_authority` is trace metadata unless paired with `design_system_source` or `design_system_adapter`.
 - Treat `visual_token_adapter` as the token/font/icon evidence envelope for the active design-system source. Asset guidance cannot replace activity fit, primitive coverage, state coverage, accessibility evidence, static checks, or browser QA.
 - Keep implementation terms out of product UI unless the activity is setup, debugging, auditing, integration, or explicit source inspection.
 - When a model proposes an activity model, call `review_activity_model_candidate` before trusting it.
@@ -53,7 +53,7 @@ Before handing off UI work, confirm:
 - implementation terms contained in disclosure, evidence, or guardrails
 - workflow topology, work units, surface set, primary actions, decision support, and handoff are named
 - implementation contract names approved primitives and required states
-- token, font, icon, and renderer component guidance comes from `implementation_contract.design_system_source`, with no implied font CDN, remote icon package, or fallback from external systems to JudgmentKit defaults
+- token, font, icon, and renderer component guidance comes from `implementation_contract.design_system_source`, with no implied font CDN, remote icon package, or fallback from external systems to JudgmentKit default assets
 - substantive visual requirements have an image-generation, premium 3D/rendering, or high-quality visualization path when present
 - static checks, browser QA, core accessibility evidence, and any conditional visual-background contrast, non-text contrast, forced-colors, target-size, focus-not-obscured, no-keyboard-trap, reduced-motion, pause/stop/hide, form/error/status, media alternative, or semantic fallback evidence are specified when required
 - review-packet terms are not copied into the product UI

diff --git a/docs/daily-agent-workflows.md b/docs/daily-agent-workflows.md
@@ -224,7 +224,7 @@ review_cognitive_dimensions_candidate({ brief, candidate, activity_review, surfa
 
 Use the returned `findings` and `repair_instructions` as diagnostic guidance. If a Cognitive Dimensions review is supplied to the handoff gate, it must be `ready_for_review`.
 
-Call `create_ui_implementation_contract` with the default JudgmentKit design-system source, or with a complete `design_system_adapter` when an external design system should own tokens, typography, icons, and renderer components. `external_authority` is trace metadata unless it is paired with a complete adapter. The implementation contract names approved primitives, required states, static checks, browser QA expectations, `design_system_source`, visual asset policy, and accessibility policy.
+Call `create_ui_implementation_contract`. Omit design-system fields to use the JudgmentKit package default, or pass a complete `design_system_source` or `design_system_adapter` when an external design system should own tokens, typography, icons, and renderer components. `external_authority` is trace metadata unless it is paired with a source or complete adapter. The implementation contract names approved primitives, required states, static checks, browser QA expectations, `design_system_source`, visual asset policy, and accessibility policy.
 
 MCP handoff calls should pass this packet as `implementation_contract`.
 
@@ -241,6 +241,7 @@ Library equivalent:
 ```js
 const workflowReview = reviewUiWorkflowCandidate(brief, workflowCandidate);
 const implementationContract = createUiImplementationContract({
+  design_system_source: optionalCompleteExternalDesignSystemSource,
   design_system_adapter: optionalCompleteExternalDesignSystemAdapter,
 });
 const handoff = createUiGenerationHandoff(workflowReview, {
@@ -276,7 +277,7 @@ create_frontend_implementation_skill_context({
 
 The skill context compiles the local frontend implementation workflow into structured instructions, approved primitives, approved component families, active design-system policy, visual asset policy, accessibility policy, verification checklist, and disclosure guardrails. It requires a ready frontend context and does not expose raw `SKILL.md` contents. The legacy `design_system_adapter` argument is a compatibility path only; prefer passing the adapter to `create_ui_implementation_contract`.
 
-The JudgmentKit default source includes semantic token roles, system font stacks for body, heading, label, numeric, and diagnostic text, and a committed Lucide icon catalog exposed through `list_icon_catalog`, `search_icon_catalog`, and `get_icon_svg`. Normal implementation context returns only the catalog summary, policy, count, source/version, and tool names; it does not embed the full catalog. These defaults do not load a font CDN, ship font files, use a runtime icon CDN, or mix with an external design system unless the external adapter explicitly names those assets.
+JudgmentKit still exposes icon catalog tools for review and examples, and the package default remains the active design-system source when no external source is supplied. Normal implementation context returns only the active source metadata, catalog summary, policy, count, source/version, and tool names; it does not embed a full catalog or imply a fallback from external systems to JudgmentKit assets.
 
 When a frontend spec calls for substantive visuals, the implementation path should use `imagegen`, premium Three.js/WebGL rendering, or D3-style data visualization. Deterministic CSS, SVG, and JavaScript remain appropriate for layout, exact text, UI chrome, icons, state indicators, simple diagrams, and accessible fallback structure.
 

diff --git a/docs/releases/v0.6.0.md b/docs/releases/v0.6.0.md
@@ -6,7 +6,7 @@ JudgmentKit 0.6.0 makes design-system provenance a contract authority for genera
 
 ## Improvements
 
-- Added `implementation_contract.design_system_source` with explicit `judgmentkit_default` and `external_design_system` modes.
+- Added `implementation_contract.design_system_source` with `judgmentkit_default` and `external_design_system` modes.
 - Added complete external design-system adapter support for tokens, fonts, icons, and components.
 - Added fail-fast validation for incomplete external design-system authority.
 - Added a hard `design_system_provenance` implementation review gate.

diff --git a/docs/releases/v0.6.1.md b/docs/releases/v0.6.1.md
@@ -7,7 +7,7 @@ JudgmentKit 0.6.1 is the public release for contract-first design-system authori
 ## Improvements
 
 - Carries the 0.6 design-system authority contract into the public MCP metadata and examples.
-- Normalizes committed model UI capture metadata to the new `judgmentkit_default` and `external_design_system` source modes.
+- Normalizes committed model UI capture metadata to the `judgmentkit_default` package source mode and `external_design_system` source mode.
 - Keeps public model UI manifests, captures, and generated static routes aligned for release verification.
 
 ## Included from 0.6.0

diff --git a/evals/run-mcp-pilot-evals.mjs b/evals/run-mcp-pilot-evals.mjs
@@ -1367,7 +1367,9 @@ export async function buildMcpContextForCase(testCase, mcpRuntime) {
       toolCalls,
       mcpRuntime,
       "create_ui_implementation_contract",
-      testCase.implementation_contract_args ?? {},
+      {
+        ...(testCase.implementation_contract_args ?? {}),
+      },
     );
     const repairAttempts = testCase.repair_loop?.attempts ?? null;
     const attemptReviews = [];