Authoring · Porting Caret

Porting Caret

Caret is a design language first, an implementation second. The TypeScript registry is one binding. Ports to Go, Rust, Python, or any other ecosystem are encouraged — what binds them is the spec.

What ports must reproduce

Layer	Source of truth	Latitude
Component anatomy	specs/<name>.md	Layout described per-row — port exactly
Symbol set	specs/look.md + tokens/symbols	Use the same glyphs (^, ▸, ●, ○, ✓, ✗, ⚠)
Color tokens	tokens/colors.ts	Brand truecolor fixed; semantic emit ANSI names
Capability detection	lib/capability.ts	Detect TTY / NO_COLOR / Unicode / reduced motion identically
API shape	specs/<name>.md	Match field names; idiomatic style allowed
Internal structure	— / your call	Implementation detail — pick whatever fits the language

Reading a spec

Each spec markdown file follows the same shape: title, one-line description, and a series of ## sections. The standard sections are:

Section	What it gives the porter
Anatomy	ASCII or block diagram of the component's rendered output, row by row
API / Options	Field names, types, defaults — your binding's public surface
Behavior	State machine — what happens on each input event
Keyboard	Every key press the component listens for
Capability	How the component degrades when capabilities are missing
Examples	Idiomatic usage in TypeScript — translate to your language

A worked example: prompt.confirm

From specs/prompt.md:

### confirm

  ^ Deploy to production?
    [ Yes ]   No
    ←→ toggle · y/n shortcut · ↵ confirm · esc cancel

API:
  label    string                    required
  default  boolean                   default: false

Keys:
  ←/→         toggle the highlighted choice
  y, Y        select Yes
  n, N        select No
  ↵ Enter     submit the highlighted choice
  Esc         cancel — resolve null

That's enough to write a Go port. The Yes/No glyph is [ ... ] on the highlighted side. Keys are listed explicitly. Cancel resolves a null/None — your language's nullable equivalent. The brand ^ mark and the focus glyph are token references — pull them from your tokens file.

Reference helmets

Two libraries Caret leans on at the visual layer have ports already:

Helmlab — color science, palette generation. JS, Python ports exist; github.com/Grkmyldz148/helmlab.
figlet — ASCII art for splash banners. Has implementations in nearly every major language.

Spec + AI workflow

For ports specifically, AI assistants are useful. Drop the relevant spec markdown into the LLM context, give it your caret.md-equivalent for the target language, and ask for the implementation. Caret was designed with this loop in mind — every spec is unambiguously parseable.

ℹOne symbol, every binding

The reason the manifesto says never customize symbols is portability. If a Go port renders a different glyph than the JS port, the result feels like two products. Hold the line — same glyphs, every language.

For the symbol reference, Symbols. For the capability protocol every port has to reproduce, Capability detection.