petals

Brand that agents read. petals carries your brand into everything a coding agent builds, and checks what came out: a skill the agent reads before it writes a line, and a deterministic check after, with no model in the loop.

Landing page · Feature map

Try it

The repository carries a frozen copy of a real brand and a draft hero with the slips an agent makes: a font outside the brand, a framework blue, off-scale spacing, a pure black shadow, a forbidden term, placeholder copy and a link to nowhere. Check it:

git clone https://github.com/jahala/petals && cd petals
petals/bin/petals check test/fixtures/landing/hero.html \
  --brand test/fixtures/brand-plotplot-v1.11.0/.brand --product petals

WARNING [layout] line 3: 13px is outside the spacing scale. Did you mean 12px or 16px?
WARNING [surface] line 3: 7px is off the radius scale. Did you mean 6px or 8px?
ERROR [typography] line 4: "Inter" is not a typography.md family (Protest Riot, Hanken Grotesk, JetBrains Mono).
ERROR [color] line 4: #3B82F6 is not in the palette. Did you mean #4E88A6?
ERROR [color] line 5: #000 is not in the palette. Did you mean #1C1610?
WARNING [surface] line 5: shadow uses pure black. Brand shadows are ink-tinted (components.md Shadow Recipes).
ERROR [content] line 7: placeholder copy. Write the real words, or keep this page under a mockup path.
ERROR [voice] line 8: "supercharge" is a forbidden term. Use "strengthen, improve, clarify" instead.
ERROR [content] line 9: href="#" goes nowhere. Link the real page, or keep this page under a mockup path.

--- petals check (deterministic) ---
Colors:   2 error(s), 0 warning(s)
Layout:   0 error(s), 1 warning(s)
Surface:  0 error(s), 2 warning(s)
Voice:    1 error(s), 0 warning(s)
Typography: 1 error(s), 0 warning(s) (families; heading and body roles stay with the agent)
Content:  2 error(s), 0 warning(s), 0 note(s) (production stage)
Access:   0 error(s), 0 warning(s) (what the source shows; rendered checks stay with a browser)
Reuse:    no contracts (.brand/components/ holds none)
Result: FAIL (6 error(s) to fix, 3 warning(s) to review).

The run takes milliseconds, makes no network calls and exits 1. Add --format sarif for one SARIF 2.1.0 log instead of text.

Install

petals needs bash, awk, git and python3. There is no build and no account.

git clone https://github.com/jahala/petals
ln -s "$PWD/petals/petals" ~/.claude/skills/petals          # the skill
ln -s "$PWD/petals/petals/bin/petals" ~/.local/bin/petals   # the command

Then give a project its brand, from a folder of guidelines (a PDF, assets, a deck) or from a central brand repository:

/petals init brand-assets/
/petals init --from github.com/yourcompany/brand

Extraction writes .brand/: seven markdown files (colors, typography, layout, components, voice, identity, DESIGN), two token files derived from them (tokens.css, tokens.json) and a byte-for-byte copy of your logo. Only stated values are written. Anything missing is flagged for a person, never guessed. From then on the agent reads the brand before it builds UI or writes copy.

What it checks

Dimension	Against	Finds
color	colors.md	off-palette colours in hex, oklch(), oklab(), rgb() or hsl() (with the nearest match), colours outside sRGB, contrast below the minimum in each theme
typography	typography.md	fonts the brand does not use, weights or italics a face does not ship
layout	layout.md	spacing and breakpoints off the scale
surface	components.md	radii, strokes and shadows off the tokens
voice	voice.md	forbidden terms with their replacements, banned synonyms, em dashes
content	the stage	placeholder copy, dummy contacts, dead links
reuse	components/	a control rebuilt by hand where a component contract covers it
access	the source	an image without alt, a field without a label, a nameless button, focus removed, zoom blocked, a clickable div

Two judgments stay with the agent: whether a heading or body role got the right face, and tone.

Four faces on one check

Command	Does
petals check <file>	judges one file against the brand and prints each finding, or one SARIF log
petals gate [--base <ref>]	judges the files a change touches, with the brand and rules the base carries, so a change cannot loosen its own rules
petals guard pre-commit	judges what is staged when a commit is made, and refuses the commit over an error
petals review <page>	opens pages in your browser behind an index, and leaves nothing behind

Exit 0 is clean or warnings only, exit 1 is at least one error, and exit 3 means the check could not judge (no brand, for example) and says why. Exit 3 is a refusal, not a pass.

To check every commit, plant the hooks:

printf '#!/bin/sh\nexec petals guard pre-commit\n' > .git/hooks/pre-commit
printf '#!/bin/sh\nexec petals guard commit-msg "$1"\n' > .git/hooks/commit-msg
chmod +x .git/hooks/pre-commit .git/hooks/commit-msg

A finding can go through on the record with a trailer on the commit, Petals-allow: <rule> <reason>. It stays in the log as a note that carries the reason. A trailer without a reason allows nothing.

Mockups and production

Believable filler is how a mockup gets judged, so content findings are errors in production and notes in a mockup. Brand rules are the same in both. Mark mockup paths in .petalsrc:

stages:
  mockup:
    - docs/designs/**

This is the beginning of the README. Read the rest at the original. Read the full README ↗