openuispec 0.1.32 → 0.1.34

package/cli/init.ts

@@ -347,7 +347,9 @@ This means the project has existing UI code but hasn't been specced yet. Your jo
        type: scroll_vertical
    \`\`\`
 4. **Extract tokens** — scan for colors, fonts, spacing and create files in \`${specDir}/tokens/\`.
-5. **Update the manifest** — fill in \`data_model\`, \`api.endpoints\`, and \`generation.code_roots.backend\` in \`${specDir}/openuispec.yaml\`.
+5. **Create contract extensions** — define visual variants for the 7 built-in contracts (action_trigger, data_display, input_field, collection, nav_container, feedback, surface) in \`${specDir}/contracts/\`. These encode the design system's visual identity (shapes, token overrides, platform mappings). Read \`schema/contract.schema.json\` and examples in the package for the format.
+6. **Create locale files** — for each locale in \`i18n.supported_locales\`, create \`${specDir}/locales/<locale>.json\` with all \`$t:\` keys used in screens and flows.
+7. **Update the manifest** — fill in \`data_model\`, \`api.endpoints\` in \`${specDir}/openuispec.yaml\`.
 
 ## OpenUISpec Source Of Truth
 
@@ -762,10 +764,14 @@ Done! Your spec project is ready at ./${answers.specDir}/
 
 Getting started (new project):
   1. Edit ${answers.specDir}/openuispec.yaml — define your data model and API
-  2. Create screens in ${answers.specDir}/screens/ (one YAML per screen)
-  3. Create flows in ${answers.specDir}/flows/ (multi-step navigation)
-  4. Ask AI to generate native code from the spec
-  5. Run \`openuispec drift --snapshot --target ${answers.targets[0]}\` to baseline the first accepted target state after that target output directory exists
+  2. Create tokens in ${answers.specDir}/tokens/ (colors, typography, spacing, etc.)
+  3. Create contract extensions in ${answers.specDir}/contracts/ (visual variants for the 7 built-in contracts)
+  4. Create screens in ${answers.specDir}/screens/ (one YAML per screen)
+  5. Create flows in ${answers.specDir}/flows/ (multi-step navigation)
+  6. Create locale files in ${answers.specDir}/locales/ (one JSON per supported locale)
+  7. Run \`openuispec validate\` and \`openuispec validate semantic\` to check everything
+  8. Ask AI to generate native code from the spec
+  9. Run \`openuispec drift --snapshot --target ${answers.targets[0]}\` to baseline the first accepted target state after that target output directory exists
 
 Getting started (existing project):
   1. Ask AI to read your existing UI code and generate spec files:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openuispec",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "license": "MIT",
   "type": "module",
   "description": "A semantic UI specification format for AI-native, platform-native app development",

package/prepare/index.ts

@@ -1050,14 +1050,13 @@ function buildBootstrapPrepareResult(cwd: string, target: string): PrepareResult
   const codeRoots = suggestCodeRoots(target, outputDir);
   const missingDecisions = missingPlatformDecisions(target, platformDef);
   const backendRoot = resolveBackendRoot(projectDir, manifest);
-  const backendContextRequired = hasApiEndpoints(manifest);
-  const backendContextReady = !backendContextRequired || (backendRoot !== null && existsSync(backendRoot));
+  const backendContextReady = true; // backend is optional — not a generation blocker
   const pendingUserConfirmation = platformConfig.stack_confirmation.requires_user_confirmation;
 
   const nextSteps = [
-    ...(!backendContextReady
+    ...(hasApiEndpoints(manifest) && (backendRoot === null || !existsSync(backendRoot))
       ? [
-          "Set `generation.code_roots.backend` in openuispec.yaml to the backend folder used to implement the declared API endpoints.",
+          "Optional: set `generation.code_roots.backend` in openuispec.yaml to help AI locate your backend code.",
         ]
       : []),
     ...(pendingUserConfirmation

package/schema/semantic-lint.ts

@@ -17,6 +17,7 @@ export interface Includes {
 export interface UsageLint {
   path: string;
   message: string;
+  severity?: "error" | "warning";
 }
 
 interface SemanticContext {
@@ -545,27 +546,18 @@ function lintLocaleCoverage(context: SemanticContext): UsageLint[] {
 function lintManifestGenerationContext(projectDir: string, manifest: unknown): UsageLint[] {
   if (!isRecord(manifest)) return [];
 
-  const hasApiEndpoints =
-    isRecord(manifest.api) &&
-    isRecord(manifest.api.endpoints) &&
-    Object.keys(manifest.api.endpoints).length > 0;
-  if (!hasApiEndpoints) return [];
-
+  // code_roots.backend is optional — it's a hint for AI generation, not a hard requirement
   const generation = isRecord(manifest.generation) ? manifest.generation : {};
   const codeRoots = isRecord(generation.code_roots) ? generation.code_roots : null;
   const backendRoot = codeRoots && typeof codeRoots.backend === "string" ? codeRoots.backend.trim() : "";
 
-  if (!backendRoot) {
-    return [{
-      path: "openuispec.yaml",
-      message: 'api endpoints require generation.code_roots.backend to point at the backend folder',
-    }];
-  }
+  if (!backendRoot) return [];
 
   const resolvedBackendRoot = resolve(projectDir, backendRoot);
   if (!existsSync(resolvedBackendRoot)) {
     return [{
       path: "openuispec.yaml",
+      severity: "warning",
       message: `generation.code_roots.backend points to a missing folder: ${backendRoot}`,
     }];
   }
@@ -577,14 +569,24 @@ function printSemanticErrors(label: string, errors: UsageLint[]): number {
   if (errors.length === 0) return 0;
   const previewLimit = 10;
 
-  console.log(`  FAIL  ${label} (${errors.length} semantic error(s))`);
-  for (const error of errors.slice(0, previewLimit)) {
-    console.log(`        [${error.path}] ${error.message}`);
+  const realErrors = errors.filter((e) => e.severity !== "warning");
+  const warnings = errors.filter((e) => e.severity === "warning");
+
+  if (realErrors.length > 0) {
+    console.log(`  FAIL  ${label} (${realErrors.length} semantic error(s))`);
+    for (const error of realErrors.slice(0, previewLimit)) {
+      console.log(`        [${error.path}] ${error.message}`);
+    }
+    if (realErrors.length > previewLimit) {
+      console.log(`        ... and ${realErrors.length - previewLimit} more`);
+    }
   }
-  if (errors.length > previewLimit) {
-    console.log(`        ... and ${errors.length - previewLimit} more`);
+
+  for (const warning of warnings) {
+    console.log(`  WARN  ${label}: ${warning.message}`);
   }
-  return errors.length;
+
+  return realErrors.length;
 }
 
 export function collectSemanticLint(projectDir: string, includes: Includes): UsageLint[] {