skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/experience-design/skills/design-system-spec/examples/text-field-spec.md

@@ -0,0 +1,121 @@
+# Worked example — a text field with async validation
+
+## Input given to the skill
+
+> Spec our text field for the Northwind design system. Used in sign-up (username, which we check
+> for availability as you type), settings forms, and checkout. Today each product has its own and
+> they look different. Our tokens: `color.text.default`, `color.text.subtle`, `color.text.danger`,
+> `color.border.default`, `color.border.hover`, `color.border.focus`, `color.border.danger`,
+> `color.background.input`, `color.background.disabled`, `space.100`, `space.200`, `radius.small`,
+> `font.body.md`, `font.label.md`, `font.helper.sm`. Web, React.
+
+## Output
+
+# Component spec: Text field
+
+**Status:** draft · **Platform:** web (React) · **Token source:** Northwind tokens, plus two `[proposed token]`s
+**Assumptions to confirm first:** availability checks call an API that answers in under 2 seconds, and fields are single-line (multi-line is a separate textarea component).
+
+### Purpose and boundary
+
+- **Use it for:** short free-text input of one line: names, usernames, email, card number.
+- **Use something else when:** the answer is one of a known set (select or radio group), it's a date (date picker), or it's more than one line (textarea).
+
+### Anatomy
+
+| # | Part | Required | Notes |
+|---|---|---|---|
+| 1 | Label | yes | Always visible, above the input. Never replaced by placeholder. |
+| 2 | Input container | yes | Border and background |
+| 3 | Input text | yes | |
+| 4 | Helper text | optional | Format or reason we ask. Replaced by the error message in the error state. |
+| 5 | Error message | in error state | Icon + text |
+| 6 | Status indicator | optional | Spinner (loading) or check (valid), at the input's end |
+
+### Variants
+
+| Axis | Values | When to use each |
+|---|---|---|
+| Size | md (default), sm | sm only in dense tables and filters; md everywhere else |
+| Width | full, fixed to expected length | Fixed width for known-length data (postcode, CVC) so the size hints at the answer |
+
+No "outlined/filled" style variant: one style across products is the point of the spec.
+
+### States
+
+| State | Visual change (by token, by part #) | Cursor | Announced by assistive tech |
+|---|---|---|---|
+| Default | 2 border `color.border.default`, background `color.background.input`; 1 `color.text.default`; 4 `color.text.subtle` | text | Label, then helper text (via `aria-describedby`) |
+| Hover | 2 border `color.border.hover` | text | nothing |
+| Focus | 2 border `color.border.focus` plus a focus ring `[proposed token: border.width.focus]` outside the border | text | Same as default |
+| Filled | No change from default | text | Label and value |
+| Disabled | 2 background `color.background.disabled`; 3 `color.text.subtle`; helper text says why it's disabled | not-allowed | Label, value, "dimmed" or "unavailable" (from `disabled`) |
+| Read-only | 2 border removed, value shown as text | default | Label, value, "read only" |
+| Error | 2 border `color.border.danger`; 5 shown with icon in `color.text.danger`; 4 hidden | text | Label, value, "invalid", then the error text |
+| Loading | 6 spinner at the end of 2; input stays editable | text | "Checking availability" in a status region, once per check |
+| Valid (async only) | 6 check icon, colour `color.text.default` (not green alone) | text | "Username available" in the status region |
+
+Focus differs from hover by the added ring, not by colour alone.
+
+### Tokens
+
+| Part # | Property | Token | Notes |
+|---|---|---|---|
+| 1 | type | `font.label.md` | |
+| 1 | colour | `color.text.default` | |
+| 2 | background | `color.background.input` | |
+| 2 | border colour | `color.border.default` / `.hover` / `.focus` / `.danger` | by state |
+| 2 | radius | `radius.small` | |
+| 2 | padding | `space.100` vertical, `space.200` horizontal | |
+| 2 | min height | `[proposed token: size.target.min]` | Must meet the 24×24 CSS px target minimum. Recommend larger for touch. |
+| 3 | type | `font.body.md` | |
+| 4, 5 | type | `font.helper.sm` | |
+| 1→2, 2→4 | gap | `space.100` | |
+
+### Behaviour
+
+- **Async check:** starts 400 ms after the last keystroke `[assumption]`; a newer keystroke cancels the pending check. The result shows only for the current value.
+- **Validation timing:** format errors show on blur, not on every keystroke. Once a field is in error, it re-validates on input so the error clears as soon as it's fixed.
+- **Overflow:** text scrolls horizontally inside the input; the label wraps, never truncates.
+- **Responsive:** full width below the small breakpoint, whatever the width variant.
+- **Submit:** Enter submits the parent form. On submit with errors, focus moves to the first field in error.
+
+### Content rules
+
+- Label: a noun, 1–4 words, sentence case, no colon, no "Enter your…".
+- Helper text: one sentence, under 80 characters, says the format or why we ask.
+- Error: what's wrong and how to fix it, naming the field. Exact strings come from `ux-writing`.
+- Placeholder: off by default. If used, only an example value ("sam@northwind.example"), never the label or instructions.
+
+### Accessibility
+
+- **Native element / role:** `<input>` with a `<label for>`. No ARIA role needed.
+- **Accessible name:** from the visible label, so it satisfies 2.5.3 Label in Name.
+- **States → ARIA:** `aria-describedby` → helper text (default) or error message (error); `aria-invalid="true"` in error; `disabled` attribute for disabled; `readonly` for read-only. Required fields use `required` and a visible "(required)" or "(optional)" convention, picked once per form.
+- **Keyboard:** standard text input; Tab and Shift+Tab move in and out, so there's no trap.
+- **Focus:** stays in the field during async checks; after a failed submit, moves to the first invalid field.
+- **Contrast and size:** label, value, helper and error text at least 4.5:1; the input border and the focus ring at least 3:1 against the background; target at least 24×24 CSS px.
+- **Announcements:** async results ("Checking availability", "Username available", "Username taken") go to a `role="status"` region so they're announced without moving focus.
+- **WCAG 2.2 criteria:** 1.3.1 Info and Relationships, 1.4.1 Use of Color, 1.4.3 Contrast (Minimum), 1.4.11 Non-text Contrast, 2.4.7 Focus Visible, 2.5.3 Label in Name, 2.5.8 Target Size (Minimum), 3.3.1 Error Identification, 3.3.2 Labels or Instructions, 3.3.3 Error Suggestion, 4.1.2 Name, Role, Value, 4.1.3 Status Messages.
+
+### Do / don't
+
+| ✅ Do | ❌ Don't | Why |
+|---|---|---|
+| Label above the field, always visible | Placeholder as the only label | It disappears on typing, and has weak contrast |
+| Show format errors on blur | Show "Invalid email" after the first keystroke | Users get told off before they've finished |
+| Fixed width for a 3-digit CVC | Full-width CVC field | Width hints at the expected answer |
+| Error icon + text + red border | Red border alone | Colour alone fails users who can't see red |
+| Explain a disabled field in its helper text | Grey out with no reason | The user can't fix what they can't see |
+
+### Open questions for engineering
+
+| Question | Blocks |
+|---|---|
+| Controlled, uncontrolled, or both? | The React API and how forms libraries integrate |
+| Who owns the debounce and cancel: the component or the caller? | Whether the async state is a prop or internal |
+| Is the 400 ms debounce acceptable for the username API's rate limits? | The behaviour timing |
+| Can we add `border.width.focus` and `size.target.min` to the token set? | Focus and size tokens; otherwise raw values leak in |
+| Does the error message render in the component or via a form-level slot? | Where `aria-describedby` points |
+
+**Next:** once built, run `accessibility-audit` on the sign-up form that uses it.

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

@@ -0,0 +1,46 @@
+{
+  "name": "design-system-spec",
+  "version": "0.1.0",
+  "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.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "accessibility-audit",
+    "brand-kit",
+    "information-architecture",
+    "ux-writing"
+  ],
+  "handoff": [
+    {
+      "to": "accessibility-audit",
+      "when": "the component is built",
+      "purpose": "Check the real component against WCAG 2.2 AA, which a spec can't prove.",
+      "fallback": "If accessibility-audit is absent, test it by hand: tab through every state, use it with a screen reader, and measure text and border contrast."
+    },
+    {
+      "to": "ux-writing",
+      "when": "the content rules are set and the product needs the actual strings",
+      "purpose": "Write labels, helper text and errors to the spec's rules.",
+      "fallback": "If ux-writing is absent, give one example string per slot that follows the content rules."
+    }
+  ],
+  "tags": [
+    "design-system",
+    "component-spec",
+    "ui",
+    "tokens",
+    "accessibility",
+    "wcag"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Fills a fixed spec shape (anatomy, states, tokens, accessibility) against a checked WCAG list. Needs care on states and keyboard patterns, but the structure bounds it."
+  }
+}

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

