npm - @utopia-studio-design/design-system-cli - Versions diffs - 0.4.0 → 0.5.0 - Mend

@utopia-studio-design/design-system-cli 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (127) hide show

package/data/templates/composition-registry-lab/index.html ADDED Viewed

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en" dir="ltr" data-theme="utopia-default" data-color-mode="light">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="Ceramic Composition Registry and Layout JSON review lab." />
+    <title>Ceramic Composition Registry Lab</title>
+  </head>
+  <body>
+    <a class="skip-link" href="#main-content">Skip to composition registry</a>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

package/data/templates/composition-registry-lab/main.tsx ADDED Viewed

@@ -0,0 +1,217 @@
+import { StrictMode, useEffect, useMemo, useState, type CSSProperties } from 'react'
+import { createRoot } from 'react-dom/client'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import {
+  listCeramicBlockDefinitions,
+  validateCeramicLayout,
+  type CeramicLayoutDocument,
+} from '@utopia-studio-design/design-system/Composition'
+import '@utopia-studio-design/design-system/core.css'
+import '@utopia-studio-design/design-system/themes/utopia-default.css'
+import sampleLayout from './sample-layout.json'
+import './styles.css'
+const activeTheme = 'utopia-default'
+const layout = sampleLayout as CeramicLayoutDocument
+type LayoutBlockStyle = CSSProperties & {
+  '--layout-column': number
+  '--layout-order': number
+  '--layout-span': number
+}
+function App() {
+  const [direction, setDirection] = useState<'ltr' | 'rtl'>('ltr')
+  const [dark, setDark] = useState(false)
+  const [showPlanned, setShowPlanned] = useState(true)
+  const definitions = listCeramicBlockDefinitions()
+  const visibleDefinitions = definitions.filter(
+    (definition) => showPlanned || definition.availability === 'available',
+  )
+  const definitionsById = useMemo(
+    () => new Map(definitions.map((definition) => [definition.id, definition])),
+    [definitions],
+  )
+  const validation = validateCeramicLayout(layout)
+  const warnings = validation.issues.filter((issue) => issue.severity === 'warning')
+  useEffect(() => {
+    document.documentElement.dir = direction
+    document.documentElement.dataset.previewDirection = direction
+    return () => {
+      document.documentElement.dir = 'ltr'
+      delete document.documentElement.dataset.previewDirection
+    }
+  }, [direction])
+  return (
+    <main
+      className="registry-lab"
+      data-color-mode={dark ? 'dark' : 'light'}
+      data-preview-direction={direction}
+      data-theme={activeTheme}
+      dir={direction}
+      id="main-content"
+    >
+      <header className="registry-header">
+        <div>
+          <p>Step 2 · Composition contract</p>
+          <h1>Review who controls the dashboard</h1>
+          <span>
+            Ceramic defines the blocks and layout rules. Agents and optional visual editors arrange only what the registry allows.
+          </span>
+        </div>
+        <div aria-label="Preview controls" className="registry-controls">
+          <div className="registry-control-actions">
+            <Button asChild>
+              <a href="/templates/dashboard-composer/">Open live composer</a>
+            </Button>
+            <Button asChild variant="outline">
+              <a href="/templates/dashboard-composer/visual-editor/">Open Puck editor</a>
+            </Button>
+            <Button
+              aria-pressed={direction === 'rtl'}
+              variant="outline"
+              onClick={() => setDirection((value) => value === 'ltr' ? 'rtl' : 'ltr')}
+            >
+              {direction === 'ltr' ? 'Switch to RTL' : 'Switch to LTR'}
+            </Button>
+            <Button
+              aria-pressed={dark}
+              variant="outline"
+              onClick={() => setDark((value) => !value)}
+            >
+              {dark ? 'Switch to light' : 'Switch to dark'}
+            </Button>
+          </div>
+          <output aria-live="polite" className="registry-preview-status">
+            Preview: {direction === 'ltr' ? 'LTR · starts on the left' : 'RTL · starts on the right'} · {dark ? 'dark mode' : 'light mode'}
+          </output>
+          <div
+            aria-label={`${direction.toUpperCase()} direction preview`}
+            className="registry-direction-preview"
+            dir={direction}
+          >
+            <span>Start edge</span>
+            <strong aria-hidden="true">{direction === 'ltr' ? '→' : '←'}</strong>
+            <span>End edge</span>
+          </div>
+        </div>
+      </header>
+      <section aria-labelledby="ownership-title" className="ownership-section">
+        <div>
+          <p className="eyebrow">Source of truth</p>
+          <h2 id="ownership-title">Puck is an editor, not the architecture</h2>
+          <p>
+            The registry already lets an agent and Studio read and write the same JSON. The optional Puck adapter now provides human drag-and-drop over that contract.
+          </p>
+        </div>
+        <ol className="ownership-flow">
+          <li><strong>Components</strong><span>Semantic UI</span></li>
+          <li><strong>Blocks</strong><span>Dashboard jobs</span></li>
+          <li data-current="true"><strong>Registry</strong><span>Allowed composition</span></li>
+          <li><strong>Layout JSON</strong><span>Shared document</span></li>
+          <li><strong>Agent / Studio / Puck</strong><span>Editors and runtime</span></li>
+        </ol>
+      </section>
+      <section aria-labelledby="guardrails-title" className="guardrails-section">
+        <div>
+          <p className="eyebrow">Ceramic concept</p>
+          <h2 id="guardrails-title">Semantic choices stay in; arbitrary styling stays out</h2>
+        </div>
+        <div className="guardrail-grid">
+          <article>
+            <Badge variant="secondary">Allowed</Badge>
+            <h3>Meaning and behavior</h3>
+            <p>Density, view, comparison, semantic surface, registered span, state, direction, and permissions.</p>
+          </article>
+          <article>
+            <Badge variant="outline">Rejected</Badge>
+            <h3>Design-system bypasses</h3>
+            <p>Raw color, shadow, radius, spacing, className, style, sx, CSS, and token overrides.</p>
+          </article>
+        </div>
+      </section>
+      <section aria-labelledby="palette-title" className="palette-section">
+        <header>
+          <div>
+            <p className="eyebrow">Registry palette</p>
+            <h2 id="palette-title">{visibleDefinitions.length} registered block definitions</h2>
+            <p>Only definitions with an available renderer can be placed in production today.</p>
+          </div>
+          <Button variant="outline" onClick={() => setShowPlanned((value) => !value)}>
+            {showPlanned ? 'Show renderable only' : 'Show planned blocks'}
+          </Button>
+        </header>
+        <div className="definition-grid">
+          {visibleDefinitions.map((definition) => (
+            <article className="definition-card" key={definition.id}>
+              <div>
+                <Badge variant={definition.availability === 'available' ? 'secondary' : 'outline'}>
+                  {definition.availability}
+                </Badge>
+                <span>v{definition.version}</span>
+              </div>
+              <h3>{definition.title}</h3>
+              <p>{definition.description}</p>
+              <dl>
+                <div><dt>Spans</dt><dd>{definition.allowedSpans.join(', ')}</dd></div>
+                <div><dt>Responsive</dt><dd>{definition.responsiveBehavior}</dd></div>
+                <div><dt>Agent create</dt><dd>{definition.agentPermissions.create ? 'Allowed' : 'Not yet'}</dd></div>
+              </dl>
+            </article>
+          ))}
+        </div>
+      </section>
+      <section aria-labelledby="layout-title" className="layout-section">
+        <header>
+          <div>
+            <p className="eyebrow">Shared Layout JSON</p>
+            <h2 id="layout-title">One document, three consumers</h2>
+            <p>The agent, Studio runtime, and the Puck adapter use this same validated structure.</p>
+          </div>
+          <output aria-label="Layout validation result" data-valid={validation.ok}>
+            {validation.ok ? 'Schema valid' : 'Schema failed'} · {warnings.length} registry warnings
+          </output>
+        </header>
+        <div aria-label="Sample operations dashboard layout" className="layout-preview">
+          {layout.blocks.map((block) => {
+            const definition = definitionsById.get(block.type)
+            return (
+              <article
+                className="layout-block"
+                data-availability={definition?.availability}
+                key={block.id}
+                style={{
+                  '--layout-column': block.placement.column,
+                  '--layout-order': block.placement.order,
+                  '--layout-span': block.placement.span,
+                } as LayoutBlockStyle}
+              >
+                <span>{definition?.category}</span>
+                <strong>{definition?.title ?? block.type}</strong>
+                <small>{block.locked ? 'Locked by owner' : 'Agent may move after renderer approval'}</small>
+              </article>
+            )
+          })}
+        </div>
+      </section>
+      <details className="registry-evidence">
+        <summary>Developer evidence: inspect the versioned Layout JSON</summary>
+        <pre>{JSON.stringify(layout, null, 2)}</pre>
+      </details>
+    </main>
+  )
+}
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/data/templates/composition-registry-lab/sample-layout.json ADDED Viewed

