design-systemdi Alireza Rezvani

Design System Skill.

Una skill per Claude Code e Codex per il lavoro su brand e design system: cattura l'identità di brand una volta tramite una procedura guidata di 10 domande per documenti e presentazioni successivi.

Brand e design system
Design system

Scarica OpenDesign Guida all'uso

alirezarezvani/claude-skills · markdown-html/skills/design-system/SKILL.mdSKILL.md

--- name: design-system description: Captures the user's brand identity once via a 10-question onboarding wizard (primary/accent HEX + heading + body Google Fonts + design style editorial/technical/minimal/playful + default output directory + syntax theme + TOC behavior + optional logo/company), validates body-text and link contrast against WCAG 2.2 AA, derives 12 CSS custom properties in HSL space, and stores the result for every markdown-html … --- ## When to invoke ## Onboarding question set (10 questions) ## Hard rules ## Derived 12-token palette ## Forcing-question library (Matt Pocock grill-with-docs pattern) ## Customization in use (worked example)

Metadati iniziali e intestazioni di sezione letti dal file upstream il 14-09-2026 · 11.234 caratteri per intero

01 Cosa fa

Cosa fa lo Skill design-system in Claude Code e Codex

Sintesi, workflow e output, tutto letto dal SKILL.md della skill.

Dal SKILL.mdLetto il 14-09-2026 · non è un'esecuzione registrata

Nelle parole della skill

Lo Skill design-system è il proprietario condiviso del brand per il plugin markdown-html. Cattura l'identità di brand una sola volta tramite un wizard di onboarding in 10 domande — valori HEX primario e di accento, Google Fonts per titoli e corpo del testo, uno stile di design (editoriale, tecnico, minimale o giocoso), directory di output predefinita, tema del codice, comportamento del sommario e un nome aziendale e un logo opzionali — poi verifica il contrasto di testo e link rispetto a WCAG 2.2 AA e deriva 12 proprietà personalizzate CSS nello spazio HSL.

Tre strumenti Python basati solo sulla libreria standard gestiscono l'onboarding, il caricamento della configurazione e la validazione della palette; la precedenza è progetto su globale su valori predefiniti integrati. Ogni convertitore (md-document, md-review, md-slides) legge la configurazione salvata, quindi modificare un token cambia ogni documento renderizzato.

Che cosa produce

Un file di configurazione che contiene il brand e la palette derivata, scritto a livello globale o all'interno del progetto.
Dodici proprietà personalizzate CSS inserite inline nel blocco di stile di ogni convertitore, come --md-surface, --md-border, --md-link e --md-warn.
Uno schema JSON per la configurazione, fornito come asset per la validazione.

Vedi l'esempio di prompt ↗

Come funziona

01
Esegui l'onboarding una volta
La skill è il titolare condiviso del brand per il plugin markdown-html: md-document, md-review e md-slides consumano tutti la configurazione che scrive, quindi una sola esecuzione applica il brand a ogni conversione.
02
Rispondi alle dieci domande
La procedura guidata registra default_output_dir, l'HEX primario e di accento, i font per i titoli e per il corpo, design_style, code_theme, toc.behavior e, facoltativamente, company_name e logo_url.
03
Fai in modo che la validazione condizioni il salvataggio
brand_palette_validator.validate() viene eseguito dopo ogni modifica, quindi la coppia viene ricontrollata a ogni modifica di un campo e non solo alla fine della procedura guidata.
04
Deriva i dodici token
derive_palette() calcola token come --md-surface a bg più o meno 4-6% di luminanza e --md-text-muted come rgba(text, 0.68), e li memorizza in derived_palette nello stesso file di configurazione.
05
Risolvi la configurazione per precedenza
config_loader.py è il loader importabile che ogni convertitore chiama prima del rendering; unisce progetto, poi globale, poi valori predefiniti integrati, e rispetta la variabile d'ambiente di bypass.
06
Esegui override o reset in modo non interattivo
Oltre alla procedura guidata, onboard.py accetta --defaults, --set key=value, --scope project, --show e --reset, così i campi del brand possono essere modificati o azzerati senza ripercorrere le domande.

