create-cogitato 0.0.0-stage → 0.1.0

package/template/design/contract/decisions.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "../../node_modules/@cogitato/contract/schema/decisions.schema.json",
+  "decisions": [
+    {
+      "id": "dec_brand-blue-600",
+      "topic": "tokens.color.brand.600",
+      "question": "Code and Figma use slightly different values for the main brand blue. Which is canonical?",
+      "options": [
+        {
+          "id": "code",
+          "label": "Keep the production value",
+          "value": "#2563eb",
+          "evidence": [{ "source": "code", "detail": "src/ui/theme.ts: brand600, used in 214 places" }]
+        },
+        {
+          "id": "figma",
+          "label": "Use the Figma value",
+          "value": "#2462e8",
+          "evidence": [{ "source": "figma", "detail": "Variable Brand/600 in Acme Shop Library" }]
+        }
+      ],
+      "recommendation": "code",
+      "status": "decided",
+      "choice": "code",
+      "decidedBy": "dev_alex",
+      "decidedAt": "2026-11-01T00:00:00Z",
+      "note": "Figma variable to be updated to match."
+    },
+    {
+      "id": "dec_input-name",
+      "topic": "components.Input",
+      "question": "Production calls the text field TextInput; Figma calls it Input. Which name do designers see?",
+      "options": [
+        { "id": "input", "label": "Input (Figma name)" },
+        { "id": "text-input", "label": "TextInput (production name)" }
+      ],
+      "recommendation": "input",
+      "status": "open"
+    }
+  ]
+}

package/template/design/contract/gaps.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "../../node_modules/@cogitato/contract/schema/gaps.schema.json",
+  "gaps": [
+    {
+      "id": "gap_stepper",
+      "kind": "component",
+      "name": "Stepper",
+      "context": "Show checkout progress (Cart, Shipping, Payment) at the top of each checkout screen.",
+      "screen": "checkout.shipping",
+      "workaround": "A row of Text labels in a Stack.",
+      "requestedBy": "designer_sam",
+      "status": "open",
+      "createdAt": "2026-11-01T00:00:00Z"
+    }
+  ]
+}

package/template/design/contract/rules.md

@@ -0,0 +1,19 @@
+# Acme Shop design rules
+
+These apply to every prototype screen. The validator enforces the ones marked **(checked)**.
+
+## Do
+- Use tokens for every color, size, space, radius and shadow. **(checked)**
+- Build with kit components from `@/kit/...`. **(checked)**
+- Give every interactive element a `data-kit-id`. **(checked)**
+- Lay out with `Stack` and its `gap`, not custom margins.
+- Keep one primary `Button` per view.
+- Write button labels as verbs ("Pay now").
+
+## Don't
+- Hardcode values like `#2563eb` or `16px`. **(checked)**
+- Nest a `Card` inside another `Card`.
+- Use `danger` styles for anything that isn't destructive or an error.
+
+## Missing something?
+If the kit doesn't have what you need, log a gap instead of improvising. Developers review gaps before the next contract update.

