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

package/data/manifests/blocks.json

@@ -0,0 +1,392 @@
+{
+  "version": "1.0.0",
+  "intent": "Copyable Ceramic compositions that demonstrate a reviewed interaction contract without turning product workflow into a core primitive.",
+  "blocks": [
+    {
+      "id": "interaction-workbench",
+      "title": "Interaction Workbench",
+      "status": "available",
+      "category": "interaction-lab",
+      "purpose": "A deterministic lab for selection, logical grid navigation, typeahead, reordering, resizing, virtualization, undo, RTL, and reduced motion.",
+      "bundlePath": "blocks/interaction-workbench",
+      "sourcePath": "blocks/interaction-workbench/InteractionWorkbench.tsx",
+      "exportName": "InteractionWorkbench",
+      "requiredImports": [
+        "@utopia-studio-design/design-system",
+        "@utopia-studio-design/design-system/Interaction"
+      ],
+      "contracts": [
+        "single, multiple, range, and select-all selection",
+        "roving focus and logical grid navigation",
+        "pointer drag with keyboard and touch alternatives",
+        "resize with keyboard-operable native range input",
+        "virtualized range calculation and stable item keys",
+        "undo and redo command history"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "analytics-chart-card",
+      "title": "Analytics Chart Card",
+      "status": "available",
+      "category": "analytics",
+      "purpose": "A page-ready chart composition with governed states, semantic series, keyboard exploration, and optional exact-value evidence.",
+      "bundlePath": "blocks/analytics-dashboard",
+      "sourcePath": "blocks/analytics-dashboard/AnalyticsDashboardBlocks.tsx",
+      "exportName": "AnalyticsChartCard",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Charts"
+      ],
+      "contracts": [
+        "line, bar, area, stacked, scatter, and donut families",
+        "loading, empty, error, partial, and ready states",
+        "keyboard point exploration and live exact values",
+        "semantic series and pattern differentiation"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "kpi-grid",
+      "title": "KPI Grid",
+      "status": "available",
+      "category": "analytics",
+      "purpose": "A governed metric group with locale-aware values, comparisons, density, and complete data states.",
+      "bundlePath": "blocks/analytics-dashboard",
+      "sourcePath": "blocks/analytics-dashboard/AnalyticsMetricBlocks.tsx",
+      "exportName": "KPIGrid",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Badge"
+      ],
+      "contracts": [
+        "locale-aware number, percent, and currency formatting",
+        "compact, default, and comfortable density",
+        "loading, empty, error, partial, and ready states"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "comparison-chart-panel",
+      "title": "Comparison Chart Panel",
+      "status": "available",
+      "category": "analytics",
+      "purpose": "A benchmark and period-comparison chart panel with semantic annotations.",
+      "bundlePath": "blocks/analytics-dashboard",
+      "sourcePath": "blocks/analytics-dashboard/AnalyticsDashboardBlocks.tsx",
+      "exportName": "ComparisonChartPanel",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Charts"
+      ],
+      "contracts": [
+        "benchmark annotation",
+        "period comparison",
+        "legend synchronization",
+        "accessible summary"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "chart-with-data-table",
+      "title": "Chart with Data Table",
+      "status": "available",
+      "category": "analytics",
+      "purpose": "A chart paired with a semantic table as the exact-value and screen-reader alternative.",
+      "bundlePath": "blocks/analytics-dashboard",
+      "sourcePath": "blocks/analytics-dashboard/AnalyticsDashboardBlocks.tsx",
+      "exportName": "ChartWithDataTable",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Charts"
+      ],
+      "contracts": [
+        "visual and table data parity",
+        "component-owned horizontal overflow",
+        "semantic caption, row headers, and column headers"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "database-toolbar",
+      "title": "Database Toolbar",
+      "status": "available",
+      "category": "database",
+      "purpose": "Search, filter, sort, group, and create controls for a schema-driven record workspace.",
+      "bundlePath": "blocks/database-workspace",
+      "sourcePath": "blocks/database-workspace/DatabaseWorkspaceBlocks.tsx",
+      "exportName": "DatabaseToolbar",
+      "requiredImports": ["@utopia-studio-design/design-system/Database"],
+      "contracts": ["query controls", "saved view context", "permission-aware create action"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "database-table-block",
+      "title": "Database Table Block",
+      "status": "available",
+      "category": "database",
+      "purpose": "A virtualized, editable semantic record grid with controlled persistence and mobile record transformation.",
+      "bundlePath": "blocks/database-workspace",
+      "sourcePath": "blocks/database-workspace/DatabaseWorkspaceBlocks.tsx",
+      "exportName": "DatabaseTableBlock",
+      "requiredImports": ["@utopia-studio-design/design-system/Database"],
+      "contracts": ["schema-driven properties", "grid keyboard model", "virtualization", "optimistic recovery"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "saved-views-bar",
+      "title": "Saved Views Bar",
+      "status": "available",
+      "category": "database",
+      "purpose": "An explicit saved-view switcher for governed filter, sort, grouping, and visibility presets.",
+      "bundlePath": "blocks/database-workspace",
+      "sourcePath": "blocks/database-workspace/DatabaseWorkspaceBlocks.tsx",
+      "exportName": "SavedViewsBar",
+      "requiredImports": ["@utopia-studio-design/design-system/Database"],
+      "contracts": ["controlled active view", "current view semantics"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "record-detail-drawer",
+      "title": "Record Detail Drawer",
+      "status": "available",
+      "category": "database",
+      "purpose": "A mobile and desktop detail surface that preserves every property outside the dense grid.",
+      "bundlePath": "blocks/database-workspace",
+      "sourcePath": "blocks/database-workspace/DatabaseWorkspaceBlocks.tsx",
+      "exportName": "RecordDetailDrawer",
+      "requiredImports": ["@utopia-studio-design/design-system/Database"],
+      "contracts": ["dialog semantics", "complete property detail", "logical inline-end placement"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "bulk-action-bar",
+      "title": "Bulk Action Bar",
+      "status": "available",
+      "category": "database",
+      "purpose": "A permission-aware action surface for selected records.",
+      "bundlePath": "blocks/database-workspace",
+      "sourcePath": "blocks/database-workspace/DatabaseWorkspaceBlocks.tsx",
+      "exportName": "BulkActionBar",
+      "requiredImports": ["@utopia-studio-design/design-system/Button"],
+      "contracts": ["selection count", "clear selection", "bulk mutation action"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "scheduler-shell",
+      "title": "Scheduler Shell",
+      "status": "available",
+      "category": "calendar",
+      "purpose": "An application scheduler shell with Month, Week, Day, Agenda, timezone, recurrence, conflict, and mutation contracts.",
+      "bundlePath": "blocks/calendar-application",
+      "sourcePath": "blocks/calendar-application/CalendarApplicationBlocks.tsx",
+      "exportName": "SchedulerShell",
+      "requiredImports": ["@utopia-studio-design/design-system/Calendar"],
+      "contracts": ["controlled events and adapter", "accessible agenda", "keyboard and touch move alternatives", "responsive view transition"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "calendar-sidebar",
+      "title": "Calendar Sidebar",
+      "status": "available",
+      "category": "calendar",
+      "purpose": "Date and resource controls for a multi-calendar scheduler.",
+      "bundlePath": "blocks/calendar-application",
+      "sourcePath": "blocks/calendar-application/CalendarApplicationBlocks.tsx",
+      "exportName": "CalendarSidebar",
+      "requiredImports": ["@utopia-studio-design/design-system/Calendar"],
+      "contracts": ["controlled date", "resource visibility", "logical sidebar placement"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "event-editor-drawer",
+      "title": "Event Editor Drawer",
+      "status": "available",
+      "category": "calendar",
+      "purpose": "A modal event editor with occurrence-versus-series scope, validation, dismissal, and focus restoration.",
+      "bundlePath": "blocks/calendar-application",
+      "sourcePath": "blocks/calendar-application/CalendarApplicationBlocks.tsx",
+      "exportName": "EventEditorDrawer",
+      "requiredImports": ["@utopia-studio-design/design-system/Calendar"],
+      "contracts": ["modal focus and scroll lock", "Escape dismissal", "recurrence edit scope", "required and chronological date validation", "async save recovery with preserved draft", "controlled save and delete"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "agenda-panel",
+      "title": "Agenda Panel",
+      "status": "available",
+      "category": "calendar",
+      "purpose": "A chronological semantic event list that remains available beside or instead of visual time grids.",
+      "bundlePath": "blocks/calendar-application",
+      "sourcePath": "blocks/calendar-application/CalendarApplicationBlocks.tsx",
+      "exportName": "AgendaPanel",
+      "requiredImports": ["@utopia-studio-design/design-system/Calendar"],
+      "contracts": ["chronological event order", "screen-reader names", "equivalent event activation"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "timezone-selector",
+      "title": "Timezone Selector",
+      "status": "available",
+      "category": "calendar",
+      "purpose": "An explicit IANA timezone selector for cross-timezone event display.",
+      "bundlePath": "blocks/calendar-application",
+      "sourcePath": "blocks/calendar-application/CalendarApplicationBlocks.tsx",
+      "exportName": "TimezoneSelector",
+      "requiredImports": ["@utopia-studio-design/design-system/Calendar"],
+      "contracts": ["IANA timezone values", "controlled selection", "visible display context"],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "activity-feed",
+      "title": "Activity Feed",
+      "status": "available",
+      "category": "operations",
+      "purpose": "A locale-aware chronological activity stream with grouped views, semantic sources, timezone formatting, and recoverable pagination.",
+      "bundlePath": "blocks/activity-feed",
+      "sourcePath": "blocks/activity-feed/ActivityFeedBlock.tsx",
+      "exportName": "ActivityFeedBlock",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Badge",
+        "@utopia-studio-design/design-system/Button",
+        "@utopia-studio-design/design-system/DataDisplay",
+        "@utopia-studio-design/design-system/Utilities"
+      ],
+      "contracts": [
+        "actor-independent localized activity labels",
+        "none, day, and source grouping",
+        "locale and IANA timezone-aware timestamps",
+        "inherit, auto, LTR, and RTL direction modes",
+        "loading, empty, error, and ready states",
+        "recoverable page-size pagination",
+        "product-owned records and backend cursors"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "agent-status",
+      "title": "Agent Status",
+      "status": "available",
+      "category": "agentic",
+      "purpose": "A locale-aware execution surface for progress, risk, approval, failure, and completion with product-owned operational data and decisions.",
+      "bundlePath": "blocks/agent-status",
+      "sourcePath": "blocks/agent-status/AgentStatusBlock.tsx",
+      "exportName": "AgentStatusBlock",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Badge",
+        "@utopia-studio-design/design-system/Button",
+        "@utopia-studio-design/design-system/DataDisplay",
+        "@utopia-studio-design/design-system/Utilities"
+      ],
+      "contracts": [
+        "queued, running, approval, blocked, failed, and completed states",
+        "localized progress, risk, timestamps, and accessible state labels",
+        "inherit, auto, LTR, and RTL direction modes",
+        "loading, empty, error, filtered-empty, and ready states",
+        "product-owned execution records and approval callbacks",
+        "sanitized summaries without raw prompts, stacks, credentials, or command output"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "todo-list",
+      "title": "To-do List",
+      "status": "available",
+      "category": "productivity",
+      "purpose": "A focused task list with controlled product data, semantic filters, completion, due context, priority, and complete loading states.",
+      "bundlePath": "blocks/dashboard-composer",
+      "sourcePath": "blocks/dashboard-composer/DashboardComposerBlocks.tsx",
+      "exportName": "TodoListBlock",
+      "requiredImports": [
+        "@utopia-studio-design/design-system/Badge",
+        "@utopia-studio-design/design-system/Button",
+        "@utopia-studio-design/design-system/Forms"
+      ],
+      "contracts": [
+        "controlled and uncontrolled task data",
+        "keyboard and pointer completion",
+        "semantic task filters",
+        "loading, empty, error, and ready states",
+        "product-owned persistence"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "ceramic-dashboard-renderer",
+      "title": "Ceramic Dashboard Renderer",
+      "status": "available",
+      "category": "composition",
+      "purpose": "A Layout JSON runtime that maps registered definitions to product renderers and validates every agent-style move or removal.",
+      "bundlePath": "blocks/dashboard-composer",
+      "sourcePath": "blocks/dashboard-composer/DashboardComposerBlocks.tsx",
+      "exportName": "CeramicDashboardRenderer",
+      "requiredImports": ["@utopia-studio-design/design-system/Composition"],
+      "contracts": [
+        "versioned layout validation",
+        "product-supplied renderer map",
+        "locked block and region enforcement",
+        "keyboard and touch arrange controls",
+        "responsive registered placement"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    },
+    {
+      "id": "ceramic-puck-adapter",
+      "title": "Ceramic Puck Adapter",
+      "status": "available",
+      "category": "composition",
+      "purpose": "An optional visual-editor adapter that generates Puck fields and permissions from the Ceramic registry, then validates Puck output before producing Layout JSON.",
+      "bundlePath": "blocks/dashboard-composer",
+      "sourcePath": "blocks/dashboard-composer/CeramicPuckAdapter.tsx",
+      "exportName": "createCeramicPuckConfig",
+      "requiredImports": [
+        "@puckeditor/core",
+        "@utopia-studio-design/design-system/Composition"
+      ],
+      "contracts": [
+        "registry-generated component palette and semantic fields",
+        "Puck Data and Ceramic Layout JSON conversion",
+        "locked block and region permissions",
+        "validated publish boundary",
+        "no arbitrary style payloads"
+      ],
+      "rtlReady": true,
+      "reducedMotion": true,
+      "responsiveMinimum": "320px"
+    }
+  ]
+}

package/data/manifests/catalog.json

@@ -193,10 +193,13 @@
             "Avatar",
             "Badge",
             "Bubble",
-            "Calendar",
-            "Carousel",
-            "Chart",
-            "Data Table",
+        "Calendar",
+        "Scheduler Root",
+        "Carousel",
+        "Chart",
+        "Chart Root",
+        "Database Root",
+        "Data Table",
             "Empty",
             "Item",
             "Kbd",

package/data/manifests/components.json

@@ -853,6 +853,8 @@
           "defaultSelectedDate": "Initial selected date for uncontrolled usage.",
           "onSelect": "Called with a Date when an enabled day is selected.",
           "onMonthChange": "Called when previous/next or month/year controls change the visible month.",
+          "locale": "BCP 47 locale used for month/day labels, direction, and default numeral selection.",
+          "numberingSystem": "Optional react-day-picker numeral system override. Defaults to the locale-resolved numbering system.",
           "weekStartsOn": "Use product locale requirements. 0 is Sunday, 1 Monday, 6 Saturday.",
           "disabledDates": "Product-owned predicate for disabled days."
         },
@@ -1020,6 +1022,62 @@
         "Utopia brand primitives inside reusable component logic"
       ]
     },
+    {
+      "name": "Chart Root",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { ChartRoot, ChartDataTable, ChartLegendList, ChartResponsiveContainer, ChartTooltipPanel, RechartsChartRenderer } from '@utopia-studio-design/design-system/Charts';",
+      "sourcePath": "packages/design-system/src/components/Charts.tsx",
+      "shadcnFoundation": [
+        "shadcn/ui chart composition",
+        "Recharts adapter boundary",
+        "Ceramic interaction foundation",
+        "semantic visualization token contract"
+      ],
+      "fallbackToShadcn": "chart",
+      "requiredTokens": [
+        "--visualization-series-1",
+        "--visualization-series-2",
+        "--visualization-positive",
+        "--visualization-negative",
+        "--visualization-neutral",
+        "--visualization-forecast",
+        "--visualization-benchmark",
+        "--visualization-grid",
+        "--interaction-selection-surface",
+        "--interaction-selection-border"
+      ],
+      "useWhen": [
+        "Application analytics need Line, Bar, Area, Stacked, Scatter, or Donut families",
+        "Charts need controlled series visibility and keyboard point exploration",
+        "Loading, empty, error, partial, and ready data states must remain explicit",
+        "A semantic data table is required as the exact-value alternative"
+      ],
+      "avoidWhen": [
+        "A small decorative bar scaffold is sufficient",
+        "The chart lacks an accessible summary or stable series IDs",
+        "Renderer-specific styling must bypass Ceramic tokens"
+      ],
+      "neverInvent": [
+        "Raw series colors",
+        "Color-only series identity",
+        "Missing values represented as zero",
+        "SVG-only interaction without a keyboard and table alternative",
+        "Left/right-only keyboard behavior",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "type": "'line' | 'bar' | 'area' | 'stacked' | 'scatter' | 'donut'",
+          "state": "'loading' | 'empty' | 'error' | 'partial' | 'ready'",
+          "renderer": "Optional tree-shakeable adapter implementing ChartRendererProps.",
+          "direction": "'ltr' | 'rtl'. Changes chronological rendering and logical Arrow key exploration.",
+          "showDataTable": "boolean. Renders the exact-value semantic table alternative."
+        },
+        "arabicFriendly": "Chart Root inherits localized labels and formatters from the consumer, mirrors chronological start and logical keyboard exploration under RTL, and keeps numbers formatted by the supplied locale.",
+        "cli": "npm run ds -- component \"Chart Root\" --dense"
+      }
+    },
     {
       "name": "Assistant Panel",
       "category": "Chat",
@@ -2295,6 +2353,127 @@
         "Utopia brand primitives inside reusable component logic"
       ]
     },
+    {
+      "name": "Scheduler Root",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { SchedulerRoot, MonthView, WeekView, DayView, AgendaView, TimeGrid, AllDayLane, EventCard, DateNavigator } from '@utopia-studio-design/design-system/Calendar';",
+      "sourcePath": "packages/design-system/src/components/Calendar.tsx",
+      "shadcnFoundation": [
+        "shadcn/ui Calendar through the Ceramic react-day-picker Calendar",
+        "Ceramic Button, IconButton, and ButtonGroup composition",
+        "Radix Select through the Ceramic Select family",
+        "Ceramic interaction foundation",
+        "application scheduler",
+        "controlled persistence adapter"
+      ],
+      "fallbackToShadcn": "calendar, button group, select, sheet",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--popover-surface",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--ring",
+        "--interaction-selection-surface",
+        "--interaction-selection-border",
+        "--success",
+        "--warning",
+        "--destructive"
+      ],
+      "useWhen": [
+        "A product needs event or resource scheduling rather than date selection",
+        "Month, Week, Day, and Agenda views share controlled events",
+        "Recurrence, overlap, conflict, permissions, and timezone display need one contract"
+      ],
+      "avoidWhen": [
+        "A date picker or single-date Calendar is sufficient",
+        "Product persistence or authorization would be owned by the component package",
+        "Pointer drag would be the only way to move or resize an event"
+      ],
+      "neverInvent": [
+        "Raw event colors",
+        "Persistence or authorization inside SchedulerRoot",
+        "Mouse-only move or resize behavior",
+        "Hidden timezone conversion",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "events": "Controlled SchedulerEvent records with stable IDs and ISO instants.",
+          "timezone": "IANA timezone used for displayed date and time; stored instants remain unchanged.",
+          "view": "Controlled month, week, day, or agenda view.",
+          "adapter": "Optional controlled mutation adapter. Ceramic provides optimistic UI and rollback but never owns persistence.",
+          "permissions": "Explicit create, edit, move, resize, duplicate, and delete capabilities.",
+          "direction": "Optional ltr or rtl override. When omitted, direction is derived from locale.",
+          "locale": "BCP 47 locale used for labels, dates, numerals, week information, and automatic direction.",
+          "weekStartsOn": "Optional JS weekday override. Defaults to Intl.Locale week information.",
+          "weekendDays": "Optional JS weekday list. Defaults to Intl.Locale weekend information.",
+          "calendarSystem": "Primary display calendar. Event placement remains based on Gregorian instants.",
+          "secondaryCalendar": "Optional secondary display calendar such as islamic-umalqura.",
+          "labels": "Product-localized visible and accessibility copy. Use labels.monthGrid for the ARIA month grid, labels.compactView for shorter mobile view names, labels.compactMore for narrow month-cell overflow counts, and labels.selectDate for date actions."
+        },
+        "arabicFriendly": "Event titles and accessibility copy are product-localized; logical placement and navigation mirror in RTL, while dates, times, and numerals use the supplied locale and timezone."
+      }
+    },
+    {
+      "name": "Database Root",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { DatabaseRoot, DataGrid, DatabasePropertyCell } from '@utopia-studio-design/design-system/Database';",
+      "sourcePath": "packages/design-system/src/components/Database.tsx",
+      "shadcnFoundation": [
+        "data table and form composition",
+        "Ceramic interaction foundation",
+        "schema-driven record grid",
+        "controlled persistence adapter"
+      ],
+      "fallbackToShadcn": "data-table",
+      "requiredTokens": [
+        "--background",
+        "--surface",
+        "--surface-elevated",
+        "--foreground",
+        "--muted-foreground",
+        "--border",
+        "--input",
+        "--ring",
+        "--interaction-selection-surface",
+        "--interaction-selection-border"
+      ],
+      "useWhen": [
+        "A product needs schema-driven editable records and saved views",
+        "Large datasets need virtualized grid navigation and controlled persistence",
+        "A dense desktop grid must transform into mobile record details"
+      ],
+      "avoidWhen": [
+        "A read-only Table or lightweight DataTable is sufficient",
+        "Product persistence or authorization would be owned by the component package",
+        "Arbitrary cell CSS is required instead of registered property types"
+      ],
+      "neverInvent": [
+        "Raw property colors",
+        "Persistence or authorization inside DatabaseRoot",
+        "Mouse-only resize, reorder, or editing behavior",
+        "Page-level horizontal overflow",
+        "Left/right-only layout rules",
+        "Utopia brand primitives inside reusable component logic"
+      ],
+      "ai": {
+        "props": {
+          "schema": "DatabaseSchema with stable property IDs and text, number, select, multi-select, date, person, checkbox, or URL property types.",
+          "records": "Controlled records with stable IDs and property values.",
+          "density": "compact, default, or comfortable. Density changes desktop row height without changing mobile record semantics.",
+          "query": "Semantic filters, sorts, and grouping; saved view state stays product-controlled.",
+          "adapter": "Optional controlled mutation adapter. Ceramic applies optimistic UI and rollback but never owns persistence.",
+          "permissions": "Explicit edit, resize, reorder, and bulk-action capabilities.",
+          "direction": "ltr or rtl. Logical grid navigation and inline placement follow direction."
+        },
+        "arabicFriendly": "Property labels and values are supplied by the product; grid arrows follow logical inline direction, dates and numbers use the supplied locale, and the mobile record-detail transformation preserves property order."
+      }
+    },
     {
       "name": "Data Table",
       "category": "Data Display",