@sanjeevsaniel/inkwell-skill

A skill for AI coding agents (Claude Code and any agent that reads AGENTS.md skills folders) to use and maintain a DESIGN.md, plus a checker that fails when DESIGN.md drifts from your code.

Born from the Inkwell design system at sanjeevkujur.dev. Works with any project that keeps its tokens as CSS custom properties.

Install the skill

npx @sanjeevsaniel/inkwell-skill init

This copies the design-md skill into ./.claude/skills (if the project has a .claude folder) or ./.agents/skills. Other places: --target claude|agents, --dir <path>, --personal for your user folder. update replaces it with the newest version, remove deletes it. Add --dry-run to preview.

Start from the Inkwell DESIGN.md

npx @sanjeevsaniel/inkwell-skill template

Writes the Inkwell design system's own DESIGN.md to ./DESIGN.md (or --out <file>), as a worked example and a starting point. It describes Inkwell's palette, type, motion and rules and refers to Inkwell's file paths, so replace its tokens and rules with your own before you rely on it. The copy ships at templates/inkwell/DESIGN.md.

Check DESIGN.md for drift

Add design-md.config.json to the project root:

{
  "doc": "DESIGN.md",
  "css": "src/app/globals.css",
  "typographyConfig": "src/config/typography.config.ts",
  "fontLoader": "src/app/layout.tsx",
  "sourceDir": "src"
}

Then:

npx @sanjeevsaniel/inkwell-skill check

It prints what matched, or lists every drift and exits 1, so it works in CI and as a pre-commit step. Only doc and css are needed for colours and radii. typographyConfig is needed for typography and font_size; fontLoader is optional and adds a "family is loaded" check.

| Front matter block | Compared with | | --- | --- | | colors.light, colors.dark | CSS custom properties, resolved through var() | | rounded | --radius-* (key base is --radius) | | typography | --font-*, fontFamily in the type config, family in the font loader | | font_size | fontSize in the type config, both directions | | motion | each cubic-bezier(...) must appear under sourceDir |

A block is checked only if it is in the front matter. The skill documents the exact format.

What it assumes

• Tokens are CSS custom properties. Light values sit in :root or :where(:root, [data-theme="light"]); dark overrides in [data-theme="dark"].
• The type config exports fontFamily and fontSize as as const objects with single-quoted string values.
• It does not read the prose in DESIGN.md, or tell you what an easing is used for. Keyword easings (ease-out, linear) are not checked.

If your project is shaped differently, open an issue with a small example.

Use the checker from code

import { check } from '@sanjeevsaniel/inkwell-skill';
const { errors, counts } = check('.', { css: 'styles/tokens.css' });

Develop

npm test

Licence

MIT