Skip to content

ilandahan/AID / skills/atomic-design

atomic-design

Verified

Build an Atomic Design system from design spec style guides - extract tokens, create atoms/molecules/organisms/templates/pages as reusable component libraries. Use when building or extending a design system or component library.

references/design-deviation-rules.extended.md

View on GitHub
# Design Deviation Rules - Zero Tolerance Policy

## ๐Ÿšซ ืžื“ื™ื ื™ื•ืช ืืคืก ืกื˜ื™ื•ืช

```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                                                                         โ”‚
โ”‚   โŒ NO CREATIVE FREEDOM IN IMPLEMENTATION                              โ”‚
โ”‚                                                                         โ”‚
โ”‚   ื”ืžืคืชื— ื”ื•ื ืœื ืžืขืฆื‘.                                                    โ”‚
โ”‚   ืชืคืงื™ื“ ื”ืžืคืชื— ื”ื•ื ืœืชืจื’ื ืืช ื”ืขื™ืฆื•ื‘ ืœืงื•ื“ - ืœื ืœืฉืคืจ ืื•ืชื•.                  โ”‚
โ”‚                                                                         โ”‚
โ”‚   "ืื ื™ ื—ื•ืฉื‘ ืฉื–ื” ื™ื™ืจืื” ื™ื•ืชืจ ื˜ื•ื‘ ื›ื›ื”" = โŒ FORBIDDEN                       โ”‚
โ”‚   "design spec ืžืจืื” X, ืื– ื”ืงื•ื“ ื™ื”ื™ื” X" = โœ… CORRECT                            โ”‚
โ”‚                                                                         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## ืกื•ื’ื™ ืกื˜ื™ื•ืช ืืกื•ืจื•ืช

### 1. ืกื˜ื™ื•ืช "ืืกืชื˜ื™ื•ืช"

| ืคืขื•ืœื” ืืกื•ืจื” | ื“ื•ื’ืžื” | ืœืžื” ืืกื•ืจ |
|-------------|-------|----------|
| ืฉื™ื ื•ื™ ืฆื‘ืขื™ื | `#3B82F6` โ†’ `#3F85F7` | ื”ืžืขืฆื‘ ื‘ื—ืจ ื‘ืฆื‘ืข ืกืคืฆื™ืคื™ ืžืกื™ื‘ื” |
| ืขื™ื’ื•ืœ ืขืจื›ื™ื | `13px` โ†’ `12px` | "ื ื•ื— ื™ื•ืชืจ" ืœื ืจืœื•ื•ื ื˜ื™ |
| ื”ื•ืกืคืช ืืคืงื˜ื™ื | ื”ื•ืกืคืช shadow ืฉืœื ืงื™ื™ื | ื–ื• ื”ื—ืœื˜ื” ืขื™ืฆื•ื‘ื™ืช |
| ืฉื™ื ื•ื™ fonts | Inter โ†’ System fonts | ืคื•ื’ืข ื‘ื–ื”ื•ืช ื”ืžื•ืชื’ |
| ืฉื™ื ื•ื™ spacing | `24px` โ†’ `20px` | ืžืฉื‘ืฉ ืืช ื”ืจื™ืชืžื•ืก ื”ื•ื™ื–ื•ืืœื™ |

### 2. ืกื˜ื™ื•ืช "ื˜ื›ื ื™ื•ืช"

| ืคืขื•ืœื” ืืกื•ืจื” | ื“ื•ื’ืžื” | ื”ืคืชืจื•ืŸ ื”ื ื›ื•ืŸ |
|-------------|-------|--------------|
| "ืื•ืคื˜ื™ืžื™ื–ืฆื™ื”" ืฉืœ ืขืจื›ื™ื | ืฉื™ืžื•ืฉ ื‘-rem ื‘ืžืงื•ื px ื›ืฉื”ืžืขืฆื‘ ืฆื™ื™ืŸ px | ืฉืืœ ืืช ื”ืžืขืฆื‘ ืื™ื–ื• ื™ื—ื™ื“ื” ืžื•ืขื“ืคืช |
| "ืกื˜ื ื“ืจื˜ื™ื–ืฆื™ื”" | ืฉื™ื ื•ื™ font-weight 450 ืœ-500 | ื‘ื“ื•ืง ืื ื”ืคื•ื ื˜ ืชื•ืžืš ื‘-450 |
| "ืชื™ืงื•ืŸ" inconsistencies | ื™ื™ืฉื•ืจ padding ืœื ืื—ื™ื“ | ื“ื•ื•ื— ืœืžืขืฆื‘ - ืืœ ืชืชืงืŸ ืœื‘ื“ |

### 3. ืกื˜ื™ื•ืช "responsive"

