Skip to content

Contributing: candidates, not edits

The design system has one owner. Projects and agents propose; only Abhishek merges.

In a project

  1. Use what exists first. Check components.md for the closest component and compose from it. Most "new" components are an existing one with different content.
  2. If something is genuinely missing, build it in src/ds-candidates/<component>.* using tokens only (ds lint must pass). Add any new value as a named token in the project's own *.tokens.css.
  3. Add an entry to DS_CANDIDATES.md (template inside): why, closest existing component, anatomy, variants, states with motion tokens, new tokens needed.
  4. Never copy files into the DS repo or edit node_modules/@abhishekshankar/ds.

Proposing

Run /ds-propose <component> (Claude Code plugin abhishek-ds). It opens a pull request on abhishekshankr/abhishek-ds containing:

  • a spec section in docs/components.md (anatomy / variants / states / rules, marked "derived"),
  • plain CSS appended to src/components.css on tokens only (no framework code),
  • any new tokens in tokens/tokens.json with light and dark values,
  • a rendered example in site/examples.html,
  • a changeset (minor for a new component or token).

It then marks the candidate proposed with the PR link. Abhishek reviews, edits, merges and releases; the project picks it up with a normal package update.

In the DS repo

  • tokens/tokens.json is the only hand-edited value file. Run npm run build after editing.
  • npm test must pass: it lints src/components.css with the package's own rules.
  • Every change needs npx changeset. Renaming or removing a token or class is a major bump.