Getting started
CLI
The expressive CLI sets up your project, copies components in, regenerates your theme, and shows how your copies differ from the originals.
Run it with npx @grenishrai/expressive, as in the examples below. If you install it globally (npm i -g @grenishrai/expressive), the command is simply expressive.
init
Sets up config, tokens, the motion layer, the stylesheet and your theme. Run it once.
npx @grenishrai/expressive init
npx @grenishrai/expressive init --yes --seed "#0B57D0" --motion motion| Prop | Type | Default | Description |
|---|---|---|---|
| -y, --yes | flag | — | Skip prompts and use defaults for anything not passed. |
| --seed <hex> | string | #6750A4 | Seed color. |
| --variant <scheme> | string | expressive | expressive, tonal-spot, vibrant, neutral, monochrome, fidelity, content, rainbow or fruit-salad. |
| --font <family> | string | Roboto Flex | Font family, or a CSS variable like var(--font-geist). |
| --scheme <scheme> | expressive | standard | fluid | expressive | Default motion scheme. fluid needs the Motion or GSAP engine. |
| --motion <engine> | css | motion | gsap | css (motion for fluid) | Motion engine. |
| --shape <scale> | expressive | soft | sharp | expressive | Corner scale. |
| --css <file> | path | detected | Global CSS file that imports Tailwind. |
| --no-install | flag | — | Don't install npm packages. |
| -c, --cwd <path> | path | current dir | Project directory. |
| -r, --registry <url|path> | url | path | from expressive.json | Registry to read components from. |
add
Copies components, and anything they depend on, into your project.
npx @grenishrai/expressive add button text-field navigation-barIf a file already exists and you've changed it, add asks before replacing it. With --yes it skips those files and tells you which ones; with --overwrite it replaces them.
| Prop | Type | Default | Description |
|---|---|---|---|
| -o, --overwrite | flag | — | Replace files that have local changes. |
| -y, --yes | flag | — | Don't prompt; keep locally changed files. |
| --no-install | flag | — | Don't install npm packages. |
| -c, --cwd <path> | path | current dir | Project directory. |
| -r, --registry <url|path> | url | path | from expressive.json | Registry to read components from. |
theme
Regenerates the theme variables in your global CSS (between the expressive:theme markers) and saves the new settings to expressive.json.
npx @grenishrai/expressive theme --seed "#B3261E" --variant vibrant
npx @grenishrai/expressive theme --contrast 0.5
npx @grenishrai/expressive theme --scheme fluid --motion motion| Prop | Type | Default | Description |
|---|---|---|---|
| --seed <hex> | string | — | New seed color. |
| --variant <scheme> | string | — | New color scheme. |
| --contrast <level> | number | — | From -1 (lower) through 0 (standard) to 1 (high contrast). |
| --font <family> | string | — | New font family. |
| --shape <scale> | string | — | New corner scale. |
| --scheme <scheme> | expressive | standard | fluid | — | New default motion scheme. |
| --motion <engine> | css | motion | gsap | — | Switch engine: installs its adapter and repoints tokens/motion.ts. |
| -c, --cwd <path> | path | — | Project directory. |
list
Lists available components and marks the ones you've installed.
npx @grenishrai/expressive listdiff
Shows how your copy of a component differs from the registry version, for example before updating it.
npx @grenishrai/expressive diff buttonexpressive.json
Written by init. Edit it to move files or change aliases; the CLI reads it on every command.
{
"registry": "https://expressive.grenishrai.pro/r",
"framework": "next",
"rsc": true,
"css": "src/app/globals.css",
"motion": "css",
"theme": {
"seed": "#6750A4",
"variant": "expressive",
"contrast": 0,
"font": { "brand": "Roboto Flex", "plain": "Roboto Flex" },
"shape": "expressive",
"motionScheme": "expressive"
},
"dirs": {
"components": "src/components/expressive",
"lib": "src/lib/expressive",
"tokens": "src/lib/expressive/tokens",
"styles": "src/app"
},
"aliases": {
"components": "@/components/expressive",
"lib": "@/lib/expressive",
"tokens": "@/lib/expressive/tokens"
}
}rsc: keep"use client"directives. On for the Next.js App Router, off elsewhere.aliases: import prefixes from yourtsconfig.jsonpaths. Leave it empty to get relative imports.