create-tanqory-theme 0.0.0-stage → 0.2.2

package/templates/nova/src/components/states/Alert.css

@@ -0,0 +1,10 @@
+/* Nova 13 · 12 Alert — 3px inline-start rule, radius 8, icon + title + text. */
+.nv-alert { --nv-tone: var(--color-info); --nv-tone-bg: var(--color-info-surface); display: flex; align-items: flex-start; gap: var(--space-3); padding: var(--space-3) var(--space-4); border-inline-start: 3px solid var(--nv-tone); border-radius: var(--overlay-radius-alert); background: var(--nv-tone-bg); color: var(--nv-tone); font-size: 0.875rem; line-height: 1.45; }
+.nv-alert[data-tone='success'] { --nv-tone: var(--color-success); --nv-tone-bg: var(--color-success-surface); }
+.nv-alert[data-tone='warning'] { --nv-tone: var(--color-warning-ink); --nv-tone-bg: var(--color-warning-surface); }
+.nv-alert[data-tone='error'] { --nv-tone: var(--color-danger); --nv-tone-bg: var(--color-danger-surface); }
+.nv-alert__icon { flex: none; margin-block-start: 1px; }
+.nv-alert__text { flex: 1; min-width: 0; }
+.nv-alert__title { font-weight: var(--weight-medium); }
+.nv-alert__action { flex: none; min-height: 24px; padding: 0; border: 0; background: none; color: inherit; font: inherit; font-weight: var(--weight-medium); text-decoration: underline; text-underline-offset: var(--underline-offset); cursor: pointer; }
+.nv-alert__dismiss { flex: none; width: 32px; height: 32px; margin: -6px -8px -6px 0; color: inherit; }

package/templates/nova/src/components/states/Alert.tsx

@@ -0,0 +1,50 @@
+import type { ReactNode } from 'react'
+import { Icon, type IconName } from '../../styles/Icon'
+import { IconButton } from '../base/IconButton'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import './Alert.css'
+
+export type FeedbackTone = 'info' | 'success' | 'warning' | 'error'
+
+/** Every status carries an icon and a word — colour is a third signal, never the only one. */
+export const TONE_ICON: Record<FeedbackTone, IconName> = { info: 'info', success: 'check', warning: 'warning', error: 'error' }
+
+export interface AlertProps {
+  tone: FeedbackTone
+  title: string
+  children?: ReactNode
+  /** One way forward ("Try another card"). */
+  action?: { label: string; href?: string; onClick?: () => void }
+  /** Alerts persist unless marked dismissible. */
+  onDismiss?: () => void
+}
+
+/**
+ * Nova 13 · 12 Alert — inline, in the page: a 3px rule at the inline-start,
+ * icon + title + text, radius 8, the tone's surface. Persistent unless
+ * dismissible. Errors use role=alert; the others are quiet (no live region).
+ */
+export function Alert({ tone, title, children, action, onDismiss }: AlertProps): JSX.Element {
+  const { strings } = useNova()
+  return (
+    <div className="nv-alert" data-tone={tone} role={tone === 'error' ? 'alert' : undefined}>
+      <Icon name={TONE_ICON[tone]} size="sm" className="nv-alert__icon" />
+      <div className="nv-alert__text">
+        <p className="nv-alert__title">{title}</p>
+        {children && <div className="nv-alert__body">{children}</div>}
+      </div>
+      {action &&
+        (action.href ? (
+          <a className="nv-alert__action" href={action.href}>
+            {action.label}
+          </a>
+        ) : (
+          <button type="button" className="nv-alert__action" onClick={action.onClick}>
+            {action.label}
+          </button>
+        ))}
+      {onDismiss && <IconButton icon="close" label={fmt(strings.dismissNamed, { name: title })} onClick={onDismiss} className="nv-alert__dismiss" />}
+    </div>
+  )
+}

package/templates/nova/src/components/states/EditorFrame.css