02 Trova la tua applicazione

Quando usare la skill design-system

Usa la skill design-system in Claude Code o Codex quando il lavoro riguarda brand e design system di questo tipo. Idoneità e limiti sono presi dal file della skill stessa.

Buona applicazione

Un workspace in cui qualcuno chiede di convertire markdown in HTML per la prima volta, quindi l'onboarding non è mai stato eseguito.
Un repository che necessita di un brand diverso dal resto del suo lavoro e non deve ereditare la configurazione globale.
Una CI o una sessione effimera che necessita di valori predefiniti zero-touch invece di dieci domande interattive.
Ha già almeno un HEX di brand che desidera applicare in modo coerente a tutte le conversioni HTML.
Desidera testare un primario e un accento candidati rispetto a WCAG prima di salvarli nella configurazione.

Conosci i limiti

Non è un sistema completo di design token come Style Dictionary o Theo; fornisce dodici token, non un centinaio.
Non ospita font personalizzati — Google Fonts via CDN è l'unica fonte tipografica.
Non è una suite di audit dell'accessibilità; axe-core o pa11y coprono questo ambito, e la skill applica solo il contrasto.
Non trasforma il CSS esistente: la palette derivata viene iniettata solo nell'HTML appena generato.

Cosa fornire

Directory di output predefinitaUn percorso che deve essere scrivibile; il valore predefinito è ./markdown-html-out/ e un valore non scrivibile o vuoto blocca il salvataggio.
HEX primario del brandConvalidato rispetto a ^#?[0-9a-fA-F]{6}$; predefinito #0A1628. La libreria di domande vincolanti consiglia un HEX che già utilizza, non un blu generico.
HEX dell'accento, oppure vuotoLascialo vuoto alla prima esecuzione per permettere alla derivazione di produrre un colore complementare; impostalo esplicitamente solo se un brand kit ne specifica uno.
Nomi dei font per titoli e corpo del testoNomi di Google Font scelti tra 12 opzioni predefinite sicure, con Inter come predefinito per entrambi i ruoli.
Nome azienda e URL del logo (opzionali)Entrambi hanno come valore predefinito una stringa vuota; l'URL del logo può essere lasciato vuoto ed è incorporato in base64 al momento del rendering.

03 Dentro la skill

Regole che la Skill design-system fornisce a Claude Code e Codex

7 istruzioni concrete, valori predefiniti e limiti che SKILL.md definisce per l'agente — la parte del file che cambia il risultato.

Il contrasto deve superare la verifica, altrimenti nulla si salva
Il testo del corpo sullo sfondo e i link sullo sfondo devono entrambi raggiungere un rapporto di 4,5:1 secondo WCAG 2.2 §1.4.3.
La directory di output deve essere scrivibile
Il wizard risale a un antenato esistente e verifica os.access(parent, os.W_OK); un percorso vuoto o non scrivibile termina con codice 3, e output_path_resolver.py applica la stessa regola per ogni conversione.
La personalizzazione deve modificare l'output
I campi puramente decorativi non rispettano la disciplina progettuale: ogni consumer deve leggere la configurazione e renderizzare in modo diverso quando cambiano design_style, brand.primary, code_theme o toc.behavior.
La precedenza è fissa
La configurazione di progetto prevale su quella globale, che a sua volta prevale sui valori predefiniti integrati, e il deep-merge preserva le chiavi annidate: sovrascrivere brand.primary in un progetto non elimina typography.heading_font dalla configurazione globale.
Bypass è solo per esecuzioni headless
MARKDOWN_HTML_NO_CONFIG=1 serve per CI, container di test effimeri e cicli di valutazione; non impostarlo mai silenziosamente per un utente interattivo, che si chiederebbe dove sono finiti i suoi token.
Non usare mai un colore primario vivace come sfondo
Un colore primario del brand molto saturo, usato direttamente come brand.bg, produce un basso contrasto del testo; dovrebbe invece essere collocato nello slot accent.
Rimani All'interno Della Tassonomia Di 12 Token
La semantica del brand non viene codificata in derived_palette fuori da questi dodici token; aggiungerne uno richiede un nome, uno scopo e una regola di derivazione deliberati.