@@ -0,0 +1,63 @@
+{
+  "schemaVersion": 1,
+  "id": "operations-dashboard",
+  "theme": "utopia-default",
+  "columns": 12,
+  "blocks": [
+    {
+      "id": "overview-metrics",
+      "type": "metric-grid",
+      "version": 1,
+      "placement": {
+        "column": 1,
+        "span": 4,
+        "order": 1,
+        "compactSpan": 12
+      },
+      "props": {
+        "metrics": ["open", "blocked", "resolved"],
+        "density": "compact",
+        "comparison": "previous-period"
+      }
+    },
+    {
+      "id": "automation-status",
+      "type": "agent-status",
+      "version": 1,
+      "placement": {
+        "column": 9,
+        "span": 4,
+        "order": 1,
+        "compactSpan": 12
+      },
+      "props": {
+        "showApprovals": true,
+        "density": "default"
+      },
+      "locked": true
+    },
+    {
+      "id": "active-issues",
+      "type": "issue-table",
+      "version": 1,
+      "placement": {
+        "column": 1,
+        "span": 12,
+        "order": 2,
+        "compactSpan": 12
+      },
+      "props": {
+        "view": "active",
+        "density": "compact",
+        "columns": ["title", "status", "priority", "assignee"]
+      }
+    }
+  ],
+  "regions": [
+    {
+      "id": "governance",
+      "locked": true,
+      "blockIds": ["automation-status"]
+    }
+  ]
+}

