![\"grfti](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/intro.svg\")
\n \n\n \n \n \n
![\"dsl\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/dsl.svg\")
\n\n| Flags | |\n| --- | --- |\n| Direction | `horizontal` `h` `row`, `vertical` `v` `column`, `diagonal` `diag` `d` |\n| Reverse | `reverse` `reversed` `rev` `r` |\n| Space | `oklab` `oklch` `hsl` `hsv` `hsb` `rgb` |\n| Hue spin | `short` `long` |\n| Depth | `truecolor` `24bit`, `ansi256` `256`, `ansi16` `16`, `none` `plain` |\n| Background | `bg` `background` `on` |\n\nColors can be a CSS name, `#rgb` / `#rgba` / `#rrggbb` / `#rrggbbaa`, `rgb()` / `rgba()`,\n`hsl()` / `hsla()`, `hsv()`, `oklab()`, `oklch()`, `ansi256(196)`, or a raw ANSI escape\nsequence. An unknown color or flag throws a `GrftiError` that suggests the nearest match.\n\n![\"stops\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/stops.svg\")
![\"css-gradient\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/css-gradient.svg\")
\n\n![\"errors\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/errors.svg\")
\n\n## Gradients\n\n`gradient(...)` returns a callable, immutable gradient. Every modifier returns a new one.\n\n```ts\nconst brand = gradient('#ff7a59', '#7c2bff');\n\nbrand('hello'); // paint, horizontally\nbrand.vertical(banner); // paint, down the lines\nbrand.diagonal(banner); // paint, across both axes\nbrand.reverse.vertical(banner); // chain as far as you like\nbrand.bg(' padded '); // paint the background instead\nbrand.space('oklch')(banner); // pick the interpolation space\nbrand.depth('ansi256')(banner); // pin the color depth\n\ngradient.vertical('#ff7a59', '#7c2bff')(banner); // or set direction up front\n```\n\n![\"directions\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/directions.svg\")
![\"chaining\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/chaining.svg\")
\n\n![\"background\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/background.svg\")
\n\nMulti-line input is handled without asking. Each line is painted across the width of the\nwidest line, so columns line up — ASCII art and figlet banners come out straight.\n\n```ts\ngradient.atlas(`\n ___ ___ ___\n| || || |\n|___||___||___|\n`);\n```\n\nThe banner at the top of this page is exactly that, painted four ways —\n[`examples/gradients/multiline.ts`](./examples/gradients/multiline.ts).\n\nGrapheme clusters stay whole (emoji and combining marks are never split), existing ANSI\nescapes in the input pass through untouched, and runs of identical color share one escape.\n\n### Reading the colors out\n\nA gradient is a color ramp, not just a text painter:\n\n```ts\nbrand.at(0.5).hex; // '#c860a8'\nbrand.sample(5).map((c) => c.hex); // five evenly spaced stops\nbrand.stops; // [{ color, position }, ...]\nbrand.colors; // just the colors\n```\n\n![\"sampling\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/sampling.svg\")
\n\nThat is what makes it shareable across renderers — a chart colors its bars with\n`sample(bars.length)`, an SVG writer asks for `svg()`, a web preview asks for `css()`.\n\n```ts\nbrand.css(); // 'linear-gradient(90deg, #ff7a59 0%, #7c2bff 100%)'\nbrand.vertical.css(); // 'linear-gradient(180deg, ...)'\nbrand.css({ angle: 45 });\nbrand.svg({ id: 'bg' }); // '![\"handoff\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/handoff.svg\")
\n\n## Colors\n\n`color(...)` returns a callable, immutable color with the same shape.\n\n```ts\nconst accent = color('#3d7fb3');\n\naccent('hello'); // paint the text\naccent.bg('hello'); // paint the background\naccent.ansi; // the raw escape sequence\n\naccent.hex; // '#3d7fb3'\naccent.rgb; // { r, g, b, alpha }\naccent.hsl; // { h, s, l, alpha }\naccent.hsv;\naccent.oklab;\naccent.oklch;\naccent.name; // the CSS color name, when it has one\naccent.luminance;\naccent.isDark;\n\naccent.lighten(0.1); // perceptual, in oklch\naccent.darken(0.1);\naccent.saturate(0.3);\naccent.desaturate(0.3);\naccent.rotate(180);\naccent.alpha(0.5);\naccent.mix('pink'); // oklab midpoint\naccent.mix('pink', 0.25, 'hsl');\naccent.contrast('white'); // WCAG ratio\n```\n\n![\"formats\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/formats.svg\")
![\"inspect\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/inspect.svg\")
\n\n![\"adjust\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/adjust.svg\")
![\"mix\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/mix.svg\")
\n\n![\"contrast\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/contrast.svg\")
\n\nEvery name it answers to:\n\n![\"named\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/named.svg\")
\n\nStandalone helpers are exported too: `rgb()`, `hsl()`, `oklch()`, `parseRgb()`,\n`tryParseRgb()`, `mixRgb()`, `rgbToOklab()`, `rgbToAnsi256()`, `ansi256ToRgb()`, and the\nrest of the conversion set.\n\n## Color depth\n\nDepth is detected once per paint from `FORCE_COLOR`, `NO_COLOR`, `GRFTI_DEPTH`, `COLORTERM`,\n`TERM`, `TERM_PROGRAM`, `CI` and whether stdout is a TTY. Truecolor terminals get 24-bit\nescapes; 256-color terminals get the nearest palette entry, chosen by comparing the color\ncube against the grayscale ramp; 16-color terminals get the nearest base color; everything\nelse gets plain text. Pin it explicitly with `.depth('truecolor')` — worth doing in tests.\n\n![\"depth\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/depth.svg\")
\n\n## Presets\n\nReach for one by property, by name, or from the DSL:\n\n```ts\ngradient.vaporwave('hello');\ngradient('vaporwave')('hello');\ngradient('vaporwave:vertical:reverse')(banner);\ngradient('sunset', 'ice'); // presets concatenate\n```\n\nNo preset name collides with a CSS color name, so the DSL is never ambiguous.\n\n![\"presets\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/presets.svg\")
\n\n![\"concat\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/concat.svg\")
\n\n| Preset | Colors |\n| --- | --- |\n| `atlas` | #feac5e → #c779d0 → #4bc0c8 |\n| `cristal` | #bdfff3 → #4ac29a |\n| `teen` | #77a1d3 → #79cbca → #e684ae |\n| `mind` | #473b7b → #3584a7 → #30d2be |\n| `morning` | #ff5f6d → #ffc371 |\n| `vice` | #5ee7df → #b490ca |\n| `passion` | #f43b47 → #453a94 |\n| `fruit` | #ff4e50 → #f9d423 |\n| `instagram` | #833ab4 → #fd1d1d → #fcb045 |\n| `retro` | #3f51b1 → … → #f7c978 |\n| `summer` | #fdbb2d → #22c1c3 |\n| `rainbow` | full hue sweep |\n| `pastel` | full pastel sweep |\n| `aurora` | #00c9a7 → #4aa3df → #845ec2 |\n| `sunset` | #ff7a59 → #c860a8 → #7c2bff |\n| `synthwave` | #ff2e97 → #7b2ff7 → #2de2e6 |\n| `vaporwave` | #ff71ce → #01cdfe → #05ffa1 |\n| `matrix` | #00ff41 → #008f11 |\n| `amber` | #ffd166 → #ffb000 → #ff6a00 |\n| `phosphor` | #00ff9f → #00d4ff |\n| `midnight` | #a5b4fc → #6366f1 → #312e81 |\n| `paper` | #f6f1e5 → #c9b99b |\n| `hotdog` | #ff0000 → #ffff00 |\n| `breeze` | #cf2f98 → #6a3dec |\n| `candy` | #a58efb → #e9bff8 |\n| `ember` | #ff6363 → #733434 |\n| `falcon` | #bde3ec → #363654 |\n| `meadow` | #59d499 → #a0872d |\n| `raindrop` | #8ec7fb → #1c55aa |\n| `noir` | #e6e6e6 → #4a4a4a |\n| `ice` | #ffffff → #80deea |\n| `sand` | #eed5b6 → #af8856 |\n| `forest` | #83c98d → #2f4f38 |\n| `mono` | #e0e0e0 → #3a3a3a |\n| `fire` | #ffe259 → #ff6b35 → #c1121f |\n| `neon` | #00f5d4 → #f15bb5 |\n| `toxic` | #d8ff3e → #56ab2f |\n| `royal` | #8e2de2 → #4a00e0 |\n| `peach` | #ffecd2 → #fcb69f |\n| `abyss` | #00c6ff → #0072ff |\n| `bubblegum` | #ffafbd → #ffc3a0 |\n| `cyberpunk` | #fcee0a → #00f0ff → #ff003c |\n| `vercel` | #ffffff → #7a7a7a |\n| `supabase` | #6ee7b7 → #3ecf8e → #12805c |\n| `openai` | #74aa9c → #10a37f |\n| `prisma` | #71e8df → #5a67d8 |\n| `stripe` | #00d4ff → #635bff |\n| `cloudflare` | #faad3f → #f6821f |\n| `nuxt` | #36e4da → #00dc82 |\n| `gemini` | #4285f4 → #9b72cb → #d96570 |\n| `tailwind` | #38bdf8 → #818cf8 |\n| `firecrawl` | #fbbf24 → #f97316 → #dc2626 |\n\n## Types\n\nEverything is typed, and the names autocomplete. `NamedColor` is the union of all 148 CSS\ncolor names plus `marine` and `transparent`; `PresetName` is the union of all 52 presets. Both flow into\n`gradient()` and `color()` through a literal union that still accepts arbitrary DSL\nstrings, so you get suggestions without losing expressiveness.\n\n```ts\nimport type { Color, ColorDepth, ColorSpace, Direction, Gradient, NamedColor, PresetName, Rgb, Stop } from 'grfti';\n```\n\n## Interpolation\n\nDefault is **oklab** — perceptually uniform, so pink → cyan does not sag through grey and\nblue → yellow does not dip through mud. Where a straight oklab line leaves the sRGB gamut,\ngrfti reduces chroma at constant lightness and hue until the color fits, instead of clipping\neach channel (which shifts hue).\n\n`oklch` interpolates hue directly, for deliberate hue sweeps. `hsl` and `hsv` are there for\ncompatibility and for vivid wheel spins — pair them with `long` to sweep the whole wheel.\n`rgb` matches what gradient-string and most other tools do.\n\n```ts\ngradient('pink', 'cyan').at(0.5).hex; // '#bbe2e5' oklab\ngradient('pink', 'cyan').space('rgb').at(0.5).hex; // '#80e0e5' rgb\ngradient('pink', 'cyan').space('oklch').at(0.5).hex; // '#ccd1ff' oklch\n```\n\n![\"spaces\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/spaces.svg\")
\n\n![\"hue-spin\"](\"https://raw.githubusercontent.com/tool3/grfti/master/examples/svgs/hue-spin.svg\")
\n\n## Examples\n\nEvery picture on this page is a script in [`examples/`](./examples), and every one of them\nruns:\n\n```sh\nnpm run examples # render all 21\nnpm run example examples/gradients/spaces.ts # or just one\n```\n\nThey run through `tsx`, which is a devDependency — `node examples/….ts` on its own fails\nwith `ERR_MODULE_NOT_FOUND … /src/index`, because grfti's sources carry no file extensions\nin their internal imports and native type stripping insists on them.\n\n`█` is the widest thing a terminal can paint, so a run of them is the closest a text grid\ngets to a swatch — every ramp above is one call, `gradient('sunset')('█'.repeat(40))`, with\nthe terminal filling each cell with a slightly different 24-bit color. Multi-line blocks are\nhow `vertical` and `diagonal` become visible at all.\n\n[`gradients/`](./examples/gradients) holds 14 scripts and [`colors/`](./examples/colors)\nseven; [examples/README.md](./examples/README.md) has the full table.\n\n## CLI\n\n```sh\nnpm install -g grfti-cli\ngrfti sunset \"hello world\"\n```\n\nSee [grfti-cli](https://github.com/tool3/grfti-cli).\n\n## Development\n\nSources are pure TypeScript: no `.js` anywhere outside `dist`, and no file extensions in\ninternal imports. `tsup` resolves them at build time and emits ESM, CJS and declarations.\n\n```sh\nnpm run typecheck # tsc, noEmit — it can never scatter .js next to sources\nnpm test # vitest, runs the .ts directly\nnpm run build # dist/index.js (esm), dist/index.cjs, dist/index.d.ts, dist/index.d.cts\nnpm run examples # tsx, renders examples/svgs\n```\n\n### Running the sources\n\nAnything that executes `src/` needs a loader that resolves extensionless imports. `tsup`\ndoes it at build time, `vitest` does it in tests, and `tsx` does it everywhere else:\n\n```sh\nnpx tsx examples/gradients/spaces.ts\nnpx tsx -e \"import { gradient } from './src/index'; console.log(gradient('sunset')('hi'))\"\n```\n\n`node` and `ts-node` both fail, with the same error and for the same reason:\n\n```\nError [ERR_MODULE_NOT_FOUND]: Cannot find module '…/grfti/src/index'\n```\n\nThe package is `\"type\": \"module\"`, so a relative import is resolved as a URL and must name\na real file. `src/index.ts` imports `'./gradient/create'`, not `'./gradient/create.ts'` —\nNode's native type stripping requires the exact specifier, and `ts-node`'s ESM loader does\nno extension resolution either. Neither has a flag for it; the old\n`--experimental-specifier-resolution=node` was removed in Node 20. Reach for `tsx`.\n\nThe CLI in `grfti-cli` is CommonJS, so it does run under `ts-node` — that is what\n`npm start` there uses.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}