@bestagentkits/render

A declarative page compiler for coding agents. An agent writes a short YAML or JSON Page Spec; ak-render compiles it into one deterministic, self-contained, interactive HTML file.

render.agentkit.best · Gallery · Agent guide · npm

Agents describe meaning and composition. The compiler owns HTML, CSS, interaction, accessibility, responsive layout, theming, fonts, security policy and byte-for-byte determinism. The agent spends tokens on the content instead of on markup, and the result looks designed every time.

• Offline by default. The file opens from disk (file://) and makes zero network requests. Fonts are embedded; nothing loads from a CDN.
• Deterministic. The same spec and compiler version produce the same bytes.
• No escape hatch. A spec cannot carry raw HTML, CSS or JavaScript, so a page cannot drift off the design system or smuggle in a script.
• Local is canonical. No account, no server, no API key.

Quick start

Requires Node.js >= 20.11.

1. Write a spec, plan.yaml:

   version: 1
   meta:
     title: Migration plan
     description: How we move the API to the new gateway.
   theme:
     preset: editorial
   blocks:
     - type: hero
       eyebrow: Plan
       title: Migration plan
       description: Move the public API to the new gateway without downtime.
     - type: section
       title: Steps
       blocks:
         - type: steps
           items:
             - title: Mirror traffic
               text: Send a copy of production requests to the new gateway.
             - title: Switch reads
               text: Route read endpoints once error rates match.
     - type: callout
       tone: info
       title: Rollback
       text: Point DNS back to the old gateway; no data migrates.
   

2. Validate it, then compile it:

   npx -y @bestagentkits/render validate plan.yaml
   npx -y @bestagentkits/render plan.yaml --out plan.html
   

3. Open plan.html in any browser. It is one file you can attach, email or commit.

Usage guide

Find the blocks you need

There are 92 block types in eight categories (layout, content, data, interaction, media, showcase, engineering, product), from primitives (section, grid, split, text) to semantic blocks that carry the design for you (hero, steps, timeline, kpi, data-table, chart, kanban, pricing, social-post, social-feed, cta). Find the ones you need, then read only their contracts:

ak-render catalog                        # every block by category, and every action
ak-render catalog --category data        # one category
ak-render search-catalog sortable table  # rank block types by intent words
ak-render describe kpi chart --compact   # one line per prop, for several types
ak-render describe timeline --json       # one full contract: defaults, bounds, a11y notes

Icons

Blocks take an icon by meaning, never as markup. icon: gauge names a concept and the theme's icon profile decides which pack draws it; icon: phosphor:rocket pins an exact glyph; icon: { name: gauge, size: lg, label: Speed } sets a size (xs–xl) and an accessible name. Five packs are bundled as a curated, license-tracked subset (Lucide, Phosphor, Tabler, Pixelarticons, Codicons); a page embeds only the glyphs it uses, once each, as same-document SVG symbols, so the output stays offline and deterministic. See docs/icons.md.

ak-render icons search gauge          # English or Vietnamese, up to 8 hits
ak-render icons describe gauge        # packs, variants, license; never SVG
ak-render icons packs                 # bundled packs and their licenses

Containers (section, grid, split, stack and the page layouts sidebar-layout, main-aside, rail-layout) take their children under blocks:. Tabs, accordion sections, carousel slides and bento tiles hold blocks too, under items[i].blocks.

Text is plain text, with one exception: in prose props such as text, a step's or list item's text, a description or a caption, a pair of backticks renders as inline code, so `ak-render catalog` reads as a command, and a pair of double asterisks renders as bold, so **required** stands out. Block titles, step, timeline and card titles, table cells, comparison items and key-value values render the same spans. Nothing else is parsed as markup, an unpaired marker stays literal, and the document title, code blocks and terminal lines are never changed. describe marks each prose prop.

Compose a page from an intent

For a common page kind, skip the spec: compose takes a typed intent and its content slots and expands them, deterministically and without a model call, into an ordinary Page Spec built from existing blocks, then compiles it. The first intent is investment-report (thesis, key facts, metrics, scenario projections over one shared dataset, risks, milestones and sources). The expanded spec is yours to keep editing with the full block vocabulary; see docs/compose.md.

ak-render compose intents                                   # intents and their slot schemas (--json)
ak-render compose report.yaml --out report.html --spec-out report.spec.yaml
ak-render compose report.yaml --dry-run                     # print the expanded spec only

Start from a page recipe

A recipe is a complete, valid starter spec for a common page: a dashboard, a benchmark report, an architecture review, an incident report, a product showcase, a case study, a release recap, an implementation plan, a research report or a decision memo. Replace its placeholder text and data, then validate.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