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

package/data/manifests/composition-registry.json

@@ -0,0 +1,427 @@
+{
+  "version": 1,
+  "layoutSchemaVersion": 1,
+  "intent": "Ceramic-owned composition definitions for agent, Studio runtime, and optional visual-editor control of modular dashboard layouts.",
+  "designGuardrails": {
+    "sourceOfTruth": "Ceramic Composition Registry and versioned Layout JSON",
+    "editorRole": "Puck and other editors are optional adapters that read and write this contract; they do not define components, styling, or schema.",
+    "forbiddenPayloads": [
+      "raw colors",
+      "raw shadows",
+      "raw radii",
+      "arbitrary spacing",
+      "className",
+      "style",
+      "sx",
+      "css",
+      "token overrides"
+    ],
+    "requiredContracts": [
+      "Ceramic components",
+      "semantic tokens",
+      "registered props",
+      "responsive placement",
+      "loading empty error ready states",
+      "RTL",
+      "reduced motion",
+      "agent permissions",
+      "user locks"
+    ]
+  },
+  "definitions": [
+    {
+      "id": "interaction-workbench",
+      "version": 1,
+      "title": "Interaction Workbench",
+      "category": "development-tool",
+      "description": "Runnable Ceramic interaction fixture for selection, movement, resize, virtualization, direction, and recovery.",
+      "availability": "available",
+      "renderer": "blocks/interaction-workbench/InteractionWorkbench.tsx#InteractionWorkbench",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": [],
+        "properties": {
+          "direction": {
+            "type": "string",
+            "enum": ["ltr", "rtl"]
+          }
+        }
+      },
+      "allowedSpans": [6, 8, 12],
+      "allowedSurfaces": ["default", "subtle"],
+      "responsiveBehavior": "stack",
+      "states": ["ready"],
+      "dataRequirements": ["deterministic fixture data"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": ["direction"]
+      }
+    },
+    {
+      "id": "metric-grid",
+      "version": 1,
+      "title": "Metric Grid",
+      "category": "analytics",
+      "description": "A governed group of comparable metrics with semantic emphasis and compact responsive behavior.",
+      "availability": "available",
+      "renderer": "blocks/analytics-dashboard/AnalyticsMetricBlocks.tsx#KPIGrid",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": ["metrics"],
+        "properties": {
+          "metrics": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" }
+          },
+          "density": {
+            "type": "string",
+            "enum": ["compact", "default", "comfortable"]
+          },
+          "comparison": {
+            "type": "string",
+            "enum": ["none", "previous-period", "target"]
+          }
+        }
+      },
+      "allowedSpans": [3, 4, 6, 12],
+      "allowedSurfaces": ["default", "subtle", "elevated"],
+      "responsiveBehavior": "stack",
+      "states": ["loading", "empty", "error", "ready"],
+      "dataRequirements": ["metric id", "label", "value", "format", "comparison"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": ["metrics", "density", "comparison"]
+      }
+    },
+    {
+      "id": "issue-table",
+      "version": 1,
+      "title": "Issue Table",
+      "category": "database",
+      "description": "A dense issue workspace with governed columns, views, selection, overflow, and batch actions.",
+      "availability": "available",
+      "renderer": "blocks/database-workspace/DatabaseWorkspaceBlocks.tsx#DatabaseTableBlock",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": ["view"],
+        "properties": {
+          "view": {
+            "type": "string",
+            "enum": ["active", "backlog", "blocked", "completed"]
+          },
+          "density": {
+            "type": "string",
+            "enum": ["compact", "default", "comfortable"]
+          },
+          "columns": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" }
+          }
+        }
+      },
+      "allowedSpans": [6, 8, 12],
+      "allowedSurfaces": ["default", "subtle"],
+      "responsiveBehavior": "scroll",
+      "states": ["loading", "empty", "error", "ready"],
+      "dataRequirements": ["stable row ids", "column definitions", "permissions", "pagination or virtualization"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": [
+          "view",
+          "density",
+          "columns"
+        ]
+      }
+    },
+    {
+      "id": "chart-panel",
+      "version": 1,
+      "title": "Chart Panel",
+      "category": "analytics",
+      "description": "A chart composition with semantic series, summary, legend, tooltip, and accessible table alternative.",
+      "availability": "available",
+      "renderer": "blocks/analytics-dashboard/AnalyticsDashboardBlocks.tsx#AnalyticsChartCard",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": ["chartType"],
+        "properties": {
+          "chartType": {
+            "type": "string",
+            "enum": ["line", "bar", "area", "stacked", "scatter", "donut"]
+          },
+          "comparison": {
+            "type": "string",
+            "enum": ["none", "previous-period", "benchmark", "target"]
+          },
+          "showTable": {
+            "type": "boolean"
+          }
+        }
+      },
+      "allowedSpans": [4, 6, 8, 12],
+      "allowedSurfaces": ["default", "subtle", "elevated"],
+      "responsiveBehavior": "preserve",
+      "states": ["loading", "empty", "error", "ready"],
+      "dataRequirements": ["series ids", "labels", "values", "formatters", "accessible summary"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": ["chartType", "comparison", "showTable"]
+      }
+    },
+    {
+      "id": "calendar-panel",
+      "version": 1,
+      "title": "Calendar Panel",
+      "category": "temporal",
+      "description": "A locale-aware calendar or scheduler composition with timezone, navigation, event priority, and collision contracts.",
+      "availability": "available",
+      "renderer": "blocks/calendar-application/CalendarApplicationBlocks.tsx#SchedulerShell",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": ["view", "timeZone"],
+        "properties": {
+          "view": {
+            "type": "string",
+            "enum": ["month", "week", "day", "agenda"]
+          },
+          "timeZone": {
+            "type": "string"
+          },
+          "locale": {
+            "type": "string",
+            "enum": ["en-US", "ar-SA", "ar-EG", "ar-AE"]
+          },
+          "direction": {
+            "type": "string",
+            "enum": ["inherit", "auto", "ltr", "rtl"]
+          },
+          "weekStartsOn": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 6
+          },
+          "secondaryCalendar": {
+            "type": "string",
+            "enum": ["none", "islamic-umalqura"]
+          },
+          "initialScrollHour": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 23
+          },
+          "showAgendaAlternative": {
+            "type": "boolean"
+          }
+        }
+      },
+      "allowedSpans": [6, 8, 12],
+      "allowedSurfaces": ["default", "subtle"],
+      "responsiveBehavior": "collapse",
+      "states": ["loading", "empty", "error", "conflict", "ready"],
+      "dataRequirements": ["event ids", "instants", "IANA timezone", "BCP 47 locale", "localized labels", "permissions", "conflict policy"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": [
+          "view",
+          "timeZone",
+          "locale",
+          "direction",
+          "weekStartsOn",
+          "secondaryCalendar",
+          "initialScrollHour",
+          "showAgendaAlternative"
+        ]
+      }
+    },
+    {
+      "id": "todo-list",
+      "version": 1,
+      "title": "To-do List",
+      "category": "productivity",
+      "description": "A focused task list with completion, priority, due context, semantic filters, and product-owned persistence.",
+      "availability": "available",
+      "renderer": "blocks/dashboard-composer/DashboardComposerBlocks.tsx#TodoListBlock",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": [],
+        "properties": {
+          "title": {
+            "type": "string"
+          },
+          "filter": {
+            "type": "string",
+            "enum": ["all", "today", "upcoming", "completed"]
+          },
+          "density": {
+            "type": "string",
+            "enum": ["compact", "default", "comfortable"]
+          },
+          "showCompleted": {
+            "type": "boolean"
+          }
+        }
+      },
+      "allowedSpans": [4, 6, 8, 12],
+      "allowedSurfaces": ["default", "subtle"],
+      "responsiveBehavior": "stack",
+      "states": ["loading", "empty", "error", "ready"],
+      "dataRequirements": ["stable task ids", "localized task labels", "completion state", "product mutation adapter"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": ["title", "filter", "density", "showCompleted"]
+      }
+    },
+    {
+      "id": "activity-feed",
+      "version": 1,
+      "title": "Activity Feed",
+      "category": "operations",
+      "description": "A locale-aware chronological activity stream with actor-independent labels, semantic sources, grouped views, and recoverable pagination.",
+      "availability": "available",
+      "renderer": "blocks/activity-feed/ActivityFeedBlock.tsx#ActivityFeedBlock",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": [],
+        "properties": {
+          "density": {
+            "type": "string",
+            "enum": ["compact", "default", "comfortable"]
+          },
+          "groupBy": {
+            "type": "string",
+            "enum": ["none", "day", "source"]
+          },
+          "locale": {
+            "type": "string",
+            "enum": ["en-US", "ar-SA", "ar-EG", "ar-AE"]
+          },
+          "direction": {
+            "type": "string",
+            "enum": ["inherit", "auto", "ltr", "rtl"]
+          },
+          "timeZone": {
+            "type": "string"
+          },
+          "showSources": {
+            "type": "boolean"
+          },
+          "pageSize": {
+            "type": "number",
+            "minimum": 2,
+            "maximum": 20
+          }
+        }
+      },
+      "allowedSpans": [3, 4, 6, 12],
+      "allowedSurfaces": ["default", "subtle"],
+      "responsiveBehavior": "stack",
+      "states": ["loading", "empty", "error", "ready"],
+      "dataRequirements": ["activity id", "instant", "IANA timezone", "BCP 47 locale", "localized label", "source", "pagination cursor"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": [
+          "density",
+          "groupBy",
+          "locale",
+          "direction",
+          "timeZone",
+          "showSources",
+          "pageSize"
+        ]
+      }
+    },
+    {
+      "id": "agent-status",
+      "version": 1,
+      "title": "Agent Status",
+      "category": "agentic",
+      "description": "A locale-aware agent execution surface that separates progress, risk, approval, failure, and completion while products retain control of operational data and decisions.",
+      "availability": "available",
+      "renderer": "blocks/agent-status/AgentStatusBlock.tsx#AgentStatusBlock",
+      "propsSchema": {
+        "additionalProperties": false,
+        "required": [],
+        "properties": {
+          "density": {
+            "type": "string",
+            "enum": ["compact", "default", "comfortable"]
+          },
+          "filter": {
+            "type": "string",
+            "enum": ["all", "active", "attention", "completed"]
+          },
+          "locale": {
+            "type": "string",
+            "enum": ["en-US", "ar-SA", "ar-EG", "ar-AE"]
+          },
+          "direction": {
+            "type": "string",
+            "enum": ["inherit", "auto", "ltr", "rtl"]
+          },
+          "timeZone": {
+            "type": "string"
+          },
+          "showApprovals": {
+            "type": "boolean"
+          },
+          "maxItems": {
+            "type": "number",
+            "minimum": 1,
+            "maximum": 12
+          }
+        }
+      },
+      "allowedSpans": [3, 4, 6, 12],
+      "allowedSurfaces": ["default", "subtle", "elevated"],
+      "responsiveBehavior": "stack",
+      "states": ["loading", "empty", "error", "ready"],
+      "dataRequirements": ["stable execution id", "localized agent and task labels", "execution state", "bounded progress", "risk state", "human approval request", "sanitized summary", "instant", "IANA timezone"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "agentPermissions": {
+        "create": true,
+        "remove": true,
+        "move": true,
+        "editableProps": [
+          "density",
+          "filter",
+          "locale",
+          "direction",
+          "timeZone",
+          "showApprovals",
+          "maxItems"
+        ]
+      }
+    }
+  ]
+}