04 Mettila al lavoro

Installare design-system in Claude Code o Codex

Un comando npx skills add, poi un primo task nel tuo agente e una checklist per il risultato.

Aggiungere design-system a Claude Code, Codex o al tuo agente

Eseguitelo nel Suo progetto; l'installer chiede a quale agente aggiungerlo.

Terminal

npx skills add https://github.com/alirezarezvani/claude-skills --skill design-system

Forma CLI generica skills per markdown-html/skills/design-system/SKILL.md; il repository potrebbe documentare un proprio percorso.

Assegna alla Skill un Primo Task di Lavoro su Brand e Design System

Redatto nei termini propri della skill; sostituisca le parti tra parentesi con il suo materiale.

Starter prompt

Set up the brand for this repo: primary #FF6B35, Inter for headings and body, editorial style, sticky-sidebar TOC, and save it per-project. Point the default output at [output directory] and then convert [document.md] with md-document so it comes out branded.

Fonte: redatto a partire dal SKILL.md, nei termini propri della skill.

Verifica il primo risultato

Ciò che il SKILL.md stesso indica come risultato corretto:

Ispeziona la configurazione effettiva con config_loader.py --show, che risolve project su global su defaults.
Verificare che il file di configurazione esista e che setup_completed_at sia impostato; se manca o è null, il convertitore si rifiuta e mostra l'onboarding.
Verifica rapidamente il contrasto di una coppia candidata con brand_palette_validator.py --primary e --accent prima di adottare un brand.
Verifica che il bypass si comporti come documentato eseguendolo con MARKDOWN_HTML_NO_CONFIG=1, che restituisce solo DEFAULTS.

In OpenDesign importa design-system dal link SKILL.md: Plugins → Add → Skill → Import from link, poi selezionalo nella barra superiore.

Scarica OpenDesign Leggi il quickstart

05 Open source, tracciabile

Sorgente, licenza e verifica

Da dove provengono i dati di questa pagina e quando sono stati verificati l'ultima volta.

Author: Alireza Rezvani
Repository: github.com/alirezarezvani/claude-skills Branch main
File della skill: markdown-html/skills/design-system/SKILL.md Checksum del contenuto registrato alla verifica; commit 19392f7
License: MIT Da LICENSE; SKILL.md indica "MIT".
Stelle del repository: 25.934 Snapshot GitHub del 2026-09-14 per l'intero repository alirezarezvani/claude-skills, che contiene 5 skill in questo catalogo. Non è una valutazione o un conteggio di utilizzo per design-system.
Verificato da OpenDesign: 14/09/2026 File sorgente, percorso, testo della licenza e conteggio delle stelle sono stati verificati. Non inclusa in OpenDesign main (verificato il 28/08/2026); un'esecuzione live non è stata registrata in questa pagina.

All'interno di SKILL.md

