@utopia-studio-design/design-system-cli 0.3.0 → 0.3.1

package/README.md

@@ -9,6 +9,8 @@ npx utopia-ds search "Arabic data table" --json
 npx utopia-ds component DataTable --json
 npx utopia-ds template template-saas-solution-homepage --copy ./saas-website
 npx utopia-ds template template-saas-solution-homepage --theme dextrum --copy ./dextrum-website
+npx utopia-ds template validate ./my-community-template
+npx utopia-ds template submit ./my-community-template
 npx utopia-ds theme create nova
 npx utopia-ds manifest --json
 npx utopia-ds mcp

package/bin/utopia-ds-mcp.mjs

@@ -1,17 +1,19 @@
 #!/usr/bin/env node
 import {
-  capabilityManifest, getComponent, getDoc, getTemplate, getTheme,
-  listComponents, listDocs, listTemplates, listThemes, repositoryDoctor, search,
+  capabilityManifest, getComponent, getDoc, getMotionProfile, getTemplate, getTheme,
+  listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, repositoryDoctor, search,
 } from '../lib/api.mjs'
 
 const tools = [
-  ['search', 'Search components, docs, templates, and themes.', { query: { type: 'string' } }, ({ query }) => search(query)],
+  ['search', 'Search components, docs, templates, themes, and motion profiles.', { query: { type: 'string' } }, ({ query }) => search(query)],
   ['list_components', 'List every Ceramic component contract.', {}, () => listComponents()],
   ['get_component', 'Get one component including imports, tokens, usage, and Arabic rules.', { name: { type: 'string' } }, ({ name }) => getComponent(name)],
   ['list_templates', 'List Ceramic starter templates.', {}, () => listTemplates()],
   ['get_template', 'Get a template contract and sections.', { id: { type: 'string' } }, ({ id }) => getTemplate(id)],
   ['list_themes', 'List themes that implement the semantic contract.', {}, () => listThemes()],
   ['get_theme', 'Get a theme policy and semantic mappings.', { id: { type: 'string' } }, ({ id }) => getTheme(id)],
+  ['list_motion_profiles', 'List theme-owned semantic motion personalities.', {}, () => listMotionProfiles()],
+  ['get_motion_profile', 'Get a motion profile, its rules, contract, and compatible runtime adapters.', { id: { type: 'string' } }, ({ id }) => getMotionProfile(id)],
   ['list_docs', 'List AI-readable design-system documents.', {}, () => listDocs()],
   ['get_docs', 'Read one design-system document.', { topic: { type: 'string' } }, ({ topic }) => getDoc(topic)],
   ['doctor', 'Validate the Ceramic source of truth.', {}, () => repositoryDoctor()],

package/bin/utopia-ds.mjs

@@ -3,9 +3,10 @@ import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, wri
 import { dirname, join, resolve } from 'node:path'
 import { spawn } from 'node:child_process'
 import {
-  capabilityManifest, envelope, getComponent, getDoc, getTemplate, getTheme,
-  listComponents, listDocs, listTemplates, listThemes, mcpLaunch, repositoryDoctor, search,
+  capabilityManifest, envelope, getComponent, getDoc, getMotionProfile, getTemplate, getTheme,
+  listComponents, listDocs, listMotionProfiles, listTemplates, listThemes, mcpLaunch, repositoryDoctor, search,
 } from '../lib/api.mjs'
+import { createTemplateSubmissionUrl, validateTemplateSubmission } from '../lib/template-submission.mjs'
 
 const args = process.argv.slice(2)
 const command = args.find((arg) => !arg.startsWith('--')) ?? 'help'
@@ -43,8 +44,11 @@ Commands:
   template <id>|--list [--skeleton]       Inspect starter structures
   template <id> --copy <directory> [--theme <id>]
                                               Generate a themed runnable project
+  template validate [directory]               Validate a community submission
+  template submit [directory]                 Open a validated GitHub review request
   theme <id>|--list                       Inspect theme contracts
   theme create <id> [directory]           Scaffold and register a theme
+  motion <id>|--list                      Inspect motion personalities and adapters
   docs <topic>|--list                     Read design-system guidance
   manifest                                Print the self-describing CLI contract
   doctor                                  Validate the design-system source
@@ -96,40 +100,42 @@ function scaffoldTheme() {
   }
 
   const themeValues = {
-    '--background': '#15171C', '--foreground': '#F7F7F5', '--card': '#1D2027', '--card-foreground': '#F7F7F5',
-    '--primary': '#6F5CFF', '--primary-foreground': '#FFFFFF', '--secondary': '#292D37', '--secondary-foreground': '#F7F7F5',
-    '--muted': '#222630', '--muted-foreground': '#A8ADB8', '--border': 'rgba(247,247,245,0.16)', '--input': 'rgba(247,247,245,0.24)',
-    '--ring': '#6F5CFF', '--radius': '8px', '--radius-control': '8px', '--radius-surface': '12px', '--radius-chat-bubble': '18px',
-    '--radius-chat-composer': '24px', '--radius-chat-token': '14px', '--shadow-control': 'none', '--motion-duration-press': '160ms',
-    '--motion-duration-page': '200ms', '--motion-duration-expand': '320ms', '--motion-duration-reveal': '520ms', '--motion-duration-icon': '640ms',
+    '--background': '#F2EFE8', '--foreground': '#292725', '--card': '#FAF8F3', '--card-foreground': '#292725',
+    '--primary': '#4A514B', '--primary-foreground': '#FAF8F3', '--secondary': '#DFDBD1', '--secondary-foreground': '#292725',
+    '--muted': '#E8E4DB', '--muted-foreground': '#66625C', '--border': 'rgba(41,39,37,0.18)', '--input': 'rgba(41,39,37,0.28)',
+    '--ring': '#4A514B', '--radius': '2px', '--radius-control': '2px', '--radius-surface': '4px', '--radius-chat-bubble': '4px',
+    '--radius-chat-composer': '6px', '--radius-chat-token': '4px', '--shadow-control': 'none', '--motion-duration-press': '100ms',
+    '--motion-duration-page': '200ms', '--motion-duration-expand': '220ms', '--motion-duration-reveal': '240ms', '--motion-duration-icon': '320ms',
     '--motion-ease-standard': 'cubic-bezier(0.2, 0, 0, 1)', '--motion-ease-emphasized': 'cubic-bezier(0.16, 1, 0.3, 1)',
-    '--motion-ease-icon': 'cubic-bezier(0.16, 1, 0.3, 1)', '--motion-press-scale': '0.97', '--motion-distance-page': '8px',
-    '--motion-distance-reveal': '8px', '--font-sans': 'Inter', '--font-display': 'Inter', '--font-ui-support': 'Inter',
-    '--font-marketing-display': 'Inter', '--font-arabic': 'IBM Plex Sans Arabic', '--font-arabic-body': 'IBM Plex Sans Arabic',
+    '--motion-ease-icon': 'cubic-bezier(0.16, 1, 0.3, 1)', '--motion-press-scale': '0.985', '--motion-distance-page': '0px',
+    '--motion-distance-reveal': '0px', '--font-sans': 'ui-sans-serif, sans-serif', '--font-display': 'ui-sans-serif, sans-serif', '--font-ui-support': 'ui-sans-serif, sans-serif',
+    '--font-marketing-display': 'ui-sans-serif, sans-serif', '--font-arabic': 'IBM Plex Sans Arabic', '--font-arabic-body': 'IBM Plex Sans Arabic',
     '--font-arabic-display': 'IBM Plex Sans Arabic', '--font-weight-arabic-body': '400', '--font-weight-arabic-display': '700',
     '--font-size-display': 'clamp(2.75rem, 7vw, 5.5rem)', '--font-size-arabic-body': '16px', '--font-size-arabic-body-lg': '18px',
     '--font-size-arabic-display': 'clamp(2.625rem, 6.6vw, 5.25rem)', '--line-height-arabic': '1.75', '--line-height-arabic-body': '1.75',
     '--line-height-arabic-display': '1.14', '--tracking-arabic': '0', '--tracking-arabic-display': '0', '--sidebar-width': '17rem',
     '--control-height-sm': '2rem', '--sidebar-width-collapsed': '4rem', '--sidebar-min-block-size': '30rem', '--sidebar-rail-size': '8px',
-    '--button-height': '40px', '--card-padding': '24px', '--overlay': 'rgba(21,23,28,0.86)', '--modal-surface': '#1D2027', '--popover-surface': '#1D2027',
+    '--button-height': '40px', '--card-padding': '24px', '--overlay': 'rgba(41,39,37,0.72)', '--modal-surface': '#FAF8F3', '--popover-surface': '#FAF8F3',
   }
   const declarations = Object.entries(themeValues).map(([token, value]) => `  ${token}: ${value};`).join('\n')
-  const css = `[data-theme="${id}"] {\n  color-scheme: dark;\n${declarations}\n}\n\n[data-theme="${id}"][data-color-mode="light"] {\n  color-scheme: light;\n  --background: #F7F7F5;\n  --foreground: #15171C;\n  --card: #FFFFFF;\n  --card-foreground: #15171C;\n  --secondary: #ECECF0;\n  --secondary-foreground: #15171C;\n  --muted: #E5E6EA;\n  --muted-foreground: #5F6470;\n  --border: rgb(21 23 28 / 16%);\n  --input: rgb(21 23 28 / 24%);\n  --surface: rgb(21 23 28 / 4.5%);\n  --surface-strong: rgb(21 23 28 / 8%);\n  --surface-elevated: #FFFFFF;\n  --overlay: rgb(247 247 245 / 86%);\n  --modal-surface: #FFFFFF;\n  --popover-surface: #FFFFFF;\n}\n\n[data-theme="${id}"] :where(:lang(ar), [lang|="ar"]) {\n  font-family: var(--font-arabic-body);\n  line-height: var(--line-height-arabic-body);\n  letter-spacing: var(--tracking-arabic);\n  text-transform: none;\n}\n`
+  const css = `[data-theme="${id}"] {\n  color-scheme: light;\n${declarations}\n}\n\n[data-theme="${id}"][data-color-mode="dark"] {\n  color-scheme: dark;\n  --background: #252523;\n  --foreground: #EEEAE1;\n  --card: #2D2D2A;\n  --card-foreground: #EEEAE1;\n  --primary: #B8C0B8;\n  --primary-foreground: #252523;\n  --secondary: #3A3935;\n  --secondary-foreground: #EEEAE1;\n  --muted: #33322F;\n  --muted-foreground: #B9B4AA;\n  --border: rgb(238 234 225 / 18%);\n  --input: rgb(238 234 225 / 28%);\n  --surface: rgb(238 234 225 / 4%);\n  --surface-strong: rgb(238 234 225 / 8%);\n  --surface-elevated: #2D2D2A;\n  --overlay: rgb(37 37 35 / 82%);\n  --modal-surface: #2D2D2A;\n  --popover-surface: #2D2D2A;\n}\n\n[data-theme="${id}"] :where(:lang(ar), [lang|="ar"]) {\n  font-family: var(--font-arabic-body);\n  line-height: var(--line-height-arabic-body);\n  letter-spacing: var(--tracking-arabic);\n  text-transform: none;\n}\n`
   const policy = {
     '$schema': 'https://utopia-studio.co/design-system/theme.schema.json', id, name, type: 'theme-policy', locked: false,
-    summary: `${name} brand theme mapped to the Ceramic semantic contract.`,
+    motionProfile: 'precise',
+    summary: `${name} neutral theme scaffold mapped to the Ceramic semantic contract; replace placeholder primitives before release.`,
     sourceFiles: [`packages/design-system/src/themes/${id}.css`, `packages/design-system/src/manifests/theme-${id}.json`],
-    brandPrimitives: { colors: { background: themeValues['--background'], foreground: themeValues['--foreground'], accent: themeValues['--primary'] }, typography: { latin: 'Inter', arabic: 'IBM Plex Sans Arabic' }, geometry: { controlRadius: themeValues['--radius-control'], surfaceRadius: themeValues['--radius-surface'] } },
+    brandPrimitives: { colors: { background: themeValues['--background'], foreground: themeValues['--foreground'], accent: themeValues['--primary'] }, typography: { latin: 'Unassigned', arabic: 'IBM Plex Sans Arabic' }, geometry: { controlRadius: themeValues['--radius-control'], surfaceRadius: themeValues['--radius-surface'] } },
     semanticMappings: Object.fromEntries(Object.entries(themeValues).map(([token, value]) => [token, value])),
-    visualPolicy: { tone: ['clear', 'intentional', 'product-focused'], allow: ['semantic color roles', 'logical layout properties', 'theme-owned brand expression'], avoid: ['Utopia brand primitives', 'component-specific color literals', 'left/right-only layout APIs'] },
+    visualPolicy: { tone: ['neutral', 'restrained', 'unfinished-by-design'], allow: ['semantic color roles', 'logical layout properties', 'theme-owned brand expression'], avoid: ['shipping placeholder primitives', 'generic SaaS gradients', 'default purple accents', 'component-specific color literals', 'left/right-only layout APIs'] },
     arabicFriendly: { direction: 'Support dir="rtl" with logical CSS properties.', typography: 'Use the declared Arabic family without Latin tracking or casing.' },
     translations: { ar: { summary: `ثيم ${name} مبني على عقد Ceramic الدلالي.`, iconPolicy: { description: 'استخدم أيقونات واضحة ومحايدة الاتجاه، واعكس الأيقونات الاتجاهية في RTL.', allow: ['أيقونات Lucide', 'أيقونات محايدة الاتجاه', 'انعكاس الأيقونات الاتجاهية في RTL'] } } },
   }
   const entry = {
     id, name, shortName: name, locked: false, role: 'brand theme', description: policy.summary,
+    motionProfile: 'precise',
     bestFor: [`${name} product interfaces`], principles: policy.visualPolicy.tone,
     translations: { ar: { name, role: 'ثيم علامة', description: `ثيم ${name} مبني على عقد Ceramic الدلالي.`, bestFor: [`واجهات ${name}`], principles: ['وضوح', 'اتساق', 'دعم العربية'] } },
-    policyManifest: `packages/design-system/src/manifests/theme-${id}.json`, css: `packages/design-system/src/themes/${id}.css`, iconSystem: 'lucide', values: themeValues,
+    policyManifest: `packages/design-system/src/manifests/theme-${id}.json`, css: `packages/design-system/src/themes/${id}.css`, iconSystem: 'unassigned', values: themeValues,
   }
 
   write(cssPath, css)
@@ -157,15 +163,16 @@ function init() {
 2. Run \`npm run ceramic -- search <intent> --json\`, then inspect the selected component or template.
 3. Prefer \`@utopia-studio-design/design-system\` exports over raw shadcn/ui source.
 4. Components consume semantic tokens only. The active theme is \`${theme}\`.
-5. Read \`npm run ceramic -- docs arabic-friendly --dense\` before Arabic or RTL work.
-6. Never invent component props, import paths, tokens, Arabic product copy, or left/right-only APIs.
-7. Validate with \`npm run ceramic:doctor\` before handoff.
+5. Request semantic motion only; inspect \`npm run ceramic -- motion ${getTheme(theme)?.motionProfile} --json\` before choosing an application runtime adapter.
+6. Read \`npm run ceramic -- docs arabic-friendly --dense\` before Arabic or RTL work.
+7. Never invent component props, import paths, tokens, Arabic product copy, or left/right-only APIs.
+8. Validate with \`npm run ceramic:doctor\` before handoff.
 `
   write(join(target, 'AGENTS.md'), rules)
   write(join(target, 'CLAUDE.md'), rules)
   write(join(target, '.cursor/rules/ceramic-design-system.mdc'), `---\ndescription: Ceramic Design System rules\nalwaysApply: true\n---\n\n${rules}`)
   write(join(target, '.github/copilot-instructions.md'), rules)
-  write(join(target, '.ceramic/config.json'), `${JSON.stringify({ apiVersion: 1, theme, arabicFriendly: true, source: '@utopia-studio-design/design-system' }, null, 2)}\n`)
+  write(join(target, '.ceramic/config.json'), `${JSON.stringify({ apiVersion: 1, theme, motionProfile: getTheme(theme)?.motionProfile, arabicFriendly: true, source: '@utopia-studio-design/design-system' }, null, 2)}\n`)
   write(join(target, '.mcp.json'), `${JSON.stringify({ mcpServers: { ceramic: mcpLaunch } }, null, 2)}\n`)
   output('init-result', { ok: true, target, theme, files: ['AGENTS.md', 'CLAUDE.md', '.cursor/rules/ceramic-design-system.mdc', '.github/copilot-instructions.md', '.ceramic/config.json', '.mcp.json'] },
     (data) => `Ceramic initialized in ${data.target}.\nCreated ${data.files.join(', ')}.`)
@@ -226,13 +233,40 @@ function copyTemplateProject(entry) {
     },
     devDependencies: { '@utopia-studio-design/design-system-cli': cliDependency, '@vitejs/plugin-react': '^4.3.4', typescript: '^5.7.2', vite: '^6.0.7' },
   }, null, 2)}\n`)
-  write(join(target, '.ceramic/config.json'), `${JSON.stringify({ apiVersion: 1, theme, arabicFriendly: true, source: '@utopia-studio-design/design-system' }, null, 2)}\n`)
+  write(join(target, '.ceramic/config.json'), `${JSON.stringify({ apiVersion: 1, theme, motionProfile: getTheme(theme)?.motionProfile, motionAdapter: 'framer-motion', arabicFriendly: true, source: '@utopia-studio-design/design-system' }, null, 2)}\n`)
   write(join(target, 'vite.config.ts'), `import { resolve } from 'node:path'\nimport react from '@vitejs/plugin-react'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [react()],\n  build: {\n    rollupOptions: {\n      input: {\n        home: resolve('index.html'),\n        product: resolve('product/index.html'),\n        agents: resolve('agents/index.html'),\n        integrations: resolve('integrations/index.html'),\n        integrationDetail: resolve('integrations/slack/index.html'),\n        customers: resolve('customers/index.html'),\n        customerStory: resolve('customers/aster-labs/index.html'),\n        pricing: resolve('pricing/index.html'),\n        changelog: resolve('changelog/index.html'),\n        contactSales: resolve('contact-sales/index.html'),\n      },\n    },\n  },\n})\n`)
   const existingReadme = readFileSync(join(target, 'README.md'), 'utf8')
   write(join(target, 'README.md'), `# Generated Ceramic SaaS website\n\nActive theme: \`${theme}\`\n\n\`\`\`sh\nnpm install\nnpm run dev\n\`\`\`\n\nOpen \`http://localhost:5173/?seed=1974341818\`. All ten page entries share the same seed, theme, and locale state.\n\n${existingReadme}`)
   output('template-copy-result', { ok: true, id: entry.id, target, theme, pages: entry.pages ?? [] }, (data) => `Generated ${data.id} with theme ${data.theme} in ${data.target}.\nNext: cd ${data.target} && npm install && npm run dev`)
 }
 
