# Design System Loop

> Open-source npm package and agent skill that helps coding agents audit, build, and maintain design systems with local source checks.

Design System Loop (DS Loop) is an MIT-licensed npm package and agent skill built by Mohammad Owaiz Shaik. It pairs a local audit engine with a skill that guides a coding agent through investigating a codebase, proposing a plan, and carrying out the changes a team approves. The project is described as a supervised alpha that requires Node.js 22.6 or later.

## What It Is

DS Loop is a design-system toolkit for teams whose codebases are growing and drifting, for example where buttons are rebuilt or tokens are bypassed. It has two parts: an engine that supplies repeatable source checks and evidence, and a skill that guides the agent through diagnosis, delivery, and verification. The team keeps control of priorities and shared decisions.

## How the Workflow Runs

The workflow has four stages: investigate, consult, build, and keep healthy. The agent first reads code, tokens, components, and docs, and findings include source references. It then reports and proposes an ordered plan in which each step states what it changes and how success will be checked. After approval, the agent implements the work, reruns the audit, and records notes. Optional hooks and CI can keep issues from drifting back.

## Outputs and Reports

The CLI can run without an AI account, model calls, or API keys. Commands such as `audit`, `consumers`, `report`, `scorecard`, and `dashboard` produce self-contained HTML reports covering findings with source locations, coverage, token references, component usage, and saved trends. The `fix` command previews mechanical `var()` fallback edits until `--write` is passed. The work leaves behind shared components, editable tokens, working examples, and documented decisions in the project.

## Setup and Coverage Limits

Install with `npm install -D ds-loop@latest`, then connect a host such as Claude Code, Codex, or Cursor with `npx ds-loop install --agent`. The engine reads CSS custom properties and selected CSS properties, Tailwind values in JavaScript and TypeScript, DTCG and Style Dictionary token JSON, and bounded SCSS/Sass. It does not cover Vue/Svelte templates, CSS-in-JS, layout, interaction, accessibility, or design quality, which need rendered review. Changes should be reviewed before shipping.

## Features
- Local source audit of design-token inconsistencies
- Agent-guided investigate, consult, build, and keep-healthy workflow
- Self-contained HTML audit, consulting, component-usage, and dashboard reports
- Component consumer and usage analysis
- Previewable fix for var() fallback edits
- Optional post-edit guard hook and CI checks
- Claude Code plugin commands
- Runs locally with no model calls or API keys
- Supports CSS, Tailwind, DTCG/Style Dictionary tokens, and SCSS/Sass

## Integrations
Claude Code, Codex, Cursor, Storybook, shadcn/ui, Style Dictionary, Tailwind CSS

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
0.4.0

## Links
- Website: https://designsystemloop.dev
- Documentation: https://designsystemloop.dev/guide/workflow.html
- Repository: https://github.com/owaizin/ds-loop
- EveryDev.ai: https://www.everydev.ai/tools/design-system-loop