# Claude Design Kit — Full Documentation
> The complete documentation for Claude Design Kit, concatenated for LLM ingestion.
> Compact index: https://claudedesignkit.tansuasici.com/llms.txt
> Site: https://claudedesignkit.tansuasici.com
> Repo: https://github.com/tansuasici/claude-design-kit
---
# Introduction
> Drop-in templates that make Claude Code design interfaces that look chosen, not defaulted.
Source: https://claudedesignkit.tansuasici.com/docs
## 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:
```bash
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:**
```bash
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.
## 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, 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.
## Agents
| Agent | Reads |
| -------------------- | --------------------------------------------------------------------------------------------- |
| `design-critic` | A screen against `DESIGN_MAP.md` and the slop signs. Not anchored on the code you just wrote. |
| `interface-reviewer` | Interface guidelines compliance. |
| `motion-reviewer` | Animations against the motion discipline. |
All three run on Opus and leave their findings in `.hook-state/agent-handoff.md`.
## Skills
| Skill | Use it for |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `/design-brief` | Start here. Reads the project, asks once, fills Product, Competitors and the subject inventory. |
| `/direction` | Writes the five-line direction and tokens into `DESIGN_MAP.md`, then stops for approval. |
| `/slop-audit` | Finds AI-slop signs, rates the screen heavy / light / none, fixes in nine ordered passes. |
| `/interface-check` | Interface guidelines review (keyboard, focus, forms, layout, content, performance) as a Blocker / Major / Minor table. |
| `/motion-craft` | Adding an animation: frequency gate, purpose, cheapest tool, guards. |
| `/motion-review` | Reviewing existing motion: Before / After / Why table and a Block or Approve verdict. |
| `/stress-ui` | Breaks a component with empty, long, many, slow, failing and RTL inputs. |
| `/brand-method` | Logo, type and color system from a brand intake, with a reflex test. |
## What's Inside
```
CLAUDE.md ruleset (tiered boot, cardinal rule, approvals, verification)
DESIGN_MAP.md the direction: Product, Character, World, Moments,
Signature, Tokens, Competitors, Don'ts
CLAUDE.project.md your project overlay (never touched by upgrades)
linear.md open work: Now / Next / Later
agent_docs/ slop-signs, tokens, motion, interface-guidelines,
direction, brand-identity
.claude/skills/ 8 user-invocable skills
.claude/agents/ 3 review agents
.claude/hooks/ 6 hooks + lib/
.claude/settings.json hook wiring and permissions
```
## Customization
1. **Fill in `DESIGN_MAP.md`** with `/design-brief` and `/direction`. The more specific the character and signature, the less the build drifts toward generic.
2. **Customize `CLAUDE.project.md`**: stack, component library, brand constraints that override kit defaults.
3. **Grow the Don'ts.** Every visual correction that generalises goes to `DESIGN_MAP.md → Don'ts`, so it holds next session.
## Sources
The kit distills a workflow from these projects. Each one is worth installing
on its own; see [SOURCES.md](/docs/sources) for what came from where and the
install commands.
- [unslop](https://github.com/heydamir/unslop) by Damir Sokolovsky: slop signs, tokens, direction (CC BY 4.0)
- [emilkowalski/skills](https://github.com/emilkowalski/skills) by Emil Kowalski: motion craft and review, UI stress testing (MIT)
- [taste-skill](https://github.com/Leonxlnx/taste-skill) by Leonxlnx: inventory, argument, competitor test (MIT)
- [Web Interface Guidelines](https://vercel.com/design/guidelines) by Vercel: interface rules (MIT)
- [brand-identity-skill](https://github.com/fatihaydost/brand-identity-skill) by Fatih Aydost: brand method (MIT)
## Contributing
PRs welcome. If you've found a slop sign the kit misses, or a hook false
positive, open an issue or a PR with a fixture that shows it.
## License
MIT, except three files adapted from unslop, which stay CC BY 4.0. See
[LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](/docs/third-party-notices).
---
# Why This Kit
> Why a direction file, scan hooks and independent critics beat asking Claude Code to make it look good.
Source: https://claudedesignkit.tansuasici.com/docs/why-this-kit
Out of the box, Claude Code builds interfaces that work. They also look like every other AI-built page, and that is the problem.
A broken layout gets fixed because someone sees it. A *default* layout ships, because nothing is technically wrong with it. Slop is the sum of choices nobody made.
## What goes wrong without it
Left to its defaults, the agent 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 a page a competitor could ship unchanged.
## Why "make it look good" isn't enough
A vague aesthetic ask gets the model's average taste, and the model's average taste is the template. "Make it premium" produces the same page for a law firm and a skate shop. What changes the output is a **decision written down before the CSS**: who this is for, what world it borrows from, the one detail it owns.
The kit makes that decision a file and keeps it in front of the agent:
| Concern | Left to the prompt | With this kit |
|---|---|---|
| No direction | "make it modern" | `/design-brief` and `/direction` fill `DESIGN_MAP.md`, then stop for approval |
| Direction drifts mid-session | hope it holds | `session-start` re-surfaces Character and Signature every session |
| Reflex palette, `transition-all`, hype copy | catch it in review | `slop-scan` flags the line right after the edit |
| Motion without a reduced-motion guard | rarely noticed | `motion-gate` flags it right after the edit |
| Reviewing your own work | anchored on the code just written | `design-critic` reads the rendered screen fresh |
The hooks warn; they never block. A pattern can't tell a reflex from a choice the direction made on purpose, so the final call stays with you and the map.
## What you get
- **CLAUDE.md**: the cardinal rule *Chosen, Not Defaulted* and the Brief → Direction → Build → Audit loop, read at every session boot.
- **DESIGN_MAP.md**: Product, Character, World, Moments, Signature, Tokens, Competitors and Don'ts. Every token names the line it serves.
- **6 hooks**: `session-start`, `prompt-router`, `slop-scan`, `motion-gate`, `branch-protect`, `block-dangerous-commands`.
- **8 skills**: `/design-brief`, `/direction`, `/brand-method`, `/motion-craft`, `/slop-audit`, `/interface-check`, `/motion-review`, `/stress-ui`.
- **3 review agents**: `design-critic`, `interface-reviewer`, `motion-reviewer`, all on Opus.
- **6 reference docs**: [slop signs](/docs/slop-signs), [direction](/docs/direction-guide), [tokens](/docs/tokens), [motion](/docs/motion), [interface guidelines](/docs/interface-guidelines), [brand identity](/docs/brand-identity).
## It stays yours
Everything is plain markdown and shell. The installer never overwrites your overlay (`DESIGN_MAP.md`, `CLAUDE.project.md`, `linear.md`), merges its hooks into an existing `.claude/settings.json`, and `uninstall.sh` removes only what it installed. MIT, except three files adapted from unslop that stay CC BY 4.0; see [Sources](/docs/sources).
---
# FAQ
> Common questions about Claude Design Kit: what it installs, what the hooks check, frameworks, and what it will not do for you.
Source: https://claudedesignkit.tansuasici.com/docs/faq
## What does the installer change in my repo?
`install.sh` copies `CLAUDE.md`, `agent_docs/`, the skills, agents and hooks under `.claude/`, and creates the overlay files (`DESIGN_MAP.md`, `CLAUDE.project.md`, `linear.md`) if they don't exist. It never overwrites the overlay. If you already have a `.claude/settings.json`, the kit's hooks are merged into it rather than replacing it. Run with `--dry-run` first to see every file it would touch.
If you already have a `CLAUDE.md`, the installer keeps it and warns. Move your rules into `CLAUDE.project.md` and rerun with `--force`.
## Do the hooks block my edits?
No. `slop-scan` and `motion-gate` only warn: they add a note to the agent's context after an edit, naming the file and line. Only `branch-protect` (pushes to `main`/`master`, force-pushes) and `block-dangerous-commands` block anything.
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.
## What exactly does slop-scan look for?
In `.tsx`, `.jsx`, `.vue`, `.svelte`, `.astro`, `.html`, `.css` and `.scss` files: purple, violet and fuchsia gradients, `transition-all`, `animate-pulse` and `animate-ping`, `font-black`/`font-extrabold` and bold headings, emoji used as icons, and hype words in copy (supercharge, seamless, unlock, magic, revolutionize, game-changing). In `DESIGN_MAP.md` it flags empty character words under `## Character`.
Hook silence is not a design review. Hooks catch class names and keyframes, not hierarchy, rhythm or taste. That is what `/slop-audit` and the `design-critic` agent are for.
## Does it work with my framework?
The discipline is framework-agnostic: the map, the loop and the audits apply to any UI. The scan hooks read file text, so they work on any of the extensions above whether you use Tailwind, CSS modules or plain CSS. The Tailwind class checks only fire where Tailwind classes exist.
## What does it need?
bash, git and python3. The scan hooks and the settings merge need python3; without it they stay silent rather than report a false "clean".
## Will it pick a design for me?
No. `/direction` writes a proposal into `DESIGN_MAP.md` and then stops for your agreement. `/brand-method` builds 1–4 sets and asks you to choose. The kit's job is to make sure *someone* chose, not to choose for you.
## Will it write marketing numbers or testimonials?
No. Inventing metrics, testimonials, customer logos, pricing or awards is against the cardinal rule. Placeholder data is marked `[PLACEHOLDER]` so it can't ship as if it were real.
## Where did the rules come from?
The kit distills a workflow from unslop, Emil Kowalski's skills, taste-skill, Vercel's Web Interface Guidelines and brand-identity-skill. [Sources](/docs/sources) lists what came from where, with install commands for each.
---
# CLAUDE.md
> Core agent instructions: tiered boot, the cardinal rule, approvals and verification.
Source: https://claudedesignkit.tansuasici.com/docs/claude-md
You are working with a designer-engineer on a product's interface. Your job is
not to make it "look nice". Your job is to make it look **chosen**: every
color, typeface, spacing value, icon and animation should trace back to a
decision about *this* product. A default that nobody chose is the most common
way an AI-built page ends up looking like every other one.
## Session Boot (Tiered)
At the start of every session, load context in tiers. Do not load everything at once.
> *Partially enforced via* `.claude/hooks/session-start.sh`. *It injects pointers to the design map and the open tasks. You still have to* Read *the files yourself.*
**Tier 1: Always (direction awareness)**
1. Read `DESIGN_MAP.md`: product, audience, character, world, signature, tokens, and the competitors to beat.
2. Read `CLAUDE.project.md` if it exists.
**Tier 2: If continuing work**
3\. Read `linear.md`. Look at **Now** only; Next and Later are not this session's work.
**Tier 3: On demand (load when relevant)**
4\. `agent_docs/slop-signs.md`: before any audit or redesign.
5\. `agent_docs/direction.md`: before writing or changing a direction.
6\. `agent_docs/tokens.md`: before touching color, type, spacing or radius scales.
7\. `agent_docs/motion.md`: before adding or reviewing any animation.
8\. `agent_docs/interface-guidelines.md`: before shipping a form, a dialog, navigation, or anything a keyboard user has to reach.
9\. `agent_docs/brand-identity.md`: only for logo, palette or type-system work.
Before doing anything, restate the current design task in 1–2 sentences.
Never build UI before Tier 1 is loaded: you can't follow a direction you
haven't read. If `DESIGN_MAP.md` is still the empty template, run `/design-brief` first.
---
## After Compaction
Compaction can happen in the middle of a session. When you notice it (a conversation summary appears, or earlier detail is gone):
1. Re-read `DESIGN_MAP.md → Character` and `→ Signature`. Drifting back to generic is the long-session failure mode.
2. Re-read the component or page file you were editing.
3. Re-read `linear.md → Now`.
4. Don't resume building until this context is back.
---
## The Core Loop
Every piece of design work runs **Brief → Direction → Build → Audit**.
1. **Brief.** Find out what this is, who it is for, and what it has to make them feel or do. Inventory the things that belong only to this subject: its materials, its vocabulary, its numbers, its artefacts. If the brief is thin, ask. Do not invent the product. (`/design-brief`)
2. **Direction.** Write a short, opinionated direction *before* writing CSS: character in plain words, a world to borrow from, the one signature move, and the token set that follows from them. Run the competitor test and the idea sentence. **Then stop and get the user's agreement.** (`/direction`)
3. **Build.** Implement against the direction. Every token you introduce has to be named in the map or added to it. Reuse the project's existing components and scale before adding new ones.
4. **Audit.** **Look** at the result: screenshots at three widths, light and dark, keyboard only. Then run the audits: slop signs (`/slop-audit`), interface guidelines (`/interface-check`), motion (`/motion-review`), edge cases (`/stress-ui`). Fix findings, or log them in `linear.md`.
If the build is drifting toward generic, STOP. Re-read the direction and re-plan; don't paper over it with effects.
---
## Chosen, Not Defaulted (the cardinal rule)
The whole kit exists to enforce this rule.
- **Every visual choice traces to the direction.** Before you use a color, font, radius, shadow, gradient or easing, you should be able to say which line of `DESIGN_MAP.md` it serves. "It's the framework default" and "it looks modern" are not reasons.
- **No reflex palette.** Purple-to-blue gradients, glowing orbs, glassmorphism stacked on glassmorphism, and generic indigo accents are the visual equivalent of filler words. Use them only if the direction calls for them by name.
- **No empty character words.** *Clean, modern, sleek, minimal, premium, intuitive, seamless* describe every product, so they describe none. In a direction or in UI copy, replace them with something specific to this product.
- **Never invent product facts.** Do not make up metrics, testimonials, customer logos, pricing, feature claims, integrations or awards. Mock data must look like this product's real data and must be marked as placeholder (`[PLACEHOLDER]`, or a code comment). It must never be ship-ready fiction.
- **Never fake assets.** Do not hotlink or make up logos, photos or brand marks for real companies. If you need an asset you don't have, leave a labelled slot.
> *Enforced via* `.claude/hooks/slop-scan.sh` *(warns on reflex palette, `transition-all`, ambient pulse/ping, emoji-as-icons, hype copy and heavy display weights in edited UI files, and on banned character words in `DESIGN_MAP.md`).*
---
## Build Discipline
- **Reuse before you add.** Before you write a new component, token, or utility, look for the project's existing one. A second button style is a regression.
- **Match the codebase.** Use its styling approach (Tailwind, CSS modules, vanilla-extract and so on), its naming, and its file layout. Don't introduce a new styling system to fix one page.
- **Use tokens, not literals.** Repeated raw hex values, pixel spacing or one-off `font-size`s go into the scale. If the scale is missing a step, add it to the map; don't hard-code around it.
- **Use one spacing rhythm.** Take spacing from a single scale. Use one radius family, and keep nested radii concentric (outer = inner + padding).
- **Keep hierarchy to three levels.** Primary, secondary and tertiary is enough on most screens. If everything is bold, nothing is.
- Stay on the task. A redesign idea you notice in passing goes under `linear.md → Later`; don't smuggle it into this change.
---
## Motion Discipline
- **Every animation needs a reason**: it orients, shows cause and effect, or confirms an action. Decoration that loops forever is noise.
- Enter with **ease-out** and keep UI motion **under \~300ms**. Never use ease-in for something appearing. Exits can be faster than enters.
- Animate **`transform` and `opacity` only**. Animating `width`/`height`/`top`/`left`/`margin` causes layout thrash.
- **Never use `transition: all`.** Name the properties.
- **Respect `prefers-reduced-motion`** on every non-essential animation.
- High-frequency actions, such as typing, keyboard shortcuts and repeated toggles, should not animate at all.
> *Enforced via* `.claude/hooks/motion-gate.sh` *(warns when a file adds keyframes or transitions without a reduced-motion guard, or animates layout properties).*
---
## Approval Required
Stop and ask the user before you:
- Change the **direction** in `DESIGN_MAP.md`, meaning character, world, signature or palette.
- Change **brand assets**: logo, brand colors, typefaces.
- Change a **design token** in a way that affects other screens.
- Remove or restyle a **shared component** used outside the current task.
- Add a dependency: a UI library, an animation library, an icon set or a font.
- Write **marketing copy that makes a claim** about the product, such as numbers, comparisons or guarantees.
Restyling the component you were asked to restyle is not a protected change.
Changing the meaning of the product is.
---
## Verification (mandatory order)
Before calling any UI work done:
1. **It renders.** Typecheck and build pass. No console errors.
2. **Look at it.** Take screenshots at **mobile (\~375), tablet (\~768) and desktop (\~1280)**, in light and in dark if both are supported. Do not judge a page you have not seen. If you cannot take screenshots, say so explicitly. Do not claim it looks right.
3. **Keyboard.** Every interactive element can be reached with Tab, has a visible `:focus-visible` ring, and can be operated with Enter/Space/Escape where that is expected.
4. **States.** Check empty, loading, error, long content, a long single word, and 1 item versus 1,000 items (`/stress-ui`).
5. **Slop pass.** Run `/slop-audit`, or at least scan the result against `agent_docs/slop-signs.md`.
6. **Direction check.** Does the result still pass the competitor test? Could a competitor ship this screen unchanged? If yes, it isn't done.
Never mark work complete without evidence. "It should look fine" is not verification.
---
## Model vs Code
Hooks and scripts check what can be checked mechanically: class names, keyframes, banned words. You judge everything else: hierarchy, rhythm, whether the signature lands. Don't present a hook's silence as a design review, and don't present your own judgement as a measurement. When you report contrast, say whether you **measured** it (with a tool and the actual values) or are **estimating**.
---
## Model Selection
- **Opus**: direction, brand work, critique, and multi-screen redesigns.
- **Sonnet**: building components against an agreed direction, and audits.
- **Haiku**: mechanical sweeps, such as renaming tokens or swapping an icon set.
Delegate audits to subagents (`design-critic`, `interface-reviewer`, `motion-reviewer`) when you want a read that isn't anchored on the code you just wrote.
---
## Self-Improvement Loop
When the user corrects a visual choice ("too heavy", "this isn't us", "no gradients"):
1. Fix it.
2. If the correction generalises, add it to `DESIGN_MAP.md → Don'ts` so it holds in future sessions.
3. If it applies across projects, propose it as an addition to `agent_docs/slop-signs.md`.
---
## Task Tracking
Open work lives in **`linear.md`** (Now / Next / Later). It is the single task file; don't create `tasks/todo.md`.
---
## Core Principles
- **Specific beats safe.** A page that is distinctly *this* product with one rough edge beats a polished page that could be anyone's.
- **Subtract first.** Most slop is addition: extra cards, badges, gradients, icons. Remove something before adding something.
- **Content drives layout.** Real copy and real data decide the grid. Lorem ipsum hides every layout problem.
- **The details are the design.** Tabular numbers, optical alignment, concentric radii, honest focus states: users feel these even when they can't name them.
---
## Credits
This kit's audit vocabulary and direction method are adapted from **unslop** by
Damir Sokolovsky (@heydamir), CC BY 4.0. Motion craft is adapted from Emil
Kowalski's skills (MIT). Taste and direction practices come from taste-skill
(MIT). Interface rules come from Vercel's Web Interface Guidelines (MIT). The
brand method comes from Fatih Aydost's brand-identity-skill (MIT). See
`SOURCES.md` and `THIRD_PARTY_NOTICES.md`.
---
# Design Map
> The single most important file: product, character, world, signature, tokens and competitors. Read first, every session.
Source: https://claudedesignkit.tansuasici.com/docs/design-map
> The single source of truth for this product's design direction. Every color,
> typeface, spacing value, icon and animation should trace back to a line here.
> Fill it with `/design-brief` (Product, Competitors, inventory) and
> `/direction` (Character → Tokens). Replace every `<…>`; session-start.sh
> treats `<` as "still the template".
>
> Changing Character, World, Signature or the palette needs the user's approval.
## Product
<One plain sentence: what it is, for whom, and the one thing this screen must get someone to do.\\>
- **Kind:** <page (read and scrolled) | app screen (worked in)\\>
- **Audience:** \<…\\>
- **Existing brand:** <logo / color / typeface: keep, refresh or none>
- **Constraints:** <framework, component library, dark mode, languages/RTL, accessibility target>
- **Assets that exist:** <logo files, product screenshots, photography; plan only around these>
## Character
\<2–3 concrete words, e.g. "patient, exact, a little dry".\\>
{/* Don't use: clean, modern, sleek, minimal, premium, intuitive, seamless. slop-scan.sh flags them here. */}
## World
<A place or material to borrow from, not a style label. e.g. "a ship's chart room: paper, brass, pencil marks".\\>
Subject inventory (8–12 things only this product has):
- \<…\\>
## Moments
\<1–2 places that get rich color and detail. Everything else stays quiet.\\>
1. \<…\\>
## Signature
<Exactly one ownable detail.>
**Idea sentence:** On this page, <subject thing> becomes <device>.
## Tokens
| Token | Value | Why (which line above) |
| ------------ | ------------------------------------------------------------ | ---------------------- |
| Neutral ramp | \<…\\> | \<…\\> |
| Accent | \<…\\> (contrast: <measured value + tool, or "estimated">) | \<…\\> |
| Type | <family> / <partner, optional> | \<…\\> |
| Type scale | \<…\\> | |
| Spacing | 4px base: 4 8 12 16 20 24 32 40 48 64 80 96 128 | |
| Radius | <family> | \<…\\> |
| Motion | ease-out `cubic-bezier(0.23, 1, 0.32, 1)`, UI \< 300ms | |
| Icons | <set>, <size>/<stroke> | |
## Competitors
\<3–5 real competitors or alternatives. The competitor test runs against these.\\>
- <name>: <what their screen looks like, in one line>
## Don'ts
<Corrections that should hold in future sessions. Add one each time the user says "this isn't us".\\>
- \<…\\>
---
# Slop Signs
> The catalogue of AI-default signs: reflex palette, glows, hype copy, heavy headings, template layouts.
Source: https://claudedesignkit.tansuasici.com/docs/slop-signs
The predictable ways AI-built UI goes wrong, grouped by layer. Each line pairs
the sign with its fix. Go through every group during an audit and record each
sign you find, with the place it lives (`file:line` or a screen region).
Slop is not "ugly". It is **unchosen**: a value that landed because it was the
default, the trend, or the first thing typed. The fix is almost always
subtraction plus one deliberate choice.
> Adapted (condensed and reorganised) from unslop's `references/signs.md`.
> Not covered by the kit's MIT license; see `THIRD_PARTY_NOTICES.md`.
## Surfaces and color
- Purple to blue or violet to pink gradients on backgrounds, cards, buttons or the active nav item → one neutral surface; the accent only where it means something
- Gradient text in headings, numbers or the logo → solid primary text
- Colored glows (`shadow-[0_0_20px_rgba(139,92,246,.5)]`, drop-shadow on emoji, glowing pills) → remove; get depth from surface steps and hairlines
- Radial color washes or blurred blobs behind content → remove
- Neon or high-contrast colored borders → a hairline at 6–10% opacity
- Five near-identical tints for text → three text roles from one neutral ramp
- Everything highlighted, so nothing stands out → one accent, used once or twice per screen
- Glass cards with a white inner highlight and a colored shadow → a plain raised surface with a hairline
## Type
- Headings at weight 800/900 → 400–500, with hierarchy coming from size and color
- `UPPERCASE TRACKED LABELS` → sentence case, normal tracking
- Too many sizes and weights on one screen → a few sizes from the scale; weights 400 and 500
- Mixed number formats (`$48,210` next to `$124,860.40`) → one format, `tabular-nums`
- Negative letter-spacing on small text → zero or slightly positive
- Italic used for emphasis → color or weight instead
## Icons
- Emoji as nav icons, label decoration or status (🏠 🚀 💰 🔥) → one line-icon set, or nothing
- Emoji inside pills and counts (`18 👤`) → the plain number
- Icons in many sizes and colors → one size, one stroke, the color of their text role
- Icons nudged off the column → the same icon-box width in every row
- ✨ for anything AI → remove it, or use a plain icon where it actually explains something
## Spacing
- Arbitrary values (`mt-[13px]`, `h-[31px]`) → steps on the 4px scale
- Rows in one list with different heights or gaps → one height, one gap
- Groups sitting closer to their neighbours than to their own items → smaller gaps inside groups, bigger gaps between them
- Uneven padding in sibling cards → one padding
- A big gap above a section and cramped space below it → a balanced rhythm
## Copy
- Greeting headlines (`Welcome back, Sam! 👋`) → the page or period as the title
- Exclamation marks, `!!` → a plain statement
- Changes without a reference (`+12%!!`) → `+12% vs last month`
- Wordy placeholders (`Search anything...`) → `Search`
- Hype words (supercharge, seamless, unlock, magic, revolutionize, game-changing, AI-powered) → what the thing actually does
- Trailing periods on labels and buttons → none
- Fake-looking data (`$123,456`, `[X]`, `Lorem ipsum`) → plausible numbers, marked as placeholder
- Unverifiable claims (`Loved by 10,000+ teams`, `10x faster`) → ask whether they're real; then make them specific, or remove them
## Components
- Glowing pills for counts, plans, shortcuts or status → quiet mono text or a keycap
- `PRO`, `New ✨`, `Beta 🚀` badges everywhere → remove them, or keep one quiet text badge
- Every element a full pill → radius chosen by size, with nested radius math
- Charts with rainbow, glowing or pill-shaped bars → one or two series, a muted grid, mono labels, one highlight
- Sparklines or mini bars stuffed into every stat card → the number, its label, and its change
- A row of equal cards with the same layout → one main chart, compact stats, varied widths
- A logo made of a gradient tile with a sparkle → the product name as text plus a flat mark
## Landing pages and heroes
- A pill badge above the headline (`✨ Introducing X 2.0`) → remove it, or use a quiet text link if the news is real
- A headline that fits any product (`Supercharge your workflow with AI`) → what this product does, and for whom
- Everything stacked and centered → an asymmetric split, or text over a large product view
- Three or more buttons, or chips and avatars stacked under the CTA → one primary action and at most one secondary
- Rows of avatar dots or five stars without a source → ask; then make them specific, or remove them
- Feature cards with an emoji, a bold title and one vague line → fewer features, concrete copy
## Visuals
- Glossy 3D blobs, orbs, liquid chrome, a purple nebula → the product itself, or one concrete metaphor for what it does
- Stock robots, glowing brains, circuit lines for anything AI → show what the AI actually produces
- Text, fake buttons or a fake logo baked into an image → real text in the page
- An image with a hard edge and a different black from the page → match the page background and soften the edges
- A visual on every section → one visual where it helps, usually only the hero
## Motion
- `animate-pulse` / `animate-ping` / breathing glows on things that are not live → static
- `transition-all`, `hover:scale` on cards → a color or surface step on hover, a tiny scale-down on press
- Bouncy springs on simple UI → one ease-out curve
- Everything flying in on load → at most one short fade-and-rise, with a small stagger
- Parallax, floating loops → a static layout
- Animating width/height/top/left → transform and opacity
## Template look (post-cleanup fallback)
These aren't slop, but they're what a cleaned-up screen falls back to when
nobody made a decision. Watch for them after the fixes.
- A pure grey page, Inter, white text, and the old brand color on one button, for a product whose world is warm → a ramp tinted toward the world and an accent taken from it
- A headline that still works if you swap in a competitor's name → use this product's own nouns
- A hero visual that is an empty box or a generic picture → a product preview in code, or an image from the world
- Every product ending up with the same layout, type and palette → let the direction decide
## Kit additions
These aren't from unslop. They come from this kit's other sources.
- `outline: none` with no visible replacement → a `:focus-visible` ring (Vercel guidelines)
- `...` (three dots) in UI copy → `…` (Vercel guidelines)
- `transform: scale(0)` entrances → `scale(0.95)` plus opacity (Emil Kowalski)
- `ease-in` on anything that appears → ease-out (Emil Kowalski)
- A page following the stock sequence of hero, logos, three features, testimonial, pricing, CTA → sections that come from the claims the page has to make (taste-skill)
---
Part of unslop by Damir Sokolovsky (@heydamir), CC BY 4.0. Keep this credit in copies and adaptations.
---
# Writing a Direction
> Character, world, moments and signature: how to write a direction from the subject itself.
Source: https://claudedesignkit.tansuasici.com/docs/direction-guide
A direction is the short, opinionated decision that comes **before** any CSS.
Everything that follows (tokens, layout, copy, visuals, motion) is checked
against it. Without one, the model fills every gap with its average, and the
average is what every AI-built page looks like.
> Method combined from unslop's five-line direction (Damir Sokolovsky, CC BY
> 4.0, paraphrased) and taste-skill's subject inventory, argument and idea
> sentence (Leonxlnx, MIT, paraphrased). The wording is the kit's own.
## 0. Page or app screen?
Decide this first. It changes most of the rules below.
- **A page** is read and scrolled: landing, marketing, product site, portfolio, event. The idea, the argument and the "one live thing" all apply. Surfaces may be tinted toward the world.
- **An app screen** is worked in: dashboard, settings, inbox, editor, admin. Surfaces stay neutral, density is a feature, and repeated panels and small labels are normal. The world shows up in the accent, the charts and the moments, not in the chrome.
A product site that shows its app is a page. The app fragments on it follow the app-screen rules for what's inside them.
## 1. Inventory the subject
Before the direction, write down **8–12 things that belong to this product and to no competitor**:
its name and what the name means; its users' vocabulary; the numbers in the brief; the constraint it lives with; its materials and colors; its rituals and hours; the printed or physical artefacts of its world (ticket, label, receipt, invoice, terminal, timetable); the output it produces.
This list is where the world, the moments and the signature come from. If you can't fill it, the brief is too thin. Ask (`/design-brief`); don't invent.
## 2. Write the five lines (the direction)
Write these into `DESIGN_MAP.md`.
- **Product.** What it does and for whom, in one plain sentence.
- **Character.** Two or three concrete words, such as *calm, exact, a little warm* or *fast, technical, playful*. **Banned:** clean, modern, sleek, minimal, premium, intuitive, seamless. They describe every template. (`slop-scan.sh` warns when they appear in `DESIGN_MAP.md`.)
- **World.** The place or material the product naturally belongs to: paper and ink, instruments and night shifts, maps and window light. The world sets the neutral tint, the accent and the visual.
- **Moments.** One or two places where the screen gets rich color, material and detail, chosen from what the product shows. Say exactly what they are.
- **Signature.** **One** small detail only this product would have, used consistently: a live status dot, keycaps, a route line, hand-drawn underlines. One detail, not five.
If the product already has a real brand (logo, color or typeface that isn't slop), keep it and build the direction around it. A violet-to-blue gradient with sparkles is not a brand unless the user says it is.
## 3. The argument (pages)
List the page as **claims with proof**, one line per section. The claims decide which sections exist and in what order. **Delete any section that has no claim.** This is how you avoid the stock sequence: hero → logos → three features → testimonial → pricing → CTA.
Proof is never invented: no customers, quotes, reviews, press, logos or business numbers that the user didn't give you.
## 4. The idea sentence
> On this page, **\[something that belongs to the subject]** becomes **\[the device the layout uses]**.
Fill the first blank from the inventory, never from the category. Places to look: its **output**, its **object or shape**, its **name**, its **place**, its **ritual**, its **artefact**, its **opposite** (the category that owns the feeling this one lacks).
**Competitor test.** Put the nearest real competitor into the sentence. If it still works, the idea belongs to the category, not the product. Try again. "Clean and modern" is not an idea.
## 5. One live thing (pages)
Give the page one thing the visitor can *do*, or that's different on each visit, built from the idea. For example: set the loan and read the real monthly figure, type your name and see it in the product's output, see whether the thing is open right now.
Rules: it uses the subject's real content, it works with a thumb, it has a plain fallback without script, it never blocks reading, and there is **one**, not a playground.
## 6. Tokens follow
Only now pick the values: neutral ramp (tinted by the world), accent (from the brand or the world), type family (from the character), radius family, motion curve. Start from `agent_docs/tokens.md` and write the chosen values into `DESIGN_MAP.md → Tokens`.
## 7. Words before markup
- Headlines fit in **two lines or fewer** at every width. About 32 characters is safe at a confident size.
- One supporting sentence directly under the headline that says plainly what the thing is.
- One primary action, named for what it does.
- The first screen answers the visitor's first question in large type.
- Write the **full** content. Thin sections lose to busier pages. Sample details are fine where the brief leaves gaps, as long as they're marked `[PLACEHOLDER]` and listed in the report.
## 8. Stop and agree
Show the inventory, the five lines, the idea sentence and the competitor test to the user, and **wait**. Changing the direction later means redoing everything. Skip the wait only when the user has said "just do it".
## Choosing among several directions
If you're unsure, write **three** directions that differ on at least two axes (for example, quiet↔loud, warm↔technical, editorial↔product-led). Hold each against the inventory and pick the one that can carry something only this product has, *not* the most familiar one. Say in one line why.
taste-skill's `draw.mjs` deals researched directions from a library of 247 gallery sites. If you want that, install the upstream skill (`/plugin marketplace add Leonxlnx/taste-skill`); the kit doesn't vendor it.
## Red flags in a direction
- Any banned character word, or a character that would also describe the competitor.
- A world that is a style ("glassmorphism", "brutalist") instead of a place or material.
- Five signatures.
- Moments that are effects ("glow on hover") instead of content (a rendered invoice, a route map).
- An accent that is purple-to-blue for a product with no purple in its world.
---
# Tokens
> Color, type, spacing and radius scales that follow from the direction instead of the framework.
Source: https://claudedesignkit.tansuasici.com/docs/tokens
Starting values to use when a project has no system yet. If the project
already has a good scale, keep its values and fix only how they're used. These
are starting points, not a house style. The direction in `DESIGN_MAP.md` can
move any of them. When it does, write the new value into the map.
> Values adapted from unslop's `references/tokens.md`. Not covered by the kit's
> MIT license; see `THIRD_PARTY_NOTICES.md`. The motion values are reconciled with
> Emil Kowalski's skills; see `agent_docs/motion.md`.
## Spacing
Scale: **4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96, 128**. Any multiple of 4 is fine. A 2px step is fine for nudges inside small controls.
| Use | Value |
| ------------------------------------------------ | ------------------------------------- |
| Inside a control | 4–12 |
| Between related items (list rows) | 2–8 |
| Between groups (a label and its list, two cards) | 12–24 |
| Between sections | 32–64 (80–128 on landing pages) |
| Row height | 32 compact · 36 default · 40–44 touch |
| Hero, nav to headline | 96–128 desktop · 48–64 mobile |
Space shows grouping: the space inside a group is smaller than the space between groups.
## App layout
- Sidebar 240–280. Content is fluid, with 24–32 of page padding, capped at about 1440–1600.
- Top bar 56–64. Navigation rows 32–36 with a 2–4 gap. Section labels have 24 above and 8 below.
- The main chart takes at least ⅔ of the content width and is 280–360 tall. A second data block is a list or a table, not another chart of the same size.
## Neutral ramps
Apps and dashboards: keep surfaces graphite or similarly grey, because people look at them for hours.
Landing pages: tint the ramp toward the direction's **world**. Warm suits paper, wood, food and craft. Ink suits night, water and technical subjects.
| Role | Dark graphite | Dark warm | Dark ink | Light graphite | Light warm | Light ink |
| -------------------------- | ------------- | --------- | -------- | -------------- | ---------- | --------- |
| Deepest (sidebar) | #0f0f10 | #12110f | #07080d | — | — | — |
| Page | #141415 | #161513 | #0b0d14 | #fafafa | #f7f4ee | #f5f7fa |
| Card | #19191b | #1c1a18 | #11141c | #ffffff | #fdfbf7 | #ffffff |
| Raised (active row, input) | #232325 | #262421 | #1a1e28 | #f4f4f5 | #efe9df | #eceff4 |
| Primary text | #ededed | #efe9de | #eef0f5 | #171717 | #1f1b16 | #111827 |
| Secondary text | #a1a1a6 | #aaa398 | #a3a9b8 | #525252 | #5e554a | #4b5565 |
| Muted text and icons | #85858b | #8a847a | #7a8296 | #737373 | #7b7266 | #6b7487 |
Hairline: primary text at 6–10% opacity. Muted text is for meta and captions only.
Semantic colors: positive #4cc38a (dark) / #16a34a (light); negative #e5484d (dark) / #dc2626 (light).
## Accent
- Keep a real brand color. A hue-to-hue glow gradient is not a brand color unless the user says it is.
- If there's no brand color, take the accent from the world. Warm worlds suggest amber, coral or ember. Cool worlds suggest cobalt, teal or sky. Natural worlds suggest moss or sage. Avoid the purple-to-blue family unless the brand really is purple.
- The accent covers a few percent of the screen: the primary action, the selection, one key figure.
- Text on the accent must **measure** at least 4.5:1 (WCAG 2) or meet the APCA equivalent. Report the measured value; don't estimate it.
## Type families (all free)
| Character | Interface family | Optional partner |
| ------------------------ | ---------------------------------- | ------------------------------------------------------- |
| Precise, technical, calm | Geist, IBM Plex Sans, Inter | Geist Mono / IBM Plex Mono / JetBrains Mono for figures |
| Warm, friendly, human | Instrument Sans, DM Sans, Figtree | Instrument Serif / Newsreader for the hero only |
| Editorial, literary | Inter / Instrument Sans | Newsreader / Instrument Serif / Fraunces for headlines |
| Playful, bold | Space Grotesk, Bricolage Grotesque | A mono for small labels |
Use one interface family and at most one partner. Use a display serif only for large headlines.
Inter is fine *when chosen*. It's a default when nobody chose it.
## Type scale
| Use | Size / line height | Weight |
| ------------------- | ---------------------------------------- | ------------------ |
| Meta, counts | 12 / 16 | 400 (mono welcome) |
| Captions, secondary | 13–14 / 20 | 400 |
| Body, nav | 14–15 / 20–22 | 400–500 |
| Card figures | 28–32 / 1 | 500, tabular |
| Page title | 28–36 / 1.15 | 400–500 |
| Hero subhead | 18–20 / 28–30 | 400, max \~36rem |
| Hero headline | 56–72 desktop · 36–44 mobile / 1.02–1.08 | 400–500 |
Tracking: 0 under 16px (+0.01em is fine for small muted text). From 40px, −0.02em. From 56px, −0.03em.
Weights: 400 and 500, with 600 for rare emphasis. Never 700–900 on headings unless the direction names it.
Body measure: \~45–75 characters (`max-width: 65ch`).
## Radius
| Element | Radius |
| ------------------------- | ------ |
| Keycap, tag, small button | 4–6 |
| Row, input, button | 8–10 |
| Card | 12–16 |
| Panel, window | 14–20 |
Nested radius: **inner = outer − padding**, never below 4.
## Icons
Use one set (the project's own, otherwise lucide), at 16 or 18px with a 1.5 stroke, in the muted or secondary text color, with an 8–10px gap to the label.
## Depth
- Dark: surface steps plus a hairline. An active row can carry an `inset 0 1px 0 rgb(255 255 255 / .12)` top highlight.
- Light: `0 1px 2px rgb(0 0 0 / .05)` for small things and `0 8px 24px rgb(0 0 0 / .06)` for floating ones. Layer ambient and direct shadows when needed.
## Motion
See `agent_docs/motion.md` for curves and durations. In short: use one ease-out curve, keep UI under 300ms, and animate transform and opacity only.
---
Part of unslop by Damir Sokolovsky (@heydamir), CC BY 4.0. Keep this credit in copies and adaptations.
---
# Motion
> When to animate at all, easing, duration, GPU-only properties and reduced motion.
Source: https://claudedesignkit.tansuasici.com/docs/motion
How to decide whether something moves, and how it moves if it does. The craft
bar comes from Emil Kowalski's skills (MIT). Where unslop and Emil give
different numbers, this file says which one the kit uses and why.
## 1. Should it animate at all?
| How often the user sees it | Decision |
| ------------------------------------------------------ | ------------------------------ |
| 100+ times a day (keyboard shortcuts, command palette) | **No animation.** |
| Tens of times a day (hover, list navigation) | Near-imperceptible, or nothing |
| Occasionally (modals, drawers, toasts) | Standard animation |
| Rarely or once (onboarding, success, celebration) | Delight is allowed here |
Keyboard-initiated actions don't animate. Producing zero lines of motion code is often the right outcome.
## 2. Name the purpose
**Feedback** · **spatial consistency** (where it came from or went) · **state indication** · **preventing a jarring change** · **explanation** (marketing and onboarding) · **delight** (rare tier only).
If you can't name one, don't build it. Data the user is reading or acting on doesn't move for style.
## 3. Cheapest tool that works
CSS transition → CSS `@starting-style` (entry) → CSS animation (predetermined, stays smooth under load) → WAAPI → Motion/Framer (springs, layout, exit, gestures).
If the task needs a *component* (toast, drawer, menu), use an accessible primitive. Don't hand-roll one.
## 4. Properties
- Animate **`transform` and `opacity` only**. `clip-path` is also acceptable. `height` is tolerated for accordions only.
- **Never use `scale(0)`.** Start from `scale(0.95–0.97)` plus `opacity: 0`.
- Popovers, menus and tooltips scale from the **trigger** (`transform-origin`). Modals stay centered.
- Never use `transition: all`. Name the properties (`transition-colors`, `transition-[transform,opacity]`).
- Animated blur stays small (under \~20px). Use `will-change` only after you've seen an actual problem.
- In Motion/Framer, prefer the full `transform` string over `x`/`y`/`scale` shorthands for motion that runs while the page is busy.
## 5. Easing and duration
**Easing**
| Situation | Curve |
| ----------------------------------- | ---------------------------------------------- |
| Entering or exiting | ease-out: `cubic-bezier(0.23, 1, 0.32, 1)` |
| Moving or morphing on screen | ease-in-out: `cubic-bezier(0.77, 0, 0.175, 1)` |
| Drawer / sheet | `cubic-bezier(0.32, 0.72, 0, 1)` |
| Hover color change | `ease` |
| Constant motion (progress, marquee) | `linear` |
**Never use ease-in on UI.** It delays the exact moment the user is watching.
(unslop suggests `cubic-bezier(0.22, 1, 0.36, 1)` as its single curve. That's practically the same strong ease-out. Use whichever one the project already has. Don't add both.)
**Duration**
| Element | Duration |
| ------------------------------ | -------------------------- |
| Press feedback, hover, toggles | 100–160ms |
| Tooltips, small popovers | 125–200ms |
| Dropdowns, selects | 150–250ms |
| Modals, drawers | 200–300ms |
| Stagger between items | 30–60ms, at most \~6 items |
| Marketing and explanatory | longer if needed |
**Product UI stays under 300ms.** unslop allows 300–500ms for *page entrances*. The kit allows that only on landing pages and first-load moments, never on repeated interactions.
Rise distance on enter: 6–12px. Press scale: 0.97–0.98. Exits can be faster than enters.
**Springs** are for drag with momentum, interruptible gestures, and things that should feel alive: `{ type: "spring", duration: 0.5, bounce: 0.2 }`. Keep bounce at 0.1–0.3. Avoid bounce on ordinary UI.
## 6. Interruption and exit
- Anything that can fire twice in a second (toasts, toggles) uses **transitions, not keyframes**. Transitions retarget; keyframes restart.
- Exit the way it entered.
- Use asymmetric timing where the user is deciding: the deliberate phase is slow (hold-to-confirm), the system response is snappy.
## 7. Accessibility and pointer gating
These ship **with** the animation, never as a follow-up.
```css
@media (prefers-reduced-motion: reduce) {
.thing { transition: opacity 150ms ease; transform: none; }
}
@media (hover: hover) and (pointer: fine) {
.card:hover { background: var(--surface-raised); }
}
```
Reduced motion means fewer and gentler animations, not zero: keep opacity and color, drop movement.
Autoplaying motion longer than 5s next to other content needs a pause, stop or hide control.
## Never ship
| Never | Instead |
| --------------------------------------------------- | ------------------------------------------- |
| `transition: all` | Named properties |
| `scale(0)` entrance | `scale(0.95)` plus opacity |
| `ease-in` on UI | Strong ease-out |
| Animation on a keyboard or 100+/day action | None |
| UI duration over 300ms with no reason | 150–250ms |
| `transform-origin: center` on an anchored popover | The trigger origin |
| Keyframes on toasts or toggles | Transitions |
| Animating width/height/top/left/margin | Transform and opacity |
| Ungated `:hover` motion | `@media (hover: hover) and (pointer: fine)` |
| Missing reduced-motion handling | A gentler variant |
| `animate-pulse` / `animate-ping` on non-live things | Static |
| Everything entering at once | A 30–60ms stagger, or one entrance only |
## Further reading (upstream)
Emil Kowalski's skills cover more than this file: recipes for dropdowns, toasts, drawers and hold-to-confirm, a performance deep-dive, and React Native/Expo. Install them with `npx skills@latest add emilkowalski/skills`. This kit's `/motion-craft` and `/motion-review` are distilled versions that work with `DESIGN_MAP.md`.
---
# Interface Guidelines
> Keyboard, focus, forms, layout, content, accessibility and performance rules for shipping UI.
Source: https://claudedesignkit.tansuasici.com/docs/interface-guidelines
The rules that make an interface work for keyboards, touch, screen readers,
slow networks and long content. They aren't about taste, and every project
needs them.
> Paraphrased and condensed from Vercel's Web Interface Guidelines
> (vercel-labs/web-interface-guidelines, MIT) and the public page at
> vercel.com/design/guidelines. The wording is the kit's own. For the full,
> current list, install the upstream skill:
> `npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines`.
Each rule is phrased so you can check it. `/interface-check` goes through these sections in order.
## Keyboard
- Everything that can be clicked can be reached with Tab and operated with Enter or Space. Escape closes overlays.
- Focus is always visible. Use `:focus-visible` rings, and never `outline: none` without a replacement. Use `:focus-within` for grouped controls.
- Manage focus. Trap it inside modals, return it to the trigger when an overlay closes, and move it to new content when that content replaces the view.
- Follow WAI-ARIA keyboard patterns for menus, tabs, listboxes and comboboxes (arrow keys, Home/End).
## Targets
- Hit targets are at least 24×24px, and at least 44×44px on touch. If the visual is smaller, enlarge the target with padding or a pseudo-element.
- Inputs are at least 16px on mobile, so iOS doesn't zoom on focus.
- `touch-action: manipulation` removes the double-tap zoom delay on controls.
## Forms
- Enter submits a single-field form. In a textarea, ⌘/Ctrl+Enter submits.
- Every control has a `