@@ -0,0 +1,31 @@
+.nv-editor-frame {
+  position: relative;
+  display: grid;
+  justify-items: center;
+  gap: var(--space-1);
+  padding: var(--space-7) var(--space-5);
+  border: 1px dashed var(--color-editor-frame);
+  border-radius: var(--radius-sm);
+  background: repeating-linear-gradient(-45deg, var(--color-bg-muted) 0 12px, var(--color-bg) 12px 24px);
+  color: var(--color-fg);
+  text-align: center;
+}
+.nv-editor-frame[data-compact] { padding-block: var(--space-3); }
+.nv-editor-frame__chip {
+  position: absolute;
+  top: -1px;
+  inset-inline-start: -1px;
+  padding: 3px var(--space-2);
+  border-radius: var(--radius-sm) 0 var(--radius-sm) 0;
+  background: var(--color-fg);
+  color: var(--color-bg);
+  font-family: var(--font-mono);
+  font-size: 11px;
+  font-weight: var(--weight-medium);
+  line-height: 1.3;
+  text-transform: uppercase;
+}
+.nv-editor-frame__chip[data-inline] { position: static; display: inline-block; border-radius: var(--radius-sm); }
+.nv-editor-frame__title { font-weight: var(--weight-medium); }
+.nv-editor-frame__hint { font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+.nv-editor-frame__action { margin-top: var(--space-3); }

package/templates/nova/src/components/states/EditorFrame.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from 'react'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import './EditorFrame.css'
+
+/**
+ * Nova 14 · Editor setup state — the neutral striped frame an EMPTY section
+ * shows in the editor canvas (never on the storefront, where it renders
+ * nothing). Neutral on purpose (Round 2 · D3): no hue, so it is never
+ * mistaken for info, brand, error or focus. The chip names the section.
+ */
+export interface EditorFrameProps {
+  section: string
+  title: string
+  hint?: string
+  action?: ReactNode
+  /** Compact frames sit inside chrome (announcement bar). */
+  compact?: boolean
+}
+
+export function EditorFrame({ section, title, hint, action, compact }: EditorFrameProps): JSX.Element {
+  const { strings } = useNova()
+  return (
+    <div className="nv-editor-frame" data-compact={compact ? '' : undefined}>
+      <span className="nv-editor-frame__chip">{fmt(strings.editorChip, { section })}</span>
+      <p className="nv-editor-frame__title">{title}</p>
+      {hint && <p className="nv-editor-frame__hint">{hint}</p>}
+      {action && <div className="nv-editor-frame__action">{action}</div>}
+    </div>
+  )
+}
+
+/** The chip alone — marks sample content rendered only in the editor. */
+export function EditorChip({ section }: { section: string }): JSX.Element {
+  const { strings } = useNova()
+  return <span className="nv-editor-frame__chip" data-inline="">{fmt(strings.editorChip, { section })}</span>
+}
+
+export function useIsEditor(): boolean {
+  return useNova().mode === 'editor'
+}
+
+export type { ReactNode }

package/templates/nova/src/components/states/MediaState.css

@@ -0,0 +1 @@
+.nv-media-state { display: grid; gap: var(--space-2); justify-items: start; }

package/templates/nova/src/components/states/MediaState.tsx

@@ -0,0 +1,49 @@
+import { Button } from '../base/Button'
+import { useNova } from '../../styles/NovaProvider'
+import { MediaError } from './media/MediaError'
+import { EditorFrame } from './EditorFrame'
+import './MediaState.css'
+
+export type MediaStateReason = 'missing' | 'failed' | 'unsupported' | 'unconfigured' | 'video-unavailable'
+
+export interface MediaStateProps {
+  reason: MediaStateReason
+  ratio?: string
+  /** What the media showed (the product name) — written in the tile when the grid needs one. */
+  label?: string
+  showLabel?: boolean
+  /** The editor action (Choose image · Replace file). */
+  onAction?: () => void
+  /** The section / block this slot belongs to, for the editor chip. */
+  section?: string
+}
+
+/**
+ * Nova 14 · 14.1 — one decision per media slot, shopper and editor apart:
+ *   missing / failed   shoppers: a neutral tile (or the parent collapses);
+ *                      editor: the tile + "This image is no longer available"
+ *   unsupported        shoppers: treated as missing; editor: "This file type
+ *                      can't be shown" + Replace file
+ *   unconfigured       shoppers: never rendered; editor: "Add an image" +
+ *                      Choose image
+ *   video-unavailable  both: dimmed artwork, slashed play, "Video unavailable"
+ * Dashed EDITOR frames exist only in the editor — the storefront never shows setup.
+ */
+export function MediaState({ reason, ratio = '4 / 3', label, showLabel, onAction, section = 'image' }: MediaStateProps): JSX.Element | null {
+  const { mode, strings } = useNova()
+  const editor = mode === 'editor'
+  if (reason === 'unconfigured') {
+    if (!editor) return null
+    return <EditorFrame section={section} title={strings.editorImage} hint={strings.imageRecommendation} action={onAction && <Button size="sm" onClick={onAction}>{strings.chooseImage}</Button>} />
+  }
+  if (reason === 'unsupported' && editor) {
+    return <EditorFrame section={section} title={strings.fileTypeUnsupported} hint={strings.fileTypeHint} action={onAction && <Button size="sm" onClick={onAction}>{strings.replaceFile}</Button>} />
+  }
+  if (reason === 'video-unavailable') return <MediaError reason="video-unavailable" ratio={ratio} label={label} />
+  return (
+    <span className="nv-media-state">
+      <MediaError reason={reason === 'unsupported' ? 'missing' : reason} ratio={ratio} label={label} showLabel={showLabel} />
+      {editor && reason === 'failed' && <span className="nv-editor-frame__chip" data-inline="">{strings.editorImageUnavailable}</span>}
+    </span>
+  )
+}

package/templates/nova/src/components/states/OfflineNotice.css

@@ -0,0 +1,4 @@
+.nv-offline { position: fixed; inset-block-end: var(--space-6); inset-inline-start: var(--space-6); z-index: var(--z-toast); display: flex; align-items: center; gap: var(--space-3); width: min(440px, calc(100vw - 2 * var(--space-6))); padding: var(--space-3) var(--space-4); border-radius: var(--overlay-radius-toast); background: var(--color-bg-inverse); color: var(--color-fg-inverse); box-shadow: var(--overlay-toast-shadow); font-size: 0.875rem; }
+.nv-offline__text { flex: 1; }
+.nv-offline__retry { min-height: 32px; padding: 0; border: 0; background: none; color: inherit; font: inherit; font-weight: var(--weight-medium); text-decoration: underline; text-underline-offset: var(--underline-offset); cursor: pointer; }
+@media (max-width: 639.98px) { .nv-offline { inset-inline: 12px; inset-block-end: calc(12px + var(--nv-toast-lift, 0px)); width: auto; } }

package/templates/nova/src/components/states/OfflineNotice.tsx

@@ -0,0 +1,24 @@
+import { Icon } from '../../styles/Icon'
+import { useNova } from '../../styles/NovaProvider'
+import './OfflineNotice.css'
+
+/**
+ * Nova 14 · 14.5 offline — a toast-style bar at the bottom start: "No
+ * connection. Changes will sync when you're back." + Retry. Cart actions
+ * queue once, then fail with an alert; there is no offline app mode. The
+ * inline, section-level variant is an Alert (warning) "You're offline".
+ */
+export function OfflineNotice({ onRetry }: { onRetry?: () => void }): JSX.Element {
+  const { strings } = useNova()
+  return (
+    <div className="nv-offline" role="status">
+      <Icon name="wifi" size="sm" />
+      <p className="nv-offline__text">{strings.offlineSync}</p>
+      {onRetry && (
+        <button type="button" className="nv-offline__retry" onClick={onRetry}>
+          {strings.retry}
+        </button>
+      )}
+    </div>
+  )
+}

package/templates/nova/src/components/states/SkeletonLayout.css

@@ -0,0 +1,22 @@
+.nv-sk { width: 100%; }
+.nv-sk__grid { display: grid; grid-template-columns: repeat(var(--nv-sk-cols), minmax(0, 1fr)); gap: var(--card-gap-y) var(--card-gap-x); list-style: none; margin: 0; padding: 0; }
+.nv-sk__card { display: grid; gap: var(--space-1); }
+.nv-sk__card > .nv-skeleton[data-shape='media'] { margin-block-end: var(--space-2); }
+.nv-sk__stack { display: grid; gap: var(--space-2); align-content: start; }
+.nv-sk__block { display: block; height: 44px; border-radius: var(--radius-md); background: var(--color-skeleton, var(--color-bg-muted)); }
+.nv-sk__block[data-h='52'] { height: 52px; }
+.nv-sk__block[data-h='40'] { height: 40px; }
+.nv-sk__block[data-h='36'] { height: 36px; width: 7rem; }
+[data-slow] .nv-sk__block { animation: nv-skeleton-pulse 1.2s ease-in-out infinite; }
+@media (prefers-reduced-motion: reduce) { [data-slow] .nv-sk__block { animation: none; } }
+.nv-sk__pdp { display: grid; grid-template-columns: minmax(0, 1.2fr) minmax(0, 1fr); gap: var(--space-7); }
+.nv-sk__rows { display: grid; gap: var(--space-4); list-style: none; margin: 0; padding: 0; }
+.nv-sk__rows li { display: grid; grid-template-columns: 44px minmax(0, 1fr) 4rem; gap: var(--space-3); align-items: center; }
+.nv-sk__rows[data-kind='cart'] li { grid-template-columns: 92px minmax(0, 1fr); align-items: start; }
+.nv-sk__article { display: grid; gap: var(--space-4); max-width: var(--container-content); }
+@media (max-width: 1023.98px) { .nv-sk__grid { grid-template-columns: repeat(min(var(--nv-sk-cols), 3), minmax(0, 1fr)); } }
+@media (max-width: 639.98px) {
+  .nv-sk__grid { grid-template-columns: repeat(2, minmax(0, 1fr)); }
+  .nv-sk__pdp { grid-template-columns: minmax(0, 1fr); gap: var(--space-5); }
+}
+.nv-sk__block[data-w='70'] { width: 70%; }

package/templates/nova/src/components/states/SkeletonLayout.tsx

@@ -0,0 +1,104 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import { useEffect, useState, type CSSProperties } from 'react'
+import { Skeleton } from '../base/Skeleton'
+import { useNova } from '../../styles/NovaProvider'
+import { fmt } from '../../styles/strings'
+import './SkeletonLayout.css'
+
+export type SkeletonKind = 'product-grid' | 'pdp' | 'search' | 'cart' | 'article' | 'row'
+
+export interface SkeletonLayoutProps {
+  kind: SkeletonKind
+  /** Cards / rows to draw (grid, search, cart, row). */
+  count?: number
+  /** Grid / row columns. */
+  columns?: number
+  /** What is loading, for the one announcement ("Loading products"). */
+  name: string
+  /** Start already slow (stories): the pulse normally begins after 1s. */
+  slow?: boolean
+}
+
+/** Waits over this long get the quiet pulse. */
+export const SLOW_AFTER_MS = 1000
+
+/**
+ * Nova 14 · 14.2 skeleton families — the loading shape of each surface at
+ * its final geometry, so nothing jumps when content arrives: product grid ·
+ * PDP · search results · cart lines · article · recommendations row. Loading
+ * is never artwork. aria-busy with one polite "Loading …".
+ */
+export function SkeletonLayout({ kind, count, columns = 4, name, slow: startSlow = false }: SkeletonLayoutProps): JSX.Element {
+  const { strings } = useNova()
+  const [slow, setSlow] = useState(startSlow)
+  useEffect(() => {
+    if (startSlow) return
+    const t = window.setTimeout(() => setSlow(true), SLOW_AFTER_MS)
+    return () => window.clearTimeout(t)
+  }, [startSlow])
+  const n = count ?? (kind === 'product-grid' ? columns * 2 : kind === 'row' ? columns : 3)
+  const card = (i: number) => (
+    <li key={i} className="nv-sk__card">
+      <Skeleton shape="media" />
+      <Skeleton width="70%" />
+      <Skeleton width="35%" />
+    </li>
+  )
+  let body
+  switch (kind) {
+    case 'product-grid':
+    case 'row':
+      body = <ul className="nv-sk__grid">{Array.from({ length: n }, (_, i) => card(i))}</ul>
+      break
+    case 'pdp':
+      body = (
+        <div className="nv-sk__pdp">
+          <Skeleton shape="media" ratio="4 / 5" />
+          <div className="nv-sk__stack">
+            <Skeleton width="30%" />
+            <Skeleton width="80%" />
+            <Skeleton width="25%" />
+            <span className="nv-sk__block" data-h="44" />
+            <span className="nv-sk__block" data-h="52" />
+          </div>
+        </div>
+      )
+      break
+    case 'search':
+    case 'cart':
+      body = (
+        <ul className="nv-sk__rows" data-kind={kind}>
+          {Array.from({ length: n }, (_, i) => (
+            <li key={i}>
+              <Skeleton shape="media" ratio="1 / 1" />
+              <span className="nv-sk__stack">
+                <Skeleton width="65%" />
+                {kind === 'cart' && <Skeleton width="35%" />}
+                {kind === 'cart' && <span className="nv-sk__block" data-h="36" />}
+              </span>
+              {kind === 'search' && <Skeleton width="100%" />}
+            </li>
+          ))}
+        </ul>
+      )
+      break
+    case 'article':
+      body = (
+        <div className="nv-sk__article">
+          <Skeleton width="20%" />
+          <span className="nv-sk__block" data-h="40" data-w="70" />
+          <Skeleton shape="media" ratio="16 / 9" />
+          <Skeleton lines={3} />
+        </div>
+      )
+      break
+  }
+  return (
+    <div className={sxJoin("nv-sk", sx({ '--nv-sk-cols': columns } as CSSProperties))} data-kind={kind} data-slow={slow ? '' : undefined} aria-busy="true">
+      <span className="nv-visually-hidden" role="status">
+        {fmt(strings.loadingNamed, { name })}
+      </span>
+      {body}
+    </div>
+  )
+}

package/templates/nova/src/components/states/StateBlock.css

@@ -0,0 +1,22 @@
+.nv-state {
+  display: grid;
+  justify-items: center;
+  gap: var(--space-1);
+  padding: var(--space-6) var(--space-5);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-muted);
+  text-align: center;
+}
+.nv-state__title { font-weight: var(--weight-medium); margin-top: var(--space-2); }
+.nv-state__desc { font-size: var(--type-body-sm); color: var(--color-fg-muted); }
+.nv-state__action { margin-top: var(--space-3); }
+.nv-state[data-variant='error'] { background: var(--color-danger-surface); color: var(--color-danger); }
+.nv-state[data-variant='error'] .nv-state__desc { color: var(--color-danger); }
+.nv-state[data-variant='loading'] { background: var(--color-bg); box-shadow: inset 0 0 0 1px var(--color-border); }
+
+/* Nova 14 · 14.4 page-level error and 14.3 unavailable resource: the page keeps its header and footer. */
+.nv-state[data-variant='page-error'], .nv-state[data-variant='unavailable'] { gap: var(--space-2); padding: var(--space-8) var(--space-5); background: none; }
+.nv-state[data-variant='page-error'] .nv-state__title, .nv-state[data-variant='unavailable'] .nv-state__title { font-size: 1.25rem; }
+.nv-state[data-variant='page-error'] > .nv-icon { color: var(--color-danger); }
+.nv-state[data-variant='unavailable'] > .nv-icon { color: var(--color-fg-muted); }
+.nv-state__action { display: flex; flex-wrap: wrap; justify-content: center; gap: var(--space-2); }