| ืคืขื•ืœื” ืืกื•ืจื” | ื“ื•ื’ืžื” | ื”ืคืชืจื•ืŸ ื”ื ื›ื•ืŸ |
|-------------|-------|--------------|
| ื”ืžืฆืืช breakpoints | ื”ื•ืกืคืช breakpoint ื‘-480px | ื‘ื“ื•ืง ืื™ืœื• breakpoints ืžื•ื’ื“ืจื™ื ื‘-design spec |
| "ื”ืชืืžื•ืช ื”ื’ื™ื•ื ื™ื•ืช" | ื”ืงื˜ื ืช padding ื‘ืžื•ื‘ื™ื™ืœ | ื—ืœืฅ ืขืจื›ื™ื ืž-design spec Mobile frame |
| ืฉื™ื ื•ื™ layout | ืฉื™ื ื•ื™ ืž-grid ืœ-flex | ืžืžืฉ ืืช ื”-layout ื›ืคื™ ืฉื ืจืื” ื‘-design spec |

---

## ืชื”ืœื™ืš ืขื‘ื•ื“ื”: ื›ืืฉืจ ืžืฉื”ื• "ืœื ื ืจืื” ื ื›ื•ืŸ"

```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  WORKFLOW: ื›ืืฉืจ ื ืจืื” ืœืš ืฉืžืฉื”ื• "ืฉื’ื•ื™" ื‘-design spec                     โ”‚
โ”‚                                                                 โ”‚
โ”‚  1. STOP - ืืœ ืชืฉื ื” ืฉื•ื ื“ื‘ืจ                                      โ”‚
โ”‚        โ”‚                                                        โ”‚
โ”‚        โ–ผ                                                        โ”‚
โ”‚  2. DOCUMENT - ืฆืœื ืืช ืžื” ืฉื ืจืื” ืœืš ื‘ืขื™ื™ืชื™                        โ”‚
โ”‚        โ”‚                                                        โ”‚
โ”‚        โ–ผ                                                        โ”‚
โ”‚  3. ASK - ืฉืืœ ืืช ื”ืžืขืฆื‘                                          โ”‚
โ”‚        โ”‚   "ืฉืžืชื™ ืœื‘ ืฉื‘-[frame] ื”-padding ื”ื•ื 13px.              โ”‚
โ”‚        โ”‚    ื–ื” ืžื›ื•ื•ืŸ ืื• ืฆืจื™ืš ืœื”ื™ื•ืช 12px?"                       โ”‚
โ”‚        โ”‚                                                        โ”‚
โ”‚        โ–ผ                                                        โ”‚
โ”‚  4. WAIT - ื”ืžืชืŸ ืœืชืฉื•ื‘ื” ืœืคื ื™ ืฉืžืžืฉื™ืš                               โ”‚
โ”‚        โ”‚                                                        โ”‚
โ”‚        โ–ผ                                                        โ”‚
โ”‚  5. IMPLEMENT - ืžืžืฉ ืœืคื™ ื”ื”ื ื—ื™ื” ืฉืœ ื”ืžืขืฆื‘                         โ”‚
โ”‚        โ”‚                                                        โ”‚
โ”‚        โ–ผ                                                        โ”‚
โ”‚  6. DOCUMENT - ืชืขื“ ืืช ื”ื”ื—ืœื˜ื” ื‘ืงื•ื“ ื•ื‘ืžืขืจื›ืช                       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

### ืชื‘ื ื™ืช ืฉืืœื” ืœืžืขืฆื‘

```markdown
## Design Clarification Request

**Component:** [Button/Primary]
**design spec Frame:** [link]
**Property:** padding-top
**Current Value:** 13px
**Expected Value (Grid-aligned):** 12px

**Question:**
ื”ืื ื”-13px ืžื›ื•ื•ืŸ ืื• ืฉืžื“ื•ื‘ืจ ื‘ื˜ืขื•ืช?
ืื ืžื›ื•ื•ืŸ - ืื•ื•ื“ื ืฉื”ื˜ื•ืงืŸ ื™ื”ื™ื” 13px.
ืื ื˜ืขื•ืช - ืืขื“ื›ืŸ ืืช ื”ืงื•ื“ ืื—ืจื™ ืฉืชืชืงืŸ ื‘-design spec.

**Screenshot:** [attached]
```

---

## Exception Handling - ืžืชื™ ืžื•ืชืจ ืœื—ืจื•ื’?

### ื”ืชืฉื•ื‘ื” ื”ืงืฆืจื”: ื›ืžืขื˜ ืืฃ ืคืขื

### ื”ื—ืจื™ื’ื™ื ื”ื™ื—ื™ื“ื™ื ื”ืžื•ืชืจื™ื:

#### 1. Bug ื˜ื›ื ื™ ื‘ืคืœื˜ืคื•ืจืžื”

```css
/* design spec shows: backdrop-filter: blur(10px) */
/* Safari bug: requires -webkit- prefix */