+function validateCommunityTemplate({ submit = false } = {}) {
+  const target = resolve(values[1] ?? process.cwd())
+  const result = validateTemplateSubmission(target)
+  if (!result.ok) {
+    if (json) return fail('Community template validation failed.', 'ERR_TEMPLATE_SUBMISSION', result.errors)
+    console.error(`Community template validation failed with ${result.errors.length} error(s):`)
+    for (const item of result.errors) console.error(`- ${item.code}: ${item.message}${item.path ? ` (${item.path})` : ''}`)
+    for (const item of result.warnings) console.error(`- warning ${item.code}: ${item.message}`)
+    process.exitCode = 1
+    return
+  }
+  const submissionUrl = submit ? createTemplateSubmissionUrl(result) : null
+  output(submit ? 'template-submit-result' : 'template-validation-result', {
+    ok: true,
+    id: result.manifest.id,
+    version: result.manifest.version,
+    repository: result.manifest.repository,
+    files: result.files.length,
+    warnings: result.warnings,
+    submissionUrl,
+  }, (data) => [
+    `Community template ${data.id}@${data.version} passed validation (${data.files} files).`,
+    ...data.warnings.map((item) => `Warning ${item.code}: ${item.message}`),
+    ...(data.submissionUrl ? [`Submit for review: ${data.submissionUrl}`] : []),
+  ].join('\n'))
+}
+
 if (command === 'help' || args.includes('--help')) help()
 else if (command === 'init') init()
 else if (command === 'manifest') output('manifest', capabilityManifest())
