@abhishekshankar/ds

Abhishek Shankar's design system: quiet, typographic and warm-neutral, from abhishekshankar.com. This repo is the single source of truth. The npm package, the docs site (ds.abhishekshankar.com) and the Claude Code plugin are all built from it.

Use it in a project

npx @abhishekshankar/ds init

init is explicit; nothing runs on install. It adds the token imports (or the Tailwind v4 theme), Stylelint and ESLint configs, a lint:ds script, ds.config.json, DS_CANDIDATES.md, src/ds-candidates/, and a GitHub Actions step that lints and reports back. Flags: --dry-run, --no-install, --from <spec>.

Then npx ds doctor checks the setup and version drift, and npx ds report summarises what the project uses, overrides and proposes (governance).

Or import by hand:

@import "@abhishekshankar/ds/tokens.css";      /* tokens (light default, dark via data-theme), base */
@import "@abhishekshankar/ds/fonts.css";       /* Switzer, self-hosted + Fontshare fallback */
@import "@abhishekshankar/ds/components.css";  /* plain-CSS reference components */

Tailwind v4: @import "tailwindcss"; then @import "@abhishekshankar/ds/tailwind.css";.

| Export | | |---|---| | ./tokens.css (also .) · ./tokens.json · ./tokens.js | tokens as CSS, DTCG JSON, JS (+ motion numbers) | | ./components.css · ./tailwind.css · ./fonts.css | components, Tailwind theme, font loader | | ./behavior.js | navbar, theme toggle, menu, dialog, sheet behavior (no dependencies) | | ./figma/light.tokens.json · ./figma/dark.tokens.json | strict DTCG per mode, for Figma variables | | ./stylelint · ./eslint · ./tailwind-classes | guardrails | | ./docs/* | version-matched specs: node_modules/@abhishekshankar/ds/docs |

Guardrails

• Stylelint (ds/use-tokens, ds/max-duration, ds/no-transition-all, ds/known-tokens, ds/no-deprecated-tokens, ds/no-palette): no hex/rgb/hsl or named colors outside token files (var() fallbacks included); color, radius, shadow, duration, easing, font-family and font-size must use tokens; weights are 400/450/500/600; global z-index uses --z-*; no transition: all; no durations over 300ms; every DS-namespaced var() must exist (deprecated ones warn); raw --palette-* stays in token files.
• ESLint / ds lint (ds/no-arbitrary-tailwind): no bg-[#…] or other arbitrary values on design utilities, no default palette (text-gray-500, bg-white), no transition-all, ease-linear, font-bold, shadow-md, or non-token durations.
• ds lint [paths] runs both, including on .astro, .vue, .svelte and .html.

Claude Code plugin

/plugin marketplace add abhishekshankr/abhishek-ds
/plugin install abhishek-ds@abhishek-ds

• Skill abhishek-design-system: points agents at the version-matched docs and holds the rules a linter can't check.
• Hook: after every Write/Edit in a project that uses the package, runs ds lint on that file and feeds violations back to Claude.
• /ds-propose <component>: turns src/ds-candidates/<component> and its DS_CANDIDATES.md entry into a PR on this repo (spec, plain CSS, example, changeset).

Develop

See AGENTS.md. In short: edit tokens/tokens.json or src/, run npm test, then npx changeset.