design-md-drift-check Build Log

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/omidsaffari/design-md-drift-check
• Release: https://github.com/omidsaffari/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:

git clone https://github.com/omidsaffari/design-md-drift-check ~/.claude/skills/design-md-drift-check

Install for Codex:

git clone https://github.com/omidsaffari/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.