package/template/design/contract/tokens.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "../../node_modules/@cogitato/contract/schema/tokens.schema.json",
+  "color": {
+    "$type": "color",
+    "brand": {
+      "50": { "$value": "#eff6ff", "$description": "Brand Blue 50" },
+      "100": { "$value": "#dbeafe", "$description": "Brand Blue 100" },
+      "500": { "$value": "#3b82f6", "$description": "Brand Blue 500" },
+      "600": { "$value": "#2563eb", "$description": "Brand Blue 600" },
+      "700": { "$value": "#1d4ed8", "$description": "Brand Blue 700" }
+    },
+    "neutral": {
+      "0": { "$value": "#ffffff", "$description": "White" },
+      "50": { "$value": "#f8fafc", "$description": "Neutral 50" },
+      "100": { "$value": "#f1f5f9", "$description": "Neutral 100" },
+      "200": { "$value": "#e2e8f0", "$description": "Neutral 200" },
+      "500": { "$value": "#64748b", "$description": "Neutral 500" },
+      "700": { "$value": "#334155", "$description": "Neutral 700" },
+      "900": { "$value": "#0f172a", "$description": "Neutral 900" }
+    },
+    "feedback": {
+      "success": { "$value": "#15803d", "$description": "Success green" },
+      "warning": { "$value": "#b45309", "$description": "Warning amber" },
+      "danger": { "$value": "#b91c1c", "$description": "Danger red" },
+      "danger-subtle": { "$value": "#fef2f2", "$description": "Danger background" },
+      "info": { "$value": "{color.brand.600}", "$description": "Info uses brand blue" }
+    },
+    "text": {
+      "default": { "$value": "{color.neutral.900}" },
+      "muted": { "$value": "{color.neutral.500}" },
+      "inverse": { "$value": "{color.neutral.0}" },
+      "danger": { "$value": "{color.feedback.danger}" }
+    },
+    "surface": {
+      "default": { "$value": "{color.neutral.0}" },
+      "subtle": { "$value": "{color.neutral.50}" }
+    },
+    "border": {
+      "default": { "$value": "{color.neutral.200}" },
+      "focus": { "$value": "{color.brand.500}" }
+    }
+  },
+  "space": {
+    "$type": "dimension",
+    "$description": "Spacing scale. Use for padding, margins and gaps.",
+    "0": { "$value": { "value": 0, "unit": "px" } },
+    "1": { "$value": { "value": 4, "unit": "px" } },
+    "2": { "$value": { "value": 8, "unit": "px" } },
+    "3": { "$value": { "value": 12, "unit": "px" } },
+    "4": { "$value": { "value": 16, "unit": "px" } },
+    "6": { "$value": { "value": 24, "unit": "px" } },
+    "8": { "$value": { "value": 32, "unit": "px" } }
+  },
+  "radius": {
+    "$type": "dimension",
+    "sm": { "$value": { "value": 4, "unit": "px" } },
+    "md": { "$value": { "value": 8, "unit": "px" } },
+    "lg": { "$value": { "value": 12, "unit": "px" } },
+    "full": { "$value": { "value": 9999, "unit": "px" } }
+  },
+  "font": {
+    "family": {
+      "$type": "fontFamily",
+      "sans": { "$value": ["Inter", "system-ui", "sans-serif"] }
+    },
+    "weight": {
+      "$type": "fontWeight",
+      "regular": { "$value": 400 },
+      "medium": { "$value": 500 },
+      "semibold": { "$value": 600 },
+      "bold": { "$value": 700 }
+    },
+    "size": {
+      "$type": "dimension",
+      "sm": { "$value": { "value": 14, "unit": "px" } },
+      "md": { "$value": { "value": 16, "unit": "px" } },
+      "lg": { "$value": { "value": 20, "unit": "px" } },
+      "xl": { "$value": { "value": 28, "unit": "px" } }
+    }
+  },
+  "typography": {
+    "$type": "typography",
+    "body": {
+      "$value": {
+        "fontFamily": "{font.family.sans}",
+        "fontSize": "{font.size.md}",
+        "fontWeight": "{font.weight.regular}",
+        "lineHeight": 1.5
+      }
+    },
+    "label": {
+      "$value": {
+        "fontFamily": "{font.family.sans}",
+        "fontSize": "{font.size.sm}",
+        "fontWeight": "{font.weight.medium}",
+        "lineHeight": 1.4
+      }
+    },
+    "heading": {
+      "$value": {
+        "fontFamily": "{font.family.sans}",
+        "fontSize": "{font.size.xl}",
+        "fontWeight": "{font.weight.bold}",
+        "lineHeight": 1.2,
+        "letterSpacing": { "value": -0.02, "unit": "rem" }
+      }
+    }
+  },
+  "shadow": {
+    "$type": "shadow",
+    "card": {
+      "$value": {
+        "color": "#0f172a1a",
+        "offsetX": { "value": 0, "unit": "px" },
+        "offsetY": { "value": 1, "unit": "px" },
+        "blur": { "value": 3, "unit": "px" },
+        "spread": { "value": 0, "unit": "px" }
+      }
+    }
+  },
+  "duration": {
+    "$type": "duration",
+    "fast": { "$value": { "value": 120, "unit": "ms" } },
+    "normal": { "$value": { "value": 200, "unit": "ms" } }
+  }
+}

package/template/design/flows.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "../node_modules/@cogitato/contract/schema/flows.schema.json",
+  "schemaVersion": 1,
+  "screens": [
+    {
+      "id": "cart",
+      "route": "/cart",
+      "title": "Cart",
+      "states": [
+        {
+          "id": "default",
+          "fixture": "default",
+          "title": "Two items"
+        },
+        {
+          "id": "empty",
+          "fixture": "empty",
+          "title": "Empty cart"
+        }
+      ]
+    },
+    {
+      "id": "checkout.shipping",
+      "route": "/checkout/shipping",
+      "title": "Shipping",
+      "states": [
+        {
+          "id": "default",
+          "fixture": "default",
+          "title": "Empty form"
+        },
+        {
+          "id": "invalid-address",
+          "fixture": "invalid-address",
+          "title": "Address not found"
+        }
+      ]
+    },
+    {
+      "id": "checkout.payment",
+      "route": "/checkout/payment",
+      "title": "Payment",
+      "states": [
+        {
+          "id": "default",
+          "fixture": "default",
+          "title": "Empty form"
+        },
+        {
+          "id": "processing",
+          "fixture": "processing",
+          "title": "Processing"
+        },
+        {
+          "id": "card-declined",
+          "fixture": "card-declined",
+          "title": "Card declined"
+        }
+      ]
+    },
+    {
+      "id": "checkout.confirmation",
+      "route": "/checkout/confirmation",
+      "title": "Order confirmed",
+      "states": [
+        {
+          "id": "default",
+          "fixture": "default",
+          "title": "Confirmed"
+        }
+      ]
+    }
+  ],
+  "flows": [
+    {
+      "id": "checkout",
+      "title": "Checkout",
+      "nodes": [
+        "cart.default",
+        "checkout.shipping.default",
+        "checkout.shipping.invalid-address",
+        "checkout.payment.default",
+        "checkout.payment.processing",
+        "checkout.payment.card-declined",
+        "checkout.confirmation.default"
+      ],
+      "edges": [
+        {
+          "from": "cart.default",
+          "to": "checkout.shipping.default",
+          "label": "Check out"
+        },
+        {
+          "from": "checkout.shipping.default",
+          "to": "checkout.shipping.invalid-address",
+          "label": "Continue, address not found"
+        },
+        {
+          "from": "checkout.shipping.default",
+          "to": "checkout.payment.default",
+          "label": "Continue"
+        },
+        {
+          "from": "checkout.payment.default",
+          "to": "checkout.payment.processing",
+          "label": "Pay now"
+        },
+        {
+          "from": "checkout.payment.processing",
+          "to": "checkout.payment.card-declined",
+          "label": "Declined"
+        },
+        {
+          "from": "checkout.payment.processing",
+          "to": "checkout.confirmation.default",
+          "label": "Approved"
+        }
+      ]
+    }
+  ]
+}

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Acme Shop prototype</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/netlify.toml

@@ -0,0 +1,28 @@
+# Netlify config for a Cogitato prototype repo (ADR 013). Every branch push gets a preview whose
+# canvas is at /__canvas. Snapshots need Chromium; if it can't run, the build still succeeds and
+# the canvas shows placeholders.
+
+[build]
+  command = "npx playwright install chromium && pnpm build"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "22"
+
+# Screens are client-side routes: every path serves the app.
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+
+# Previews may be framed only by their own canvas. Widen this when a team canvas on another
+# site needs to show them (Phase 4).
+[[headers]]
+  for = "/*"
+  [headers.values]
+    Content-Security-Policy = "frame-ancestors 'self'"
+
+[[headers]]
+  for = "/__kit-data/*"
+  [headers.values]
+    Cache-Control = "public, max-age=0, must-revalidate"

