create-cogitato 0.0.0-stage → 0.2.0

package/template/design/contract/components/text.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../../node_modules/@cogitato/contract/schema/component.schema.json",
+  "name": "Text",
+  "description": "All text. Picks typography and color from tokens.",
+  "source": "production",
+  "confidence": "high",
+  "import": "@/kit/Text",
+  "props": {
+    "variant": { "type": "enum", "values": ["body", "label", "heading"], "default": "body" },
+    "tone": { "type": "enum", "values": ["default", "muted", "danger", "inverse"], "default": "default" },
+    "as": { "type": "enum", "values": ["p", "span", "h1", "h2", "h3", "label"], "default": "p" },
+    "children": { "type": "node", "required": true }
+  },
+  "states": ["default"],
+  "rules": ["One h1 per screen."],
+  "mapping": {
+    "production": { "path": "src/ui/Text.tsx", "export": "Text" }
+  }
+}

package/template/design/contract/contract.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "../../node_modules/@cogitato/contract/schema/contract.schema.json",
+  "schemaVersion": 1,
+  "name": "Acme Shop",
+  "version": "0.1.0",
+  "description": "Reference contract for an invented e-commerce product. Hand-written to exercise every Cogitato format before intake exists.",
+  "sources": [
+    { "kind": "manual", "ref": "Hand-written reference contract (ADR 003)" },
+    { "kind": "code", "ref": "acme/shop-web: src/ui", "importedAt": "2026-11-01T00:00:00Z" },
+    { "kind": "figma", "ref": "Acme Shop Library", "importedAt": "2026-11-01T00:00:00Z" }
+  ]
+}

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/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/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/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/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;

package/template/kit/Card.module.css

@@ -0,0 +1,22 @@
+.card {
+  background: var(--kit-color-surface-default);
+  border: 1px solid var(--kit-color-border-default);
+  border-radius: var(--kit-radius-lg);
+}
+
+.sm {
+  padding: var(--kit-space-3);
+}
+
+.md {
+  padding: var(--kit-space-4);
+}
+
+.lg {
+  padding: var(--kit-space-6);
+}
+
+.raised {
+  border-color: transparent;
+  box-shadow: var(--kit-shadow-card);
+}

package/template/kit/Card.tsx

@@ -0,0 +1,18 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import styles from "./Card.module.css";
+
+export interface CardProps extends HTMLAttributes<HTMLDivElement> {
+  padding?: "sm" | "md" | "lg";
+  elevation?: "flat" | "raised";
+  children: ReactNode;
+}
+
+export function Card({ padding = "md", elevation = "flat", children, className, ...rest }: CardProps) {
+  return (
+    <div {...rest} className={[styles.card, styles[padding], styles[elevation], className].filter(Boolean).join(" ")}>
+      {children}
+    </div>
+  );
+}
+
+export default Card;

package/template/kit/Input.module.css

@@ -0,0 +1,43 @@
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--kit-space-1);
+}
+
+.label {
+  font: var(--kit-typography-label);
+  color: var(--kit-color-text-default);
+}
+
+.input {
+  font: var(--kit-typography-body);
+  padding: var(--kit-space-2) var(--kit-space-3);
+  border: 1px solid var(--kit-color-border-default);
+  border-radius: var(--kit-radius-md);
+  background: var(--kit-color-surface-default);
+  color: var(--kit-color-text-default);
+}
+
+.input:focus {
+  outline: 2px solid var(--kit-color-border-focus);
+  outline-offset: -1px;
+}
+
+.input:disabled {
+  background: var(--kit-color-neutral-100);
+  color: var(--kit-color-text-muted);
+}
+
+.invalid {
+  border-color: var(--kit-color-feedback-danger);
+}
+
+.hint {
+  font-size: var(--kit-font-size-sm);
+  color: var(--kit-color-text-muted);
+}
+
+.error {
+  font-size: var(--kit-font-size-sm);
+  color: var(--kit-color-text-danger);
+}

package/template/kit/Input.tsx

