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

package/data/manifests/themes.json

@@ -100,8 +100,18 @@
       "locked": true,
       "role": "default brand theme",
       "description": "The default Ceramic theme for The Utopia Studio. It maps semantic roles to Special Black, White, Brick Red, Light Grey, TWK Lausanne, IBM Plex Sans Arabic, square geometry, and border-led depth.",
-      "bestFor": ["The Utopia Studio products", "Ceramic documentation", "brand-led editorial and operational surfaces"],
-      "principles": ["architectural hierarchy", "square geometry", "restrained Brick Red emphasis", "border-led elevation", "bilingual Latin and Arabic typography"],
+      "bestFor": [
+        "The Utopia Studio products",
+        "Ceramic documentation",
+        "brand-led editorial and operational surfaces"
+      ],
+      "principles": [
+        "architectural hierarchy",
+        "square geometry",
+        "restrained Brick Red emphasis",
+        "border-led elevation",
+        "bilingual Latin and Arabic typography"
+      ],
       "brandAsset": {
         "kind": "wordmark",
         "src": "/brand/the-utopia-studio-wordmark.avif",
@@ -113,8 +123,18 @@
           "name": "ثيم The Utopia Studio الافتراضي",
           "role": "ثيم العلامة الافتراضي",
           "description": "الثيم الافتراضي لـ Ceramic وThe Utopia Studio. يربط الأدوار الدلالية بألوان العلامة وخطي TWK Lausanne وIBM Plex Sans Arabic والهندسة المربعة والعمق المعتمد على الحدود.",
-          "bestFor": ["منتجات The Utopia Studio", "توثيق Ceramic", "الأسطح التحريرية والتشغيلية المرتبطة بالعلامة"],
-          "principles": ["تسلسل معماري", "هندسة مربعة", "إبراز مقيد بلون Brick Red", "ارتفاع يعتمد على الحدود", "طباعة ثنائية للاتينية والعربية"],
+          "bestFor": [
+            "منتجات The Utopia Studio",
+            "توثيق Ceramic",
+            "الأسطح التحريرية والتشغيلية المرتبطة بالعلامة"
+          ],
+          "principles": [
+            "تسلسل معماري",
+            "هندسة مربعة",
+            "إبراز مقيد بلون Brick Red",
+            "ارتفاع يعتمد على الحدود",
+            "طباعة ثنائية للاتينية والعربية"
+          ],
           "brandAssetUsage": "يمكن للعلامة النصية تعريف الأسطح التابعة لـ The Utopia Studio، لكنها ليست أصلا مطلوبا لمكونات الجوهر."
         }
       },
@@ -188,8 +208,17 @@
       "locked": false,
       "role": "brand theme",
       "description": "Dark Blue, Ocean Blue, Charcoal Blue, Timid White. Manrope drives product UI and default headings; Clash Grotesk is marketing-only.",
-      "bestFor": ["Dextrum product UI", "technical sales surfaces", "data-heavy operational workflows"],
-      "principles": ["calm technical hierarchy", "blue-led product surfaces", "Manrope product typography", "Lucide icon system"],
+      "bestFor": [
+        "Dextrum product UI",
+        "technical sales surfaces",
+        "data-heavy operational workflows"
+      ],
+      "principles": [
+        "calm technical hierarchy",
+        "blue-led product surfaces",
+        "Manrope product typography",
+        "Lucide icon system"
+      ],
       "brandAsset": {
         "kind": "logo",
         "src": "/brand/dextrum-logo.svg",
@@ -201,8 +230,17 @@
           "name": "Dextrum",
           "role": "ثيم علامة",
           "description": "ثيم تقني بأزرق داكن وأزرق محيطي وأبيض هادئ. يستخدم Manrope لواجهة المنتج وClash Grotesk للتسويق فقط.",
-          "bestFor": ["واجهات منتج Dextrum", "أسطح المبيعات التقنية", "سير العمل التشغيلي كثيف البيانات"],
-          "principles": ["تسلسل تقني هادئ", "أسطح منتج يقودها الأزرق", "طباعة منتج بخط Manrope", "نظام أيقونات Lucide"],
+          "bestFor": [
+            "واجهات منتج Dextrum",
+            "أسطح المبيعات التقنية",
+            "سير العمل التشغيلي كثيف البيانات"
+          ],
+          "principles": [
+            "تسلسل تقني هادئ",
+            "أسطح منتج يقودها الأزرق",
+            "طباعة منتج بخط Manrope",
+            "نظام أيقونات Lucide"
+          ],
           "brandAssetUsage": "يستخدم الشعار فقط على الأسطح التابعة لعلامة Dextrum."
         }
       },