package/data/manifests/motion-profiles.json

@@ -86,7 +86,7 @@
     {
       "id": "precise",
       "label": "Precise dissolve",
-      "themes": ["barrier-intelligence"],
+      "themes": ["barrier-intelligence", "renacore"],
       "personality": "precise",
       "description": "Controlled dissolves and small scale changes for analytical surfaces.",
       "rules": ["Prefer opacity over travel", "Keep scale changes below two percent", "Preserve analytical continuity"],

package/data/manifests/patterns.json

@@ -8,5 +8,117 @@
     "Themes are token-contract and visual-policy implementations, not decorative skins.",
     "Arabic-friendly support is a baseline requirement."
   ],
-  "antiPatterns": ["Invented tokens", "Generic SaaS gradients", "Rounded marketing cards", "Glassmorphism", "Raw left/right APIs", "Unreviewed Arabic copy"]
+  "antiPatterns": ["Invented tokens", "Generic SaaS gradients", "Rounded marketing cards", "Glassmorphism", "Raw left/right APIs", "Unreviewed Arabic copy"],
+  "patterns": [
+    {
+      "id": "composite-keyboard-navigation",
+      "title": "Keyboard navigation in composite widgets",
+      "contract": "Keep one tab stop, move roving focus with logical arrows, support Home/End and documented Page movement, and preserve the active key when data changes.",
+      "requiredAlternatives": ["pointer", "keyboard", "touch"],
+      "rtl": "Inline ArrowLeft and ArrowRight movement follows reading direction; block movement does not flip."
+    },
+    {
+      "id": "inclusive-drag-and-drop",
+      "title": "Drag and drop with keyboard and touch alternatives",
+      "contract": "Every drag action has Move earlier/Move later controls, announces the result, and restores focus to the moved item.",
+      "requiredAlternatives": ["pointer drag", "keyboard move", "touch move controls"],
+      "reducedMotion": "Commit the final order without animated displacement."
+    },
+    {
+      "id": "optimistic-recovery",
+      "title": "Optimistic mutation, error recovery, and undo",
+      "contract": "Apply the local result, expose Undo, rollback on a failed commit, and announce both failure and restored state without losing focus."
+    },
+    {
+      "id": "responsive-dense-surface",
+      "title": "Responsive transformation of dense desktop surfaces",
+      "contract": "At narrow widths preserve the task and reading order, own horizontal scrolling inside the dense region, and expose equivalent actions without hover dependency."
+    },
+    {
+      "id": "chart-period-comparison",
+      "title": "Period comparison and benchmark analysis",
+      "contract": "Keep current, previous, target, forecast, and benchmark series semantically distinct in labels, line patterns, tokens, and the data table; never rely on hue alone.",
+      "states": ["loading", "empty", "error", "partial", "ready"],
+      "rtl": "Chronological start follows reading direction while period labels and numbers preserve their locale."
+    },
+    {
+      "id": "chart-drill-down",
+      "title": "Drill down from summary to detail",
+      "contract": "A selected metric or point exposes an explicit action into detail without making the SVG geometry the only actionable surface. Restore focus to the originating summary when returning."
+    },
+    {
+      "id": "chart-table-alternative",
+      "title": "Chart plus accessible tabular alternative",
+      "contract": "Provide a concise chart summary, keyboard point explorer, and semantic table containing the same series identities, periods, missing values, and formatted values."
+    },
+    {
+      "id": "chart-data-availability",
+      "title": "No-data, delayed-data, and partial-data communication",
+      "contract": "Differentiate loading, empty, error, and partial data. Never draw missing values as zero; identify unavailable cells and preserve recovery guidance."
+    },
+    {
+      "id": "database-inline-editing",
+      "title": "Inline database editing and validation",
+      "contract": "Enter or double-click starts editing, validation remains attached to the property, Escape cancels, Enter or blur commits, and focus returns to the same cell."
+    },
+    {
+      "id": "database-query-views",
+      "title": "Filtering, sorting, grouping, and saved database views",
+      "contract": "Persist semantic query clauses and property visibility in named views without encoding presentation-only CSS."
+    },
+    {
+      "id": "database-bulk-actions",
+      "title": "Database multi-selection and bulk actions",
+      "contract": "Expose selected record count and permission-aware bulk actions while preserving row and cell focus."
+    },
+    {
+      "id": "database-optimistic-recovery",
+      "title": "Database optimistic mutation and undo",
+      "contract": "Apply a controlled local mutation, announce saving, rollback rejected commits, expose Undo, and never make the design system own persistence."
+    },
+    {
+      "id": "database-mobile-detail",
+      "title": "Dense grid to mobile record detail",
+      "contract": "Replace the dense grid with scannable record cards at narrow widths and open a complete record detail surface without page-level horizontal scrolling."
+    },
+    {
+      "id": "calendar-create-edit",
+      "title": "Create and edit a calendar event",
+      "contract": "Create and edit through a controlled modal surface with explicit start, end, all-day state, validation, focus restoration, and product-owned persistence."
+    },
+    {
+      "id": "calendar-move-resize-recovery",
+      "title": "Move and resize with conflict recovery",
+      "contract": "Pointer manipulation must have keyboard and touch controls; invalid, overlapping, unavailable, or rejected changes are announced and never silently committed."
+    },
+    {
+      "id": "calendar-recurrence-scope",
+      "title": "Edit an occurrence or recurring series",
+      "contract": "A recurring event edit explicitly chooses this occurrence or the entire series, preserving stable series identity and occurrence exceptions."
+    },
+    {
+      "id": "calendar-date-timezone-navigation",
+      "title": "Navigate dates, ranges, and timezones",
+      "contract": "Today, previous, next, direct date, view, and IANA timezone controls remain explicit; displayed event date and time update without changing the stored instant."
+    },
+    {
+      "id": "calendar-responsive-views",
+      "title": "Responsive month, day, and agenda views",
+      "contract": "Dense week and month grids transform to a usable day or agenda task on narrow screens while the semantic agenda remains available to assistive technology."
+    },
+    {
+      "id": "todo-completion-and-recovery",
+      "title": "Complete and recover a task",
+      "contract": "Task completion remains keyboard and pointer operable, announces aggregate progress, keeps product data controlled, and does not make Layout JSON own task records.",
+      "states": ["loading", "empty", "error", "ready"],
+      "rtl": "Checkbox, task label, metadata, and destructive action follow logical reading order."
+    },
+    {
+      "id": "agent-dashboard-composition",
+      "title": "Agent and human dashboard composition",
+      "contract": "Agents and human arrange controls write the same versioned Layout JSON, validate before commit, preserve locked blocks and regions, and render only registered semantic props.",
+      "requiredAlternatives": ["agent mutation", "keyboard controls", "touch controls"],
+      "rtl": "Placement uses logical reading order while registered column and span values remain deterministic."
+    }
+  ]
 }