Reference

Artifact Specifications

Every artifact published on Esy carries a specification — structured metadata that describes what it is, how it was made, and who made it. The spec panel makes this provenance inspectable by any reader.

What Is an Artifact Spec?

An artifact spec is the metadata object attached to every published piece — visual essays, briefs, infographics. It appears in the collapsible “Artifact Spec” panel beneath the hero section and includes production details: template, design system, source quality, model, authorship, palette, and visualization inventory.

The spec serves two purposes: it gives readers transparency into how the artifact was produced, and it gives the production pipeline a structured contract to validate against.

Implementation

Each essay defines its spec as an ESSAY_META object in its page.tsx, passed to the ArtifactDetailWrapper component. The TypeScript interface lives at src/lib/artifact-spec/schema.ts.

Schema

Required Fields

titlestringArtifact title displayed as the page heading
subtitlestringSecondary title line below the heading
categorystringPrimary category (Science, History, Etymology, etc.)
readTimestringEstimated reading time (e.g., "25 min")
sourceCountnumberTotal number of sources cited
sourceTierstringSource quality tier (e.g., "Tier-1" for peer-reviewed)
sectionCountnumberNumber of major sections
visualizationCountnumberNumber of interactive visualizations
designSystemstringDesign approach (e.g., "Subject-derived")
publishedstringPublication date
modelModelIdAI model that produced the artifact (legacy; prefer authorship)
templatestringProduction template (e.g., "Visual Essay")

Optional Fields

authorshipArtifactAuthorshipAuthorship provenance — who made it and how
paletteArray<{name, color}>Named color palette used in the design
visualizationsArray<{name, type}>List of visualizations with implementation type
keySourcesstring[]Highlighted primary sources
citationFirstbooleanWhether the essay was written citation-first

Authorship

The authorship field describes who made the artifact and what role AI played. It separates two things that are often conflated: who is the creative author, and what tools were used in production.

Every artifact falls into one of three modes. The naming encodes directionality — in AI-Assisted, the human is the author and AI is the tool. In AI-Directed, AI is the production engine and the human is the director.

Human

human

A named person wrote the essay. No meaningful AI involvement in the writing.

Spec panel: Author: [Name]
authorship: {
  mode: 'human',
  author: { name: 'Zev Uhuru', role: 'Editor-in-Chief' },
}

AI-Assisted

ai-assisted

A named person wrote the essay. AI assisted with specific contributions like research, visualization code, or fact-checking.

Spec panel: Author: [Name] + AI Assist: [Model] · [Contributions]
authorship: {
  mode: 'ai-assisted',
  author: { name: 'Zev Uhuru', role: 'Editor-in-Chief' },
  model: 'claude-opus-4.6',
  aiContributions: ['research', 'visualization', 'fact-checking'],
}

AI-Directed

ai-directed

AI produced the artifact under human editorial direction — the standard pipeline. A human chose the topic, approved the brief, reviewed gates, and published.

Spec panel: Model: [Model label]
authorship: {
  mode: 'ai-directed',
  model: 'claude-opus-4.6',
}

AI Contributions

When an essay is ai-assisted, the aiContributions array describes what AI helped with. These render in the spec panel as a comma-separated list.

researchSource discovery, synthesis, or research packages
codeVisualization code, components, or CSS
editingProse editing, structure, or tone
fact-checkingClaim verification, date and attribution checks
visualizationData visualization design or implementation

Backward Compatibility

The authorship field is optional. When absent, the system derives { mode: 'ai-directed', model: meta.model } from the legacy model field. Every existing essay works without modification.

The Spec Panel

The spec panel is the collapsible detail section rendered by ArtifactDetailWrapper. It exposes five areas of information:

Metadata Grid — Template, design system, publication date, authorship/model, source quality, and citation-first status.
Color Palette — Named color swatches used in the essay's design system, with hex values.
Visualizations — Inventory of every interactive visualization with its implementation type (e.g., "D3 Scatter + Voronoi").
Key Sources — Highlighted primary sources, with a "+N more" indicator when the full bibliography is larger.

Model Registry

Model IDs follow the pattern {family}-{subfamily}-{version} and are registered in the model registry. The spec panel resolves IDs to display labels at render time.

claude-opus-4.6Claude Opus 4.6AnthropicRecommended
claude-sonnet-4.5Claude Sonnet 4.5AnthropicSupported
gpt-5.2GPT 5.2OpenAIRecommended

Legacy essays using unrecognized strings (e.g., 'Claude') display the string as-is for backward compatibility.

Pipeline Enforcement

Artifact specs are validated at multiple gates in the production pipeline:

G5: Content Complete — page.tsx exists with ESSAY_META and ArtifactDetailWrapper
G8: Publication Certification — Cross-checks metadata completeness before publication

Related Concepts