@mohammad-irfan/create-dashboard-kit 1.0.0

package/templates/source/components/metrics/StatCard.tsx

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react'
+
+export interface StatCardProps {
+  label: string
+  value: ReactNode
+  icon?: ReactNode
+  iconClassName?: string
+  hint?: ReactNode
+  onClick?: () => void
+  className?: string
+}
+
+export function StatCard({
+  label,
+  value,
+  icon,
+  iconClassName,
+  hint,
+  onClick,
+  className = '',
+}: StatCardProps) {
+  return (
+    <div
+      onClick={onClick}
+      className={`group rounded-2xl border border-border/40 bg-surface dark:bg-surface-elevated/40 p-5 shadow-2xs transition-all duration-200 hover:-translate-y-0.5 hover:border-primary/40 hover:shadow-md ${
+        onClick ? 'cursor-pointer' : ''
+      } ${className}`}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <p className="text-sm font-medium text-muted-foreground">{label}</p>
+          <p className="mt-2 text-3xl font-bold tracking-tight text-foreground tabular-nums group-hover:text-primary transition-colors">
+            {value}
+          </p>
+          {hint ? <p className="mt-1 text-xs text-muted-foreground/70">{hint}</p> : null}
+        </div>
+        {icon ? (
+          <span
+            className={`flex h-11 w-11 shrink-0 items-center justify-center rounded-xl transition-transform duration-200 group-hover:scale-105 ${
+              iconClassName ?? 'bg-primary/10 text-primary'
+            }`}
+          >
+            {icon}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/templates/source/components/navigation/NavItem.tsx

@@ -0,0 +1,75 @@
+import type { ComponentType, SVGProps } from 'react'
+import { renderNamedIcon } from '../icons/IconSet.tsx'
+
+export interface NavItemProps {
+  label: string
+  to: string
+  icon?: string | ComponentType<SVGProps<SVGSVGElement>>
+  badge?: string | number
+  active?: boolean
+  collapsed?: boolean
+  onClick?: () => void
+  className?: string
+}
+
+export function NavItem({
+  label,
+  to,
+  icon: IconComponent,
+  badge,
+  active = false,
+  collapsed = false,
+  onClick,
+  className = '',
+}: NavItemProps) {
+  const base = `group relative flex items-center rounded-full text-sm transition-all duration-150 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring ${
+    collapsed ? 'justify-center h-10 w-10 mx-auto' : 'gap-3.5 px-4 py-2.5 mx-2'
+  }`
+
+  const stateClass = active
+    ? `${base} bg-primary/12 font-medium text-primary shadow-2xs`
+    : `${base} font-normal text-muted-foreground hover:bg-muted/60 hover:text-foreground`
+
+  return (
+    <a
+      href={to}
+      onClick={(e) => {
+        if (onClick) {
+          e.preventDefault()
+          onClick()
+        }
+      }}
+      title={collapsed ? label : undefined}
+      aria-label={collapsed ? label : undefined}
+      aria-current={active ? 'page' : undefined}
+      className={`${stateClass} ${className}`}
+    >
+      {IconComponent ? (
+        typeof IconComponent === 'function' ? (
+          <IconComponent className="h-5 w-5 shrink-0" />
+        ) : typeof IconComponent === 'string' ? (
+          renderNamedIcon(IconComponent, { className: 'h-5 w-5 shrink-0' })
+        ) : (
+          <span className="h-5 w-5 shrink-0 flex items-center justify-center font-bold text-xs">
+            {IconComponent}
+          </span>
+        )
+      ) : null}
+
+      {!collapsed ? <span className="truncate">{label}</span> : null}
+
+      {badge !== undefined ? (
+        <span
+          aria-hidden="true"
+          className={`inline-flex items-center justify-center rounded-full bg-primary font-bold text-primary-foreground ${
+            collapsed
+              ? 'absolute -right-0.5 -top-0.5 h-4 min-w-4 px-1 text-[10px]'
+              : 'ml-auto h-5 min-w-5 px-1.5 text-xs'
+          }`}
+        >
+          {badge}
+        </span>
+      ) : null}
+    </a>
+  )
+}

package/templates/source/components/navigation/ShortcutPill.tsx

@@ -0,0 +1,39 @@
+import type { ComponentType, ReactNode, SVGProps } from 'react'
+
+export interface ShortcutPillProps {
+  label: string
+  to: string
+  icon?: ComponentType<SVGProps<SVGSVGElement>> | ReactNode
+  onClick?: () => void
+  className?: string
+}
+
+export function ShortcutPill({
+  label,
+  to,
+  icon: IconComponent,
+  onClick,
+  className = '',
+}: ShortcutPillProps) {
+  return (
+    <a
+      href={to}
+      onClick={(e) => {
+        if (onClick) {
+          e.preventDefault()
+          onClick()
+        }
+      }}
+      className={`inline-flex items-center gap-2 rounded-full border border-border/60 bg-surface dark:bg-surface-elevated/40 px-3.5 py-1.5 text-xs font-medium text-muted-foreground hover:border-primary/40 hover:bg-muted/60 hover:text-foreground transition-all shadow-2xs ${className}`}
+    >
+      {IconComponent ? (
+        typeof IconComponent === 'function' ? (
+          <IconComponent className="h-3.5 w-3.5 text-muted-foreground/80" />
+        ) : (
+          IconComponent
+        )
+      ) : null}
+      <span>{label}</span>
+    </a>
+  )
+}

package/templates/source/components/surfaces/EmptyState.tsx

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react'
+
+export interface EmptyStateProps {
+  title: string
+  description?: string
+  icon?: ReactNode
+  action?: ReactNode
+  className?: string
+}
+
+export function EmptyState({
+  title,
+  description,
+  icon,
+  action,
+  className = '',
+}: EmptyStateProps) {
+  return (
+    <div
+      className={`rounded-2xl border border-dashed border-border/70 bg-surface dark:bg-surface-elevated/40 p-10 sm:p-14 text-center shadow-2xs ${className}`}
+    >
+      {icon ? (
+        <div className="mx-auto mb-3 flex h-12 w-12 items-center justify-center rounded-full bg-primary/10 text-primary">
+          {icon}
+        </div>
+      ) : null}
+      <h3 className="text-base sm:text-lg font-bold text-foreground">{title}</h3>
+      {description ? (
+        <p className="mx-auto mt-1 max-w-md text-xs sm:text-sm text-muted-foreground leading-relaxed">
+          {description}
+        </p>
+      ) : null}
+      {action ? <div className="mt-5 flex flex-wrap items-center justify-center gap-3">{action}</div> : null}
+    </div>
+  )
+}

package/templates/source/components/surfaces/HeroSurface.tsx

@@ -0,0 +1,64 @@
+import type { ReactNode } from 'react'
+
+export interface HeroSurfaceProps {
+  greeting: string
+  title?: string
+  description?: string
+  statusContext?: ReactNode
+  actions?: ReactNode
+  illustration?: ReactNode
+  className?: string
+}
+
+export function HeroSurface({
+  greeting,
+  title,
+  description,
+  statusContext,
+  actions,
+  illustration,
+  className = '',
+}: HeroSurfaceProps) {
+  return (
+    <section
+      className={`relative overflow-hidden rounded-[28px] border border-border/40 bg-surface dark:bg-surface-elevated/70 p-8 sm:p-10 lg:p-12 shadow-2xs transition-colors ${className}`}
+    >
+      <div className="flex flex-col justify-between gap-8 lg:flex-row lg:items-center">
+        {/* LEFT COPY & ACTIONS */}
+        <div className="max-w-xl space-y-4">
+          <div className="space-y-2">
+            <h1 className="text-3xl font-bold tracking-tight text-foreground sm:text-4xl lg:text-4xl">
+              {greeting}
+            </h1>
+            {title ? (
+              <p className="text-lg font-medium text-foreground/90">{title}</p>
+            ) : null}
+            {description ? (
+              <p className="text-sm sm:text-base text-muted-foreground leading-relaxed">
+                {description}
+              </p>
+            ) : null}
+          </div>
+
+          {actions ? <div className="flex flex-wrap items-center gap-3 pt-2">{actions}</div> : null}
+
+          {statusContext ? (
+            <div className="pt-2 text-xs font-medium text-muted-foreground">
+              {statusContext}
+            </div>
+          ) : null}
+        </div>
+
+        {/* RIGHT ILLUSTRATION / GRAPHIC SLOT */}
+        {illustration ? (
+          <div
+            aria-hidden="true"
+            className="relative flex shrink-0 items-center justify-center select-none py-4 lg:py-0"
+          >
+            {illustration}
+          </div>
+        ) : null}
+      </div>
+    </section>
+  )
+}

package/templates/source/components/surfaces/Panel.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react'
+
+export interface PanelProps {
+  title: string
+  titleId?: string
+  icon?: ReactNode
+  action?: ReactNode
+  children: ReactNode
+  className?: string
+  bodyClassName?: string
+}
+
+export function Panel({
+  title,
+  titleId,
+  icon,
+  action,
+  children,
+  className = '',
+  bodyClassName = 'p-5',
+}: PanelProps) {
+  return (
+    <section
+      aria-labelledby={titleId}
+      className={`rounded-2xl border border-border bg-surface dark:bg-surface-elevated/50 shadow-2xs transition-colors ${className}`}
+    >
+      <div className="flex items-center justify-between gap-4 border-b border-border/40 px-5 py-4">
+        <div className="flex min-w-0 items-center gap-2.5">
+          {icon ? (
+            <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-xl bg-muted text-muted-foreground">
+              {icon}
+            </span>
+          ) : null}
+          <h2 id={titleId} className="truncate text-sm font-semibold text-foreground">
+            {title}
+          </h2>
+        </div>
+        {action}
+      </div>
+      <div className={bodyClassName}>{children}</div>
+    </section>
+  )
+}

package/templates/source/components/surfaces/PriorityCard.tsx

@@ -0,0 +1,75 @@
+import type { ReactNode } from 'react'
+import { SparklesIcon } from '../icons/IconSet.tsx'
+
+export interface PriorityCardProps {
+  heading?: string
+  badgeText?: string
+  badgeClassName?: string
+  icon?: ReactNode
+  title: string
+  subtitle?: string
+  description: string
+  action?: ReactNode
+  className?: string
+}
+
+export function PriorityCard({
+  heading = 'Next Best Action',
+  badgeText,
+  badgeClassName = 'border-primary/20 bg-primary/10 text-primary',
+  icon,
+  title,
+  subtitle,
+  description,
+  action,
+  className = '',
+}: PriorityCardProps) {
+  return (
+    <section className={`space-y-3 ${className}`}>
+      {/* SECTION HEADER WITH CIRCULAR ACCENT BADGE */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2.5">
+          <span
+            aria-hidden="true"
+            className="flex h-7 w-7 shrink-0 items-center justify-center rounded-full bg-primary/12 text-primary"
+          >
+            {icon || <SparklesIcon className="h-4 w-4" />}
+          </span>
+          <h2 className="text-sm font-semibold tracking-normal text-foreground">
+            {heading}
+          </h2>
+        </div>
+        {badgeText ? (
+          <span
+            className={`inline-flex items-center rounded-full border px-2.5 py-0.5 text-[11px] font-medium ${badgeClassName}`}
+          >
+            {badgeText}
+          </span>
+        ) : null}
+      </div>
+
+      {/* QUIET FEATURED CARD */}
+      <div className="rounded-2xl border border-border/40 bg-surface dark:bg-surface-elevated/60 p-6 shadow-2xs transition-colors">
+        <div className="flex flex-col justify-between gap-4 sm:flex-row sm:items-start">
+          <div className="space-y-2 min-w-0 max-w-xl">
+            <div>
+              <h3 className="text-base sm:text-lg font-bold text-foreground tracking-tight">
+                {title}
+              </h3>
+              {subtitle ? (
+                <p className="mt-0.5 text-xs font-medium text-muted-foreground">
+                  {subtitle}
+                </p>
+              ) : null}
+            </div>
+            <p className="text-xs sm:text-sm text-muted-foreground leading-relaxed">
+              {description}
+            </p>
+          </div>
+
+          {action ? <div className="shrink-0 pt-1 sm:pt-0">{action}</div> : null}
+        </div>
+      </div>
+    </section>
+  )
+}

package/templates/source/components/surfaces/QuietListCard.tsx

@@ -0,0 +1,146 @@
+import type { ReactNode } from 'react'
+
+export interface ListItemData {
+  id: string
+  title: string
+  subtitle?: string
+  avatarText?: string
+  avatarIcon?: ReactNode
+  statusBadge?: ReactNode
+  metaText?: string
+  action?: ReactNode
+  onClick?: () => void
+}
+
+export interface QuietListCardProps {
+  title: string
+  icon?: ReactNode
+  iconClassName?: string
+  viewAllLink?: {
+    label?: string
+    to: string
+    onClick?: () => void
+  }
+  items: ListItemData[]
+  emptyMessage?: string
+  emptySubtext?: string
+  emptyAction?: ReactNode
+  className?: string
+}
+
+export function QuietListCard({
+  title,
+  icon,
+  iconClassName = 'bg-primary/12 text-primary',
+  viewAllLink,
+  items,
+  emptyMessage = 'No items found',
+  emptySubtext = 'Get started by creating your first item.',
+  emptyAction,
+  className = '',
+}: QuietListCardProps) {
+  return (
+    <section className={`space-y-3 ${className}`}>
+      {/* SECTION HEADER */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2.5">
+          {icon ? (
+            <span
+              aria-hidden="true"
+              className={`flex h-7 w-7 shrink-0 items-center justify-center rounded-full ${iconClassName}`}
+            >
+              {icon}
+            </span>
+          ) : null}
+          <h2 className="text-sm font-semibold tracking-normal text-foreground">
+            {title}
+          </h2>
+        </div>
+
+        {viewAllLink ? (
+          <a
+            href={viewAllLink.to}
+            onClick={(e) => {
+              if (viewAllLink.onClick) {
+                e.preventDefault()
+                viewAllLink.onClick()
+              }
+            }}
+            className="inline-flex items-center gap-1 text-xs font-semibold text-primary hover:text-primary/80 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring rounded-md px-1 py-0.5"
+          >
+            <span>{viewAllLink.label || 'View all'}</span>
+            <span aria-hidden="true">→</span>
+          </a>
+        ) : null}
+      </div>
+
+      {/* QUIET LIST CONTAINER */}
+      <div className="rounded-2xl border border-border/40 bg-surface dark:bg-surface-elevated/60 shadow-2xs overflow-hidden transition-colors">
+        {items.length === 0 ? (
+          <div className="p-8 text-center">
+            {icon ? (
+              <div className="mx-auto mb-3 flex h-10 w-10 items-center justify-center rounded-full bg-muted text-muted-foreground">
+                {icon}
+              </div>
+            ) : null}
+            <p className="text-sm font-semibold text-foreground">{emptyMessage}</p>
+            {emptySubtext ? (
+              <p className="mt-1 text-xs text-muted-foreground max-w-sm mx-auto">
+                {emptySubtext}
+              </p>
+            ) : null}
+            {emptyAction ? <div className="mt-4">{emptyAction}</div> : null}
+          </div>
+        ) : (
+          <ul className="divide-y divide-border/30">
+            {items.map((item) => (
+              <li
+                key={item.id}
+                onClick={item.onClick}
+                className={`group flex flex-col justify-between gap-3 px-5 py-3.5 hover:bg-muted/30 transition-colors sm:flex-row sm:items-center ${
+                  item.onClick ? 'cursor-pointer' : ''
+                }`}
+              >
+                <div className="flex items-center gap-3.5 min-w-0 flex-1">
+                  {item.avatarText ? (
+                    <span
+                      aria-hidden="true"
+                      className="flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-muted/60 text-xs font-bold text-foreground border border-border/40 group-hover:border-primary/40 group-hover:bg-primary/10 group-hover:text-primary transition-colors"
+                    >
+                      {item.avatarText}
+                    </span>
+                  ) : item.avatarIcon ? (
+                    <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-xl bg-muted/60 text-muted-foreground border border-border/40">
+                      {item.avatarIcon}
+                    </span>
+                  ) : null}
+
+                  <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-semibold text-foreground">
+                      {item.title}
+                    </p>
+                    {item.subtitle ? (
+                      <p className="truncate text-xs text-muted-foreground">
+                        {item.subtitle}
+                      </p>
+                    ) : null}
+                  </div>
+                </div>
+
+                <div className="flex shrink-0 items-center justify-between gap-3 sm:gap-4 pl-12 sm:pl-0">
+                  {item.statusBadge}
+                  {item.metaText ? (
+                    <span className="text-xs tabular-nums text-muted-foreground/80 whitespace-nowrap">
+                      {item.metaText}
+                    </span>
+                  ) : null}
+                  {item.action}
+                </div>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </section>
+  )
+}

package/templates/source/design-system/animations.css

@@ -0,0 +1,25 @@
+/* ============================================================================
+ * Dashboard Starter Kit — Animations & Transitions
+ * ============================================================================
+ */
+
+/* Theme-flip cross-fade easing (~200ms) */
+@media (prefers-reduced-motion: no-preference) {
+  .theme-transition {
+    transition-property: background-color, border-color, color, fill, stroke, box-shadow, outline-color;
+    transition-duration: 200ms;
+    transition-timing-function: ease;
+  }
+}
+
+/* Reusable utility to hide visible scrollbars while preserving scrolling */
+.no-scrollbar,
+.scrollbar-none {
+  -ms-overflow-style: none;
+  scrollbar-width: none;
+}
+
+.no-scrollbar::-webkit-scrollbar,
+.scrollbar-none::-webkit-scrollbar {
+  display: none;
+}

package/templates/source/design-system/tokens.css

@@ -0,0 +1,74 @@
+/* ============================================================================
+ * Dashboard Starter Kit — Design Tokens
+ * ============================================================================
+ * Single source of truth for semantic color tokens across Light & Dark modes.
+ * Mapped to Tailwind color utilities via `@theme inline` so components consume
+ * `bg-surface`, `text-foreground`, `border-border`, `bg-primary`, etc.
+ */
+
+:root,
+[data-theme="light"] {
+  --background: #f4f5f7;
+  --foreground: #0f172a;
+  --muted-foreground: #64748b;
+  --surface: #ffffff;
+  --surface-elevated: #ffffff;
+  --muted: #eef1f4;
+  --border: #e3e7ec;
+  --input: #ffffff;
+  --canvas-background: #eef3fb;
+
+  /* Brand Primary */
+  --primary: #2563eb;
+  --primary-foreground: #ffffff;
+  --ring: #2563eb;
+
+  /* Semantic Feedback */
+  --success: #059669;
+  --success-fg: #047857;
+  --success-bg: #ecfdf5;
+  --warning: #d97706;
+  --warning-fg: #b45309;
+  --warning-bg: #fffbeb;
+  --danger: #dc2626;
+  --danger-fg: #b91c1c;
+  --danger-bg: #fef2f2;
+  --info: #0284c7;
+  --info-fg: #0369a1;
+  --info-bg: #f0f9ff;
+
+  color-scheme: light;
+}
+
+[data-theme="dark"] {
+  --background: #0b0c0e;
+  --foreground: #f3f5f7;
+  --muted-foreground: #9aa4b2;
+  --surface: #151719;
+  --surface-elevated: #1c1f22;
+  --muted: #22262b;
+  --border: #2a2f35;
+  --input: #1a1a1a;
+  --canvas-background: #181a1f;
+
+  /* Brand Primary */
+  --primary: #3b82f6;
+  --primary-foreground: #ffffff;
+  --ring: #3b82f6;
+
+  /* Semantic Feedback */
+  --success: #10b981;
+  --success-fg: #6ee7b7;
+  --success-bg: rgba(16, 185, 129, 0.15);
+  --warning: #f59e0b;
+  --warning-fg: #fcd34d;
+  --warning-bg: rgba(245, 158, 11, 0.15);
+  --danger: #ef4444;
+  --danger-fg: #fca5a5;
+  --danger-bg: rgba(239, 68, 68, 0.15);
+  --info: #38bdf8;
+  --info-fg: #7dd3fc;
+  --info-bg: rgba(56, 189, 248, 0.15);
+
+  color-scheme: dark;
+}

package/templates/source/design-system/typography.css

@@ -0,0 +1,34 @@
+/* ============================================================================
+ * Dashboard Starter Kit — Typography System
+ * ============================================================================
+ * Standard typographic rules, line heights, and tabular layout utilities.
+ */
+
+/* Antialiasing for crisp text rendering across dark/light themes */
+.dashboard-font-base {
+  font-family: 'DM Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+/* Numeric tabular display ensures uniform number column widths */
+.tabular-nums {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Heading letter-spacing tokens */
+.tracking-tight {
+  letter-spacing: -0.025em;
+}
+
+.tracking-tighter {
+  letter-spacing: -0.05em;
+}
+
+.tracking-wide {
+  letter-spacing: 0.025em;
+}
+
+.tracking-wider {
+  letter-spacing: 0.05em;
+}