package/data/templates/composition-registry-lab/styles.css ADDED Viewed

@@ -0,0 +1,343 @@
+* {
+  box-sizing: border-box;
+}
+html,
+body,
+#root {
+  min-block-size: 100%;
+  margin: 0;
+}
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: var(--font-sans);
+}
+.skip-link {
+  position: fixed;
+  inset-block-start: var(--space-2);
+  inset-inline-start: var(--space-2);
+  z-index: var(--z-modal);
+  translate: 0 -200%;
+}
+.skip-link:focus {
+  translate: 0;
+}
+.registry-lab {
+  min-block-size: 100vh;
+  padding: var(--page-gutter);
+  background: var(--background);
+  color: var(--foreground);
+  text-align: start;
+}
+.registry-header,
+.ownership-section,
+.guardrails-section,
+.palette-section,
+.layout-section,
+.registry-evidence {
+  max-inline-size: var(--container-standard);
+  margin-inline: auto;
+}
+.registry-header {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: var(--space-6);
+  padding-block: var(--space-8);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+.registry-header > div:first-child {
+  display: grid;
+  gap: var(--space-2);
+  max-inline-size: 50rem;
+}
+.registry-header h1,
+.registry-header p,
+.registry-lab h2,
+.registry-lab h3,
+.registry-lab p {
+  margin: 0;
+}
+.registry-header p,
+.registry-header span,
+.ownership-section p,
+.guardrails-section article p,
+.palette-section header p,
+.definition-card p,
+.layout-section header p {
+  color: var(--muted-foreground);
+  line-height: var(--line-height-body);
+}
+.registry-controls {
+  display: grid;
+  justify-items: end;
+  gap: var(--space-2);
+}
+.registry-control-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--space-2);
+}
+.registry-preview-status {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+.registry-direction-preview {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-3);
+  min-inline-size: min(100%, 18rem);
+  padding: var(--space-2) var(--space-3);
+  border: var(--border-width-hairline) solid var(--interaction-selection-border);
+  background: var(--interaction-selection-surface);
+  color: var(--foreground);
+  font-size: var(--font-size-small);
+}
+.registry-direction-preview strong {
+  font-size: var(--font-size-body);
+}
+.ownership-section,
+.guardrails-section,
+.palette-section,
+.layout-section {
+  display: grid;
+  gap: var(--space-4);
+  padding-block: var(--space-6);
+  border-block-end: var(--border-width-hairline) solid var(--border);
+}
+.ownership-section {
+  grid-template-columns: minmax(16rem, .7fr) minmax(0, 1.3fr);
+  align-items: start;
+}
+.ownership-section > div,
+.palette-section header > div,
+.layout-section header > div,
+.guardrails-section > div:first-child {
+  display: grid;
+  gap: var(--space-2);
+}
+.eyebrow {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-eyebrow);
+  font-weight: var(--font-weight-semibold);
+  letter-spacing: var(--tracking-eyebrow);
+  text-transform: uppercase;
+}
+.ownership-flow {
+  display: grid;
+  grid-template-columns: repeat(5, minmax(0, 1fr));
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  border: var(--border-width-hairline) solid var(--border);
+}
+.ownership-flow li {
+  display: grid;
+  align-content: start;
+  gap: var(--space-1);
+  min-inline-size: 0;
+  padding: var(--space-3);
+  border-inline-end: var(--border-width-hairline) solid var(--border);
+}
+.ownership-flow li:last-child {
+  border-inline-end: 0;
+}
+.ownership-flow li[data-current='true'] {
+  background: var(--interaction-selection-surface);
+}
+.ownership-flow span,
+.definition-card span,
+.definition-card dt,
+.layout-block span,
+.layout-block small {
+  color: var(--muted-foreground);
+  font-size: var(--font-size-small);
+}
+.guardrail-grid,
+.definition-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: var(--space-3);
+}
+.guardrails-section article,
+.definition-card {
+  display: grid;
+  align-content: start;
+  gap: var(--space-2);
+  min-inline-size: 0;
+  padding: var(--space-4);
+  border: var(--border-width-hairline) solid var(--border);
+  background: var(--surface);
+}
+.palette-section header,
+.layout-section header {
+  display: flex;
+  align-items: end;
+  justify-content: space-between;
+  gap: var(--space-4);
+}
+.definition-grid {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+.definition-card > div:first-child {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-2);
+}
+.definition-card dl {
+  display: grid;
+  gap: var(--space-1);
+  margin: var(--space-2) 0 0;
+}
+.definition-card dl div {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--space-2);
+}
+.definition-card dd {
+  margin: 0;
+  text-align: end;
+}
+.layout-section output {
+  padding: var(--space-3);
+  border: var(--border-width-hairline) solid var(--interaction-selection-border);
+  background: var(--interaction-selection-surface);
+  font-size: var(--font-size-small);
+}
+.layout-preview {
+  display: grid;
+  grid-template-columns: repeat(12, minmax(0, 1fr));
+  grid-auto-rows: minmax(8rem, auto);
+  gap: var(--space-3);
+  min-inline-size: 0;
+  padding: var(--space-4);
+  border: var(--border-width-hairline) solid var(--border);
+  background: var(--surface);
+}
+.layout-block {
+  display: grid;
+  align-content: center;
+  grid-column: var(--layout-column) / span var(--layout-span);
+  grid-row: var(--layout-order);
+  gap: var(--space-1);
+  min-inline-size: 0;
+  padding: var(--space-4);
+  border: var(--border-width-hairline) dashed var(--interaction-selection-border);
+  background: var(--interaction-selection-surface);
+}
+.layout-block[data-availability='planned']::after {
+  content: 'Renderer planned';
+  inline-size: fit-content;
+  margin-block-start: var(--space-2);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width-hairline) solid var(--border);
+  color: var(--muted-foreground);
+  font-size: var(--font-size-eyebrow);
+  text-transform: uppercase;
+}
+.registry-evidence {
+  margin-block: var(--space-4);
+  padding: var(--space-4);
+  border: var(--border-width-hairline) solid var(--border);
+  background: var(--surface);
+}
+.registry-evidence summary {
+  cursor: pointer;
+  font-weight: var(--font-weight-semibold);
+}
+.registry-evidence pre {
+  max-block-size: 28rem;
+  overflow: auto;
+  padding: var(--space-3);
+  background: var(--background);
+  font-size: var(--font-size-small);
+}
+@media (max-width: 56rem) {
+  .definition-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+  .ownership-flow {
+    grid-template-columns: 1fr;
+  }
+  .ownership-flow li {
+    border-inline-end: 0;
+    border-block-end: var(--border-width-hairline) solid var(--border);
+  }
+  .ownership-flow li:last-child {
+    border-block-end: 0;
+  }
+}
+@media (max-width: 44rem) {
+  .registry-header,
+  .palette-section header,
+  .layout-section header {
+    align-items: stretch;
+    flex-direction: column;
+  }
+  .ownership-section,
+  .guardrail-grid,
+  .definition-grid {
+    grid-template-columns: 1fr;
+  }
+  .registry-controls {
+    justify-items: start;
+    inline-size: 100%;
+  }
+  .registry-direction-preview {
+    inline-size: 100%;
+  }
+  .layout-block {
+    grid-column: 1 / -1;
+    grid-row: auto;
+  }
+}

