Skip to content
Back to skills

Brandrails

ASecurity

Set up a project so AI coding agents stay on its design system. Scans the codebase for design tokens (CSS custom properties, Tailwind v4 @theme, SCSS variables and maps, Angular Material themes), proposes a single DTCG tokens.json for the user to approve, then generates design rules for AGENTS.md, CLAUDE.md, .cursor/rules/design.mdc, .github/copilot-instructions.md and Figma Make guidelines. Use when asked to "make this repo AI-ready", "set up design tokens", "generate design rules for agents...

  • 2 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 18, 2026
ai-agentsgoangularrailsazuregit

Works with

  • cursor

Security analysis

A100/100

Scanned November 18, 2026

npx -y skills add matejholek/brandrails --skill brandrails --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Brandrails?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Brandrails
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/matejholek-brandrails/badge)](https://www.skillsdirectory.com/skills/matejholek-brandrails)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: brandrails
description: Set up a project so AI coding agents stay on its design system. Scans the codebase for design tokens (CSS custom properties, Tailwind v4 @theme, SCSS variables and maps, Angular Material themes), proposes a single DTCG tokens.json for the user to approve, then generates design rules for AGENTS.md, CLAUDE.md, .cursor/rules/design.mdc, .github/copilot-instructions.md and Figma Make guidelines. Use when asked to "make this repo AI-ready", "set up design tokens", "generate design rules for agents", "stop the AI hard-coding colours", or to add the Brandrails drift check to CI.
---

# Brandrails

Turn the design decisions already in a codebase into one source of truth, then teach every AI agent that touches the repo to use it.

## Steps

1. **Scan.** Find token sources, in this order:
   - Tailwind v4 `@theme { ... }` blocks in CSS files
   - `:root` (and `[data-theme]` / `.dark`) CSS custom properties, including shadcn/ui role colours stored as bare HSL channels (`--primary: 221 83% 53%`, typical of Lovable, v0 and shadcn projects on Tailwind v3)
   - SCSS variables and maps (`$color-*`, `$colors: (…)`, `map.get`)
   - Angular: the global `styles` in `angular.json` and the partials they `@use`; Angular Material `mat.theme()` typography, `mat.theme-overrides()` and `--mat-sys-*` values. Palettes like `mat.$azure-palette` are computed at build time, so tell the user to add overrides if they want those colours as tokens
   - an existing `tokens.json` (DTCG) — if present, treat it as the source and skip to step 3

   Read tokens only. Do not parse components; leave those to Figma and Storybook tooling.

   `npx brandrails generate --from <file>` does this deterministically for CSS, SCSS and `angular.json` (in an Angular workspace with no `tokens.json`, plain `npx brandrails generate` reads `angular.json`). Prefer it over hand-parsing, then review its output with the user. Pass its `note:` lines on: dark-theme overrides are not in `tokens.json` yet, and selectors outside `:root` with their own custom properties (`.landing-page { --bg: … }`) are usually a second palette the user should merge or retire.

2. **Propose `tokens.json`.** Write a DTCG file (W3C Design Tokens format: `$value`, `$type`, `$description`, groups by category: `color`, `dimension`/`spacing`, `typography`, `radius`, `shadow`, `motion`). Show the user a short summary: how many tokens per group, duplicates merged, values that had no name. Wait for approval before writing.

3. **Generate rules.** From the approved `tokens.json`, write:
   - `AGENTS.md` — a `## Design system` section (create the file if missing, otherwise replace only that section)
   - `CLAUDE.md` — make sure it contains `@AGENTS.md`
   - `.cursor/rules/design.mdc`
   - `.github/copilot-instructions.md` — a design section
   - `design/figma-make-guidelines.md`

   Every file says the same thing: use tokens, never raw hex/rgb or px; name the token to use for common needs (text, surface, border, accent, spacing steps, radius).

4. **Wire the check (optional).** Offer to add `.github/workflows/brandrails.yml`:

   ```yaml
   on: pull_request
   jobs:
     brandrails:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
           with: { fetch-depth: 0 }
         - uses: matejholek/brandrails@v1
           with:
             command: check
   ```

## Rules

- Never overwrite a user's hand-written content outside the sections Brandrails owns.
- A second run on an unchanged `tokens.json` must produce no diff.
- Keep examples neutral; do not invent brand names or sample data from the user's domain.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.