# Charm Lipgloss Layout

> Design, refactor, and polish terminal UI layout and styling with Charm Lip Gloss. Use when Codex needs to improve visual hierarchy, color, spacing, responsive terminal layouts, tables/lists/trees, adaptive light/dark color behavior, ANSI-aware measurement, or the View rendering layer of Bubble Tea and Charm applications.

- Skill: `peternicholls/charm-lipgloss-layout` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add peternicholls/charm-lipgloss-layout`
- Raw SKILL.md: https://api.skillmd.com/api/skills/peternicholls/charm-lipgloss-layout/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: peternicholls (https://skillmd.com/u/peternicholls)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/peternicholls/charm-lipgloss-layout

---


# Charm Lip Gloss Layout

## Overview

Use this when the work is about how a terminal UI looks, scans, wraps, and adapts. Lip Gloss should carry layout and style decisions instead of hand-built ANSI strings or fragile padding.

## Workflow

1. Read `references/layout-patterns.md` before changing a non-trivial view.
2. Identify the user's primary scanning task, then assign hierarchy: title, active region, secondary context, help, status.
3. Define reusable styles near the view or style package used by the project. Keep style names semantic: `titleStyle`, `activeItemStyle`, `mutedStyle`.
4. Measure and fit with Lip Gloss functions, not byte length.
5. Check light/dark background behavior and reduced-color terminals where the project supports them.
6. Verify manually at narrow, normal, and wide widths.

## Use Lip Gloss For

- Borders, padding, margins, alignment, width, height, foreground/background color, bold/faint/italic text, and hyperlinks.
- Horizontal and vertical composition.
- Tables, lists, and trees through Lip Gloss subpackages when the output is primarily presentational.
- Runtime color decisions with terminal-aware helpers when the app can inspect stdin/stdout.
- Rendering text in a Bubble Tea `View` without side effects.

## Design Rules

- Make the active region obvious without relying on color alone.
- Keep borders purposeful: one frame for the main focus or none. Avoid nested decorative boxes.
- Use color as state and hierarchy, not wallpaper. Pair color with text, icon, position, or shape.
- Reserve high-contrast accents for current selection, errors, destructive actions, or completion.
- Preserve useful content before decorative spacing when width or height shrinks.
- Style data density by task: dashboards and admin tools should be compact; setup wizards can breathe more.

## Avoid

- Avoid negative margins, brittle manual spacing, and repeated string padding.
- Avoid assuming one terminal theme. Test dark and light backgrounds when possible.
- Avoid using Unicode-only signals for critical state without ASCII fallback or labels.
- Avoid wide fixed columns unless the app explicitly requires a minimum terminal width and explains it.
- Avoid adding a new palette when the project already has semantic styles.

## Verification

- Run existing view/golden tests when present.
- Add or update view tests for deterministic render helpers.
- Manually inspect at `60x20`, `80x24`, and `120x32` or comparable project sizes.
- Check that status/error text remains visible after resizing.
- Use `charm-tui-qa` when screenshots, videos, or visual regression artifacts are needed.

## References

- `references/layout-patterns.md`: layout recipes, adaptive colors, measurement, and view QA checklist.