---
name: agency-design-system
description: "Creare design system coerente con tokens, components e page layouts. PRIMA di iniziare: leggi {project}/assets/catalog.md per logo e brand assets. Se mancano, richiedi @agency-archivist. Usare quando: (1) nuovo progetto needs UI system, (2) standardizzare design, (3) creare component library. Output: Design tokens, components library, page layouts, design system doc."
---

# Agency Visual Designer — Design System

Traduce la direzione creativa in un design system coerente e riutilizzabile.

## Quando Usare

- **Nuovo progetto:** Costruire UI system da zero
- **Design system refresh:** Aggiornare tokens/components
- **Multi-page project:** Standardizzare layout
- **Handoff a developer:** Documentare componenti

---

## Input

| Input | Tipo | Validazione |
|-------|------|-------------|
| `project_path` | string | Percorso progetto (cartella di lavoro) |
| `creative_direction` | object | Da creative director |
| `design_principles` | array | Principi guida |
| `brand_assets` | object | Loghi, colori brand (se esistenti) |

---

## Processo

### Fase 1: Risorse e Design Tokens

**Obiettivo:** Verificare brand assets e definire variabili di design.

**Azioni:**

1. **LEGGI CATALOGO RISORSE:**
   - Apri `{project}/assets/catalog.md`
   - Cerca:
     - Logo: `#logo`, `#brand` → Path per UI
     - Colori: `#brand`, `#guidelines` → PDF con palette
     - Font: `#brand`, `#guidelines` → Specifiche typography
   
2. **Se risorse mancanti:**
   - **FERMATI** e segnala: "🔒 Bloccato: servono brand assets"
   - Tagga: @agency-archivist
   - Specifica:
     ```
     Per creare design system, servono:
     - [ ] Logo aziendale (PNG/SVG)
     - [ ] Brand colors (codici HEX o documento guidelines)
     - [ ] Font (nomi o file font)
     ```
   - **Attendi** che archivist carichi e sblocchi

3. **Typography:**
   - Font family (primary, secondary)
   - Font sizes (H1-H6, body, caption)
   - Font weights
   - Line heights

4. **Spacing:**
   - Scala modulare (es. 4/8/16/24/32/48/64)
   - Section padding (desktop/mobile)

5. **Colors:**
   - Primary (brand)
   - Secondary (accents)
   - Neutrals (text, backgrounds)
   - Semantic (success, warning, error)

6. **Breakpoints:**
   - Mobile (<768px)
   - Tablet (768-1024px)
   - Desktop (>1024px)

**Template:**

```markdown
# Design Tokens

## Typography

### Font Families
- Primary: {font}
- Secondary: {font}

### Font Sizes
- H1: 48px / 3rem
- H2: 36px / 2.25rem
- H3: 24px / 1.5rem
- Body: 16px / 1rem
- Caption: 14px / 0.875rem

## Spacing
- 4px, 8px, 16px, 24px, 32px, 48px, 64px

## Colors
- Primary: {hex}
- Secondary: {hex}
- Text: {hex}
- Background: {hex}

## Breakpoints
- Mobile: <768px
- Tablet: 768-1024px
- Desktop: >1024px
```

**Output:**
- `{project}/design/tokens.md`

---

### Fase 2: UI Components

**Obiettivo:** Creare library componenti riutilizzabili.

**Azioni:**

1. Identifica componenti necessari:
   - Buttons (primary, secondary, tertiary)
   - Cards (service, testimonial, feature)
   - Forms (input, textarea, select)
   - Navigation (header, footer, mobile menu)
   - Content blocks (hero, features, FAQ, CTA)

2. Per ogni componente, documenta:
   - Nome
   - Scopo
   - Varianti (se applicabile)
   - States (hover, active, disabled)
   - Accessibility notes

**Template:**

```markdown
## Button

**Scopo:** CTA e azioni primarie

### Varianti
- Primary (filled)
- Secondary (outline)
- Tertiary (text-only)

### States
- Default
- Hover
- Active
- Disabled

### Accessibility
- Min height 44px
- Contrast ratio 4.5:1
- Focus visible
```

**Output:**
- `{project}/design/components.md`

---

### Fase 3: Page Layouts

**Obiettivo:** Definire strutture pagina tipo.

**Azioni:**

1. Identifica page type necessari:
   - Homepage
   - Service page
   - About page
   - Contact page
   - Case study page
   - Blog post

2. Per ogni layout, documenta:
   - Sezione header (hero)
   - Sezioni content (ordine)
   - Sezione footer
   - Pattern usati (da agency-shared-references/references)

**Template:**

```markdown
## Homepage Layout

1. **Hero section**
   - Headline
   - Sub copy
   - CTA primaria
   - Proof chips

2. **Logo wall** (trust)

3. **Services overview** (card grid)

4. **Case study teaser** (split layout)

5. **Testimonial** (hero testimonial)

6. **CTA finale + footer**
```

**Output:**
- `{project}/design/page_layouts.md`

---

### Fase 4: Design System Documentation

**Obiettivo:** Consolidare tutto in documento unico.

**Azioni:**

1. Crea documento che include:
   - Introduzione (scopo del design system)
   - Design principles (da creative director)
   - Tokens
   - Components
   - Layouts
   - Usage guidelines

2. Includi esempi visivi (se possibile)

**Output:**
- `{project}/design/design_system.md`

---

## Output

| File | Formato | Descrizione |
|------|---------|-------------|
| `{project}/design/tokens.md` | Markdown | Design tokens |
| `{project}/design/components.md` | Markdown | Component library |
| `{project}/design/page_layouts.md` | Markdown | Page layouts |
| `{project}/design/design_system.md` | Markdown | Design system completo |

---

## References

### UX/Design Patterns (Shared)
- [layout_systems.md](../agency-shared-references/references/layout_systems.md) — Grid e spacing
- [navigation_patterns.md](../agency-shared-references/references/navigation_patterns.md) — IA patterns
- [design_patterns.md](../agency-shared-references/references/design_patterns.md) — UI patterns
- [qa_visual.md](../agency-shared-references/references/qa_visual.md) — QA checklist

### Resources & Assets
- [resource_types.md](../agency-shared-references/references/resource_types.md) — Tipologie risorse e use case

### Technical Implementation (Handoff)
**Per handoff a developer o implementazione diretta:**
- [html_semantics.md](../agency-shared-references/references/html_semantics.md) — Semantic HTML structure
- [css_layout.md](../agency-shared-references/references/css_layout.md) — Bootstrap/custom CSS implementation
- [js_interactivity.md](../agency-shared-references/references/js_interactivity.md) — jQuery + GSAP patterns

**Nota:** Questa skill produce design system documentato. Per implementazione codice, consultare agency-web-developer.

---

## Note

**Edge Cases:**

- **Brand esistente:** Adatta tokens ai colori/font esistenti
- **Progetto piccolo:** Semplifica (tokens essenziali + 5-6 components base)
- **Nessun designer:** Usa pattern standard da agency-shared-references/references

**Limitazioni:**

- Componenti complessi richiedono tool di design (Figma, Sketch)
- Design system completo richiede iterazione con feedback
- Handoff a developer richiede specifiche tecniche aggiuntive

---

_Skill generata da framework-translator_