The Problem
Out of the box, Claude Code builds interfaces that work and look like every
other AI-built page. It will:
- Reach for a purple-to-blue gradient, a glowing orb and an indigo accent
- Describe the product as "clean, modern, seamless" and design to that
- Use the framework's default type, spacing and radius without deciding anything
- Animate everything, with
transition: all and no reduced-motion guard
- Invent metrics, testimonials and customer logos to fill a hero
None of it is wrong on its own. Together it is slop: a page a competitor could
ship unchanged.
The Solution
This kit provides a CLAUDE.md ruleset, a direction file, skills, review
agents and hooks that enforce one discipline:
Brief → Direction → Build → Audit, every time.
The cardinal rule the whole kit exists to enforce: every color, typeface,
spacing value, icon and animation traces back to a decision about this
product, written down in DESIGN_MAP.md before the CSS.
Quick Start
From your product repo:
npx @tansuasici/claude-design-kit init
Then start a Claude Code session and run /design-brief, then /direction.
DESIGN_MAP.md is the single most important file: it is read first every
session.
Other ways to install
As a Claude Code plugin, inside Claude Code:
/plugin marketplace add tansuasici/claude-plugins
/plugin install design-kit@tansuasici
Installed it earlier as claude-design-kit@claude-design-kit? That keeps
updating; to move over, uninstall it and install design-kit@tansuasici.
From a clone:
git clone https://github.com/tansuasici/claude-design-kit ~/claude-design-kit
bash ~/claude-design-kit/install.sh "$PWD"
| npx / clone | Plugin |
|---|
| Skills, agents, hooks | copied into .claude/ | loaded from the plugin, namespaced (/design-kit:design-brief) |
CLAUDE.md rules | installed | not loaded |
DESIGN_MAP.md, agent_docs/ | seeded in the repo | stay in the plugin; session-start points at them |
| Updates | npx @tansuasici/claude-design-kit init --upgrade | /plugin update |
The npx installer is the full kit. The plugin is the lighter option when you
want the skills and hooks without kit files in the repo.
Installer options
| Flag | Description |
|---|
--upgrade | Update kit-managed files |
--force | Replace kit files that already exist |
--gitignore | Keep the kit out of your repo |
--dry-run | Print what would happen; change nothing |
Your overlay (DESIGN_MAP.md, CLAUDE.project.md, linear.md) is never
overwritten. An existing .claude/settings.json gets the kit's hooks merged in
rather than replaced. If you already have a CLAUDE.md, the installer keeps it
and warns; move your rules into CLAUDE.project.md and rerun with --force.
npx @tansuasici/claude-design-kit uninstall (or uninstall.sh) deletes only the files the kit installed; --keep-project also
keeps the overlay.
Requirements: bash, git and python3 (Node 18+ for npx). The scan hooks (slop-scan, motion-gate)
and the settings merge need python3; without it they stay silent.
Next to another Claude kit
The Marketing, Code and Research kits use the same CLAUDE.md and the same hook names, so two kits can't share a folder. install.sh and uninstall.sh stop and change nothing when they find one of those kits in the target folder.
Install this kit into a subfolder instead, and open Claude Code in that subfolder:
bash ~/claude-design-kit/install.sh "$PWD/design"
cd design && claude
Hooks only run from the folder the session opened in. A session opened at the repo root doesn't run the subfolder's hooks, so motion-gate won't check a write under design/ from there.
A copy of one of those kits from before this check doesn't stop: its install.sh or uninstall.sh still replaces or deletes this kit's files.
What CLAUDE.md Enforces
| Rule | What it does |
|---|
| Tiered Session Boot | Loads the design map and project overlay first; slop signs, tokens, motion and interface rules only when relevant |
| Chosen, Not Defaulted | The cardinal rule: no reflex palette, no empty character words, no invented product facts or fake assets |
| Build Discipline | Reuse before adding, match the codebase, tokens not literals, one spacing rhythm, three levels of hierarchy |
| Motion Discipline | Every animation has a reason; ease-out, under ~300ms, transform/opacity only, reduced motion respected |
| Approval Required | Stops before changing the direction, brand assets, shared tokens or components, adding a dependency, or writing claims |
| Verification | Renders → screenshots at 3 widths, light and dark → keyboard → states → slop pass → competitor test |
| Self-Improvement | Corrections that generalise go to DESIGN_MAP.md → Don'ts |
Hooks
| Hook | Event | Does |
|---|
session-start.sh | SessionStart | Reports whether DESIGN_MAP.md is filled, shows Character and Signature, lists linear.md → Now. |
prompt-router.sh | UserPromptSubmit | Adds reminders for vague aesthetic asks, landing pages, page sections, motion, brand, forms and data UI. |
slop-scan.sh | PostToolUse (Edit/Write) | Warns on reflex gradients, transition-all, ambient pulse/ping, heavy display weights, emoji icons, hype copy, and banned character words in DESIGN_MAP.md. |
motion-gate.sh | PostToolUse (Edit/Write) | Warns on motion without a reduced-motion guard and on animated layout properties. |
branch-protect.sh | PreToolUse (Bash) | Blocks pushes to main/master and force-pushes. |
block-dangerous-commands.sh | PreToolUse (Bash) | Blocks destructive shell commands. |
The scan hooks warn; they never block. A file that has a reason to break a rule
can opt out with design-kit-allow-slop or design-kit-allow-motion in its
first 5 lines. Hook silence is not a design review: hooks catch class names and
keyframes, not hierarchy or taste.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
