跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

charmed-lipgloss

Style and lay out terminal text in Go with Lip Gloss v2 (charm.land/lipgloss/v2, charmbracelet): ANSI colors and terminal colors, borders and boxes, padding, alignment, joining and placing blocks, light or dark adaptation, gradients, static tables, trees, lists, and layered overlays. Use when rendering styled strings or pretty terminal output for a TUI or CLI, drawing a bordered box, building a layout from measured blocks, or migrating v1 lipgloss code. Not for the event loop (charmed-bubbletea) or interactive widgets (charmed-bubbles).

tpscloud · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add tpscloud/charmedimsure --skill charmed-lipgloss

技能说明


name: charmed-lipgloss description: "Style and lay out terminal text in Go with Lip Gloss v2 (charm.land/lipgloss/v2, charmbracelet): ANSI colors and terminal colors, borders and boxes, padding, alignment, joining and placing blocks, light or dark adaptation, gradients, static tables, trees, lists, and layered overlays. Use when rendering styled strings or pretty terminal output for a TUI or CLI, drawing a bordered box, building a layout from measured blocks, or migrating v1 lipgloss code. Not for the event loop (charmed-bubbletea) or interactive widgets (charmed-bubbles)." license: "MIT"

Lip Gloss v2

Style and lay out terminal text in Go with Lip Gloss v2: colors that adapt to the background, borders, padding, alignment, joined and layered blocks, tables, trees, and lists, measured in terminal cells.

Import as "charm.land/lipgloss/v2"; subpackages are table, tree, list, and compat. Pinned and verified against v2.0.6. Go blocks headed // examples/... are trimmed from complete programs that build against the pinned modules; // excerpt blocks are API sketches.

If the project's go.mod still requires github.com/charmbracelet/lipgloss (pre-v2), the v2 APIs here do not apply. Use go doc against the project's version and keep its import paths unless the user asks to migrate.

Workflow

  1. Standalone, decide light or dark once with HasDarkBackground before printing anything, and build a LightDark picker. Inside Bubble Tea, use tea.BackgroundColorMsg instead (see Light and dark backgrounds).
  2. Define styles as values; derive variants by chaining setters.
  3. Render blocks and measure them with lipgloss.Width, Height, or Size.
  4. Compose with JoinHorizontal, JoinVertical, and Place, or with layers for overlays; use the subpackages for tables, trees, and lists.
  5. Print with lipgloss.Println (standalone) or return the string in a tea.View.
  6. Check in a real terminal and compare lipgloss.Size with the width you expected. Wrong colors usually mean output went through fmt; a box off by its frame usually means GetFrameSize was subtracted from Width. Fix and rerun.

Mental model

A Style is a plain value. Setters return a new value, so you build styles by chaining and derive variants without mutating the base. Render turns a style plus text into a string carrying ANSI escape codes. Nothing else happens until that string reaches a terminal.

Render always emits full color; downsampling to what the terminal supports happens at output. Inside Bubble Tea v2 that is automatic. Standalone, print through Lip Gloss (see the basics example):

// examples/charmed-lipgloss/basics/main.go
title := lipgloss.NewStyle().
    Bold(true).
    Foreground(lipgloss.Color("#FAFAFA")).
    Background(lipgloss.Color("#7D56F4")).
    Padding(0, 1)

card := lipgloss.NewStyle().
    Border(lipgloss.RoundedBorder()).
    BorderForeground(lipgloss.Color("63")).
    Padding(1, 2).
    Width(40)

body := lipgloss.NewStyle().Italic(true).Faint(true)
warning := body.Faint(false).Italic(false).Foreground(lipgloss.Yellow) // body unchanged

lipgloss.Println(card.Render(title.Render("Lip Gloss v2") + "\n\n" + body.Render("...")))

lipgloss.Print, Println, Printf, Fprint*, and Sprint* all downsample. fmt.Println does not. The default writer targets stdout; for stderr use lipgloss.Fprintln(os.Stderr, s) or reassign lipgloss.Writer.

Colors

lipgloss.Color(s) is a function returning image/color.Color. It accepts hex ("#7D56F4") or an ANSI index ("212", "5"). The sixteen basic colors have names: lipgloss.Red, lipgloss.BrightGreen, and so on. Any color.Color works, so color.RGBA{...} from the standard library is fine too.

Style setters take color.Color: Foreground, Background, BorderForeground, BorderBackground, UnderlineColor, MarginBackground.

Helpers from the colors example (the gradient uses strings.Builder). lipgloss.Alpha(c, 0.5) also exists and sets a color's alpha on a 0 to 1 scale:

// examples/charmed-lipgloss/colors/main.go
base := lipgloss.Color("#7D56F4")
lipgloss.Lighten(base, 0.3)          // tint by 30 percent
lipgloss.Darken(base, 0.3)
lipgloss.Complementary(base)

// One color per rune from a two stop gradient. Index runes, not bytes:
// ranging over the string would sample at UTF-8 byte offsets.
word := "gradient"
runes := []rune(word)
stops := lipgloss.Blend1D(len(runes), lipgloss.Color("#FF5F87"), lipgloss.Color("#5FD7FF"))
var b strings.Builder
for i, r := range runes {
    b.WriteString(lipgloss.NewStyle().Foreground(stops[i]).Render(string(r)))
}

// Gradient borders are a style setting.
lipgloss.NewStyle().Border(lipgloss.RoundedBorder()).
    BorderForegroundBlend(lipgloss.Color("#FF5F87"), lipgloss.Color("#5FD7FF"))

Blend2D(width, height, angle, stops...) fills a rectangle. The gradient loop above colors per rune; wide characters and combining marks occupy cells differently, so for cell accurate gradients split by grapheme and measure with lipgloss.Width.

Light and dark backgrounds

Decide once whether the background is dark, then pick colors with LightDark. Standalone, as in the adaptive example:

// examples/charmed-lipgloss/adaptive/main.go
isDark := lipgloss.HasDarkBackground(os.Stdin, os.Stdout)   // queries the terminal
lightDark := lipgloss.LightDark(isDark)
fg := lightDark(lipgloss.Color("#1A1A1A"), lipgloss.Color("#F0F0F0")) // (light, dark)

profile := colorprofile.Detect(os.Stdout, os.Environ())
complete := lipgloss.Complete(profile)
brand
阅读完整来源 ↗