forma
/forma
Set up and use Forma, a headless CLI that renders designs from JSON frames and shared design tokens to PNG. Use this skill whenever the user mentions forma, a repo contains forma/config.json, or the user wants to add a design system (colors, type, logos, example images) to a repo and generate on-brand images such as social posts, banners, Open Graph images, thumbnails or ads from it, even if they don't name forma. Not for building web or app UI in code, or for editing existing photos.
- Author
- namzug16 ↗
- Repository
- forma ↗
- Licence
- MIT
- Last repository change
- 04.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Set up and use Forma, a headless CLI that renders designs from JSON frames and shared design tokens to PNG. Use this skill whenever the user mentions forma, a repo contains forma/config.json, or the user wants to add a design system (colors, type, logos, example images) to a repo and generate on-brand images such as social posts, banners, Open Graph images, thumbnails or ads from it, even if they don't name forma. Not for building web or app UI in code, or for editing existing photos.
Original author description
Set up and use Forma, a headless CLI that renders designs from JSON frames and shared design tokens to PNG. Use this skill whenever the user mentions forma, a repo contains forma/config.json, or the user wants to add a design system (colors, type, logos, example images) to a repo and generate on-brand images such as social posts, banners, Open Graph images, thumbnails or ads from it, even if they don't name forma. Not for building web or app UI in code, or for editing existing photos.
How it works
- Check the design system first
- Setting up
- Designing
SKILL.md preview
---
name: forma
description: Set up and use Forma, a headless CLI that renders designs from JSON frames and shared design tokens to PNG. Use this skill whenever the user mentions forma, a repo contains forma/config.json, or the user wants to add a design system (colors, type, logos, example images) to a repo and generate on-brand images such as social posts, banners, Open Graph images, thumbnails or ads from it, even if they don't name forma. Not for building web or app UI in code, or for editing existing photos.
---
# Forma
Forma turns JSON frames into PNGs. A project is a `forma/` directory that sits inside any repo, next
to whatever else lives there.
Run `command -v forma` first. If it is missing, stop and tell the user: Forma is installed with
`brew install namzug16/tap/forma`.
## Check the design system first
Every design depends on an established design system, so check for one before any other step,
every time the user asks for Forma. It is established only when all of these hold:
- `forma/config.json` exists.
- `forma/DESIGN.md` exists and describes the brand.
- `forma/tokens.json` holds the user's values, not the starter placeholders from `forma init`
(those include the colors `#E8FF57` and `#914DFF`).
If any check fails, stop what you are doing: don't write frames, don't run `forma init`, and don't
invent tokens or a style to get unblocked. Tell the user that the design system has to be defined
first, and ask for it:
- the brand and how it should feel
- colors, and what each one is for
- fonts, with weights and sizes for headings and body text
- logos, and any images of the style they want
Once they answer, follow [Setting up](#setting-up), then return to their original request through
[Designing](#designing). If the system is established, go straight to [Designing](#designing).
`forma schema` is the authority on which properties exist. Read
[references/format.md](references/format.md) before writing your first frame: it covers what the
schema can't, such as how anchors, groups, masks, gradients and fonts behave, plus every command.
For generated visuals such as patterns, particles and noise textures, write an artwork instead of
thousands of layers: read [references/artworks.md](references/artworks.md).
## Setting up
Keep the repo's own files out of this. `forma init` only adds `forma/` and one `.gitignore` line, so
the rest of the repo stays exactly as it was.
1. **Create the project.** Run `forma init` at the repo root.
2. **Write the tokens.** `forma/tokens.json` holds starter placeholders, so replace them with the
user's values, copied exactly. Use names that describe the role (`colors.background`,
`typography.heading`), and add categories when needed (`radii`, for example). Starter tokens and
`frames/example.json` depend on each other, so delete the example frame once its tokens are gone.
3. **Install the fonts.** Use `forma fonts search`, `forma fonts info` and
`forma fonts add FAMILY --weight 400,700 --subset latin`, naming only the weights the tokens use,
because a full install is large. Fonts installed this way render the same on every machine.
- A commercial font the user supplies goes in `forma/assets/fonts/` and is referenced with `file`.
- Copying a system font needs `--accept-license`. That is a legal statement about the user's
license, so ask them instead of passing it yourself.
- If you can't tell the font from an image, ask. Guessing a similar font silently changes the
brand.
4. **Store the images.** Sort them by how they will be used:
- Examples of the style go in `forma/references/`. Forma never renders these; they are there so
later sessions can look at them too.
- Logos and photos that will appear in designs go in `forma/assets/images/` or
`forma/assets/svg/`.
5. **Write `forma/DESIGN.md`.** Tokens hold values; this holds the judgment that makes a design look
like the brand, and it is the only memory a later session has. Use this structure, and skip
sections you have nothing to say about:
```markdown
# Design system
## Brand
Who this is for and how it should feel.
## Color
What each color token is for, and which combinations are allowed.
## Type
Which typography token to use where, plus case, weight and length habits.
## Layout
Margins, grid, alignment, density, how much empty space.
## Imagery
Logo placement and clear space, photo or illustration style, icon use.
## Avoid
What would look wrong for this brand.
## References
Each file in forma/references/ and what to take from it.
```
Separate what the user said from what you inferred from the images, and mark inferred rules with
`(inferred)`. The user should be able to see at a glance which rules are your guess.
6. **Prove it.** Build one small frame using the color, type and logo tokens, render it, and compare
it with the references. Then show the user the PNG and list the inferred rules for them to
confirm or correct.
## Designing
1. Read `forma/DESIGN.md`, run `forma tokens`, look at the images in `forma/references/`, and open
the frames already in `forma/frames/`. Reusing their structure is the fastest way to stay
consistent.
2. Create or edit `forma/frames/NAME.json`. Its `id` should match the file name.
3. Use tokens for every color, font, gradient and spacing value the system defines. A hard-coded
value passes validation, but it stops following the system when a token changes.
Build anything whose size depends on its content, such as cards, buttons, lists and captions,
from groups with `layout` instead of computing `x` and `y` yourself; then copy can change without
touching positions:
```json
{ "id": "card", "type": "group", "maxWidth": 480, "fill": "$colors.surface", "cornerRadius": 24,
"layout": { "direction": "column", "gap": 12, "padding": 32 },
"children": [
{ "id": "title", "type": "text", "text": "…", "width": "fill", "font": "$typography.heading",
"fill": "$colors.foreground" },
{ "id": "body", "type": "text", "text": "…", "width": "fill", "font": "$typography.body",
"fill": "$colors.muted" } ] }
```
Keep `x` and `y` for the outermost placement and for deliberate overlaps.
4. Run `forma validate NAME`, then `forma render NAME --json`. Errors include a `code`, a JSON `path`
and the `layer`, which point at the exact fix. Treat warnings as problems too: a fallback font or
substituted weight means the design isn't using the brand's type.
5. Open the PNG and look at it. Validation only proves that the file is well formed, not that the
design works, so check for text collisions, cramped margins, weak hierarchy and anything that
breaks `DESIGN.md`. Use `forma inspect NAME --json` for exact bounds, then edit and repeat.
6. Check for values that bypass the tokens:
```sh
grep -nE '#[0-9A-Fa-f]{3,8}"|"(family|file)"' forma/frames/*.json
```
Replace each match with a token, unless the user asked for it or it is a deliberate one-off.
7. Tell the user where the PNG is, and mention any deliberate exception. If they want to keep
editing it in Figma, run `forma render NAME --format svg --clipboard` and tell them to paste.
If a design needs something the system lacks, add it to `tokens.json` or `DESIGN.md` and say so,
instead of leaving a one-off in the frame. Rules then keep working in the next session.
`forma/output/` is ignored by git; everything else in `forma/` should be committed.
Files in this package (3)
- SKILL.md 7 KB
- references/artworks.md 3 KB
- references/format.md 8 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · namzug16/forma | 100 | MIT |
| FormaMindPro/formamind | 100 | MIT |
| figueirego/forma | 100 | MIT |
| figueirego/forma | 100 | MIT |
| figueirego/forma | 100 | MIT |
| figueirego/forma | 100 | MIT |
| Pukhaan/forma-board | 100 | AGPL-3.0 |
Database snapshot: 13.11.2026 · package version 3bff3a4e04fd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100forma-reference
Find and select design examples in Forma's catalog, research media with credits, analyze sources, and investigate visual or technical differences through source and runtime evidence. Use for inspiration, reproduction, comparison, or evidence-based integration; not to infer… - 100forma-reference
Find and select design examples in Forma's catalog, research media with credits, analyze sources, and investigate visual or technical differences through source and runtime evidence. Use for inspiration, reproduction, comparison, or evidence-based integration; not to infer… - 100forma-templating
Builds an installable project template (a separate plugin in the forma marketplace's templates/ directory) out of the current Forma project, under the name the human gives. Invoke when the human says "create a project template", "make a template from this project", "package the… - 95editable-design
Create and render fixed-canvas editable visual designs, including posters, marketing graphics, covers, menus, banners, and social cards. Default outputs include fixed and editable HTML, PNG, a mouse editor with scan and exploded layer views, and an evidence-backed Design Replay.… - 100brand-image
Render on-brand banners, posts, icons and listing kits from brand/templates. Use when "make a banner", "OG image", "listing kit for X". - 100brand-as-code
Keep the brand book as files in a repo and render every visual from HTML templates with headless Chrome, in every size. Use when setting up a brand book, making covers, social images, posters, banners or speaker cards, or when visuals have started to drift between tools.