@@ -0,0 +1,66 @@
+# design-system-spec — reference
+
+## WCAG 2.2 criteria this skill cites
+
+Cite only these, by number and name. If a concern isn't covered here, describe it in plain words without a criterion number. Level is the conformance level the criterion belongs to.
+
+| # | Name | Level | What it means for a component spec |
+|---|---|---|---|
+| 1.3.1 | Info and Relationships | A | Structure shown visually (label ↔ field, group ↔ options) is also in the markup: `<label for>`, `<fieldset>`/`<legend>`, `aria-describedby` for helper text. |
+| 1.4.1 | Use of Color | A | Colour isn't the only signal for a state. An error state adds an icon or text, not just a red border. |
+| 1.4.3 | Contrast (Minimum) | AA | Text at least 4.5:1 against its background; large text at least 3:1. |
+| 1.4.11 | Non-text Contrast | AA | Visual information needed to identify UI components and their states (borders of inputs, icons, focus indicators) at least 3:1 against adjacent colours. |
+| 1.4.12 | Text Spacing | AA | The component doesn't clip or overlap content when users increase line, paragraph, letter and word spacing. Don't fix heights on text containers. |
+| 1.4.13 | Content on Hover or Focus | AA | Tooltips and popovers shown on hover or focus can be dismissed without moving the pointer (usually Esc), can be hovered themselves, and stay until dismissed or no longer relevant. |
+| 2.1.1 | Keyboard | A | Everything works from a keyboard. |
+| 2.1.2 | No Keyboard Trap | A | Focus can always leave the component with the keyboard. A modal dialog holds focus inside it by design, and Esc or a close button lets the user out. |
+| 2.2.1 | Timing Adjustable | A | Content that disappears on a timer (auto-dismissing toasts that carry information or actions) needs a way to turn off, adjust or extend the time, unless an exception applies. |
+| 2.4.3 | Focus Order | A | Focus moves in an order that keeps meaning and operation intact. |
+| 2.4.7 | Focus Visible | AA | The keyboard focus indicator is visible. |
+| 2.4.11 | Focus Not Obscured (Minimum) | AA | A focused component is not entirely hidden by author-created content such as sticky headers, footers or non-modal overlays. New in 2.2. |
+| 2.5.3 | Label in Name | A | The accessible name contains the visible label text, so voice-control users can say what they see. |
+| 2.5.7 | Dragging Movements | AA | Anything done by dragging (sliders, reordering) can also be done with single-pointer actions without dragging. New in 2.2. |
+| 2.5.8 | Target Size (Minimum) | AA | Pointer targets at least 24 by 24 CSS pixels, or spaced so a 24 px circle centred on each doesn't overlap another target, with exceptions (inline links in text, an equivalent control elsewhere, essential, user-agent controls). New in 2.2. |
+| 3.2.1 | On Focus | A | Receiving focus doesn't trigger a change of context (no navigation or submit on focus). |
+| 3.2.2 | On Input | A | Changing a setting doesn't change context unexpectedly unless the user was told beforehand. |
+| 3.3.1 | Error Identification | A | An input error that is detected automatically identifies the item in error and describes the error in text. |
+| 3.3.2 | Labels or Instructions | A | Inputs have labels or instructions. |
+| 3.3.3 | Error Suggestion | AA | When a fix is known, the error message suggests it (unless that would compromise security). |
+| 4.1.2 | Name, Role, Value | A | Every control exposes its name, role, states and values to assistive tech, and changes to them are announced. |
+| 4.1.3 | Status Messages | AA | Status messages (saved, loading, n results, errors that don't move focus) are announced by assistive tech without receiving focus, for example through `role="status"` or `role="alert"`. |
+
+**Not AA:** 2.4.13 Focus Appearance (a minimum size and contrast for the focus indicator) is level AAA in WCAG 2.2. A design system may adopt it as its own rule; say so, and don't present it as an AA requirement.
+
+**Removed:** 4.1.1 Parsing is obsolete in WCAG 2.2. Don't cite it.
+
+**Large text** in 1.4.3 means at least 18 point, or 14 point bold. On the web, that is roughly 24 CSS px regular or about 18.66 CSS px bold.
+
+## Keyboard patterns by component
+
+Follow the WAI-ARIA Authoring Practices Guide (APG) pattern for the component when one exists. Typical keys:
+
+| Component | Native element first | Keys |
+|---|---|---|
+| Button | `<button>` | Enter and Space activate |
+| Link | `<a href>` | Enter activates |
+| Checkbox | `<input type="checkbox">` | Space toggles |
+| Toggle / switch | `<button aria-pressed>` or `<input type="checkbox" role="switch">` | Space toggles (Enter too, for a button) |
+| Radio group | `<input type="radio">` in a `<fieldset>` | Tab into the group, arrow keys move and select |
+| Text field | `<input>` / `<textarea>` with `<label>` | Standard text editing; Enter submits the form for a single-line input |
+| Select | `<select>` | Native behaviour; build a custom listbox or combobox only if `<select>` can't do the job |
+| Tabs | APG Tabs pattern (`tablist`, `tab`, `tabpanel`) | Tab into the tab list, arrow keys between tabs, Tab into the panel |
+| Modal dialog | `<dialog>` opened with `showModal()`, or `role="dialog"` with `aria-modal="true"` | Focus moves into the dialog on open, Tab cycles inside, Esc closes, focus returns to the trigger on close |
+| Menu button | APG Menu Button pattern | Enter, Space or Down opens; arrow keys move; Esc closes and returns focus |
+| Toast | `role="status"` (or `role="alert"` for urgent errors) | Doesn't take focus; any action in it must be reachable another way, or the toast stays until dismissed |
+
+## Token naming
+
+Specs name tokens; they never contain raw values. A common shape is `category.property.variant.state`:
+
+- Colour: `color.background.default`, `color.text.subtle`, `color.border.focus`, `color.border.danger`
+- Space: `space.100`, `space.200` (a scale, not pixel names)
+- Size and shape: `size.target.min`, `radius.medium`, `border.width.default`
+- Type: `font.body.md`, `font.label.sm`
+- Motion: `motion.duration.short`, `motion.easing.standard`
+
+Use the system's own names when they are given. When proposing a token, tag it `[proposed token]` and list it in open questions, because adding a token is a design system decision, not a component one.

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

@@ -0,0 +1,74 @@
+# Component spec: {component}
+
+**Status:** draft · **Platform:** {web / iOS / Android} · **Token source:** {system name / brand.json / [proposed token]}
+**Assumptions to confirm first:** {list, or "none"}
+
+## Purpose and boundary
+
+- **Use it for:** {one sentence}
+- **Use something else when:** {one sentence, naming the other component}
+
+## Anatomy
+
+| # | Part | Required | Notes |
+|---|---|---|---|
+| 1 | {container} | yes | |
+
+## Variants
+
+| Axis | Values | When to use each |
+|---|---|---|
+| Emphasis | {primary / secondary / tertiary} | {} |
+| Size | {sm / md / lg} | {} |
+
+## States
+
+| State | Visual change (by token, by part #) | Cursor | Announced by assistive tech |
+|---|---|---|---|
+| Default | | | |
+| Hover | | | (nothing) |
+| Focus | | | |
+| Active / pressed | | | |
+| Disabled | | | |
+| Error | | | |
+| Loading | | | |
+
+## Tokens
+
+| Part # | Property | Token | Notes |
+|---|---|---|---|
+| 1 | background | `{color.background.default}` | |
+
+## Behaviour
+
+- **Trigger and result:** {}
+- **Overflow, truncation, wrapping:** {}
+- **Responsive:** {}
+- **Timing:** {debounce, auto-dismiss, animation}
+
+## Content rules
+
+- {label length budget, case, verb-first, never …}
+
+## Accessibility
+
+- **Native element / role:** {}
+- **Accessible name:** {how it's computed}
+- **States → ARIA:** {aria-invalid, aria-describedby, aria-busy, …}
+- **Keyboard:** {key → action}
+- **Focus:** {on open / close / error}
+- **Contrast and size:** {text 4.5:1, non-text 3:1, target 24×24 CSS px}
+- **Announcements:** {live region / status message}
+- **WCAG 2.2 criteria:** {numbers and names from reference.md only}
+
+## Do / don't
+
+| ✅ Do | ❌ Don't | Why |
+|---|---|---|
+| {} | {} | {} |
+
+## Open questions for engineering
+
+| Question | Blocks |
+|---|---|
+| {} | {decision} |

skilldrop_cli/data/packs/experience-design/skills/information-architecture/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: information-architecture
+description: Design the information architecture for a product or site — a content inventory grouped by how users think, labels in their words, a navigation model split into global, local and utility nav, an indented sitemap plus a Mermaid diagram, a label rationale table, the findability risks, and the card-sort or tree-test plan that would validate it. Use when the user wants a sitemap, IA, navigation structure, menu design, "reorganise our help centre", "where should this page live", or says users "can't find anything".
+---
+
+# information-architecture
+
+Produces the structure underneath the screens: what content exists, how it groups, what each group is called, and how people move between groups. The output is a sitemap someone can build navigation from, plus the test that would prove users can find things in it. Sits below `user-journey-map` (which says what people are trying to do) and above `content-design` (what one page says) and `ux-writing` (the exact strings). A structure nobody has tested is a hypothesis; this skill says so and ships the test.
+
+## How to respond
+
+1. **Get the inputs in one message.** Ask at most 2 questions, spent on the weakest of: *who the main audiences are and their top tasks*, and *what content exists today* (a page list, current menu, URL export, or feature list). Default everything else: web, desktop and mobile, existing content kept unless obviously dead. With no content list, build the inventory from what the user described and mark it `[inferred]`.
+
+2. **Inventory before structure.** List every content item or feature as a flat table: item, type (task, reference, marketing, account, legal), audience, and a status (`keep` / `merge` / `cut` / `[inferred]`). Grouping comes after the list, never before it. Why: starting from the old menu copies its mistakes into the new one.
+
+3. **Group by user task and mental model, not by org chart.** ✅ *"Get paid", "Manage your team", "Taxes"* — ❌ *"Finance Ops", "People Platform", "Compliance Team"*. Pick one organising scheme per level and say which: task, audience, topic, or object. Mixing schemes at one level ("Products", "For developers", "Pricing", "Help") is the most common IA defect; when audience-based top-level nav is unavoidable, say why and flag the overlap risk.
+
+4. **Label in the user's words.** Each group label is the term users would type into search or say aloud. Prefer short, concrete nouns or verb phrases; no internal product names unless users already know them; no "Solutions", "Resources" or "More" as a bucket. Record every label decision in the rationale table: label, what it holds, why this word, rejected alternatives, and the evidence (`[search logs]`, `[support tickets]`, `[interview]`, `[assumption]`).
+
+5. **Split the navigation model into three systems:**
+   - **Global nav** — 5–7 top-level items, present on every page. More than 7 means the grouping is not done.
+   - **Local nav** — the sections within one global area (sidebar, tabs, sub-menu).
+   - **Utility nav** — account, settings, help, search, language, sign out. Kept out of global nav.
+   Also name cross-links (related content that lives elsewhere) and the search role: search backs up navigation, it does not replace it.
+
+6. **Keep depth and breadth honest.** Default to 3 levels or fewer for anything users reach weekly. Put the top 3 tasks one click from the home or landing page. Flag every item that sits in two places (allowed for cross-links, not as two homes) and every group with one child (merge it up) or more than ~10 (split it).
+
+7. **Name the findability risks.** For each risk: the item, why users will look in the wrong place, the severity (🟥 top task affected / 🟧 frequent task / 🟨 rare task), and the mitigation (cross-link, rename, move, search synonym). Ambiguous labels, overlapping groups and items that fit two parents are the usual sources.
+
+8. **Write the validation plan** from [`reference.md`](reference.md): an **open or hybrid card sort** when the grouping or labels are unproven, a **tree test** when the structure exists and needs proving. The tree test gets 6–10 tasks written as user goals without the label words in them (✅ *"You were charged twice this month. Where would you go?"* — ❌ *"Find Billing"*), each with the correct destination and a pass threshold. State participants and what result would change the structure.
+
+9. **Emit with [`templates/ia-spec.md`](templates/ia-spec.md)** in one message: audiences and top tasks, inventory, organising scheme per level, the indented sitemap tree, the Mermaid diagram, the nav model, the label rationale table, findability risks, and the validation plan. Hand-offs: page-level content for a key page → `content-design`; menu and button strings → `ux-writing`; requirements for a new section → `prd-draft`. See [`examples/payroll-app-nav.md`](examples/payroll-app-nav.md).
+
+**Non-interactive runs** (subagent, CI, headless): a missing content list becomes an `[inferred]` inventory and missing audiences become `[assumption]` lines at the top. If neither the product nor its content can be identified from the input, emit `BLOCKED: need the product and its content or features` and build nothing.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — organising schemes, card sort and tree test methods, participant counts, metrics and pass thresholds, label tests
+- [`templates/ia-spec.md`](templates/ia-spec.md) — the IA spec skeleton: inventory, tree, Mermaid, nav model, rationale and risk tables, validation plan
+- [`examples/payroll-app-nav.md`](examples/payroll-app-nav.md) — worked example: a cluttered payroll app menu restructured around tasks
+
+## Quality bar
+
+- **The inventory exists and comes first.** Every item in the sitemap traces to an inventory row; every `cut` is listed, not silently dropped.
+- **One organising scheme per level**, named. Mixed schemes are flagged with the reason.
+- **Labels are user words with a recorded reason.** Every global and local label appears in the rationale table with its evidence tag.
+- **Global nav has 5–7 items; utility items are not in it.**
+- **Top tasks are one click from the landing page** and depth is 3 levels or fewer for weekly tasks, or the exception is stated.
+- **The tree and the Mermaid diagram match** node for node, and the Mermaid renders.
+- **Findability risks are named with severity and a mitigation.**
+- **The validation plan has tasks written without label words**, correct destinations, a threshold, and what result would change the design.
+- **Nothing is invented.** Content items, audiences and evidence not in the input are tagged `[inferred]` or `[assumption]`.
+
+## When to use this skill
+
+- ✅ A new product, site, app or help centre needs a sitemap and navigation
+- ✅ "Users can't find anything" — restructuring an existing menu or content set
+- ✅ Merging two products or sites into one navigation
+- ✅ Deciding where a new feature or section should live
+
+## When NOT to use this skill
+
+- ❌ The steps and emotions of one persona reaching an outcome — that's `user-journey-map`
+- ❌ What one page should say and in what order — that's `content-design`
+- ❌ The exact wording of menu items, buttons and errors across a flow — that's `ux-writing`
+- ❌ The requirements and scope of a new feature — that's `prd-draft`
+
+## Anti-patterns to avoid
+
+- ❌ **The org chart as navigation.** Groups named after the teams that own them. Users don't know your teams.
+- ❌ **"Resources", "Solutions", "More".** A bucket label means the grouping stopped before it finished.
+- ❌ **Redrawing the old menu.** Skipping the inventory and rearranging the existing items keeps every old overlap.
+- ❌ **Two homes for one item.** An item that lives in both "Settings" and "Team" will be maintained in one and stale in the other. One home, cross-links elsewhere.
+- ❌ **Search as the fix.** "They can search for it" hides a structure problem; search logs full of nav-label queries are the symptom.
+- ❌ **Tree-test tasks that give away the answer.** "Find the Invoices page" tests reading, not findability.
+- ❌ **Presenting an untested structure as final.** Tag it a hypothesis and ship the test with it.

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

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Design the sitemap and navigation for our new customer portal",
+    "should_trigger": true
+  },
+  {
+    "query": "Users say they can't find anything in our help centre — restructure it",
+    "should_trigger": true
+  },
+  {
+    "query": "We're merging two products into one app; what should the main menu look like?",
+    "should_trigger": true
+  },
+  {
+    "query": "Where should the new invoicing feature live in our nav, and how would we test that?",
+    "should_trigger": true
+  },
+  {
+    "query": "Map the customer's journey from signing up to their first payroll run, with emotions and pain points",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a content spec for our pricing page: what questions it must answer and in what order",
+    "should_trigger": false
+  },
+  {
+    "query": "Write the button labels, error messages and empty states for the invite-a-teammate flow",
+    "should_trigger": false
+  },
+  {
+    "query": "Draft a PRD for adding a reporting section to the app",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/experience-design/skills/information-architecture/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "information-architecture",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Acme Learning runs a course platform for corporate training. The current top menu is: Home, Catalog, My Courses, Paths, Certificates, Live Sessions, Admin, Reports, Users, Groups, Integrations, Billing, Support, Community. Learners and their managers both use it; admins are a separate small group. Support says learners can't find their certificates and managers can't find team progress. Design the IA.",
+      "assertions": [
+        "A flat content inventory listing every current menu item with a keep/merge/cut status appears before any grouping",
+        "Each sitemap level names one organising scheme, and any mixed scheme is flagged with a reason",
+        "Global nav has 5–7 items, and account, billing, support and similar items sit in utility nav, not global nav",
+        "The indented sitemap tree and the Mermaid diagram contain the same nodes",
+        "A label rationale table gives each global label a reason, rejected alternatives, and an evidence tag",
+        "Findability risks are listed with severity and a mitigation, including certificates and team progress",
+        "The validation plan is a tree test or card sort whose tasks do not contain the label words, each with a correct destination and a pre-set threshold",
+        "Does not invent user research, search data or content items not in the prompt; anything inferred is tagged [inferred] or [assumption]"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/experience-design/skills/information-architecture/examples/payroll-app-nav.md

@@ -0,0 +1,127 @@
+# Worked example — a cluttered payroll app menu, restructured around tasks
+
+## Input given to the skill
+
+> Our payroll app for small businesses (Northwind Pay) has a left menu that's grown to 14 items and
+> customers keep raising tickets asking where things are. Current menu: Dashboard, Run Payroll,
+> Employees, Contractors, Time Tracking, PTO, Reports, Tax Filings, Tax Forms, Benefits, Integrations,
+> Company Settings, Billing, Help. Most tickets are "where do I download W-2s" and "how do I add a
+> contractor". Users are business owners and office managers, usually not accountants.
+
+## Output
+
+# Information architecture: Northwind Pay
+
+**Status:** hypothesis, not yet validated · **Evidence level:** [assumption-based], with two ticket themes from the user
+**Assumptions to confirm first:** owners and office managers share one navigation (no separate admin area); contractors are paid through the same payroll run.
+
+### Audiences and top tasks
+
+| Audience | Top tasks (ranked) |
+|---|---|
+| Business owner / office manager | 1. Run payroll 2. Add or change a person 3. Get tax forms for employees [support tickets] 4. Approve time off |
+
+### Content inventory
+
+| # | Item | Type | Status | Notes |
+|---|---|---|---|---|
+| 1 | Dashboard | task | keep, rename "Home" | landing page |
+| 2 | Run Payroll | task | keep | top task |
+| 3 | Employees | object | merge with 4 into "People" | |
+| 4 | Contractors | object | merge into 3 | "add a contractor" ticket theme |
+| 5 | Time Tracking | task | keep, under "Time" | |
+| 6 | PTO | task | merge into "Time" | |
+| 7 | Reports | reference | keep | |
+| 8 | Tax Filings | task | merge with 9 into "Taxes" | |
+| 9 | Tax Forms | reference | merge into 8 | "download W-2s" ticket theme |
+| 10 | Benefits | task | keep | |
+| 11 | Integrations | account | move to utility (Settings) | set up once |
+| 12 | Company Settings | account | move to utility | |
+| 13 | Billing | account | move to utility | |
+| 14 | Help | utility | move to utility | |
+
+### Organising scheme
+
+- **Level 1:** task, with "People" and "Taxes" as objects users already name that way. Mixed on purpose: owners say "add someone to People" and "get my tax forms", so those words beat a verb phrase.
+- **Level 2:** object (the records inside each area).
+
+### Sitemap
+
+```
+Northwind Pay
+├── Home
+├── Payroll
+│   ├── Run payroll
+│   └── Payroll history
+├── People
+│   ├── Employees
+│   └── Contractors
+├── Time
+│   ├── Timesheets
+│   └── Time off
+├── Benefits
+├── Taxes
+│   ├── Filings
+│   └── Tax forms (W-2, 1099)
+├── Reports
+└── [Utility] Settings (Company · Integrations · Billing) · Help · Search
+```
+
+```mermaid
+flowchart TD
+    root["Northwind Pay"] --> home["Home"]
+    root --> pay["Payroll"]
+    pay --> run["Run payroll"]
+    pay --> hist["Payroll history"]
+    root --> ppl["People"]
+    ppl --> emp["Employees"]
+    ppl --> con["Contractors"]
+    root --> time["Time"]
+    time --> ts["Timesheets"]
+    time --> off["Time off"]
+    root --> ben["Benefits"]
+    root --> tax["Taxes"]
+    tax --> fil["Filings"]
+    tax --> forms["Tax forms (W-2, 1099)"]
+    root --> rep["Reports"]
+    root -.-> util["Utility: Settings · Help · Search"]
+```
+
+Global nav: 7 items (Home, Payroll, People, Time, Benefits, Taxes, Reports). Utility: 3.
+
+### Label rationale
+
+| Label | Holds | Why this word | Rejected | Evidence |
+|---|---|---|---|---|
+| People | employees and contractors | one place to "add someone", whatever their type | Team, Workforce | [support tickets] "add a contractor" |
+| Taxes | filings and forms | users search for the form, not the filing process | Compliance, Tax Center | [support tickets] "download W-2s" |
+| Time | timesheets, time off | covers both without jargon | PTO (acronym), Attendance | [assumption] |
+| Tax forms (W-2, 1099) | year-end forms | names the forms users ask for | Documents | [support tickets] |
+
+### Findability risks
+
+| Severity | Item | Why users will look elsewhere | Mitigation |
+|---|---|---|---|
+| 🟥 | Tax forms | Users may look under People (forms are per employee) or Reports | Cross-link from each employee record and from Reports; add "W-2" and "1099" as search synonyms |
+| 🟧 | Contractors | Some owners don't think of contractors as "People" | Show "Add employee or contractor" as one button on People |
+| 🟨 | Integrations | Moved out of global nav; rare but needed at setup | Link it from the Home setup checklist |
+
+### Validation plan
+
+**Method:** tree test of the sitemap above against the current menu · **Participants:** owners and office managers, unmoderated · **Threshold:** 70% success and 80% correct first click per task, set before running
+
+| # | Task (no label words) | Correct destination | Tests risk |
+|---|---|---|---|
+| 1 | Your employee asks for last year's form to file her personal return. Where do you get it? | Taxes › Tax forms | 🟥 Tax forms |
+| 2 | You've hired a freelance designer for three months. Where do you set them up to be paid? | People › Contractors | 🟧 Contractors |
+| 3 | An employee wants next Friday off. Where do you approve it? | Time › Time off | |
+| 4 | You want to connect your accounting software. | Settings › Integrations | 🟨 Integrations |
+| 5 | You need to check what you paid everyone last month. | Payroll › Payroll history | |
+| 6 | Your card on file has expired. | Settings › Billing | |
+
+**What changes the design:** task 1 below threshold with most first clicks on People → move Tax forms under People and keep a Taxes cross-link. Task 2 below threshold → split People back into Employees and Contractors.
+
+### Hand-offs
+
+- The Taxes landing page content → `content-design`
+- Menu labels, the "Add employee or contractor" button and empty states → `ux-writing`

skilldrop_cli/data/packs/experience-design/skills/information-architecture/manifest.json

@@ -0,0 +1,46 @@
+{
+  "name": "information-architecture",
+  "version": "0.1.0",
+  "description": "Design the information architecture for a product or site — a content inventory grouped by how users think, labels in their words, a navigation model split into global, local and utility nav, an indented sitemap plus a Mermaid diagram, a label rationale table, the findability risks, and the card-sort or tree-test plan that would validate it. Use when the user wants a sitemap, IA, navigation structure, menu design, \"reorganise our help centre\", \"where should this page live\", or says users \"can't find anything\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "content-design",
+    "prd-draft",
+    "user-journey-map",
+    "ux-writing"
+  ],
+  "handoff": [
+    {
+      "to": "content-design",
+      "when": "the structure is agreed and a key landing page needs its content",
+      "purpose": "Specify what that page must answer, in what order, in plain language.",
+      "fallback": "If content-design is absent, list the page's top 3 user questions in priority order under its sitemap node."
+    },
+    {
+      "to": "ux-writing",
+      "when": "the nav labels are settled and the menus and buttons need final strings",
+      "purpose": "Write the strings and a terminology list so the labels stay consistent.",
+      "fallback": "If ux-writing is absent, add a terminology list to the spec: each label, the one term to use, and the terms to avoid."
+    }
+  ],
+  "tags": [
+    "information-architecture",
+    "sitemap",
+    "navigation",
+    "ux",
+    "card-sort",
+    "tree-test"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Structured synthesis from a content list into groups, labels and a nav model against fixed IA practice. Grouping needs judgment, but the method and the validation plan bound it."
+  }
+}