package/templates/nova/src/components/states/StateBlock.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react'
+import { Icon } from '../../styles/Icon'
+import { Spinner } from '../base/Spinner'
+import './StateBlock.css'
+
+/**
+ * Nova 02 · 14 StateBlock — empty · error · loading, plus Nova 14's
+ * page-error (a page-level 500: Try again + Go to home) and unavailable (a
+ * resource that is gone: "This product is no longer available" + one way
+ * on). Title + one line + one action (page-error may add a secondary). Every
+ * status carries an icon AND a word — colour is the third signal. Errors are
+ * announced (role=alert); loading is a polite status.
+ */
+export interface StateBlockProps {
+  variant: 'empty' | 'error' | 'loading' | 'page-error' | 'unavailable'
+  title: string
+  description?: string
+  action?: ReactNode
+  /** page-error only: the second way out (Go to home). */
+  secondaryAction?: ReactNode
+}
+
+const ICON = { empty: 'search', error: 'error', 'page-error': 'error', unavailable: 'info' } as const
+
+export function StateBlock({ variant, title, description, action, secondaryAction }: StateBlockProps): JSX.Element {
+  return (
+    <div className="nv-state" data-variant={variant} role={variant === 'error' || variant === 'page-error' ? 'alert' : variant === 'loading' ? 'status' : undefined}>
+      {variant === 'loading' ? <Spinner /> : <Icon name={ICON[variant]} size="md" />}
+      <p className="nv-state__title">{title}</p>
+      {description && <p className="nv-state__desc">{description}</p>}
+      {action && variant !== 'loading' && (
+        <div className="nv-state__action">
+          {action}
+          {variant === 'page-error' && secondaryAction}
+        </div>
+      )}
+    </div>
+  )
+}