@@ -278,15 +316,35 @@
       "locked": false,
       "role": "brand theme",
       "description": "Near-black surfaces with warm gold accents, restrained detector lime, domain assurance states, and Hanken Grotesk for product UI. Brand and color mode are selected independently.",
-      "bestFor": ["Barrier Intelligence product UI", "risk and intelligence workflows", "high-contrast analytical products"],
-      "principles": ["near-black hierarchy", "warm gold emphasis", "dense analytical surfaces", "Lucide icon system", "independent brand and color mode", "restrained detector and assurance signals"],
+      "bestFor": [
+        "Barrier Intelligence product UI",
+        "risk and intelligence workflows",
+        "high-contrast analytical products"
+      ],
+      "principles": [
+        "near-black hierarchy",
+        "warm gold emphasis",
+        "dense analytical surfaces",
+        "Lucide icon system",
+        "independent brand and color mode",
+        "restrained detector and assurance signals"
+      ],
       "translations": {
         "ar": {
           "name": "Barrier Intelligence",
           "role": "ثيم علامة",
           "description": "ثيم بأسطح شبه سوداء ولمسات ذهبية دافئة وتسلسل حبر واضح وخط Hanken Grotesk لواجهة المنتج.",
-          "bestFor": ["واجهات Barrier Intelligence", "سير عمل المخاطر والاستخبارات", "المنتجات التحليلية عالية التباين"],
-          "principles": ["تسلسل شبه أسود", "إبراز ذهبي دافئ", "أسطح تحليلية كثيفة", "نظام أيقونات Lucide"],
+          "bestFor": [
+            "واجهات Barrier Intelligence",
+            "سير عمل المخاطر والاستخبارات",
+            "المنتجات التحليلية عالية التباين"
+          ],
+          "principles": [
+            "تسلسل شبه أسود",
+            "إبراز ذهبي دافئ",
+            "أسطح تحليلية كثيفة",
+            "نظام أيقونات Lucide"
+          ],
           "brandAssetUsage": "تبقى أصول العلامة خارج شريط هيكل Ceramic."
         }
       },
@@ -369,6 +427,114 @@
         "--modal-surface": "#141414",
         "--popover-surface": "#141414"
       }
