@utopia-studio-design/design-system-cli 0.2.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, 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,16 +163,17 @@ 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, '.mcp.json'), `${JSON.stringify({ mcpServers: { ceramic: { command: 'npx', args: ['-y', '@utopia-studio-design/design-system-cli', 'mcp'] } } }, 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(', ')}.`)
 }
@@ -207,10 +214,10 @@ function copyTemplateProject(entry) {
   const workspaceCli = resolve(process.cwd(), 'packages/design-system-cli')
   const designSystemDependency = existsSync(join(workspacePackage, 'package.json'))
     ? `file:${workspacePackage}`
-    : '^0.2.0'
+    : '^0.3.0'
   const cliDependency = existsSync(join(workspaceCli, 'package.json'))
     ? `file:${workspaceCli}`
-    : '^0.2.0'
+    : '^0.3.0'
   write(join(target, 'package.json'), `${JSON.stringify({
     name: packageName,
     private: true,
@@ -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/ai-platform-plan.md

@@ -37,7 +37,7 @@ Every authoring command must support `--json`, `--dry-run`, deterministic output
 The generated `.mcp.json` works for clients that support project-local MCP configuration. Codex CLI can register the same stdio server explicitly:
 
 ```sh
-codex mcp add ceramic -- npx -y @utopia-studio-design/design-system-cli mcp
+codex mcp add ceramic -- npx -y --package @utopia-studio-design/design-system-cli utopia-ds mcp
 ```
 
 The server exposes read-only design-system discovery. File-writing operations remain CLI commands with dry-run and explicit user control.

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/docs/quick-start-ai.md

@@ -88,7 +88,7 @@ The MCP server exposes the same API as the CLI. A generated `.mcp.json` uses:
   "mcpServers": {
     "ceramic": {
       "command": "npx",
-      "args": ["-y", "@utopia-studio-design/design-system-cli", "mcp"]
+      "args": ["-y", "--package", "@utopia-studio-design/design-system-cli", "utopia-ds", "mcp"]
     }
   }
 }

package/data/manifests/catalog.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://utopia-studio.co/design-system/catalog.schema.json",
   "name": "Utopia Design System Catalog",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "purpose": "Standalone source of truth for the Utopia Design System home, docs, component catalog, templates, themes, and AI agent workflow.",
   "topLevelAreas": [
     {
@@ -13,8 +13,9 @@
           "id": "guide",
           "label": "Guide",
           "items": [
-            "Getting Started",
-            "Quick Start with AI",
+          "Getting Started",
+          "MCP Playground",
+          "Quick Start with AI",
             "Working with AI",
             "Principles",
             "Theme System",
@@ -193,7 +194,8 @@
             "Skeleton",
             "Spinner",
             "Table",
-            "Typography"
+            "Typography",
+            "Utopia Wordmark Loader"
           ]
         }
       ]
@@ -306,7 +308,8 @@
       "Toggle Button",
       "Toggle Button Group",
       "Tooltip",
-      "Typography"
+      "Typography",
+      "Utopia Wordmark Loader"
     ],
     "utopiaWrapped": [
       "Accordion",
@@ -383,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 }
+      }
+    }
+  }
+}