/* โœ… ALLOWED - ืชื•ืกืคืช ื˜ื›ื ื™ืช ืœื ื•ื™ื–ื•ืืœื™ืช */
.modal {
  backdrop-filter: blur(10px);
  -webkit-backdrop-filter: blur(10px); /* Safari support */
}
```

#### 2. Accessibility Override (ื ื“ื™ืจ ืžืื•ื“)

```css
/* design spec shows: color contrast 3.5:1 */
/* WCAG AA requires: 4.5:1 minimum */

/* โŒ WRONG - ืœืฉื ื•ืช ืœื‘ื“ */
color: #000;  /* "Fixed" contrast */

/* โœ… CORRECT - ืœื“ื•ื•ื— ืœืžืขืฆื‘ */
/*
 * ACCESSIBILITY ISSUE REPORTED
 * design spec contrast: 3.5:1
 * Required: 4.5:1
 * Awaiting designer update
 * Jira: DESIGN-123
 */
color: var(--color-text-secondary);  /* Current design spec value */
```

#### 3. Missing State ื‘-design spec

```tsx
/* design spec shows: Button without focus state */

/* โŒ WRONG - ืœื”ืžืฆื™ื focus state */
&:focus {
  outline: 2px solid blue;  /* Invented */
}

/* โœ… CORRECT - ื‘ืงืฉ ืžื”ืžืขืฆื‘ ืœื”ื•ืกื™ืฃ */
/*
 * TODO: Focus state not defined in design spec
 * Requested from designer - Jira: DESIGN-124
 * Using browser default until designed
 */
```

---

## Documentation Requirements - ืชื™ืขื•ื“ ื—ื•ื‘ื”

### ื›ืœ ืงื•ืžืคื•ื ื ื˜ื” ื—ื™ื™ื‘ืช ืœื›ืœื•ืœ:

```tsx
/**
 * Button Component
 *
 * @design-source ./design-spec.md
 * @extracted 2024-01-15
 * @designer Sarah Cohen
 *
 * Design Specs:
 * - Height: 48px (fixed)
 * - Padding: 12px 24px
 * - Border-radius: 8px
 * - Font: Inter 16px/500
 *
 * All values extracted from design spec - DO NOT MODIFY without designer approval.
 */
```

### ื‘ื›ืœ CSS Module:

```css
/**
 * Button Styles
 *
 * Source: design spec Design System v2.1
 * Frame: Components/Button/Primary
 * Last synced: 2024-01-15
 *
 * โš ๏ธ WARNING: All values are from design spec.
 * Do not modify without updating design spec first.
 */

.button {
  /* From design spec: padding */
  padding: 12px 24px;  /* design spec: paddingTop/Bottom: 12, paddingLeft/Right: 24 */

  /* From design spec: background */
  background: var(--color-primary);  /* design spec: fill #3B82F6 */

  /* From design spec: border-radius */
  border-radius: 8px;  /* design spec: cornerRadius: 8 */
}
```

---

## Code Review Checklist - ื‘ื“ื™ืงื” ื‘ืงื•ื“ ืจื‘ื™ื•

### ืžื” ืœื‘ื“ื•ืง:

```markdown
## Design Fidelity Review

### Pre-merge Checklist:

1. **design spec Link Verification**
   - [ ] design spec link exists in component documentation
   - [ ] Link is accessible and correct

2. **Value Extraction**
   - [ ] All CSS values have design spec source comment
   - [ ] No "magic numbers" without source

3. **Token Usage**
   - [ ] Uses design tokens (not hardcoded values)
   - [ ] Token values match current design spec

4. **Visual Comparison**
   - [ ] Screenshot comparison shows match
   - [ ] All states verified (hover, active, disabled, focus)
   - [ ] Responsive breakpoints verified

5. **No Unauthorized Changes**
   - [ ] No "improved" colors
   - [ ] No "rounded" values
   - [ ] No added effects not in design spec
   - [ ] No removed properties from design spec

### Red Flags to Block PR:

โŒ Hardcoded color: `color: #3B82F6;` instead of `var(--color-primary)`
โŒ Rounded value: `padding: 12px` when design spec shows `13px`
โŒ Missing design spec reference
โŒ "Looks better this way" in commit message
โŒ Unexplained deviation from design system
```

---

## Consequences of Deviation - ื”ืฉืœื›ื•ืช

### ืœืžื” ื—ืฉื•ื‘ ืœืฉืžื•ืจ ืขืœ ื ืืžื ื•ืช?

```
1. CONSISTENCY
   โ””โ”€โ–บ ื›ืœ ืกื˜ื™ื™ื” ืงื˜ื ื” ร— ืžืกืคืจ ืžืคืชื—ื™ื ร— ื–ืžืŸ = ืงืื•ืก ื•ื™ื–ื•ืืœื™