@@ -0,0 +1,52 @@
+import { useId, type InputHTMLAttributes } from "react";
+import styles from "./Input.module.css";
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "onChange" | "value" | "type"> {
+  label: string;
+  type?: "text" | "email" | "password" | "number" | "tel";
+  /** Starting value. The field stays editable, so prototypes can be typed into. */
+  value?: string;
+  placeholder?: string;
+  /** Help text shown under the field. */
+  hint?: string;
+  /** Error text. Setting it shows the error state. */
+  error?: string;
+  disabled?: boolean;
+  onChange?: (value: string) => void;
+}
+
+export function Input({ label, type = "text", value, hint, error, disabled = false, onChange, className, ...rest }: InputProps) {
+  const id = useId();
+  const describedBy = error ? `${id}-error` : hint ? `${id}-hint` : undefined;
+  return (
+    <div className={[styles.field, className].filter(Boolean).join(" ")}>
+      <label htmlFor={id} className={styles.label}>
+        {label}
+      </label>
+      <input
+        {...rest}
+        id={id}
+        type={type}
+        defaultValue={value}
+        disabled={disabled}
+        aria-invalid={error ? true : undefined}
+        aria-describedby={describedBy}
+        className={[styles.input, error && styles.invalid].filter(Boolean).join(" ")}
+        onChange={(e) => onChange?.(e.target.value)}
+      />
+      {error ? (
+        <span id={`${id}-error`} className={styles.error}>
+          {error}
+        </span>
+      ) : (
+        hint && (
+          <span id={`${id}-hint`} className={styles.hint}>
+            {hint}
+          </span>
+        )
+      )}
+    </div>
+  );
+}
+
+export default Input;

package/template/kit/Stack.tsx

@@ -0,0 +1,30 @@
+import type { HTMLAttributes, ReactNode } from "react";
+
+export interface StackProps extends HTMLAttributes<HTMLDivElement> {
+  direction?: "row" | "column";
+  /** Step on the space scale. */
+  gap?: "0" | "1" | "2" | "3" | "4" | "6" | "8";
+  align?: "start" | "center" | "end" | "stretch";
+  children: ReactNode;
+}
+
+const ALIGN = { start: "flex-start", center: "center", end: "flex-end", stretch: "stretch" } as const;
+
+export function Stack({ direction = "column", gap = "4", align = "stretch", children, style, ...rest }: StackProps) {
+  return (
+    <div
+      {...rest}
+      style={{
+        display: "flex",
+        flexDirection: direction,
+        alignItems: ALIGN[align],
+        gap: `var(--kit-space-${gap})`,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+export default Stack;

package/template/kit/Text.module.css

@@ -0,0 +1,32 @@
+.text {
+  margin: 0;
+}
+
+.body {
+  font: var(--kit-typography-body);
+}
+
+.label {
+  font: var(--kit-typography-label);
+}
+
+.heading {
+  font: var(--kit-typography-heading);
+  letter-spacing: var(--kit-typography-heading-letter-spacing);
+}
+
+.default {
+  color: var(--kit-color-text-default);
+}
+
+.muted {
+  color: var(--kit-color-text-muted);
+}
+
+.danger {
+  color: var(--kit-color-text-danger);
+}
+
+.inverse {
+  color: var(--kit-color-text-inverse);
+}

package/template/kit/Text.tsx

@@ -0,0 +1,19 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import styles from "./Text.module.css";
+
+export interface TextProps extends HTMLAttributes<HTMLElement> {
+  variant?: "body" | "label" | "heading";
+  tone?: "default" | "muted" | "danger" | "inverse";
+  as?: "p" | "span" | "h1" | "h2" | "h3" | "label";
+  children: ReactNode;
+}
+
+export function Text({ variant = "body", tone = "default", as: Tag = "p", children, className, ...rest }: TextProps) {
+  return (
+    <Tag {...rest} className={[styles.text, styles[variant], styles[tone], className].filter(Boolean).join(" ")}>
+      {children}
+    </Tag>
+  );
+}
+
+export default Text;