agency-skills-suite/agency-design-system/SKILL.md

name	description
agency-design-system	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: Proporre 3 opzioni

   OPZIONE A — Blocca e richiedi asset:

   • "🔒 Bloccato: servono brand assets"
   • Tagga: @agency-archivist con elenco specifico
   • Attendi upload prima di procedere

   OPZIONE B — Placeholder Mode (consigliata): ⚡

   • Procedi con placeholder tokens:
     • Logo: placeholder box grigio con testo "[LOGO]"
     • Colori: palette neutra placeholder (#CCC, #666, #333, #FFF)
     • Font: font-stack di sistema (Arial/Helvetica, Georgia/Times)
   • Genera design system completo con sezione "Placeholder Assets"
   • Documenta: sostituzioni da fare quando asset reali saranno disponibili
   • Non bloccare — sviluppo può iniziare subito

   OPZIONE C — Design system testuale/minimal:

   • Crea design tokens senza riferimenti visivi specifici
   • Focus su spacing, tipografia scale, layout principles
   • Documenta: "⏭️ Brand assets da integrare — design system strutturale pronto"

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:

# 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:

## 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:

## 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 — Grid e spacing
• navigation_patterns.md — IA patterns
• design_patterns.md — UI patterns
• qa_visual.md — QA checklist

Resources & Assets

• resource_types.md — Tipologie risorse e use case

Technical Implementation (Handoff)

Per handoff a developer o implementazione diretta:

• html_semantics.md — Semantic HTML structure
• css_layout.md — Bootstrap/custom CSS implementation
• 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