2. TRUST
   โ””โ”€โ–บ ื”ืžืขืฆื‘ ืฆืจื™ืš ืœืกืžื•ืš ืฉืžื” ืฉื”ื•ื ืžืขืฆื‘ - ื™ื•ืคื™ืข ื‘ืคืจื•ื“ืงืฉืŸ

3. MAINTENANCE
   โ””โ”€โ–บ ื›ืืฉืจ ื›ื•ืœื ืžืžืžืฉื™ื ื‘ื“ื™ื•ืง ืž-design spec, ืงืœ ืœืขื“ื›ืŸ

4. SCALABILITY
   โ””โ”€โ–บ ืžืขืจื›ืช ืขื™ืฆื•ื‘ ืขื•ื‘ื“ืช ืจืง ื›ืฉื›ื•ืœื ืžืงืคื™ื“ื™ื ืขืœื™ื”
```

### ืžื” ืงื•ืจื” ื›ืฉื™ืฉ ืกื˜ื™ื•ืช:

```
Developer A: ืฉื™ื ื” padding ืž-12px ืœ-10px ื›ื™ "ื ืจืื” ืฆืคื•ืฃ"
Developer B: ืฉื™ื ื” ืืช ืื•ืชื• ื›ืคืชื•ืจ ืœ-14px ื›ื™ "ืฆืจื™ืš ื™ื•ืชืจ ืžืจื•ื•ื—"
Developer C: ื”ืฉืื™ืจ 12px ื›ืžื• ื‘-design spec

ืชื•ืฆืื”: 3 ื’ืจืกืื•ืช ืฉื•ื ื•ืช ืฉืœ ืื•ืชื• ื›ืคืชื•ืจ ื‘ืืคืœื™ืงืฆื™ื”
```

---

## Summary: The Rules

```
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                                                                 โ”‚
โ”‚   THE DEVIATION RULES                                           โ”‚
โ”‚                                                                 โ”‚
โ”‚   1. ืืœ ืชืฉื ื” - ืžืžืฉ ื‘ื“ื™ื•ืง ืžื” ืฉ-design spec ืžืจืื”                        โ”‚
โ”‚                                                                 โ”‚
โ”‚   2. ืืœ ืชืฉืคืจ - "ืฉื™ืคื•ืจื™ื" ื”ื ืกื˜ื™ื•ืช                               โ”‚
โ”‚                                                                 โ”‚
โ”‚   3. ืืœ ืชื ื—ืฉ - ืื ืœื ื‘ืจื•ืจ, ืฉืืœ                                  โ”‚
โ”‚                                                                 โ”‚
โ”‚   4. ืืœ ืชืขื’ืœ - 13px ื–ื” 13px, ืœื 12px                            โ”‚
โ”‚                                                                 โ”‚
โ”‚   5. ืืœ ืชื•ืกื™ืฃ - ืื ื–ื” ืœื ื‘-design spec, ื–ื” ืœื ื‘ืงื•ื“                    โ”‚
โ”‚                                                                 โ”‚
โ”‚   6. ืชืขื“ - ื›ืœ ืขืจืš ืฆืจื™ืš ืžืงื•ืจ ืž-design spec                             โ”‚
โ”‚                                                                 โ”‚
โ”‚   7. ืืžืช - ื‘ื“ื•ืง ื•ื™ื–ื•ืืœื™ืช ืœืคื ื™ delivery                          โ”‚
โ”‚                                                                 โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## Quick Reference: What To Do

| ืžืฆื‘ | ืคืขื•ืœื” |
|-----|-------|
| "ื”ืขืจืš ื ืจืื” ืœื™ ืžื•ื–ืจ" | ืฉืืœ ืืช ื”ืžืขืฆื‘ |
| "ืื ื™ ื—ื•ืฉื‘ ืฉื–ื” ื™ื™ืจืื” ื™ื•ืชืจ ื˜ื•ื‘" | ืœื ืจืœื•ื•ื ื˜ื™ - ืžืžืฉ ืž-design spec |
| "ื”ืžืขืฆื‘ ื˜ืขื”" | ื“ื•ื•ื— - ืืœ ืชืชืงืŸ ืœื‘ื“ |
| "ื—ืกืจ state ื‘-design spec" | ื‘ืงืฉ ืžื”ืžืขืฆื‘ ืœื”ื•ืกื™ืฃ |
| "ืœื ื‘ื˜ื•ื— ืื™ื–ื” ืขืจืš ืœืงื—ืช" | ืฉืืœ ืืช ื”ืžืขืฆื‘ |
| "ืจื•ืฆื” ืœืฉื ื•ืช ืžืฉื”ื•" | ืคืชื— ื‘ืงืฉื” ืœืžืขืฆื‘ ืœืขื“ื›ืŸ ื‘-design spec ืงื•ื“ื |
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall