skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/experience-design/skills/content-design/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: content-design
+description: Write a content spec for a page or journey from user needs — user-need statements ("As a… I need… so that…"), the questions the page must answer in priority order, the page structure, a plain-language rewrite at a target reading level with a before/after readability check, and an explicit list of what to cut and why. Use when the user wants a content spec, content design, "rewrite this page in plain English", "what should this page say", "our page is too long and nobody reads it", or content for a service or journey.
+---
+
+# content-design
+
+Decides what a page or journey should say, starting from what the reader needs to do, not from what the organisation wants to tell them. The output is a content spec: the user needs, the questions in the order readers ask them, the structure that answers them, a plain-language draft, and the cut list. It works at page altitude. `ux-writing` works at string altitude (the button, the error, the empty state); `guide-builder` writes step-by-step how-to guides and reference docs; `information-architecture` decides where the page lives. Content design comes before all three on a new page.
+
+## How to respond
+
+1. **Get the inputs in one message.** Ask at most 2 questions, spent on the weakest of: *who reads this and what they're trying to get done*, and *the source material* (the current page, policy text, notes, support tickets, search terms). Default the target reading level to plain English a 9-year-old could follow for a general audience. For a specialist audience, keep their professional terms but still use short sentences. Default the channel to a web page.
+
+2. **Write user-need statements first.** Format: *As a {specific reader}, I need {to know or do something} so that {their outcome}.* 2–5 needs per page. ✅ *"As a tenant whose boiler has broken, I need to know how fast the landlord must fix it so that I know whether to complain."* — ❌ *"As a user, I need information about repairs."* A need with no "so that" is a topic, not a need. Tag each with its evidence: `[support tickets]`, `[search terms]`, `[research]`, `[assumption]`. If the page serves no user need, say so: that is a finding, and the page may not need to exist.
+
+3. **List the questions the page must answer, in priority order.** Rank by how many readers ask it and how much it blocks them. ✅ *1. Am I eligible? 2. How much does it cost? 3. What do I need? 4. How long will it take?* The order of the questions becomes the order of the page. The organisation's background, history and mission go last or go away.
+
+4. **Structure the page from the questions.** One heading per top question, written as the reader's words (✅ *"How much it costs"* — ❌ *"Fee schedule"*). The answer to the top question sits in the first two sentences under the title. Use lists for 3+ parallel items, numbered steps only for a sequence, and tables for comparisons. If the questions span more than one task, recommend splitting the page and say where the second page goes.
+
+5. **Rewrite in plain language** at the target level. Short sentences (aim for under 20 words, never over 25), common words (*"buy"* not *"purchase"*, *"help"* not *"facilitate"*), active voice with a named actor (*"We will reply within 10 working days"* not *"A response will be issued"*), "you" for the reader, "we" for the organisation. Front-load each paragraph with its point. Keep every fact from the source: plain language changes the words, not the rules. Where a legal term must stay, keep it and explain it once.
+
+6. **Check the before and after** with the readability script and report its numbers as-is:
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/readability.py" before.md
+   python3 "${CLAUDE_SKILL_DIR}/scripts/readability.py" after.md --max-sentence 20
+   # Other IDEs (from the skill folder)
+   python3 scripts/readability.py before.md
+   python3 scripts/readability.py after.md --max-sentence 20
+   ```
+   It reports average sentence length, the share of long words, an estimated Flesch–Kincaid grade and every over-length sentence. The grade is a heuristic: use it to compare the two versions, and fix the flagged sentences. Never quote it as a certified score. If scripts can't run, report sentence counts by hand and say the grade wasn't computed.
+
+7. **Write the cut list.** Every sentence or section removed from the source goes in a table: what was cut, why (*not a user need*, *duplicates page X*, *organisational message*, *out of date*, *belongs on another page*), and where it went if it moved. Nothing disappears silently. Facts that must stay for legal or policy reasons stay, and the reason is noted.
+
+8. **Emit with [`templates/content-spec.md`](templates/content-spec.md)** in one message: reader and target level, user needs, prioritised questions, structure, the plain-language draft, the readability before/after, the cut list, and open questions (facts the source didn't give, policies to confirm). Hand-offs: strings inside a form or flow on the page → `ux-writing`; where the page sits in the site → `information-architecture`; a step-by-step setup or how-to guide → `guide-builder`; the wider journey the page sits in → `user-journey-map`. See [`examples/parking-permit-page.md`](examples/parking-permit-page.md).
+
+**Non-interactive runs** (subagent, CI, headless): a missing reader becomes an `[assumption]` line at the top, derived from the source. Missing source material for a rewrite emits `BLOCKED: need the current page or the facts it must contain`. Never draft a page's facts (prices, deadlines, eligibility rules) from nothing.
+
+## Useful references in this skill
+
+- [`templates/content-spec.md`](templates/content-spec.md) — the content spec skeleton: needs, questions, structure, draft, readability, cut list
+- [`scripts/readability.py`](scripts/readability.py) — stdlib plain-language check: sentence length, long words, estimated grade, over-length sentences
+- [`examples/parking-permit-page.md`](examples/parking-permit-page.md) — worked example: a council page rewritten from a policy paragraph, with real script output
+
+## Quality bar
+
+- **Every need names a specific reader, a need and an outcome**, with an evidence tag.
+- **Questions are ranked, and the page order follows the ranking.** The top question is answered in the first two sentences.
+- **Headings are in the reader's words.**
+- **The draft keeps every fact from the source**, and every change of meaning is flagged. Plain language never changes a rule.
+- **No sentence over 25 words** in the draft, and the script's before/after numbers are reported as it printed them.
+- **The cut list accounts for everything removed**, with a reason each.
+- **Nothing is invented.** Fees, deadlines, eligibility and contact details not in the source are `{placeholder}`s listed in open questions.
+
+## When to use this skill
+
+- ✅ A new page or journey that needs its content worked out from user needs
+- ✅ "Rewrite this in plain English" for a policy, service or product page
+- ✅ A long page nobody reads, with support tickets asking things the page already says
+- ✅ Agreeing what a page is for before design or development starts
+
+## When NOT to use this skill
+
+- ❌ Button labels, errors, empty states and other interface strings — that's `ux-writing`
+- ❌ A step-by-step setup guide, walkthrough or API reference — that's `guide-builder`
+- ❌ Where pages live and how the navigation groups them — that's `information-architecture`
+- ❌ The persona's whole path and emotions across stages — that's `user-journey-map`
+
+## Anti-patterns to avoid
+
+- ❌ **Starting from what the organisation wants to say.** "About our scheme" as the first section; readers want to know if they qualify.
+- ❌ **"As a user, I need information."** No specific reader, no outcome, and no way to tell whether the page met the need.
+- ❌ **Plain language that changes the rule.** "You'll get it in a week" when the policy says "up to 10 working days".
+- ❌ **Dumbing down for specialists.** Plain language for clinicians keeps clinical terms and cuts the padding.
+- ❌ **Silent cuts.** Deleting the paragraph a lawyer insisted on, without noting it, gets the whole rewrite rejected.
+- ❌ **Quoting the grade as gospel.** A readability formula counts syllables. It can't tell whether the page answers the reader's question.
+- ❌ **One page for three tasks.** "Permits, fines and appeals" on one page serves none of them well. Split it.

skilldrop_cli/data/packs/experience-design/skills/content-design/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Rewrite our refunds policy page in plain English so customers understand it",
+    "should_trigger": true
+  },
+  {
+    "query": "Write a content spec for the new 'Apply for a grant' page — user needs, what it must answer, what to cut",
+    "should_trigger": true
+  },
+  {
+    "query": "Our benefits page is 2,000 words and nobody reads it. What should it actually say?",
+    "should_trigger": true
+  },
+  {
+    "query": "Work out the content for each page of our account-closure journey from user needs",
+    "should_trigger": true
+  },
+  {
+    "query": "Write the error messages and button labels for the claim form",
+    "should_trigger": false
+  },
+  {
+    "query": "Turn these setup notes into a step-by-step getting-started guide for new developers",
+    "should_trigger": false
+  },
+  {
+    "query": "Design the navigation and sitemap for our help centre",
+    "should_trigger": false
+  },
+  {
+    "query": "Map the customer's journey from first quote to renewal with emotions at each stage",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/experience-design/skills/content-design/evals/evals.json

@@ -0,0 +1,18 @@
+{
+  "skill_name": "content-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Here's our 'Making a claim' page for Acme Home Insurance. Please make it something people can actually use. Current text: 'Policyholders wishing to initiate a claim in respect of loss or damage to insured property are required to notify Acme Home Insurance at the earliest practicable opportunity and in any event within 30 days of the incident. Notification may be effected via the online portal or by telephone. Claimants will be required to furnish supporting documentation including photographs, receipts and, where applicable, a crime reference number. Acme Home Insurance is committed to delivering market-leading service and has been recognised with numerous industry accolades. Claims are typically assessed within 15 working days of receipt of all documentation.' Most calls we get are 'what do I need to send' and 'how long will it take'.",
+      "assertions": [
+        "User-need statements follow 'As a… I need… so that…' with a specific reader and an evidence tag",
+        "Questions are listed in priority order and the page headings follow that order, written in the reader's words",
+        "The draft keeps every fact: 30 days, online or phone, photos, receipts, crime reference number where applicable, and 15 working days after all documents",
+        "No sentence in the draft is over 25 words",
+        "Before/after readability numbers are reported from the script, or the output says the grade was not computed",
+        "The cut list includes the 'market-leading service' and 'industry accolades' sentence with a reason",
+        "Does not invent a phone number, URL, excess amount or other fact not in the prompt; unknowns are placeholders listed as open questions"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/experience-design/skills/content-design/examples/parking-permit-page.md

@@ -0,0 +1,102 @@
+# Worked example — a council parking permit page, rewritten from user needs
+
+## Input given to the skill
+
+> Can you redo our resident parking permit page? It's the current text below and we get a lot of
+> calls asking "how long does it take" and "what documents do I need". Our usual proof of address is
+> a council tax bill and for the car it's the V5C logbook. Readers are residents, all ages, lots of
+> them reading on a phone.
+
+Current page (`before.md`):
+
+> Residents' Parking Scheme Information
+>
+> Northwind Council operates a Controlled Parking Zone (CPZ) scheme in designated areas of the borough in order to prioritise the availability of on-street parking for residents and their visitors. Applications for a resident parking permit may be submitted by any individual whose principal residence is located within a CPZ, subject to the provision of satisfactory documentary evidence of both residency and vehicle ownership or keepership. Permits are issued for a period of twelve months and the applicable charge is determined with reference to the CO2 emissions band of the vehicle in question. Applicants should be aware that the processing of applications may take up to ten working days from receipt of all required documentation. In the event that an applicant does not possess the requisite documentation, the application will be held in abeyance until such time as it is provided.
+
+## Output
+
+# Content spec: Apply for a resident parking permit
+
+**Reader:** a resident in a controlled parking zone who wants to park near home, often on a phone · **Target level:** plain English for a general audience
+**Channel:** web page · **Assumptions to confirm first:** the page is only for resident permits, and visitor permits have their own page.
+
+### User needs
+
+| # | As a… | I need… | So that… | Evidence |
+|---|---|---|---|---|
+| 1 | resident in a parking zone | to know if I can get a permit | I don't apply for something I can't have | [assumption] |
+| 2 | resident applying | to know which documents to have ready | I can apply in one go | [support calls] "what documents do I need" |
+| 3 | resident applying | to know how long it takes | I can plan where to park until it arrives | [support calls] "how long does it take" |
+| 4 | resident applying | to know what it costs | I can budget for it | [assumption] |
+
+### Questions the page must answer (priority order)
+
+1. Can I get one? — it decides whether the rest of the page matters
+2. What do I need? — the top call reason, and it's what stops an application
+3. How much is it? — asked before people start
+4. How long does it take? — the other top call reason, but only after they've decided to apply
+
+### Structure
+
+| Order | Heading (reader's words) | Answers | Format |
+|---|---|---|---|
+| 1 | Apply for a resident parking permit — first two sentences say who can apply | Q1 | paragraph |
+| 2 | What you need | Q2 | list |
+| 3 | How much it costs | Q3 | paragraph |
+| 4 | How long it takes | Q4 | paragraph |
+
+### Draft (`after.md`)
+
+> # Apply for a resident parking permit
+>
+> You can apply if you live in a controlled parking zone. A permit gives you priority for parking on the street in your zone.
+>
+> ## What you need
+>
+> - proof you live at the address, like a council tax bill
+> - proof you own or keep the car, like the V5C logbook
+>
+> ## How much it costs
+>
+> The price depends on your car's CO2 emissions band. A permit lasts 12 months.
+>
+> ## How long it takes
+>
+> It can take up to 10 working days. We start counting when we have all your documents. If something is missing, we hold your application until you send it.
+
+### Readability (script output, before → after)
+
+Run: `python3 scripts/readability.py before.md` and `python3 scripts/readability.py after.md --max-sentence 20`.
+
+```
+before.md
+Words: 144  Sentences: 6  Avg sentence: 24.0 words
+Long words (3+ syllables): 24.3%
+Estimated Flesch-Kincaid grade: 15.1 (heuristic syllables; compare before/after, don't quote as exact)
+Sentences over 25 words: 4
+
+after.md
+Words: 105  Sentences: 13  Avg sentence: 8.1 words
+Long words (3+ syllables): 5.7%
+Estimated Flesch-Kincaid grade: 2.7 (heuristic syllables; compare before/after, don't quote as exact)
+Sentences over 20 words: none
+```
+
+(The before count includes the title line as a sentence. The four flagged sentences are the four long ones in the source.)
+
+### Cut list
+
+| What was cut | Why | Where it went |
+|---|---|---|
+| "Northwind Council operates a Controlled Parking Zone (CPZ) scheme…" | Organisational message. What a zone does for the reader is kept in one sentence. | Shortened into the opening paragraph |
+| "…and their visitors" | Visitor permits are a different task | Visitor permits page (confirm it exists) |
+| "subject to the provision of satisfactory documentary evidence" | Replaced by the concrete documents | "What you need" list |
+| The acronym "CPZ" | Readers don't use it; it appeared twice and was never needed | Removed |
+
+Kept on purpose: "own or keep the car" keeps "keepership" from the source, because a keeper who isn't the owner can still apply. "Up to 10 working days" keeps the source's limit, not a promise of a shorter time.
+
+### Open questions
+
+- What are the prices per emissions band? The page should show them, or link to them.
+- Is there an "Apply now" link, and does it need a form? If so, its strings go to `ux-writing`.
+- Which documents count besides a council tax bill and a V5C? List them if there are others.

skilldrop_cli/data/packs/experience-design/skills/content-design/manifest.json

@@ -0,0 +1,41 @@
+{
+  "name": "content-design",
+  "version": "0.1.0",
+  "description": "Write a content spec for a page or journey from user needs — user-need statements (\"As a… I need… so that…\"), the questions the page must answer in priority order, the page structure, a plain-language rewrite at a target reading level with a before/after readability check, and an explicit list of what to cut and why. Use when the user wants a content spec, content design, \"rewrite this page in plain English\", \"what should this page say\", \"our page is too long and nobody reads it\", or content for a service or journey.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "guide-builder",
+    "information-architecture",
+    "user-journey-map",
+    "ux-writing"
+  ],
+  "handoff": [
+    {
+      "to": "ux-writing",
+      "when": "the page includes a form, flow or interactive component",
+      "purpose": "Write the interface strings inside it to the same terminology.",
+      "fallback": "If ux-writing is absent, list each control on the page with a verb-plus-object label and one error message per field rule."
+    }
+  ],
+  "tags": [
+    "content-design",
+    "plain-language",
+    "content-strategy",
+    "readability",
+    "ux",
+    "user-needs"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "none", "notes": "Prints readability figures; writes nothing."},
+  "model": {
+    "tier": "standard",
+    "rationale": "Rewrites source text from user needs under fixed plain-language rules, with a script for the readability numbers. Prioritising questions needs judgment, but facts come from the source."
+  }
+}

skilldrop_cli/data/packs/experience-design/skills/content-design/scripts/readability.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Plain-language check for a block of text. Stdlib only, Python 3.9+.
+
+Reports word and sentence counts, average sentence length, the share of long words
+(3+ syllables), an estimated Flesch-Kincaid grade, and every sentence over the length limit.
+Syllables are counted with a vowel-group heuristic, so treat the grade as an estimate for
+comparing a before and after, not as a precise score.
+
+Usage:
+    python3 readability.py page.md                 # text from a file
+    cat page.md | python3 readability.py -         # text from stdin
+    python3 readability.py page.md --max-sentence 20 --json
+"""
+import argparse
+import json
+import re
+import sys
+
+WORD = re.compile(r"[A-Za-z][A-Za-z'\-]*")
+
+
+def strip_markdown(text):
+    text = re.sub(r"```.*?```", " ", text, flags=re.S)        # fenced code
+    text = re.sub(r"`[^`]*`", " ", text)                       # inline code
+    text = re.sub(r"!\[[^\]]*\]\([^)]*\)", " ", text)          # images
+    text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", text)       # links keep their text
+    text = re.sub(r"^\s{0,3}#{1,6}\s*(.*)$", r"\1.", text, flags=re.M)  # headings end a sentence
+    text = re.sub(r"^\s*[-*+]\s+(.*)$", r"\1.", text, flags=re.M)       # list items end a sentence
+    text = re.sub(r"^\s*\d+[.)]\s+(.*)$", r"\1.", text, flags=re.M)
+    text = re.sub(r"[*_>|]", " ", text)
+    return text
+
+
+def syllables(word):
+    w = word.lower().strip("'-")
+    if not w:
+        return 0
+    if len(w) <= 3:
+        return 1
+    w = re.sub(r"(?:[^laeiouy]es|ed|[^laeiouy]e)$", "", w)
+    w = re.sub(r"^y", "", w)
+    groups = re.findall(r"[aeiouy]{1,2}", w)
+    return max(1, len(groups))
+
+
+def sentences(text):
+    parts = re.split(r"(?<=[.!?])\s+|\n\s*\n", text)
+    out = []
+    for p in parts:
+        p = " ".join(p.split())
+        if WORD.search(p):
+            out.append(p)
+    return out
+
+
+def analyse(text, max_sentence):
+    plain = strip_markdown(text)
+    sents = sentences(plain)
+    words = WORD.findall(plain)
+    if not words or not sents:
+        return None
+    syl = [syllables(w) for w in words]
+    long_words = sum(1 for s in syl if s >= 3)
+    n_words, n_sents = len(words), len(sents)
+    grade = 0.39 * (n_words / n_sents) + 11.8 * (sum(syl) / n_words) - 15.59
+    too_long = []
+    for s in sents:
+        n = len(WORD.findall(s))
+        if n > max_sentence:
+            too_long.append({"words": n, "sentence": s})
+    return {
+        "words": n_words,
+        "sentences": n_sents,
+        "avg_sentence_words": round(n_words / n_sents, 1),
+        "long_word_pct": round(100.0 * long_words / n_words, 1),
+        "fk_grade_estimate": round(grade, 1),
+        "max_sentence": max_sentence,
+        "long_sentences": too_long,
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Plain-language check: sentence length, long words, estimated grade.")
+    ap.add_argument("path", help="text or markdown file, or - for stdin")
+    ap.add_argument("--max-sentence", type=int, default=25, help="flag sentences longer than this many words (default 25)")
+    ap.add_argument("--json", action="store_true", help="print JSON instead of a text report")
+    args = ap.parse_args()
+
+    if args.max_sentence < 1:
+        sys.exit("error: --max-sentence must be 1 or more")
+    try:
+        text = sys.stdin.read() if args.path == "-" else open(args.path, encoding="utf-8").read()
+    except OSError as e:
+        sys.exit("error: cannot read {}: {}".format(args.path, e.strerror))
+
+    r = analyse(text, args.max_sentence)
+    if r is None:
+        sys.exit("error: no words found in the input")
+
+    if args.json:
+        print(json.dumps(r, indent=2))
+        return
+    print("Words: {}  Sentences: {}  Avg sentence: {} words".format(r["words"], r["sentences"], r["avg_sentence_words"]))
+    print("Long words (3+ syllables): {}%".format(r["long_word_pct"]))
+    print("Estimated Flesch-Kincaid grade: {} (heuristic syllables; compare before/after, don't quote as exact)".format(r["fk_grade_estimate"]))
+    if r["long_sentences"]:
+        print("Sentences over {} words: {}".format(r["max_sentence"], len(r["long_sentences"])))
+        for s in r["long_sentences"]:
+            print("  - ({} words) {}".format(s["words"], s["sentence"]))
+    else:
+        print("Sentences over {} words: none".format(r["max_sentence"]))
+
+
+if __name__ == "__main__":
+    main()

skilldrop_cli/data/packs/experience-design/skills/content-design/templates/content-spec.md

@@ -0,0 +1,45 @@
+# Content spec: {page or journey}
+
+**Reader:** {specific reader} · **Target level:** {plain English for a general audience / specialist terms, short sentences}
+**Channel:** {web page / email / app screen} · **Assumptions to confirm first:** {list, or "none"}
+
+## User needs
+
+| # | As a… | I need… | So that… | Evidence |
+|---|---|---|---|---|
+| 1 | {reader} | {to know / do} | {outcome} | {[support tickets] / [search terms] / [research] / [assumption]} |
+
+## Questions the page must answer (priority order)
+
+1. {question} — {why it ranks here}
+2. {question}
+
+## Structure
+
+| Order | Heading (reader's words) | Answers question | Format |
+|---|---|---|---|
+| 1 | {title} — first two sentences answer Q1 | 1 | {paragraph / list / steps / table} |
+
+## Draft
+
+{plain-language draft}
+
+## Readability (script output, before → after)
+
+| | Before | After |
+|---|---|---|
+| Words | {} | {} |
+| Avg sentence (words) | {} | {} |
+| Long words (3+ syllables) | {}% | {}% |
+| Estimated grade (heuristic) | {} | {} |
+| Sentences over limit | {} | {} |
+
+## Cut list
+
+| What was cut | Why | Where it went |
+|---|---|---|
+| {text or section} | {not a user need / duplicate / organisational message / out of date / belongs elsewhere} | {page, or "removed"} |
+
+## Open questions
+
+- {fact the source didn't give}

skilldrop_cli/data/packs/experience-design/skills/design-system-spec/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: design-system-spec
+description: Write a design system component spec — purpose, anatomy, variants, every state (default, hover, focus, active, disabled, error, loading), the design tokens each part uses by name, behaviour, content rules, accessibility (keyboard, focus order, ARIA role, contrast, target size) cited to WCAG 2.2 criteria, do/don't examples, and the open questions engineering must answer. Use when the user wants a component spec, design system documentation, "spec out this button / modal / text field", a component's states and tokens, or a design-to-engineering hand-off for a component.
+---
+
+# design-system-spec
+
+Writes the spec a designer and an engineer can both build a component from, so it behaves the same in every product that uses it. The unit is one component (button, text field, modal, tabs, toast). The spec covers what it is for, its parts, its variants, every state, the tokens that style it, how it behaves, what text goes in it, and how it works with a keyboard and a screen reader. Accessibility is part of the spec, not a later pass. Once the component is built, `accessibility-audit` checks the real thing. The component's strings come from `ux-writing`, and the colours and fonts behind the tokens come from the brand (`brand-kit`).
+
+## How to respond
+
+1. **Get the component and the system in one message.** Ask at most 2 questions, spent on the weakest of: *which component and where it's used* (screenshots, a Figma description, existing code, or a list of use cases), and *the token set* (token names from the system, or a `brand.json`). Default the platform to web. With no token set, propose token names in the system's likely shape and tag each `[proposed token]`.
+
+2. **State the purpose and the boundary.** One sentence on what the component is for, and one on when to use something else: ✅ *"Use a toggle for a setting that takes effect immediately. Use a checkbox when the change waits for a Save button."* A component without a boundary gets used for everything and grows variants until nobody can maintain it.
+
+3. **Draw the anatomy.** Number every part (container, label, icon, helper text, and so on) and say which parts are required and which optional. Use the same numbers in the token and state tables.
+
+4. **Define variants on separate axes.** Keep *emphasis* (primary, secondary, tertiary), *size* (small, medium, large) and *type* (with icon, icon-only) as independent axes, not a flat list of 14 combinations. Every variant states when to use it. Cut any variant with no use case in the input; a variant "for later" is debt.
+
+5. **Specify every state** in a table: default, hover, focus (keyboard), active/pressed, disabled, error (if it takes input), loading (if it triggers async work), plus selected/checked or read-only where they apply. For each state give the visual change *by token*, the cursor, and what assistive tech announces. Focus is never shown by colour change alone, and it never looks the same as hover. Disabled states say why the component is disabled (a hint or tooltip), or the spec explains why it isn't needed.
+
+6. **Name tokens, never raw values.** ✅ *`color.border.focus`, `space.200`, `radius.medium`, `font.label.md`* — ❌ *`#2563EB`, `8px`*. A raw value in a component spec forks the system. If a needed token doesn't exist, propose one and list it in open questions. When the brand colours are known, check that each text and border pair meets the contrast minimums in [`reference.md`](reference.md), and flag any pair that fails.
+
+7. **Write the behaviour and the content rules.** Behaviour: what triggers the component, what it does, what happens on overflow, truncation, wrapping, and different screen widths, and its timing (debounce, auto-dismiss). Content rules: label length budget, case, verb-first for actions, what may never appear (e.g. no punctuation in button labels). Exact strings for the product come from `ux-writing`; the spec sets the rules.
+
+8. **Write the accessibility section** from [`reference.md`](reference.md), and cite only the WCAG 2.2 criteria listed there:
+   - **Keyboard:** every key and what it does (Tab, Shift+Tab, Enter, Space, Esc, arrow keys), matching the WAI-ARIA Authoring Practices pattern for that component when one exists.
+   - **Focus order and management:** where focus goes on open, on close, and after an error, and that it is never trapped except inside a modal dialog that can be closed with Esc.
+   - **Role and name:** the native element first (`<button>`, `<input>`, `<dialog>`), ARIA only when no native element fits. Say how the accessible name is computed and which states map to ARIA attributes (`aria-expanded`, `aria-invalid`, `aria-describedby`).
+   - **Contrast and size:** text 4.5:1 (3:1 for large text); borders, icons and focus indicators 3:1 against their background; pointer target at least 24×24 CSS px or spaced to meet 2.5.8.
+   - **Announcements:** errors, loading and success that don't move focus are announced through a live region or status message.
+
+9. **Add do/don't pairs** for the 3–5 misuses most likely in the input's context, each with a one-line reason. ✅/❌ side by side.
+
+10. **Emit with [`templates/component-spec.md`](templates/component-spec.md)** in one message: purpose and boundary, anatomy, variants, state table, token table, behaviour, content rules, accessibility, do/don't, and **open questions for engineering** (each with the decision it blocks: framework constraints, animation, controlled vs uncontrolled, how the error state is set). Hand-off: after build, run `accessibility-audit` on the component. See [`examples/text-field-spec.md`](examples/text-field-spec.md).
+
+**Non-interactive runs** (subagent, CI, headless): a missing token set becomes `[proposed token]` names, and missing use cases become an `[assumption]` line at the top. If the component can't be identified from the input, emit `BLOCKED: need the component and where it is used`.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the WCAG 2.2 criteria this skill cites (checked list), contrast and target size figures, keyboard patterns by component, token naming
+- [`templates/component-spec.md`](templates/component-spec.md) — the spec skeleton with anatomy, variant, state, token and accessibility tables
+- [`examples/text-field-spec.md`](examples/text-field-spec.md) — worked example: a text field with async validation, every state and its tokens
+
+## Quality bar
+
+- **Purpose and boundary are stated**, including when to use a different component.
+- **Anatomy parts are numbered** and the numbers are reused in the state and token tables.
+- **Variants sit on independent axes**, each with a use case. No speculative variants.
+- **Every applicable state is specified**, including focus, disabled, error and loading. Focus differs from hover and isn't shown by colour alone.
+- **Tokens are named, never raw values.** Proposed tokens are tagged and listed as open questions.
+- **Accessibility covers keyboard, focus, role and name, contrast and announcements**, and every WCAG citation is one from the reference list with the right number and name.
+- **Open questions for engineering each name the decision they block.**
+- **Nothing is invented.** Token names, brand values and platform constraints not in the input are tagged `[proposed token]` or `[assumption]`.
+
+## When to use this skill
+
+- ✅ Documenting a new or existing component for a design system
+- ✅ A design-to-engineering hand-off for one component
+- ✅ Reconciling a component that behaves differently in three products
+- ✅ Adding a state (loading, error) or a variant to an existing component
+
+## When NOT to use this skill
+
+- ❌ Auditing a built page or component against WCAG — that's `accessibility-audit`
+- ❌ Writing the product's interface strings for a flow — that's `ux-writing`
+- ❌ Capturing brand colours, fonts and logo — that's `brand-kit`
+- ❌ Page-level structure or navigation — that's `information-architecture`
+
+## Anti-patterns to avoid
+
+- ❌ **Hex codes in the spec.** `#2563EB` is right until the rebrand, then wrong in 40 places.
+- ❌ **The happy-path spec.** Default and hover only; engineering invents error, loading and disabled, three different ways.
+- ❌ **Focus = hover.** A focus style that matches hover gives keyboard users no way to tell focus apart from where the mouse is.
+- ❌ **`div` with a click handler.** No keyboard support, no role, no name. Specify the native element.
+- ❌ **ARIA as decoration.** `role="button"` on a `<button>`, or `aria-label` that contradicts the visible label.
+- ❌ **Disabled with no reason.** A greyed-out Save button with no hint leaves the user stuck.
+- ❌ **Variant explosion.** "Primary-large-icon-left-destructive" as a named variant; use axes.
+- ❌ **Citing WCAG from memory.** A wrong criterion number undermines the whole accessibility section. Cite only what the reference lists.

skilldrop_cli/data/packs/experience-design/skills/design-system-spec/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Write a component spec for our button: variants, states, tokens and accessibility",
+    "should_trigger": true
+  },
+  {
+    "query": "Document the tabs component for our design system so engineering can build it",
+    "should_trigger": true
+  },
+  {
+    "query": "Spec out a toast notification with all its states and keyboard behaviour",
+    "should_trigger": true
+  },
+  {
+    "query": "Our date picker behaves differently in three products — write one spec they can all build to",
+    "should_trigger": true
+  },
+  {
+    "query": "Audit our sign-up page for WCAG 2.2 AA problems",
+    "should_trigger": false
+  },
+  {
+    "query": "Set up our brand kit with our logo, colours and fonts",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the error messages and helper text for the checkout form",
+    "should_trigger": false
+  },
+  {
+    "query": "Design the navigation structure for our settings area",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/experience-design/skills/design-system-spec/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "design-system-spec",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write the component spec for Acme's modal dialog. It's used for confirmations (delete project), short forms (rename), and a long terms-and-conditions view that scrolls. Our tokens include color.background.surface, color.background.overlay, color.border.subtle, color.text.default, space.200, space.300, radius.large, font.heading.md, font.body.md, shadow.overlay. Web, built in Vue.",
+      "assertions": [
+        "States purpose and boundary, including when to use something other than a modal",
+        "Anatomy parts are numbered and the same numbers are used in the state and token tables",
+        "Every applicable state is specified, including focus, and focus is distinguishable from hover without relying on colour alone",
+        "Styling uses only token names, never hex codes or pixel values; any needed token not in the prompt is tagged [proposed token]",
+        "Keyboard behaviour covers focus moving into the dialog on open, Tab staying inside, Esc closing, and focus returning to the trigger",
+        "Specifies a native <dialog> or role=dialog with aria-modal and an accessible name from the heading",
+        "Every WCAG citation is a real WCAG 2.2 criterion with the correct number and name",
+        "Ends with open questions for engineering, each naming the decision it blocks"
+      ]
+    }
+  ]
+}