package/templates/nova/src/components/states/media/MediaError.css

@@ -0,0 +1,6 @@
+.nv-media-error { position: relative; display: grid; place-items: center; width: 100%; overflow: hidden; background: var(--color-media-bg); color: var(--color-fg-subtle); }
+.nv-media-error[data-rounded] { border-radius: var(--radius-media); }
+.nv-media-error__name { padding: var(--space-4); color: var(--color-fg-muted); font-size: var(--type-body-sm); text-align: center; }
+.nv-media-error[data-reason='video-unavailable'] { place-items: stretch; background: none; }
+.nv-media-error[data-reason='video-unavailable'] > .nv-placeholder { position: absolute; inset: 0; height: 100%; }
+.nv-media-error__text { position: absolute; inset-block-end: var(--space-3); inset-inline-start: var(--space-3); padding: var(--space-1) var(--space-2); border-radius: var(--radius-sm); background: var(--color-bg); color: var(--color-fg); font-size: var(--type-caption); }

package/templates/nova/src/components/states/media/MediaError.tsx

@@ -0,0 +1,49 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties } from 'react'
+import { Icon } from '../../../styles/Icon'
+import { useNova } from '../../../styles/NovaProvider'
+import { MediaPlaceholder } from './MediaPlaceholder'
+import './MediaError.css'
+
+/**
+ * Missing / failed media for shoppers (Nova 02 · Nova 14 · 14.1) — a neutral
+ * tile at the ratio the media would have had, so nothing shifts. Decorative
+ * by default; `label` names what is missing, and `showLabel` writes it in the
+ * tile (a grid that needs a tile: "Linen Napkins, Set of 4"). A video that
+ * cannot play keeps its poster artwork, dimmed, with a slashed play and the
+ * words "Video unavailable". Editor recovery UI lives in states/MediaState.
+ */
+export interface MediaErrorProps {
+  reason?: 'missing' | 'failed' | 'video-unavailable'
+  /** CSS aspect-ratio of the media it stands in for. */
+  ratio?: string
+  rounded?: boolean
+  label?: string
+  /** Write the label in the tile instead of the image glyph. */
+  showLabel?: boolean
+  className?: string
+}
+
+export function MediaError({ reason = 'missing', ratio = '4 / 3', rounded = true, label, showLabel, className }: MediaErrorProps): JSX.Element {
+  const { strings } = useNova()
+  if (reason === 'video-unavailable') {
+    return (
+      <span className={sxJoin(['nv-media-error', className].filter(Boolean).join(' '), sx({ aspectRatio: ratio } as CSSProperties))} data-reason={reason} data-rounded={rounded ? '' : undefined}>
+        <MediaPlaceholder family="video" state="unavailable" ratio={ratio} rounded={rounded} />
+        <span className="nv-media-error__text">{label ? `${strings.videoUnavailable} · ${label}` : strings.videoUnavailable}</span>
+      </span>
+    )
+  }
+  return (
+    <span
+      className={sxJoin(['nv-media-error', className].filter(Boolean).join(' '), sx({ aspectRatio: ratio } as CSSProperties))}
+      data-reason={reason}
+      data-rounded={rounded ? '' : undefined}
+      role={label && !showLabel ? 'img' : undefined}
+      aria-label={label && !showLabel ? label : undefined}
+      aria-hidden={label ? undefined : true}
+    >
+      {showLabel && label ? <span className="nv-media-error__name">{label}</span> : <Icon name="image" size="md" />}
+    </span>
+  )
+}

