Tidgrid

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 atoms

Appearance 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.

Roles

What 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 style attribute. Geometry is allowed.
  • Own CSS: a style block, or a stylesheet that is not allowed by name.
  • A stylesheet that differs from what build would 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 works

Try it

Install the tool, write a starter vocabulary, and give your agent three lines of instructions.