design-system-skill

A Claude Code skill by @marlon14421 that bundles a personal design system — tokens, the four core components (Button, Input, Card, Badge), the motion system, and the philosophy.

This skill IS the design system. Every value, class name, and pattern is canonical. No parallel tokens, no drifting hex codes, no extra easing curves.

Why

Building UIs that look consistent, accessible, and on-brand is painful. Designers drift, devs invent new hex codes, motion gets bolted on later. This skill ships all of it as a single source of truth that Claude loads before writing any UI.

Install

Option 1 — One-liner via npx (no permanent install)

npx design-system-skill

Downloads the package, copies the skill into ~/.claude/skills/design-system-skill/, exits. Then restart Claude Code.

Option 2 — Global install

npm install -g design-system-skill
dsskill

Option 3 — Manual install

git clone https://github.com/marlon14421/design.system.skill
mkdir -p ~/.claude/skills
cp -R design.system.skill/skills/design-system-skill ~/.claude/skills/

The skill lives at ~/.claude/skills/design-system-skill/SKILL.md after any of the above.

How to use it

Once installed, just ask Claude anything that touches UI:

• “Add a primary button using the system.”
• “Build a card with the indigo gradient.”
• “Use a card like the kit.”
• “Match the brand.”

Claude will load this skill automatically and ask for your primary brand color first (everything else is derived from it). Paste any hex — #10B981, #F97316, #EC4899, your custom brand.

What you get

| Area | Contents | | -------------- | ----------------------------------------------------- | | Tokens | Color, spacing, typography, radius, shadow, motion | | Components | Button, Input, Card, Badge — vanilla CSS + Tailwind | | Motion | 200ms durations, reduced-motion fallbacks | | A11y | Focus rings, contrast, prefers-reduced-motion |

Repo layout

.
├── README.md                        ← you are here
├── package.json                     ← npm config (npx entry point)
├── bin/
│   └── install.js                   ← the npx installer
└── skills/
    └── design-system-skill/         ← the actual skill
        ├── SKILL.md                 ← main entry (loaded by Claude)
        └── references/
            ├── derivation.md        ← primary color → full scale
            ├── tokens.md            ← canonical token reference
            ├── components-css.md    ← vanilla CSS snippets
            ├── components-tailwind.md   ← Tailwind snippets + preset
            ├── motion.md            ← motion system
            └── blueprint-philosophy.md  ← philosophy & rules

How the npx install works

The package itself has no runtime code for the consumer — it's a delivery vehicle for the skills/design-system-skill/ folder. The bin/install.js script:

1. Reads the bundled skills/design-system-skill/ from the npm tarball
2. Copies it to ~/.claude/skills/design-system-skill/
3. Removes the previous install first (safe to re-run)

That folder is exactly what Claude Code's skill system looks for. No build step, no transpilation, no symlinks.

Development

The skill is plain Markdown + reference docs. To iterate:

1. Edit files under skills/design-system-skill/
2. Bump version in package.json
3. npm publish

A typical iteration: change a token → Claude loads the new file next session → next UI you ask for uses the new token. No build step.

To test changes locally before publishing:

node bin/install.js
# or
npm link && dsskill

Publishing

npm login
npm publish --access public

After publishing, anyone can install with:

npx design-system-skill

Contributing

PRs welcome. Two rules:

1. Don't invent parallel tokens. If a value isn't in references/tokens.md, it doesn't exist.
2. Ask for primary color first. Anything color-derived must go through references/derivation.md.

Author

@marlon14421

Credits

The design system (tokens, components, motion) is from the DesignMotionHQ kit. I only packaged it as a Claude Code skill.

License

MIT