OpenParable
Skip to content
← Back to skills

Takumi Usage

Design
takumi-usage

Takumi Usage is an Agent Skill for design published in the kane50613/takumi repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guidelines, syntax, templates, API usage, and styling best practices for rendering static/animated images and vector SVG using Takumi.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/kane50613/takumi/blob/HEAD/.agents/skills/takumi-usage/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/takumi-usage, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Takumi Usage & Best Practices

All-in-one guide for rendering with Takumi. Built-in layout rules, advanced styles, and performance.

JS / TS API Reference

1. Static Render (render & renderSvg)

Renders JSX templates, HTML strings, or JSON node trees to raster buffers (PNG/JPEG/WebP) or vector SVG markup.

import { render, renderSvg } from "takumi-js";

// Renders dynamic JSX layout directly to PNG bytes
const pngBuffer = await render(
  <div tw="w-full h-full bg-zinc-950 flex items-center justify-center">
    <h1 tw="text-white text-6xl">Takumi Engine</h1>
  </div>,
  {
    width: 1200,
    height: 630,
    format: "png", // "png" | "jpeg" | "webp"
    quality: 90    // (Optional) For JPEG/WebP formats
  }
);

// Renders to responsive XML SVG string containing glyph path vector data
const svgString = await renderSvg(
  <div tw="w-full h-full bg-zinc-900">
    <span tw="text-white">Scalable Vector</span>
  </div>,
  { width: 800, height: 400 }
);

2. Animated Render (renderAnimation)

Compiles sequences of scenes into animated WebP, GIF, or APNG buffers.

import { renderAnimation } from "takumi-js";

const animatedBuffer = await renderAnimation({
  width: 400,
  height: 400,
  fps: 30,
  format: "webp", // "webp" | "gif" | "apng"
  quality: 80,    // Compression quality (0-100)
  scenes: [
    {
      durationMs: 1500,
      node: (
        <div tw="w-full h-full bg-black flex items-center justify-center">
          <div tw="w-24 h-24 bg-rose-500 animate-bounce rounded-full" />
        </div>
      )
    }
  ]
});

3. Edge / Framework Integration (ImageResponse)

A next/og compatible handler designed for Edge runtimes, Cloudflare Workers, Next.js API endpoints, and standard HTTP server frameworks.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(
    <div tw="w-full h-full bg-slate-900 flex items-center justify-center">
      <h1 tw="text-white text-5xl">Dynamic OG Card</h1>
    </div>,
    {
      width: 1200,
      height: 630
    }
  );
}

4. Parsing Helpers (takumi-js/helpers/*)

Low-level utilities for compiling layout elements without executing the full renderer.

import { fromHtml } from "takumi-js/helpers/html";
import { fromJsx } from "takumi-js/helpers/jsx";

// Converts raw HTML template string into JSON layout node tree
const htmlNodeTree = fromHtml(
  "<div class='flex'><span>Hello</span></div>",
  { max_depth: 512 }
);

// Compiles React ReactNode elements into JSON layout node tree
const jsxNodeTree = fromJsx(
  <div tw="flex"><span>Hello</span></div>
);

Options Configuration (RenderOptions)

  • fonts: An array of custom fonts [{ name, url, weight, style }]. Values can point to remote URLs (WOFF2/WOFF/TTF), local file paths, or binary Node.js Buffer arrays.
  • emoji: Configures the emoji fallback strategy: "twemoji" (default), "blob-emoji", "openmoji", "noto-emoji", or "from-font" (uses custom loaded font glyphs).
  • images: Option to pass pre-fetched image arrays [{ url, buffer }] or supply a shared caching fetch-client configuration.
  • stylesheets: An array of raw global CSS string sheets to inject into the rendering layout context.

Hidden Layout Capabilities (Deep-Dive)

1. Auto-scaling Text (text-fit)

Automatically scales font-size to fit the containing inline line-box width, avoiding clipping or wrapping.

  • Syntax: text-fit: [ none | grow | shrink ] [ consistent | per-line | per-line-all ]? [percentage]?
  • Example: tw="text-fit-grow-consistent" or style={{ textFit: "grow consistent 120%" }}.

2. CSS Motion Paths (offset-path)

Enables complex placement and animation sequences of elements along custom vector paths or geometric rays.

  • Properties: offset-path, offset-distance (percentage), offset-rotate (angle / auto).
  • Syntax: ray(<angle> <size> contain? at <position>?) or path("<svg path command>") or basic shapes (circle(), polygon(), inset()).

3. OpenType Typography Settings

Provides fine-grained control over font rendering features and variable layout configurations.

  • font-variation-settings: Configures variable font axis settings (e.g. "'wght' 750, 'wdth' 90").
  • font-feature-settings: Enables OpenType font ligatures, kerning, and variants (e.g. "'ss01' 1, 'kern' 1").

4. Custom Filters & Graphics

  • filter: Supports blur(), brightness(), contrast(), drop-shadow(), grayscale(), hue-rotate(), invert(), opacity(), saturate(), sepia().
  • mix-blend-mode & background-blend-mode: Layer blending modes (e.g. multiply, screen, overlay).
  • backdrop-filter: Applies filter effects to elements behind the container.
  • clip-path: Clips elements via shapes: polygon(...), circle(...), inset(...).

5. Layout Defaults

  • CSS Grid support: Supports grid-cols-X, gap-X, flex, and block layout.
  • Tag Presets: Custom HTML styles are pre-mapped for tags: h1–h6, div, pre (keeps space layout), strong, em, blockquote, and hr.
  • Line Breaks: <br> tags parse to \n in text elements automatically.

Rust Crate API (takumi)

use takumi::prelude::*;
use takumi::render;

let node = Node::container([Node::text("Hello, world!").with_style(
  Style::default().with(StyleDeclaration::font_size(Length::Px(32.0).into())),
)]);

let mut fonts = Fonts::default();
fonts.register(FontResource::new(include_bytes!(
  "../../assets/fonts/geist/Geist[wght].woff2"
)))?;

let options = RenderOptions::builder()
  .viewport(Viewport::new((1200, 630)))
  .node(node)
  .fonts(&fonts)
  .build();

let image = render(options)?;

To build the node tree from HTML instead, enable the from-html feature and use from_html:

use takumi::prelude::*;
use takumi::{from_html, render};

let mut fonts = Fonts::default();
fonts.register(FontResource::new(include_bytes!(
  "../../assets/fonts/geist/Geist[wght].woff2"
)))?;

let html = r#"<div style="background: red; width: 100%; height: 100%;"></div>"#;
let node = from_html(html, FromHtmlOptions::default())?;

let options = RenderOptions::builder()
  .viewport(Viewport::new((1200, 630)))
  .node(node)
  .fonts(&fonts)
  .build();

let image = render(options)?;