tidgrid.dev
A closed CSS vocabulary for coding agents.
One file per project defines every class a page may use. A build turns it into one static stylesheet. A check fails on anything outside it.
Why
Left alone, a coding agent writes whatever CSS comes to mind: a new class name here, a hex colour there, a <style> block when it is in a hurry. Every page is a little different, and nobody reviews CSS line by line.
Tidgrid closes the list. The agent reads the vocabulary with tidgrid list and styles pages only with what it finds there. tidgrid check fails when it does not. What the project looks like is decided once, in one file, and reviewed there.
A vocabulary and a page that uses it
tidgrid.toml
[project]
out = "site.css"
scan = ["."]
[tokens.color]
ground = "#0f1214"
ink = "#e6e9eb"
accent = "#5ed5dc"
[tokens.space]
sm = "0.5rem"
md = "1rem"
[tokens.border]
hair = "1px"
[element.body]
background = "{color.ground}"
color = "{color.ink}"
[role.surface.card]
use = "A panel that lifts off the ground. One per group of related content."
border = "{border.hair} solid {color.accent}"
[role.text.title]
use = "The one title of a page."
color = "{color.accent}"
index.html
<main class="tg-col tg-gap(md) tg-pad(md)">
<h1 class="tg-text(title)">Hello</h1>
<section class="tg-surface(card) tg-pad(sm)">
One card.
</section>
</main>
Layout comes from atoms (tg-col, tg-gap(md)) that take their values from the space tokens. Colour and border come only from the roles. tidgrid check passes on this page.
tidgrid list, the part about roles
# roles
## surface
tg-surface(card) A panel that lifts off the ground. One per group of related content.
## text
tg-text(title) The one title of a page.
tidgrid check, after a slip
slip.html:1: unknown class tg-gap(2); tg-gap takes: sm md
slip.html:2: appearance in style attribute: color; use a role (`tidgrid list`)
slip.html:3: unknown class border-l-4: not in the vocabulary; run `tidgrid list`
slip.html:7: own CSS: <style> block; make it a role in the vocabulary
An unknown atom value, an inline colour, a class from nowhere and a <style> block each fail, and the exit code is 1.
Atoms for layout, roles for looks
Layout is atoms
Rows, gaps, padding and widths are free to combine. They always run on the project's token scales, so a gap is tg-gap(md) and never an arbitrary number.
Layout atomsAppearance is roles
Colour, border, shadow and type are reachable only through named roles such as tg-surface(card). What a role looks like is decided once, in the vocabulary file. There is no border atom and no colour atom.
RolesWhat check catches
- A class that is not in the vocabulary, such as
border-l-4. - A class name built from pieces, such as
is-${state}. - Appearance in a
styleattribute. Geometry is allowed. - Own CSS: a style block, or a stylesheet that is not allowed by name.
- A stylesheet that differs from what
buildwould write. - An ignore comment that is never closed.
A message names the fix where there is one, for example src/pages/index.astro:14: unknown class tg-gap(2); tg-gap takes: sm md.
How the checker worksTry it
Install the tool, write a starter vocabulary, and give your agent three lines of instructions.