package/template/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "my-prototype",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "kit export-flows && vite",
+    "build": "kit validate && kit export-flows && tsc --noEmit && vite build && kit snapshots",
+    "typecheck": "tsc --noEmit",
+    "validate": "kit validate",
+    "kit": "kit"
+  },
+  "dependencies": {
+    "@cogitato/runtime": "^0.1.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.28.0"
+  },
+  "devDependencies": {
+    "@cogitato/contract": "^0.1.0",
+    "@cogitato/kit-cli": "^0.1.0",
+    "@cogitato/kit-mcp": "^0.1.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "playwright": "^1.64.1",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.7"
+  }
+}

package/template/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+allowBuilds:
+  esbuild: true

package/template/src/components/Page.module.css

@@ -0,0 +1,5 @@
+.page {
+  max-width: 480px;
+  margin: 0 auto;
+  padding: var(--kit-space-8) var(--kit-space-4);
+}

package/template/src/components/Page.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+import { Stack } from "@/kit/Stack";
+import { Text } from "@/kit/Text";
+import styles from "./Page.module.css";
+
+const STEPS = ["Cart", "Shipping", "Payment"] as const;
+
+/** Page frame shared by the checkout screens. `step` highlights the progress row. */
+export function Page({ title, step, children }: { title: string; step?: (typeof STEPS)[number]; children: ReactNode }) {
+  return (
+    <main className={styles.page}>
+      <Stack gap="6">
+        {step && (
+          // Stand-in for the Stepper component until it exists (gap_stepper).
+          <Stack direction="row" gap="3" aria-label="Checkout progress">
+            {STEPS.map((s) => (
+              <Text key={s} as="span" variant="label" tone={s === step ? "default" : "muted"}>
+                {s}
+              </Text>
+            ))}
+          </Stack>
+        )}
+        <Text as="h1" variant="heading">
+          {title}
+        </Text>
+        {children}
+      </Stack>
+    </main>
+  );
+}

package/template/src/flows.ts

@@ -0,0 +1,18 @@
+import { defineFlows } from "@cogitato/runtime";
+
+// How screens connect. Each step is "{screen id}.{state}". `kit export-flows` turns this into
+// design/flows.json for the canvas; steps appear in the order they're first mentioned.
+export default defineFlows([
+  {
+    id: "checkout",
+    title: "Checkout",
+    edges: [
+      { from: "cart.default", to: "checkout.shipping.default", label: "Check out" },
+      { from: "checkout.shipping.default", to: "checkout.shipping.invalid-address", label: "Continue, address not found" },
+      { from: "checkout.shipping.default", to: "checkout.payment.default", label: "Continue" },
+      { from: "checkout.payment.default", to: "checkout.payment.processing", label: "Pay now" },
+      { from: "checkout.payment.processing", to: "checkout.payment.card-declined", label: "Declined" },
+      { from: "checkout.payment.processing", to: "checkout.confirmation.default", label: "Approved" },
+    ],
+  },
+]);

package/template/src/kit/Banner.module.css

@@ -0,0 +1,48 @@
+.banner {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--kit-space-3);
+  padding: var(--kit-space-3) var(--kit-space-4);
+  border-radius: var(--kit-radius-md);
+  border-left: 4px solid currentColor;
+}
+
+.body {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  gap: var(--kit-space-1);
+  color: var(--kit-color-text-default);
+}
+
+.title {
+  font: var(--kit-typography-label);
+}
+
+.info {
+  color: var(--kit-color-feedback-info);
+  background: var(--kit-color-brand-50);
+}
+
+.success {
+  color: var(--kit-color-feedback-success);
+  background: var(--kit-color-surface-subtle);
+}
+
+.warning {
+  color: var(--kit-color-feedback-warning);
+  background: var(--kit-color-surface-subtle);
+}
+
+.danger {
+  color: var(--kit-color-feedback-danger);
+  background: var(--kit-color-feedback-danger-subtle);
+}
+
+.dismiss {
+  border: 0;
+  background: transparent;
+  color: var(--kit-color-text-muted);
+  font-size: var(--kit-font-size-lg);
+  cursor: pointer;
+}