package/templates/nova/src/components/states/media/MediaPlaceholder.css

@@ -0,0 +1,24 @@
+/* Nova 14 · 14.1b placeholders — base steps --ph-b0…4 (the family's page palette) mapped per scheme. */
+.nv-placeholder {
+  --ph-0: var(--ph-b0); --ph-1: var(--ph-b1); --ph-2: var(--ph-b2); --ph-3: var(--ph-b3); --ph-4: var(--ph-b4);
+  position: relative; display: block; width: 100%; overflow: hidden; background: var(--ph-0);
+  container-type: inline-size;
+}
+.nv-placeholder[data-rounded] { border-radius: var(--radius-media); }
+.nv-placeholder > svg { display: block; width: 100%; height: 100%; }
+/* muted — the page steps, 7% deeper (sits on --color-bg-muted). */
+:is(.nv-placeholder[data-scheme='muted'], [data-nv-surface='muted'] .nv-placeholder:not([data-scheme])) {
+  --ph-0: color-mix(in srgb, var(--ph-b0), #000 7%); --ph-1: color-mix(in srgb, var(--ph-b1), #000 7%); --ph-2: color-mix(in srgb, var(--ph-b2), #000 7%);
+  --ph-3: color-mix(in srgb, var(--ph-b3), #000 7%); --ph-4: color-mix(in srgb, var(--ph-b4), #000 7%);
+}
+/* inverse — the type's deepest hue mixed 56–86% into #141414 (inverse sections and the dark scheme). */
+:is(.nv-placeholder[data-scheme='inverse'], [data-nv-surface='inverse'] .nv-placeholder:not([data-scheme]), :root[data-scheme='dark'] .nv-placeholder:not([data-scheme])) {
+  --ph-0: color-mix(in srgb, #141414 86%, var(--ph-b3)); --ph-1: color-mix(in srgb, #141414 80%, var(--ph-b3)); --ph-2: color-mix(in srgb, #141414 70%, var(--ph-b3));
+  --ph-3: color-mix(in srgb, #141414 56%, var(--ph-b3)); --ph-4: color-mix(in srgb, #141414 64%, var(--ph-b3));
+}
+/* density — below 160px the secondary layers drop (one file, container query). */
+@container (max-width: 159.98px) { .nv-ph-sec { display: none; } }
+/* video · unavailable — dimmed, no live play or timeline, a slashed play instead. */
+.nv-placeholder[data-state='unavailable'] > svg:first-child { opacity: 0.7; }
+.nv-placeholder[data-state='unavailable'] > svg:first-child :is([style*='--ph-play'], [style*='--ph-ink']) { display: none; }
+.nv-placeholder__slash { position: absolute; inset: 0; }

package/templates/nova/src/components/states/media/MediaPlaceholder.tsx

@@ -0,0 +1,101 @@
+import { sx, sxJoin } from '@tanqory/theme-kit'
+import type { CSSProperties } from 'react'
+import type { NovaImage } from '@tanqory/theme-kit'
+import { PLACEHOLDER_ART } from './placeholder-art'
+import './MediaPlaceholder.css'
+
+/**
+ * Nova 14 · SVG placeholder system — nine families, each one tonal palette in
+ * five steps (--ph-0…4, + --ph-play/ink/scrim for video). Token-driven: the
+ * palette is CSS custom properties on the wrapper, so a theme can re-point
+ * them. Always decorative (aria-hidden); `slice` fills any ratio.
+ *
+ *   scheme   page · muted (7% deeper) · inverse (the type's deepest hue mixed
+ *            into #141414). Default: from context — a muted section → muted,
+ *            an inverse section or the dark scheme → inverse.
+ *   density  one file: below 160px wide (container query) the secondary layers
+ *            drop — highlights, shadows, text bars, scallops.
+ *   video    state "unavailable": dimmed, a slashed play, no timeline.
+ */
+export type PlaceholderFamily = keyof typeof PLACEHOLDER_ART
+export const PLACEHOLDER_FAMILIES = Object.keys(PLACEHOLDER_ART) as PlaceholderFamily[]
+export type PlaceholderScheme = 'page' | 'muted' | 'inverse'
+
+export interface MediaPlaceholderProps {
+  family?: PlaceholderFamily
+  /** CSS aspect-ratio; defaults to the family's own viewBox. */
+  ratio?: string
+  rounded?: boolean
+  /** Omit to follow the surrounding surface. */
+  scheme?: PlaceholderScheme
+  /** Video only: the poster of a video that cannot play. */
+  state?: 'unavailable'
+  className?: string
+}
+
+const SHAPE = /<(rect|circle|ellipse|path|line|polygon)\b([^>]*?)(\/?)>/g
+
+/**
+ * Secondary layers — the ones the canvas's compact (< 160px) frames drop:
+ * anything with its own opacity (shadows, highlights), bars ≤ 10 thick
+ * (text lines, rims) and dots r ≤ 10 (scallops, details). Derived from the
+ * approved compact frames (it reproduces all four exactly); the video play
+ * disc always stays.
+ */
+function isSecondary(tag: string, attrs: string): boolean {
+  const a = Object.fromEntries([...attrs.matchAll(/([\w-]+)="([^"]*)"/g)].map((m) => [m[1], m[2]]))
+  if (tag === 'circle' && /--ph-play/.test(attrs)) return false
+  if ('opacity' in a) return true
+  if (tag === 'rect' && (Number(a.height ?? 99) <= 10 || Number(a.width ?? 99) <= 10)) return true
+  if (tag === 'circle' && Number(a.r ?? 99) <= 10) return true
+  return false
+}
+
+const marked = new Map<PlaceholderFamily, string>()
+function artOf(family: PlaceholderFamily): string {
+  let inner = marked.get(family)
+  if (!inner) {
+    inner = PLACEHOLDER_ART[family].inner.replace(/ data-dc-tpl="\d+"/g, '').replace(SHAPE, (m, tag: string, attrs: string, end: string) =>
+      isSecondary(tag, attrs) ? `<${tag} class="nv-ph-sec"${attrs}${end}>` : m,
+    )
+    marked.set(family, inner)
+  }
+  return inner
+}
+
+/** The tokens as base steps; the scheme maps them onto --ph-0…4 in CSS. */
+function baseTokens(family: PlaceholderFamily): Record<string, string> {
+  return Object.fromEntries(Object.entries(PLACEHOLDER_ART[family].tokens).map(([k, v]) => [/^--ph-\d$/.test(k) ? k.replace('--ph-', '--ph-b') : k, v as string]))
+}
+
+export function MediaPlaceholder({ family = 'generic', ratio, rounded = true, scheme, state, className }: MediaPlaceholderProps): JSX.Element {
+  const art = PLACEHOLDER_ART[family]
+  const [, , w, h] = art.viewBox.split(' ').map(Number)
+  const style = { ...baseTokens(family), aspectRatio: ratio ?? `${w} / ${h}` } as CSSProperties
+  const unavailable = family === 'video' && state === 'unavailable'
+  return (
+    <span className={sxJoin(['nv-placeholder', className].filter(Boolean).join(' '), sx(style))} data-family={family} data-scheme={scheme} data-state={unavailable ? 'unavailable' : undefined} data-rounded={rounded ? '' : undefined} aria-hidden>
+      <svg viewBox={art.viewBox} preserveAspectRatio="xMidYMid slice" width="100%" height="100%" focusable="false" dangerouslySetInnerHTML={{ __html: artOf(family) }} />
+      {unavailable && (
+        <svg className="nv-placeholder__slash" viewBox={art.viewBox} preserveAspectRatio="xMidYMid slice" width="100%" height="100%" focusable="false">
+          <circle cx="600" cy="320" r="56" fill="none" stroke="var(--ph-ink)" strokeOpacity=".45" strokeWidth="4" />
+          <path d="M584 292l46 28-46 28z" fill="none" stroke="var(--ph-ink)" strokeOpacity=".45" strokeWidth="4" strokeLinejoin="round" />
+          <path d="M560 280l80 80" stroke="var(--ph-ink)" strokeOpacity=".45" strokeWidth="4" strokeLinecap="round" />
+        </svg>
+      )}
+    </span>
+  )
+}
+
+/**
+ * The same art as a self-contained image (palette resolved into the SVG), so
+ * fixtures can hand components a real `src` — deterministic, offline, and
+ * exercising the real <img> path. `width`/`height` set the intrinsic ratio.
+ */
+export function placeholderImage(family: PlaceholderFamily, width: number, height: number, alt = ''): NovaImage {
+  const art = PLACEHOLDER_ART[family]
+  let inner: string = art.inner
+  for (const [k, v] of Object.entries(art.tokens)) inner = inner.split(`var(${k})`).join(v as string)
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${art.viewBox}" preserveAspectRatio="xMidYMid slice" width="${width}" height="${height}">${inner}</svg>`
+  return { src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`, width, height, alt }
+}