@sudajs/cli 0.12.0 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -34,7 +34,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "4.0.0"
+    "@sudajs/theme-engine": "4.0.1"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.0",

package/templates/theme/AGENTS.md

@@ -308,8 +308,8 @@ example `FeaturedPosts`, `LatestPosts`, or `TopicPosts`. Use it for homepage
 insights, featured articles, case studies, news teasers, or tag-filtered post
 groups on ordinary pages.
 
-Define that section with one or more top-level `type: "posts"` fields and a
-default query on each matching prop:
+Define that section with exactly one top-level `type: "posts"` field and a
+default query on the same prop:
 
 ```tsx
 fields: {
@@ -328,6 +328,11 @@ platform. In the section render function, call
 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`.
 Those recommended pages are not hard requirements, but a publishable theme
@@ -409,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}";`.