package/data/templates/composition-registry-lab/template.manifest.json ADDED Viewed

@@ -0,0 +1,34 @@
+{
+  "id": "template-composition-registry-lab",
+  "name": "Composition Registry Lab",
+  "category": "development-tool",
+  "status": "available",
+  "purpose": "A runnable review surface for Ceramic block definitions, design guardrails, Layout JSON, and editor ownership boundaries.",
+  "packageImport": "@utopia-studio-design/design-system/Composition",
+  "sourcePath": "templates/composition-registry-lab/main.tsx",
+  "entryPath": "templates/composition-registry-lab/index.html",
+  "requiredTokens": [
+    "interaction-selection-*",
+    "background",
+    "surface",
+    "foreground",
+    "muted-foreground",
+    "border"
+  ],
+  "features": {
+    "registryDefinitions": true,
+    "layoutValidation": true,
+    "agentPermissions": true,
+    "lockedRegions": true,
+    "darkMode": true,
+    "rtl": true,
+    "responsiveMinimum": "320px",
+    "puckAdapter": false
+  },
+  "translations": {
+    "ar": {
+      "name": "مختبر سجل التركيب",
+      "purpose": "واجهة مراجعة قابلة للتشغيل لتعريفات كتل Ceramic وضوابط التصميم وعقد تخطيط JSON."
+    }
+  }
+}