@popcraft/kit

The library PopCraft designs are made with. PopCraft's own templates are written with this Kit, and so are the design scripts its in-editor agent and the popcraft command line run. Code written against it builds ordinary, editable PopCraft layers: brand colour roles, text styles, auto-layout stacks, components, motion, size variants and music.

npm i @popcraft/kit      # Node 24 or newer

Two ways to use it

Run a design script, the same text the write_design command takes, in a sandbox, and get the document and the checks back:

import { runDesign, toPopcraft } from '@popcraft/kit'
import { writeFileSync } from 'node:fs'

const { document, issues, error } = await runDesign(`
k.brand({ paper: '#F4F1EA', ink: '#141414', hot: '#E8361E' })
k.textStyle('Hook', { size: 120, fontWeight: 900, lineHeight: 110 })
k.flowSheet(k.sheet, 32, 96, 'paper')
k.text(k.sheet, 'Half price, this week only.', { style: 'Hook', color: 'ink', width: 'FILL' })
`, { size: 'ig-post', name: 'Sale' })

if (error) throw new Error(`line ${error.line}: ${error.message}`)
for (const i of issues) console.log(i.kind, i.message)   // contrast, small text, safe areas, overlap, seams…
writeFileSync('sale.popcraft', toPopcraft(document!))

Build directly, with the Kit and its helpers as ordinary imports:

import { Kit, preset, web, beat } from '@popcraft/kit'

const k = new Kit('Landing', preset('web-desktop'))
// … k.brand, k.textStyle, web.page, web.nav, k.stack, k.text …
const document = k.finish()

Templates, as PopCraft's own are made

Everything PopCraft's gallery is made with is in this package:

• Every official template's source. 1,275 of them, importable as @popcraft/kit/templates/<path> and readable in src/templates/. dist/templates/index.json catalogues them by id.
• Every module they use. The Kit, the helpers, twelve SaaS style systems, fifty-odd theme kits, the comic and anime engines, the Lottie kit, 3D devices and stages, and the music library. The app modules the sources import are @popcraft/kit/lib/<path>.
• The official build (buildFromSource), with real type first (prepareFonts) and PopCraft's music fetched as needed.
• Every check the official templates pass (checkTemplate): practices, contrast, type size, safe areas, the trim, finished timelines and golden poses for every cue, real-type layout and hugging, responsive web, brand-kit re-skins and editability.

import { prepareFonts, buildFromSource, checkTemplate } from '@popcraft/kit'
import official from '@popcraft/kit/templates/social/promo-sale-drop'

const mine = { ...official, id: 'my-sale-drop' }
await prepareFonts()                                 // real type: every character the official templates draw
const template = await buildFromSource(mine)        // what template.json holds; `popcraft template publish` uploads it
console.log(await checkTemplate(template, { source: mine }))   // [] when it passes every official check

The command line runs all of it, plus the gallery's pictures and a review render of every size: popcraft template list|new|check|look|pictures|publish. The guide is Making templates.

A design script (below) can also become a template with toTemplate(document, listing).

Types for scripts

A design script runs with k, W, H, NAME, TRACKS and the helpers as globals. Start one with

/// <reference types="@popcraft/kit/design-script" />

for completion and checking in your editor.

What is in it

| Export | What it is | | --- | --- | | Kit, hex, preset, ease | The kit, a colour from hex, a size by its preset id, animation curves | | draw, marks | Vector paths: boxes, lines, curves; grids, dots, confetti, bursts, arrows, charts | | texture, overlays | Shadows, glows, halos, grain; scanlines, rain, snow, halftone | | motion, beat, captions, pointer | Motion recipes, music beds and beat timing, caption tracks, cursor paths | | fit, type, windows, devices | Laying a design out at another size, font pairs, app and browser windows, device frames | | web, site | Web pages (nav, buttons, responsive sizes) and page parts (type scales, columns, footers) | | social, video, effects | Post and feed variants; reel sheets, cuts and camera moves; shader backdrops | | runDesign, checkDesign, tracks | Run a script in a sandbox; the design checks; every music track's tempo | | toPopcraft, fromPopcraft | A document as a .popcraft file's text, and back | | defineTemplate, buildFromSource (buildTemplateSource without fetching), prepareFonts, checkTemplate, media, templatePopcraft | Templates as the official ones are made: a source, its build, every official check, your own media, a file to look at | | toTemplate | A design script's document as a template | | mediaHash, TEMPLATE_CATEGORIES, TEMPLATE_PLATFORMS, TEMPLATE_FORMATS, TEMPLATE_USE_CASES | A media file's media:// hash; the gallery's vocabulary |

Examples

In getpopcraft/examples: event cards from a JSON file, a design check for CI, a typed design script.

Documentation

• Design reference: the kit by topic, editing designs, how decisions are made, and worked examples that build with no failing check.
• Designing with an AI agent: the build, check, look and fix loop.
• Command line: popcraft run file.popcraft write_design --script @design.js.

Release notes: CHANGELOG.md.