@sudajs/cli 0.11.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@puckeditor/core": "^0.21.3",
+    "@puckeditor/core": "^0.22.0",
     "commander": "^12.1.0",
     "esbuild": "^0.25.12",
     "lucide-react": "^1.17.0",
@@ -34,7 +34,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "3.0.0"
+    "@sudajs/theme-engine": "4.0.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",
@@ -49,8 +49,8 @@
     "typescript": "^5.7.2",
     "vite": "^7.3.3",
     "vitest": "^3.2.4",
-    "@suda/eslint-config": "0.0.0",
     "@suda/build-config": "0.0.0",
+    "@suda/eslint-config": "0.0.0",
     "@suda/tsconfig": "0.0.0"
   },
   "scripts": {

package/templates/theme/AGENTS.md

@@ -320,10 +320,18 @@ defaultProps: {
 },
 ```
 
-Supported strategies are `latest`, `featured`, `by_tag`, and `manual`. In the
-section render function, call `getPostResource(puck?.metadata, id)` to get the
-posts. Never import Prisma, call platform APIs, or query the database from
-theme code.
+Supported strategies are `latest`, `featured`, `by_tag`, and `manual`. Manual
+queries store only `items` and must not include `limit`. Runtime post resources
+are keyed as `${props.id}.${fieldKey}` with both parts URL-encoded by the
+platform. In the section render function, call
+`getPostResource(puck?.metadata, { componentId: props.id, fieldKey: "postList" })`
+with the exact posts field key. Never import Prisma, call platform APIs, or
+query the database from theme code.
+
+Do not add `resourceQuery: { type: "posts" }` or
+`resource_query: { type: "posts" }`. Do not assume the field must be named
+`query`. A section may have only one top-level posts field; do not nest posts
+fields inside `object`, `array`, native slots, or `blockSlots`.
 
 Starter pages must include one home/index page with `isHome: true`. Recommended
 starter pages include `index`, `about-us`, `contact-us`, `services`, and `team`.
@@ -406,6 +414,67 @@ export const Hero: SudaComponentConfig<HeroProps> = {
 - If a page section needs controlled nested content, use Suda `blockSlots`, not a hand-written Puck slot field. `blockSlots` lets the theme define exactly which local block kinds are allowed inside that section.
 - Do not use legacy DropZone or `zones` patterns.
 
+## Design system rules
+
+Build every theme from one theme-level design system. Do not let each section,
+CMS template, block slot, or starter page invent its own colors, type scale,
+radius, shadows, or spacing.
+
+- Define the editable theme system once in `src/manifest.ts` as
+  `sourceManifest.designSystem`. Include `version`, `defaultPresetId`, and
+  named `presets` with complete token sets.
+- Use stable token names from the engine contract. At minimum, provide the
+  color tokens the theme renders (`background`, `foreground`, `primary`,
+  `primaryForeground`, `accent`, `accentForeground`, `muted`,
+  `mutedForeground`) and the radius tokens the CSS consumes (`card`, `button`,
+  `input`). Do not invent platform-facing token keys without checking the
+  generated types first.
+- Expose the design system at the layout root only:
+  `designSystem: designSystemField(t("common.fields.designSystem"),
+  sourceManifest.designSystem)`, with
+  `createThemeDesignDefault(sourceManifest.designSystem)` in `ROOT_DEFAULTS`.
+- In the root render, resolve the value once with
+  `resolveThemeDesignTokens(sourceManifest.designSystem, props.designSystem)`
+  and apply `createThemeDesignCssVariables(tokens)` to the theme root element.
+  Components should consume CSS variables; they should not resolve design
+  presets themselves.
+- In `src/styles.css`, map Suda variables to theme-local or Tailwind variables
+  once, for example `--color-primary: var(--suda-color-primary, #...)` and
+  `--radius-card: var(--suda-radius-card, 24px)`. Use those variables across
+  sections, cards, CMS layouts, post lists, forms, and local blocks.
+- Keep typography and spacing scales centralized in `src/styles.css`. Define
+  reusable classes or variables for containers, section padding, headings,
+  eyebrow text, body copy, cards, buttons, inputs, and media frames. Reuse those
+  classes instead of writing new one-off Tailwind values in every section.
+- Section props may expose semantic choices such as `tone`, `variant`,
+  `columns`, `mediaPosition`, `showImage`, or `spacing`. Map those choices to
+  the existing design tokens and shared CSS classes.
+- Do not add raw `color`, `font`, `spacing`, `radius`, or `shadow` fields to a
+  section just because the CSS has a value. Expose a design token field only
+  when the user should intentionally customize that value per component
+  instance. Otherwise, keep the value in the theme CSS.
+- Use `color`, `font`, and `spacing` field types only for real editor-facing
+  design controls. Use `select`/`radio` for named variants that are already
+  part of the theme design system.
+- Local blocks inside `blockSlots` inherit the host section's design system.
+  Local block fields should edit content or semantic variants, not define their
+  own palette, type scale, radius, shadows, or spacing.
+- CMS main sections (`MainPosts`, `MainPost`, `MainTags`, `MainTagPosts`) and
+  ordinary post-resource sections must use the same containers, heading scale,
+  card style, media ratio, pagination style, and empty/loading states as the
+  rest of the theme.
+- Starter pages must demonstrate the same design system across different page
+  types. Vary content, order, media, and semantic variants; do not hardcode
+  unrelated colors, spacing, rounded corners, or shadows in starter page data to
+  make pages look different.
+- When adding a new section, first choose the existing container, heading,
+  button, card, form, and media patterns it should reuse. Add a new CSS utility
+  or token only when multiple sections will use it or the theme needs a new
+  named pattern.
+- Keep preview screenshots, default props, starter pages, CMS templates, and
+  AI examples aligned with the same token presets. The default preset should
+  look publishable without manual editor tweaks.
+
 ## Styling and assets
 
 - Tailwind v4 starts in `src/styles.css` with `@import "tailwindcss";` and `@source "./**/*.{ts,tsx}";`.

package/templates/theme/package.json

@@ -19,7 +19,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@tailwindcss/postcss": "^4.3.0",
-    "@puckeditor/core": "^0.21.3",
+    "@puckeditor/core": "^0.22.0",
     "@sudajs/cli": "*",
     "@sudajs/theme-engine": "*",
     "@types/node": "^24.13.2",
@@ -42,7 +42,7 @@
     "vite": "^8.1.0"
   },
   "peerDependencies": {
-    "@puckeditor/core": "^0.21.3",
+    "@puckeditor/core": "^0.22.0",
     "@sudajs/theme-engine": "*",
     "lucide-react": "^1.17.0",
     "react": "^19.2.7",

package/templates/theme/src/layout.tsx

@@ -1,11 +1,21 @@
 import type { SudaComponentConfig, SudaRootConfig } from "@sudajs/theme-engine";
-import { getIcpRecord, getPageSlot, getWhiteLabel } from "@sudajs/theme-engine/runtime";
+import {
+  createThemeDesignCssVariables,
+  createThemeDesignDefault,
+  designSystemField,
+  getIcpRecord,
+  getPageSlot,
+  getWhiteLabel,
+  resolveThemeDesignTokens,
+  type ThemeDesignValue,
+} from "@sudajs/theme-engine/runtime";
 import type { ReactElement, ReactNode } from "react";
 
 import { t } from "./i18n.js";
+import { sourceManifest } from "./manifest.js";
 
 type PuckExtras = { puck?: { metadata?: Record<string, unknown> } };
-type RootProps = { children?: ReactNode; title?: string };
+type RootProps = { children?: ReactNode; title?: string; designSystem?: ThemeDesignValue };
 type HeaderProps = { siteName?: string };
 type PageOutletProps = PuckExtras;
 type FooterProps = { text?: string } & PuckExtras;
@@ -13,13 +23,21 @@ type FooterProps = { text?: string } & PuckExtras;
 export const rootConfig: SudaRootConfig<RootProps> = {
   fields: {
     title: { type: "text", label: t("layout.root.fields.title") },
+    designSystem: designSystemField(t("layout.root.fields.designSystem"), sourceManifest.designSystem),
+  },
+  defaultProps: {
+    title: "__SUDA_THEME_KEY__",
+    designSystem: createThemeDesignDefault(sourceManifest.designSystem),
+  },
+  render: ({ children, designSystem, title }) => {
+    const tokens = resolveThemeDesignTokens(sourceManifest.designSystem, designSystem);
+    const style = createThemeDesignCssVariables(tokens);
+    return (
+      <div className="__SUDA_THEME_KEY__-root" data-site-name={title} style={style}>
+        {children}
+      </div>
+    );
   },
-  defaultProps: { title: "__SUDA_THEME_KEY__" },
-  render: ({ children, title }) => (
-    <div className="__SUDA_THEME_KEY__-root" data-site-name={title}>
-      {children}
-    </div>
-  ),
 };
 
 export const Header: SudaComponentConfig<HeaderProps> = {

package/templates/theme/src/locales/en.json

@@ -2,7 +2,8 @@
   "layout": {
     "root": {
       "fields": {
-        "title": "Site title"
+        "title": "Site title",
+        "designSystem": "Design system"
       }
     },
     "header": {

package/templates/theme/src/manifest.ts

@@ -8,7 +8,55 @@ export const sourceManifest: ThemeSourceManifest = {
   key: "__SUDA_THEME_KEY__",
   name: "__SUDA_THEME_KEY__",
   categories: ["other"],
-  minEngineVersion: "0.0.0",
+  minEngineVersion: "4.0.0",
+  designSystem: {
+    version: 1,
+    defaultPresetId: "default",
+    presets: [
+      {
+        id: "default",
+        label: "Default",
+        tokens: {
+          colors: {
+            background: "#ffffff",
+            foreground: "#111827",
+            primary: "#111827",
+            primaryForeground: "#ffffff",
+            accent: "#f8fafc",
+            accentForeground: "#111827",
+            muted: "#f4f5f7",
+            mutedForeground: "#4b5563",
+          },
+          radius: {
+            card: "8px",
+            button: "8px",
+            input: "8px",
+          },
+        },
+      },
+      {
+        id: "ocean",
+        label: "Ocean",
+        tokens: {
+          colors: {
+            background: "#f8fbff",
+            foreground: "#0e1b36",
+            primary: "#2563eb",
+            primaryForeground: "#ffffff",
+            accent: "#dbeafe",
+            accentForeground: "#0e1b36",
+            muted: "#eff6ff",
+            mutedForeground: "#42526e",
+          },
+          radius: {
+            card: "14px",
+            button: "9999px",
+            input: "10px",
+          },
+        },
+      },
+    ],
+  },
   entry: "index.js",
   clientEntry: "runtime.client.js",
   // Required. SudaCloud currently hosts SSR themes only; CSR/Hybrid postures

package/templates/theme/src/sections.tsx

@@ -240,7 +240,10 @@ export const FeaturedPosts: SudaComponentConfig<FeaturedPostsProps> = {
     postList: { strategy: "featured", limit: 3 },
   },
   render: ({ id, title, description, puck }) => {
-    const resource = getPostResource(puck?.metadata, id);
+    const resource = getPostResource(puck?.metadata, {
+      componentId: id,
+      fieldKey: "postList",
+    });
     const posts = resource.posts;
     return (
       <section className="__SUDA_THEME_KEY__-section">

package/templates/theme/src/styles.css

@@ -3,22 +3,22 @@
 
 .__SUDA_THEME_KEY__-root {
   font-family: Inter, ui-sans-serif, system-ui, sans-serif;
-  color: #111827;
-  background: #ffffff;
+  color: var(--suda-color-foreground, #111827);
+  background: var(--suda-color-background, #ffffff);
 }
 .__SUDA_THEME_KEY__-header,
 .__SUDA_THEME_KEY__-footer {
   padding: 20px clamp(20px, 5vw, 64px);
-  border-bottom: 1px solid #e5e7eb;
+  border-bottom: 1px solid var(--suda-color-muted, #e5e7eb);
 }
 .__SUDA_THEME_KEY__-footer {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
   gap: 12px 20px;
-  border-top: 1px solid #e5e7eb;
+  border-top: 1px solid var(--suda-color-muted, #e5e7eb);
   border-bottom: 0;
-  color: #6b7280;
+  color: var(--suda-color-muted-foreground, #6b7280);
 }
 .__SUDA_THEME_KEY__-footer a {
   display: inline-flex;
@@ -35,19 +35,19 @@
   padding: 64px clamp(20px, 5vw, 64px);
 }
 .__SUDA_THEME_KEY__-hero {
-  background: #f8fafc;
+  background: var(--suda-color-accent, #f8fafc);
 }
 .__SUDA_THEME_KEY__-hero-logo {
   width: 64px;
   height: 64px;
-  border-radius: 14px;
+  border-radius: var(--suda-radius-card, 14px);
   margin-bottom: 24px;
 }
 .__SUDA_THEME_KEY__-eyebrow {
   text-transform: uppercase;
   letter-spacing: 0.08em;
   font-size: 12px;
-  color: #2563eb;
+  color: var(--suda-color-primary, #2563eb);
   font-weight: 700;
 }
 .__SUDA_THEME_KEY__-section h1 {
@@ -65,16 +65,16 @@
 .__SUDA_THEME_KEY__-section p {
   max-width: 680px;
   line-height: 1.7;
-  color: #4b5563;
+  color: var(--suda-color-muted-foreground, #4b5563);
 }
 .__SUDA_THEME_KEY__-button {
   display: inline-flex;
   align-items: center;
   min-height: 42px;
   padding: 0 18px;
-  border-radius: 8px;
-  background: #111827;
-  color: #ffffff;
+  border-radius: var(--suda-radius-button, 8px);
+  background: var(--suda-color-primary, #111827);
+  color: var(--suda-color-primary-foreground, #ffffff);
   text-decoration: none;
   font-weight: 700;
 }
@@ -85,14 +85,14 @@
   margin-top: 28px;
 }
 .__SUDA_THEME_KEY__-card {
-  border: 1px solid #e5e7eb;
-  border-radius: 8px;
+  border: 1px solid var(--suda-color-muted, #e5e7eb);
+  border-radius: var(--suda-radius-card, 8px);
   padding: 20px;
 }
 .__SUDA_THEME_KEY__-card-icon {
   width: 24px;
   height: 24px;
-  color: #2563eb;
+  color: var(--suda-color-primary, #2563eb);
 }
 .__SUDA_THEME_KEY__-quote blockquote {
   max-width: 780px;
@@ -101,15 +101,15 @@
   margin: 0 0 16px;
 }
 .__SUDA_THEME_KEY__-cta {
-  background: #111827;
-  color: #ffffff;
+  background: var(--suda-color-foreground, #111827);
+  color: var(--suda-color-background, #ffffff);
 }
 .__SUDA_THEME_KEY__-cta p {
-  color: #d1d5db;
+  color: var(--suda-color-muted, #d1d5db);
 }
 .__SUDA_THEME_KEY__-cta .__SUDA_THEME_KEY__-button {
-  background: #ffffff;
-  color: #111827;
+  background: var(--suda-color-background, #ffffff);
+  color: var(--suda-color-foreground, #111827);
 }
 @media (max-width: 760px) {
   .__SUDA_THEME_KEY__-grid {