package/template/src/kit/Banner.tsx

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import styles from "./Banner.module.css";
+
+export interface BannerProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  tone?: "info" | "success" | "warning" | "danger";
+  title?: string;
+  children: ReactNode;
+  /** Shows a close button when set. */
+  onDismiss?: () => void;
+  "data-kit-id"?: string;
+}
+
+export function Banner({ tone = "info", title, children, onDismiss, className, ...rest }: BannerProps) {
+  const kitId = rest["data-kit-id"];
+  return (
+    <div
+      {...rest}
+      role={tone === "danger" || tone === "warning" ? "alert" : "status"}
+      className={[styles.banner, styles[tone], className].filter(Boolean).join(" ")}
+    >
+      <div className={styles.body}>
+        {title && <strong className={styles.title}>{title}</strong>}
+        <div>{children}</div>
+      </div>
+      {onDismiss && (
+        <button
+          type="button"
+          className={styles.dismiss}
+          aria-label="Dismiss"
+          data-kit-id={kitId ? `${kitId}.dismiss` : undefined}
+          onClick={onDismiss}
+        >
+          ×
+        </button>
+      )}
+    </div>
+  );
+}
+
+export default Banner;

package/template/src/kit/Button.module.css

@@ -0,0 +1,86 @@
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--kit-space-2);
+  border: 1px solid transparent;
+  border-radius: var(--kit-radius-md);
+  font: var(--kit-typography-label);
+  cursor: pointer;
+  transition: background-color var(--kit-duration-fast), border-color var(--kit-duration-fast);
+}
+
+.button:focus-visible {
+  outline: 2px solid var(--kit-color-border-focus);
+  outline-offset: 2px;
+}
+
+.button:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.sm {
+  padding: var(--kit-space-1) var(--kit-space-3);
+}
+
+.md {
+  padding: var(--kit-space-2) var(--kit-space-4);
+}
+
+.lg {
+  padding: var(--kit-space-3) var(--kit-space-6);
+  font-size: var(--kit-font-size-md);
+}
+
+.full {
+  width: 100%;
+}
+
+.primary {
+  background: var(--kit-color-brand-600);
+  color: var(--kit-color-text-inverse);
+}
+
+.primary:hover:not(:disabled) {
+  background: var(--kit-color-brand-700);
+}
+
+.secondary {
+  background: var(--kit-color-surface-default);
+  border-color: var(--kit-color-border-default);
+  color: var(--kit-color-text-default);
+}
+
+.secondary:hover:not(:disabled) {
+  background: var(--kit-color-neutral-100);
+}
+
+.ghost {
+  background: transparent;
+  color: var(--kit-color-brand-600);
+}
+
+.ghost:hover:not(:disabled) {
+  background: var(--kit-color-brand-50);
+}
+
+.danger {
+  background: var(--kit-color-feedback-danger);
+  color: var(--kit-color-text-inverse);
+}
+
+.spinner {
+  width: 1em;
+  height: 1em;
+  border: 2px solid currentColor;
+  border-right-color: transparent;
+  border-radius: var(--kit-radius-full);
+  animation: spin 0.8s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}

package/template/src/kit/Button.tsx

@@ -0,0 +1,43 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+import styles from "./Button.module.css";
+
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onClick" | "children"> {
+  variant?: "primary" | "secondary" | "ghost" | "danger";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  /** Shows a spinner and blocks presses. */
+  loading?: boolean;
+  fullWidth?: boolean;
+  /** Button label. */
+  children: ReactNode;
+  onPress?: () => void;
+}
+
+export function Button({
+  variant = "primary",
+  size = "md",
+  disabled = false,
+  loading = false,
+  fullWidth = false,
+  children,
+  onPress,
+  className,
+  ...rest
+}: ButtonProps) {
+  const classes = [styles.button, styles[variant], styles[size], fullWidth && styles.full, className];
+  return (
+    <button
+      type="button"
+      {...rest}
+      className={classes.filter(Boolean).join(" ")}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      onClick={onPress}
+    >
+      {loading && <span className={styles.spinner} aria-hidden="true" />}
+      {children}
+    </button>
+  );
+}
+
+export default Button;