+    },
+    {
+      "id": "renacore",
+      "name": "Renacore",
+      "shortName": "Renacore",
+      "locked": false,
+      "role": "brand theme",
+      "description": "A calm, precise operational theme for critical energy infrastructure, built from a white product canvas, muted grey structure, and restrained Renacore Teal active states.",
+      "motionProfile": "precise",
+      "bestFor": [
+        "Renacore marketing websites",
+        "predictive-intelligence product interfaces",
+        "energy infrastructure dashboards"
+      ],
+      "principles": [
+        "quiet",
+        "precise",
+        "utilitarian",
+        "operational"
+      ],
+      "translations": {
+        "ar": {
+          "name": "Renacore",
+          "role": "ثيم علامة",
+          "description": "ثيم تشغيلي هادئ ودقيق للبنية التحتية الحرجة للطاقة، مبني على مساحة بيضاء وهيكل رمادي وإشارات نشطة بلون Renacore Teal.",
+          "bestFor": [
+            "مواقع Renacore",
+            "واجهات الذكاء التنبؤي",
+            "لوحات معلومات البنية التحتية للطاقة"
+          ],
+          "principles": [
+            "هادئ",
+            "دقيق",
+            "عملي",
+            "تشغيلي"
+          ]
+        }
+      },
+      "brandAsset": {
+        "type": "image",
+        "src": "/brand/renacore-mark.svg",
+        "alt": "Renacore",
+        "usage": "Use the eight-part mark for Renacore identity moments. Do not repeat it as a generic interface icon."
+      },
+      "policyManifest": "packages/design-system/src/manifests/theme-renacore.json",
+      "css": "packages/design-system/src/themes/renacore.css",
+      "iconSystem": "lucide",
+      "values": {
+        "--background": "#FFFFFF",
+        "--foreground": "#000000",
+        "--card": "#F2F2F2",
+        "--card-foreground": "#000000",
+        "--primary": "#12414B",
+        "--primary-foreground": "#FFFFFF",
+        "--secondary": "#F2F2F2",
+        "--secondary-foreground": "#12414B",
+        "--muted": "#F2F2F2",
+        "--muted-foreground": "#666666",
+        "--border": "#F2F2F2",
+        "--input": "#D8D8D8",
+        "--ring": "#12414B",
+        "--radius": "8px",
+        "--radius-control": "6px",
+        "--radius-surface": "12px",
+        "--radius-chat-bubble": "14px",
+        "--radius-chat-composer": "16px",
+        "--radius-chat-token": "8px",
+        "--shadow-control": "none",
+        "--motion-duration-press": "120ms",
+        "--motion-duration-page": "300ms",
+        "--motion-duration-expand": "260ms",
+        "--motion-duration-reveal": "520ms",
+        "--motion-duration-icon": "360ms",
+        "--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.985",
+        "--motion-distance-page": "6px",
+        "--motion-distance-reveal": "14px",
+        "--font-sans": "Host Grotesk",
+        "--font-display": "Host Grotesk",
+        "--font-ui-support": "Host Grotesk",
+        "--font-marketing-display": "Host Grotesk",
+        "--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": "500",
+        "--font-size-display": "clamp(3rem, 7vw, 6.75rem)",
+        "--font-size-arabic-body": "16px",
+        "--font-size-arabic-body-lg": "18px",
+        "--font-size-arabic-display": "clamp(3rem, 7.1vw, 6.8rem)",
+        "--line-height-arabic": "1.75",
+        "--line-height-arabic-body": "1.75",
+        "--line-height-arabic-display": "1.12",
+        "--tracking-arabic": "0",
+        "--tracking-arabic-display": "0",
+        "--sidebar-width": "17rem",
+        "--control-height-sm": "2.125rem",
+        "--sidebar-width-collapsed": "4rem",
+        "--sidebar-min-block-size": "30rem",
+        "--sidebar-rail-size": "8px",
+        "--button-height": "42px",
+        "--card-padding": "24px",
+        "--overlay": "rgb(0 0 0 / 65%)",
+        "--modal-surface": "#FFFFFF",
+        "--popover-surface": "#FFFFFF"
+      }
     }
   ],
   "plannedThemeSlots": [
@@ -377,44 +543,164 @@
       "name": "Venture Proof",
       "status": "planned",
       "purpose": "Portfolio and company proof surfaces.",
-      "audience": ["venture studios", "portfolios", "company profiles"],
+      "audience": [
+        "venture studios",
+        "portfolios",
+        "company profiles"
+      ],
       "visualDirection": "Editorial proof hierarchy with strong media, concise evidence, and calm navigation.",
-      "semanticExtensions": ["--proof-accent", "--proof-media-surface", "--proof-metric-foreground"],
-      "requiredValidation": ["case-study density", "mixed media ratios", "Arabic company profiles", "LTR and RTL carousels"],
-      "translations": { "ar": { "name": "إثبات المشاريع", "purpose": "أسطح للمحافظ وإثبات الشركات.", "audience": ["استوديوهات المشاريع", "المحافظ", "ملفات الشركات"], "visualDirection": "تسلسل تحريري للأدلة مع وسائط قوية وأدلة مختصرة وتنقل هادئ.", "requiredValidation": ["كثافة دراسات الحالة", "نسب الوسائط المختلطة", "ملفات شركات عربية", "عارضات شرائح LTR وRTL"] } }
+      "semanticExtensions": [
+        "--proof-accent",
+        "--proof-media-surface",
+        "--proof-metric-foreground"
+      ],
+      "requiredValidation": [
+        "case-study density",
+        "mixed media ratios",
+        "Arabic company profiles",
+        "LTR and RTL carousels"
+      ],
+      "translations": {
+        "ar": {
+          "name": "إثبات المشاريع",
+          "purpose": "أسطح للمحافظ وإثبات الشركات.",
+          "audience": [
+            "استوديوهات المشاريع",
+            "المحافظ",
+            "ملفات الشركات"
+          ],
+          "visualDirection": "تسلسل تحريري للأدلة مع وسائط قوية وأدلة مختصرة وتنقل هادئ.",
+          "requiredValidation": [
+            "كثافة دراسات الحالة",
+            "نسب الوسائط المختلطة",
+            "ملفات شركات عربية",
+            "عارضات شرائح LTR وRTL"
+          ]
+        }
+      }
     },
     {
       "id": "operator",
       "name": "Operator Console",
       "status": "planned",
       "purpose": "Dense product and internal tool interfaces.",
-      "audience": ["operators", "internal tools", "admin products"],
+      "audience": [
+        "operators",
+        "internal tools",
+        "admin products"
+      ],
       "visualDirection": "High-density operational hierarchy with compact controls and clear exception states.",
-      "semanticExtensions": ["--operator-density", "--operator-row-height", "--operator-exception"],
-      "requiredValidation": ["dense tables", "keyboard navigation", "Arabic filters", "RTL side navigation"],
-      "translations": { "ar": { "name": "وحدة المشغّل", "purpose": "واجهات كثيفة للمنتجات والأدوات الداخلية.", "audience": ["المشغّلون", "الأدوات الداخلية", "منتجات الإدارة"], "visualDirection": "تسلسل تشغيلي عالي الكثافة مع عناصر تحكم مختصرة وحالات استثناء واضحة.", "requiredValidation": ["الجداول الكثيفة", "التنقل بلوحة المفاتيح", "مرشحات عربية", "تنقل جانبي RTL"] } }
+      "semanticExtensions": [
+        "--operator-density",
+        "--operator-row-height",
+        "--operator-exception"
+      ],
+      "requiredValidation": [
+        "dense tables",
+        "keyboard navigation",
+        "Arabic filters",
+        "RTL side navigation"
+      ],
+      "translations": {
+        "ar": {
+          "name": "وحدة المشغّل",
+          "purpose": "واجهات كثيفة للمنتجات والأدوات الداخلية.",
+          "audience": [
+            "المشغّلون",
+            "الأدوات الداخلية",
+            "منتجات الإدارة"
+          ],
+          "visualDirection": "تسلسل تشغيلي عالي الكثافة مع عناصر تحكم مختصرة وحالات استثناء واضحة.",
+          "requiredValidation": [
+            "الجداول الكثيفة",
+            "التنقل بلوحة المفاتيح",
+            "مرشحات عربية",
+            "تنقل جانبي RTL"
+          ]
+        }
+      }
     },
     {
       "id": "editorial",
       "name": "Editorial Resource",
       "status": "planned",
       "purpose": "Resource articles and technical guides.",
-      "audience": ["documentation teams", "research publishers", "technical resources"],
+      "audience": [
+        "documentation teams",
+        "research publishers",
+        "technical resources"
+      ],
       "visualDirection": "Reading-first typography with restrained navigation, annotations, code, and media.",
-      "semanticExtensions": ["--editorial-measure", "--editorial-note", "--editorial-code-surface"],
-      "requiredValidation": ["long-form reading", "code overflow", "Arabic article rhythm", "bilingual tables of contents"],
-      "translations": { "ar": { "name": "المورد التحريري", "purpose": "مقالات الموارد والأدلة التقنية.", "audience": ["فرق التوثيق", "ناشرو الأبحاث", "الموارد التقنية"], "visualDirection": "طباعة تضع القراءة أولا مع تنقل هادئ وملاحظات وكود ووسائط.", "requiredValidation": ["قراءة المحتوى الطويل", "تجاوز الكود", "إيقاع المقال العربي", "جداول محتويات ثنائية اللغة"] } }
+      "semanticExtensions": [
+        "--editorial-measure",
+        "--editorial-note",
+        "--editorial-code-surface"
+      ],
+      "requiredValidation": [
+        "long-form reading",
+        "code overflow",
+        "Arabic article rhythm",
+        "bilingual tables of contents"
+      ],
+      "translations": {
+        "ar": {
+          "name": "المورد التحريري",
+          "purpose": "مقالات الموارد والأدلة التقنية.",
+          "audience": [
+            "فرق التوثيق",
+            "ناشرو الأبحاث",
+            "الموارد التقنية"
+          ],
+          "visualDirection": "طباعة تضع القراءة أولا مع تنقل هادئ وملاحظات وكود ووسائط.",
+          "requiredValidation": [
+            "قراءة المحتوى الطويل",
+            "تجاوز الكود",
+            "إيقاع المقال العربي",
+            "جداول محتويات ثنائية اللغة"
+          ]
+        }
+      }
     },
     {
       "id": "application",
       "name": "Application Flow",
       "status": "planned",
       "purpose": "Forms, eligibility, conversion, and onboarding flows.",
-      "audience": ["applications", "onboarding", "eligibility and conversion flows"],
+      "audience": [
+        "applications",
+        "onboarding",
+        "eligibility and conversion flows"
+      ],
       "visualDirection": "Trustworthy step-by-step interaction with strong progress, validation, and recovery states.",
-      "semanticExtensions": ["--flow-progress", "--flow-validation", "--flow-review-surface"],
-      "requiredValidation": ["multi-step recovery", "localized validation", "Arabic forms", "RTL progress order"],
-      "translations": { "ar": { "name": "مسار التقديم", "purpose": "النماذج والأهلية والتحويل ومسارات الانضمام.", "audience": ["طلبات التقديم", "الانضمام", "مسارات الأهلية والتحويل"], "visualDirection": "تفاعل موثوق خطوة بخطوة مع حالات واضحة للتقدم والتحقق والاستعادة.", "requiredValidation": ["استعادة المسارات متعددة الخطوات", "تحقق موضّع", "نماذج عربية", "ترتيب تقدم RTL"] } }
+      "semanticExtensions": [
+        "--flow-progress",
+        "--flow-validation",
+        "--flow-review-surface"
+      ],
+      "requiredValidation": [
+        "multi-step recovery",
+        "localized validation",
+        "Arabic forms",
+        "RTL progress order"
+      ],
+      "translations": {
+        "ar": {
+          "name": "مسار التقديم",
+          "purpose": "النماذج والأهلية والتحويل ومسارات الانضمام.",
+          "audience": [
+            "طلبات التقديم",
+            "الانضمام",
+            "مسارات الأهلية والتحويل"
+          ],
+          "visualDirection": "تفاعل موثوق خطوة بخطوة مع حالات واضحة للتقدم والتحقق والاستعادة.",
+          "requiredValidation": [
+            "استعادة المسارات متعددة الخطوات",
+            "تحقق موضّع",
+            "نماذج عربية",
+            "ترتيب تقدم RTL"
+          ]
+        }
+      }
     }
   ],
   "arabicFriendly": {

package/data/templates/analytics-dashboard/AnalyticsDashboardBlocks.tsx

@@ -0,0 +1,107 @@
+import * as React from 'react'
+import { Button } from '@utopia-studio-design/design-system/Button'
+import {
+  ChartRoot,
+  type ChartAnnotationDefinition,
+  type ChartDatum,
+  type ChartSeriesDefinition,
+  type ChartState,
+  type ChartType,
+} from '@utopia-studio-design/design-system/Charts'
+import './analytics-dashboard.css'
+
+export {
+  KPIGrid,
+  type KPIGridProps,
+  type MetricDefinition,
+} from './AnalyticsMetricBlocks'
+
+export interface AnalyticsChartCardProps extends Omit<React.HTMLAttributes<HTMLElement>, 'title'> {
+  annotations?: ChartAnnotationDefinition[]
+  data: ChartDatum[]
+  description?: React.ReactNode
+  direction?: 'ltr' | 'rtl'
+  series: ChartSeriesDefinition[]
+  showDataTable?: boolean
+  state?: ChartState
+  title: React.ReactNode
+  type?: ChartType
+}
+
+export function AnalyticsChartCard({
+  annotations = [],
+  data,
+  description,
+  direction,
+  series,
+  showDataTable,
+  state,
+  title,
+  type,
+  ...props
+}: AnalyticsChartCardProps) {
+  return (
+    <ChartRoot
+      accessibleSummary={`${String(title)} across ${data.length} periods. Use the chart explorer or data table for exact values.`}
+      annotations={annotations}
+      axis={{ showGrid: true }}
+      data={data}
+      description={description}
+      direction={direction}
+      series={series}
+      showDataTable={showDataTable}
+      state={state}
+      title={title}
+      type={type}
+      {...props}
+    />
+  )
+}
+
+export interface ComparisonChartPanelProps extends AnalyticsChartCardProps {
+  benchmarkLabel?: string
+  benchmarkValue?: number
+}
+
+export function ComparisonChartPanel({
+  benchmarkLabel = 'Target',
+  benchmarkValue,
+  annotations = [],
+  ...props
+}: ComparisonChartPanelProps) {
+  const nextAnnotations = benchmarkValue === undefined
+    ? annotations
+    : [
+        ...annotations,
+        { id: 'benchmark', label: benchmarkLabel, value: benchmarkValue, tone: 'neutral' as const },
+      ]
+  return <AnalyticsChartCard annotations={nextAnnotations} {...props} />
+}
+
+export function ChartWithDataTable(props: AnalyticsChartCardProps) {
+  return <AnalyticsChartCard {...props} showDataTable />
+}
+
+export interface AnalyticsDashboardHeaderProps extends React.HTMLAttributes<HTMLElement> {
+  onRefresh?: () => void
+  periodLabel: string
+  title: string
+}
+
+export function AnalyticsDashboardHeader({
+  onRefresh,
+  periodLabel,
+  title,
+  ...props
+}: AnalyticsDashboardHeaderProps) {
+  return (
+    <header className="ceramic-analytics-header" {...props}>
+      <div>
+        <span>Analytics dashboard</span>
+        <h1>{title}</h1>
+        <p>{periodLabel}</p>
+      </div>
+      <Button variant="outline" onClick={onRefresh}>Refresh data</Button>
+    </header>
+  )
+}

package/data/templates/analytics-dashboard/AnalyticsMetricBlocks.tsx

@@ -0,0 +1,87 @@
+import * as React from 'react'
+import { Badge } from '@utopia-studio-design/design-system/Badge'
+import type { ChartState } from '@utopia-studio-design/design-system/Charts'
+import './analytics-dashboard.css'
+
+export interface MetricDefinition {
+  change?: number
+  changeLabel?: string
+  format?: 'number' | 'percent' | 'currency'
+  id: string
+  label: string
+  value: number
+}
+
+export interface KPIGridProps extends React.HTMLAttributes<HTMLDivElement> {
+  currency?: string
+  density?: 'compact' | 'default' | 'comfortable'
+  locale?: string
+  metrics: MetricDefinition[]
+  state?: ChartState
+}
+
+export function KPIGrid({
+  className,
+  currency = 'USD',
+  density = 'default',
+  locale,
+  metrics,
+  state = metrics.length === 0 ? 'empty' : 'ready',
+  ...props
+}: KPIGridProps) {
+  const formatMetric = (metric: MetricDefinition) => {
+    if (metric.format === 'percent') {
+      return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: 1 }).format(metric.value)
+    }
+    if (metric.format === 'currency') {
+      return new Intl.NumberFormat(locale, {
+        style: 'currency',
+        currency,
+        notation: 'compact',
+        maximumFractionDigits: 1,
+      }).format(metric.value)
+    }
+    return new Intl.NumberFormat(locale, { notation: 'compact', maximumFractionDigits: 1 }).format(metric.value)
+  }
+
+  return (
+    <section
+      aria-busy={state === 'loading'}
+      aria-label="Key performance indicators"
+      className={['ceramic-kpi-grid', className].filter(Boolean).join(' ')}
+      data-density={density}
+      data-state={state}
+      {...props}
+    >
+      {state === 'loading' ? (
+        <>
+          {[0, 1, 2].map((item) => <span aria-hidden="true" className="ceramic-kpi-skeleton" key={item} />)}
+          <span className="uds-visually-hidden" role="status">Loading metrics…</span>
+        </>
+      ) : null}
+      {state === 'empty' ? (
+        <div className="ceramic-kpi-state" role="status">
+          <strong>No metrics available</strong>
+          <span>Choose another period or data source.</span>
+        </div>
+      ) : null}
+      {state === 'error' ? (
+        <div className="ceramic-kpi-state" role="alert">
+          <strong>Metrics unavailable</strong>
+          <span>Reconnect the data source and try again.</span>
+        </div>
+      ) : null}
+      {state === 'ready' || state === 'partial' ? metrics.map((metric) => (
+        <article className="ceramic-kpi" key={metric.id}>
+          <span>{metric.label}</span>
+          <strong>{formatMetric(metric)}</strong>
+          {metric.change !== undefined ? (
+            <Badge variant="outline">
+              {metric.change > 0 ? '+' : ''}{metric.change.toFixed(1)}% {metric.changeLabel ?? 'vs previous'}
+            </Badge>
+          ) : <span className="ceramic-kpi-unavailable">No comparison</span>}
+        </article>
+      )) : null}
+    </section>
+  )
+}

package/data/templates/analytics-dashboard/README.md

@@ -0,0 +1,6 @@
+# Ceramic analytics dashboard
+
+Runnable integration template for the Ceramic Charts system. It demonstrates all
+chart families, governed data states, semantic series, keyboard exploration,
+RTL, light/dark modes, benchmark annotations, KPI blocks, and an accessible data
+table alternative.