Quando richiamarloTabella sintomo-azione: onboarding, rifiuto della conversione, ambito di progetto, impostazione di un singolo campo, reset, valori predefiniti, bypass.
Set di domande di onboarding (10 domande)Tabella delle dieci chiavi, dei validatori e dei valori predefiniti, dalla cartella di output all'URL del logo.
Regole inderogabiliCinque regole numerate: gate WCAG AA, directory scrivibile, personalizzazione reale, precedenza fissa, bypass deliberato.
Palette derivata di 12 tokenTabella che associa ogni custom property CSS al suo scopo e alla regola di derivazione HSL.
Libreria di domande obbligate (pattern grill-with-docs di Matt Pocock)Cinque domande, una per turno, con risposte consigliate e citazioni dal canone.
Personalizzazione in uso (esempio pratico)Blocco Bash che mostra onboarding, valori predefiniti, set, ambito di progetto, reset, show e bypass.
PresuppostiQuattro precondizioni: un HEX di brand, configurazione in uno o due minuti, Google Fonts, soglia minima WCAG AA.
Non obiettiviCiò che non è: sistema di token, hosting dei font, selettore dark mode, suite di audit, trasformatore CSS.
Diverso daContrappone questo validatore e lo script di onboarding alle versioni landing e clinical-research.
Artefatto di outputIndica i percorsi JSON globale e di progetto, più la risorsa schema.
Anti-pattern (da evitare)Quattro errori da evitare: saltare l'onboarding, bg vibrante, bypass silenzioso, token fuori tassonomia.
RiferimentiClausole WCAG, testi su tipografia e colore, linee guida TOC, script affini.

Descrizione della skill

"Acquisisce l'identità del brand dell'utente una volta tramite una procedura guidata di onboarding in 10 domande (HEX primario/accent + font Google per intestazioni + body + stile di design editoriale/tecnico/minimale/giocoso + directory di output predefinita + tema di sintassi + comportamento TOC + logo/azienda opzionali), convalida il contrasto del testo body e dei link rispetto a WCAG 2.2 AA, deriva 12 proprietà personalizzate CSS nello spazio HSL e memorizza il risultato da utilizzare per ogni convertitore markdown-html. Usare prima di qualsiasi conversione markdown-html. Si attiva al primo avvio dell'onboarding ("configura il brand", "configura markdown-html", "esegui onboarding"), su reset esplicito ("resetta il design system", "ri-onboarding") ed è verificato da ogni convertitore tramite config_loader.py prima del rendering. Rifiuta di salvare se il contrasto del testo body non supera AA 4.5:1 o se la directory di output non è scrivibile. La precedenza è progetto (./.markdown-html/) > globale (~/.config/markdown-html/) > predefiniti integrati; MARKDOWN_HTML_NO_CONFIG=1 bypassa."

Descrizione front-matter da SKILL.md. Il file completo è di circa 11.234 caratteri. Leggi il file completo su GitHub.

06 Prima di installare

Domande sullo skill design-system

Le risposte provengono dal SKILL.md letto il 2026-09-14, non da un'esecuzione registrata.

Devo completare l'onboarding prima di convertire qualcosa?

I converter controllano la configurazione tramite config_loader.py e, se questa manca o setup_completed_at è null, la conversione viene rifiutata e viene proposto l'onboarding. Finché la configurazione non è completa, l'output viene generato con valori predefiniti segnaposto: tecnicamente funzionante ma privo di brand.

Design System

Esegui design-system su un Task Reale di Lavoro su Brand e Design System.

Scarica OpenDesign, importa design-system dal suo link SKILL.md, incolla il prompt qui sopra e leggi il piano prima del risultato.

Scarica OpenDesign Esplora tutte le skill

Terminale

npx skills add https://github.com/alirezarezvani/claude-skills --skill design-system

Cosa fa lo Skill design-system in Claude Code e Codex

Nelle parole della skill

Come funziona

Quando usare la skill design-system

Buona applicazione

Conosci i limiti

Cosa fornire

Regole che la Skill design-system fornisce a Claude Code e Codex

Il contrasto deve superare la verifica, altrimenti nulla si salva

La directory di output deve essere scrivibile

La personalizzazione deve modificare l'output

La precedenza è fissa

Bypass è solo per esecuzioni headless

Non usare mai un colore primario vivace come sfondo

Rimani All'interno Della Tassonomia Di 12 Token