@@ -246,7 +280,9 @@ else if (command === 'search') {
   else { const item = getComponent(name); item ? output('component', item, formatComponent) : fail(`Unknown component "${name}".`, 'ERR_COMPONENT', search(name).slice(0, 5).map((result) => result.id)) }
 } else if (command === 'template') {
   const name = values[0]
-  if (!name || args.includes('--list')) output('template-list', listTemplates(), (rows) => rows.map((item) => `${item.id}|${item.category}|${item.title}|${item.purpose}`).join('\n'))
+  if (name === 'validate') validateCommunityTemplate()
+  else if (name === 'submit') validateCommunityTemplate({ submit: true })
+  else if (!name || args.includes('--list')) output('template-list', listTemplates(), (rows) => rows.map((item) => `${item.id}|${item.category}|${item.title}|${item.purpose}`).join('\n'))
   else {
     const item = getTemplate(name)
     if (!item) fail(`Unknown template "${name}".`, 'ERR_TEMPLATE')
@@ -258,11 +294,15 @@ else if (command === 'search') {
   if (name === 'create') scaffoldTheme()
   else if (!name || args.includes('--list')) output('theme-list', listThemes(), (rows) => rows.map((item) => `${item.id}|${item.name}|${item.role}|${item.policyManifest}`).join('\n'))
   else { const item = getTheme(name); item ? output('theme', item) : fail(`Unknown theme "${name}".`, 'ERR_THEME') }
+} else if (command === 'motion') {
+  const name = values[0]
+  if (!name || args.includes('--list')) output('motion-profile-list', listMotionProfiles(), (rows) => rows.map((item) => `${item.id}|${item.themes.join(',')}|${item.label}|${item.description}`).join('\n'))
+  else { const item = getMotionProfile(name); item ? output('motion-profile', item) : fail(`Unknown motion profile "${name}".`, 'ERR_MOTION_PROFILE', listMotionProfiles().map((item) => item.id)) }
 } else if (command === 'docs') {
   const topic = values[0]
   if (!topic || args.includes('--list')) output('docs-list', listDocs(), (rows) => rows.join('\n'))
   else { const item = getDoc(topic); item ? output('docs', item, (doc) => dense ? doc.content.replace(/\n{2,}/g, '\n').trim() : doc.content) : fail(`Unknown docs topic "${topic}".`, 'ERR_DOCS', listDocs()) }
 } else if (command === 'doctor') {
-  const result = repositoryDoctor(); output('doctor-result', result, (data) => data.ok ? `Ceramic doctor passed. ${data.checks.components} components, ${data.checks.templates} templates, ${data.checks.themes} themes, MCP ready.` : `Ceramic doctor failed: ${data.missing.join(', ')}`); if (!result.ok) process.exitCode = 1
+  const result = repositoryDoctor(); output('doctor-result', result, (data) => data.ok ? `Ceramic doctor passed. ${data.checks.components} components, ${data.checks.templates} templates, ${data.checks.themes} themes, ${data.checks.motionProfiles} motion profiles, MCP ready.` : `Ceramic doctor failed: ${data.missing.join(', ')}`); if (!result.ok) process.exitCode = 1
 } else if (command === 'mcp') runMcp()
 else fail(`Unknown command "${command}".`, 'ERR_COMMAND', capabilityManifest().commands.map((item) => item.name))

package/data/docs/community-template-contributions.md

@@ -0,0 +1,85 @@
+# Share a community template
+
+Ceramic community templates stay in the creator's public GitHub repository. Ceramic reviews a pinned version before listing it in the catalog; submitting a repository does not execute its code on the documentation website.
+
+## What the designer prepares
+
+1. A public GitHub repository containing the runnable template source.
+2. A working preview URL when possible.
+3. A license covering the source and included assets.
+4. A `ceramic.template.json` file at the repository root.
+5. Responsive, dark-mode, keyboard, and RTL coverage.
+
+Do not include credentials, `.env` files, private keys, production customer data, unlicensed media, or install lifecycle scripts.
+
+## Manifest
+
+Create `ceramic.template.json` in the repository root:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/The-Utopia-Studio/Ceramic-Design-System/main/packages/design-system/src/manifests/community-template.schema.json",
+  "schemaVersion": 1,
+  "id": "operations-dashboard",
+  "name": "Operations Dashboard",
+  "version": "1.0.0",
+  "summary": "A responsive operations dashboard for queues, incidents, and team handoffs.",
+  "category": "dashboard",
+  "author": {
+    "name": "Example Studio",
+    "url": "https://example.com"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/example/operations-dashboard",
+  "preview": "https://operations-dashboard.example.com",
+  "designSystem": {
+    "package": "@utopia-studio-design/design-system",
+    "version": "^0.4.4"
+  },
+  "entry": "src/main.tsx",
+  "files": ["src", "index.html", "package.json"],
+  "themes": ["utopia-default", "dextrum"],
+  "features": {
+    "responsive": true,
+    "darkMode": true,
+    "rtl": true
+  }
+}
+```
+
+## Validate
+
+Install the public CLI and run validation from the template repository root:
+
+```sh
+npm install -D @utopia-studio-design/design-system-cli
+npx utopia-ds template validate .
+```
+
+Warnings identify raw color values or physical left/right CSS. Explain intentional theme-owned media values in the review request. Validation errors must be fixed before submission.
+
+## Submit
+
+Either use the form in the Ceramic Templates page or run:
+
+```sh
+npx utopia-ds template submit .
+```
+
+The command returns a GitHub review URL populated from the manifest. Open it, verify the declaration, and submit the issue. Pin a release or commit for review instead of asking maintainers to review a moving branch.
+
+## Review and publication
+
+Ceramic maintainers verify:
+
+- public component APIs and package imports;
+- semantic-token usage and theme compatibility;
+- responsive, dark-mode, keyboard, reduced-motion, and RTL behavior;
+- licensing, demo-data labeling, and asset ownership;
+- the absence of secrets and install lifecycle scripts.
+
+Approved submissions receive a catalog record under **Community**. The creator continues to own the source and releases. A new published version requires a new review; an existing version is never overwritten.
+
+## Instructions to send to a designer
+
+> Put the runnable template in a public GitHub repository and deploy a preview if possible. Add `ceramic.template.json` at the repository root using the example above. Confirm that the template uses `@utopia-studio-design/design-system`, semantic tokens, logical CSS properties, responsive layouts, dark mode, keyboard interaction, and RTL. Remove `.env` files, credentials, private keys, install scripts, private customer data, and unlicensed assets. Run `npx utopia-ds template validate .`, fix every error, then run `npx utopia-ds template submit .` or use the Submit a template form on the Ceramic Templates page. Send the generated GitHub review request with a pinned release or commit.

package/data/docs/foundations.md

@@ -69,26 +69,46 @@ Arabic display sizing should follow the Latin display scale at about 95%, rather
 
 ## Motion Contract
 
-- Ceramic defines five semantic patterns: `press`, `page`, `expand`, `reveal`, and `icon`.
+- Ceramic separates motion policy from motion execution: the theme selects a personality, the application selects an adapter, and components request semantic motion.
+- Component timing continues to use five semantic patterns: `press`, `page`, `expand`, `reveal`, and `icon`.
+- Runtime recipes use four engine-neutral intents: `feedback`, `page`, `surface`, and `layout`.
 - Components consume `--motion-duration-*` and `--motion-ease-*` roles rather than hardcoded milliseconds or easing curves.
-- `MotionProvider` sets the subtree default. Motion-aware components expose `motion?: boolean` for a local override.
+- `MotionProvider` sets the theme profile and runtime adapter for a subtree. Motion-aware components expose `motion?: boolean` for a local override.
 - `motion={false}` and `prefers-reduced-motion: reduce` disable decorative movement while preserving state changes and accessibility.
 - Directional motion follows logical inline start/end and mirrors in RTL when direction carries meaning.
 - Icon motion follows the action: a bell swings from its top, download moves downward, and copy snaps once. Do not apply a generic bounce.
+- `utopia-default` uses the `ceremonial` profile, `dextrum` uses `swift`, and `barrier-intelligence` uses `precise`.
+- WAAPI is built in. Motion for React, Anime.js, and GSAP are optional peer adapters, so unused engines do not need to ship with an application.
 
 ```tsx
-import { MotionProvider } from '@utopia-studio-design/design-system/Motion'
+import { getMotionThemeProfile, MotionProvider } from '@utopia-studio-design/design-system/Motion'
+import { animeMotionAdapter } from '@utopia-studio-design/design-system/MotionAnime'
 import { Button } from '@utopia-studio-design/design-system/Button'
 
 export function App() {
   return (
-    <MotionProvider motion>
+    <MotionProvider
+      adapter={animeMotionAdapter}
+      themeProfile={getMotionThemeProfile(activeTheme.motionProfile)}
+    >
       <Button motion={false}>Static local action</Button>
     </MotionProvider>
   )
 }
 ```
 
+Install only the engine selected by the application:
+
+```bash
+npm install animejs
+# or
+npm install gsap
+# or
+npm install framer-motion
+```
+
+The engine-neutral registry is published as `manifests/motion-profiles.json`. It is the runtime, CLI, and MCP source of truth for timing, easing, semantic recipes, orchestration, theme mappings, and reduced-motion behavior. Resolve custom themes through their declared `motionProfile`; reduced motion applies each semantic final state immediately and clears transform and filter effects. Optional adapters should be loaded with `import()` when they are selected. Motion AI Kit and GSAP Skills may help agents author or audit engine-specific code, but they are authoring tools rather than runtime adapters.
+
 ## Elevation Contract
 
 - Elevation is semantic hierarchy, not a mandatory shadow style.

package/data/manifests/catalog.json

@@ -194,7 +194,8 @@
             "Skeleton",
             "Spinner",
             "Table",
-            "Typography"
+            "Typography",
+            "Utopia Wordmark Loader"
           ]
         }
       ]
@@ -307,7 +308,8 @@
       "Toggle Button",
       "Toggle Button Group",
       "Tooltip",
-      "Typography"
+      "Typography",
+      "Utopia Wordmark Loader"
     ],
     "utopiaWrapped": [
       "Accordion",
@@ -384,7 +386,8 @@
       "Toggle Button",
       "Toggle Button Group",
       "Tooltip",
-      "Typography"
+      "Typography",
+      "Utopia Wordmark Loader"
     ],
     "legacy": [
       "Toast"

package/data/manifests/community-template.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://utopia-studio.co/design-system/community-template.schema.json",
+  "title": "Ceramic Community Template",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "name", "version", "summary", "category", "author", "license", "repository", "designSystem", "entry", "files", "themes", "features"],
+  "properties": {
+    "$schema": { "type": "string", "format": "uri" },
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "name": { "type": "string", "minLength": 2 },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?$" },
+    "summary": { "type": "string", "minLength": 20 },
+    "category": { "type": "string", "enum": ["application", "dashboard", "website", "workflow", "commerce", "content", "other"] },
+    "author": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 2 },
+        "url": { "type": "string", "format": "uri" }
+      }
+    },
+    "license": { "type": "string", "minLength": 2 },
+    "repository": { "type": "string", "pattern": "^https://github\\.com/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/?$" },
+    "preview": { "type": "string", "format": "uri" },
+    "designSystem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package", "version"],
+      "properties": {
+        "package": { "const": "@utopia-studio-design/design-system" },
+        "version": { "type": "string", "minLength": 1 }
+      }
+    },
+    "entry": { "type": "string", "minLength": 1 },
+    "files": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "themes": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "features": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["responsive", "darkMode", "rtl"],
+      "properties": {
+        "responsive": { "const": true },
+        "darkMode": { "const": true },
+        "rtl": { "const": true }
+      }
+    }
+  }
+}

package/data/manifests/components.json

@@ -699,7 +699,10 @@
       ],
       "ai": {
         "props": {
-          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false.",
+          "contentAlign": "Use 'start' for leading-aligned labels, 'center' for the default action layout, or 'between' to pin endContent to the logical inline end.",
+          "startContent": "Optional leading icon or content slot with package-owned alignment.",
+          "endContent": "Optional trailing content slot. With contentAlign='between', it remains pinned while the label truncates."
         }
       }
     },
@@ -2980,8 +2983,8 @@
       "name": "Native Select",
       "category": "Forms",
       "status": "available",
-      "packageImport": "import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
-      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "packageImport": "import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
       "shadcnFoundation": [
         "native-select",
         "shadcn/ui registry",
@@ -3008,10 +3011,12 @@
       "avoidWhen": [
         "Searchable or async option sets",
         "Complex custom option rendering",
+        "The opened option menu must match dark, light, or popover semantic tokens; use Select, SelectTrigger, SelectContent, and SelectItem",
         "Product localization rules inside reusable component logic"
       ],
       "neverInvent": [
         "Product-owned option values or selection rules",
+        "A promise that the opened native option menu can be fully themed; the OS or browser owns that surface",
         "Production Arabic option labels not supplied by localization",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic"
@@ -3482,10 +3487,12 @@
         "--background",
         "--foreground",
         "--muted-foreground",
+        "--icon-size-sm",
         "--button-height-sm"
       ],
       "useWhen": [
         "Compact option selection",
+        "Dark, light, or branded surfaces where the opened menu must follow popover semantic tokens",
         "Longer option sets than Radio Group",
         "AI-generated forms that need explicit trigger, value, content, and item parts",
         "Grouped option lists with labels",
@@ -3617,7 +3624,7 @@
       "name": "Side Nav",
       "category": "Navigation",
       "status": "available",
-      "packageImport": "import { PanelIcon, SideNav, SideNavCollapseButton, SideNavContent, SideNavHeading, SideNavItem, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection } from '@utopia-studio-design/design-system/Navigation';",
+      "packageImport": "import { PanelIcon, SideNav, SideNavAccount, SideNavAuxiliary, SideNavCollapseButton, SideNavCommand, SideNavContent, SideNavFooter, SideNavHeader, SideNavHeading, SideNavItem, SideNavMain, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection, SideNavStatus, SideNavWorkspaceSwitcher } from '@utopia-studio-design/design-system/Navigation';",
       "sourcePath": "packages/design-system/src/components/Navigation.tsx",
       "shadcnFoundation": [
         "sidebar",
@@ -3641,6 +3648,8 @@
       "useWhen": [
         "Persistent docs or app navigation",
         "Grouped navigation links with current page state",
+        "An application shell needs fixed header and footer regions with only the main navigation scrolling",
+        "Search, AI commands, status, and account controls must adapt to expanded and collapsed states without app CSS overrides",
         "A navigation surface needs package-owned content, search, section, nested group, item, heading, account, and collapse composition parts",
         "A navigation surface should receive heading and search as SideNav props instead of hardcoding local wrappers",
         "AI-generated app shells that need explicit section, heading, item, nested item, search, and collapse button parts"
@@ -3654,7 +3663,7 @@
         "Raw shadcn theme colors",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic",
-        "Local CSS-only search, nested group, or content wrappers when SideNavSearch, SideNavNestedGroup, SideNavNestedItems, or SideNavContent are available"
+        "Local CSS-only search, command, account, footer, or content wrappers when the corresponding SideNav composition parts are available"
       ],
       "ai": {
         "props": {
@@ -3662,7 +3671,15 @@
           "density": "Use default for app navigation; use compact for docs/library sidebars with dense catalog lists.",
           "heading": "Optional SideNavHeading node rendered before search and navigation content.",
           "search": "Optional SideNavSearch node rendered after heading and before navigation content.",
-          "SideNavContent": "Scrollable or flexible body region for repeated SideNavSection groups.",
+          "SideNavContent": "Compatibility body region. Set layout='stack' for a flex column that supports an auto-positioned footer, or layout='grid' for the legacy grid flow.",
+          "SideNavHeader": "Fixed header region for brand, workspace, and collapse controls.",
+          "SideNavMain": "The only independently scrolling navigation region. It defaults to layout='stack' and fills remaining height.",
+          "SideNavFooter": "Bottom-pinned, bounded footer region for status and account controls.",
+          "SideNavCommand": "Full-width icon, label, and shortcut action. It derives collapsed state, accessible name, and tooltip title from SideNav context.",
+          "SideNavAccount": "Stable avatar, single-line identity, and action layout. Use asChild or trigger to compose an app-owned popover/auth trigger.",
+          "SideNavStatus": "Status indicator with label and optional description. Collapsed navigation retains the label for assistive technology and exposes a tooltip title.",
+          "SideNavWorkspaceSwitcher": "Fixed region for an app-owned organization or workspace switcher.",
+          "SideNavAuxiliary": "Fixed auxiliary action region outside the independently scrolling main navigation.",
           "SideNavSearch": "Package-owned search field for filtering navigation lists without local input styling.",
           "SideNavNestedGroup": "Groups a parent SideNavItem and its nested child collection.",
           "SideNavNestedItems": "Indented child item collection using logical inline-start spacing and border.",
@@ -3823,6 +3840,7 @@
       ],
       "ai": {
         "props": {
+          "asChild": "Use with a framework-native link such as Next.js Link so the link remains the single interactive element while SideNavItem supplies styling and state.",
           "icon": "Optional leading visual slot. Omit for text-only rows; do not add placeholder marks.",
           "depth": "Use 0 for root rows, 1 for items inside a top-level section, 2 for nested section children, and 3 only for rare deep navigation.",
           "badge": "Optional trailing count or status pill aligned to the inline end.",
@@ -4089,6 +4107,54 @@
         "arabicFriendly": "Loading labels come from product localization. The spinner is direction-neutral and must not be mirrored."
       }
     },
+    {
+      "name": "Utopia Wordmark Loader",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { UtopiaWordmarkLoader } from '@utopia-studio-design/design-system/UtopiaWordmarkLoader';",
+      "sourcePath": "packages/design-system/src/components/UtopiaWordmarkLoader.tsx",
+      "shadcnFoundation": [
+        "spinner status semantics",
+        "full-screen loading state"
+      ],
+      "fallbackToShadcn": "spinner",
+      "requiredTokens": [
+        "--brand-loader-background",
+        "--brand-loader-accent",
+        "--brand-loader-foreground",
+        "--brand-loader-size",
+        "--brand-loader-duration-enter",
+        "--brand-loader-duration-cycle",
+        "--brand-loader-duration-stagger",
+        "--brand-loader-duration-exit",
+        "--brand-loader-distance-exit"
+      ],
+      "useWhen": [
+        "A Utopia product needs a branded full-page or contained loading transition",
+        "Workspace or route loading should end as soon as the consumer loading state resolves",
+        "The Utopia Default theme is active and the stacked studio wordmark is appropriate"
+      ],
+      "avoidWhen": [
+        "Short inline pending states; use Spinner",
+        "Layout-preserving content loading; use Skeleton",
+        "A non-Utopia product theme needs its own brand mark"
+      ],
+      "neverInvent": [
+        "A timer that delays navigation after the real loading state resolves",
+        "Left/right-only layout rules",
+        "Utopia brand primitives outside this explicitly branded component contract"
+      ],
+      "ai": {
+        "props": {
+          "label": "Required localized loading text announced through role=status.",
+          "phase": "Use intro while loading and exit after the consumer loading state resolves.",
+          "fullscreen": "Defaults to true. Set false for a contained loading region.",
+          "size": "sm is the production default; md and lg are available for larger brand moments.",
+          "onExitComplete": "Called after the exit motion so the consumer can unmount the overlay."
+        },
+        "arabicFriendly": "The mark is direction-neutral and must not mirror. The localized status label is visually hidden and remains consumer-owned."
+      }
+    },
     {
       "name": "Switch",
       "category": "Forms",