# design-md-drift-check Build Log

> A build log for design-md-drift-check, a skill that checks DESIGN.md drift against real frontend tokens, components, and UI patterns.

Source: https://dvnc.dev/blog/design-md-drift-check-build-log

---

:::intro
`design-md-drift-check` is a small Claude Code and Codex skill for one job:
keep an existing `DESIGN.md` honest against the frontend code that actually
ships.
:::

## Why this exists

`DESIGN.md` is becoming a useful agent-readable design file. The repo
`google-labs-code/design.md` was trending today, and its positioning is clear:
give coding agents a persistent, structured understanding of a visual identity.

The weak point is maintenance. A team changes Tailwind tokens, CSS variables,
button variants, component states, or page density, and the design file keeps
describing last week's interface. After that, every generated UI inherits stale
rules.

Generic `DESIGN.md` generators already exist. This release does the narrower
job: check drift between an existing `DESIGN.md` and local source evidence.

## What shipped

The repo is a template-backed skill package:

- Repo: https://github.com/dvnc-labs/design-md-drift-check
- Release: https://github.com/dvnc-labs/design-md-drift-check/releases/tag/v0.1.0
- Type: Claude Code / Codex skill
- Scaffold: `omidsaffari/skill-starter`
- License: MIT

The skill tells the agent to read `DESIGN.md`, inspect source-backed evidence,
classify each claim, and either report drift or patch the design file when the
user explicitly asks for repair.

The evidence list is deliberately local and practical: Tailwind config, CSS
variables, design tokens, component variants, page patterns, brand assets,
interaction states, and responsive breakpoints.

## Build notes

The first candidate was a general `DESIGN.md` maintainer skill. Dedupe rejected
that direction because the broader skill space already has credible public
repos, including URL-to-DESIGN.md and full-file generation flows.

The final scope is smaller and more defensible: drift checking. It does not
invent a visual identity, scrape a brand, redesign a UI, or act as a frontend
review framework. It keeps one repo's existing agent-facing design file aligned
with the source of truth.

Local gates passed:

- `SKILL.md` frontmatter validation
- placeholder guard
- README, LICENSE, changelog, demo GIF, and OG asset presence checks
- markdown lint with zero errors
- GitHub Actions CI on commit `89b98bf`

The repo is public, marked as a template, and tagged for discovery across
`skill`, `claude-code`, `codex`, `agent-skills`, `design-md`, `design-system`,
`tailwind`, `css`, `tokens`, and `drift-check`.

## How to use it

Install for Claude Code:

```bash
git clone https://github.com/dvnc-labs/design-md-drift-check ~/.claude/skills/design-md-drift-check
```

Install for Codex:

```bash
git clone https://github.com/dvnc-labs/design-md-drift-check ~/.agents/skills/design-md-drift-check
```

Then ask for a `DESIGN.md` drift check, a source-backed report, or an explicit
patch of stale design guidance.

## What is intentionally absent

There is no hosted app and no model runtime. The release is a perimeter artifact:
a small instruction package that makes existing coding agents better at a
specific repository maintenance job.

The preview assets live in the repo as `assets/demo.gif` and `assets/og.png`.
For this artifact type, the useful demo is the README and the skill file itself,
not a hosted web UI.
