EDS Usage Audit

A linter-style skill for product engineers consuming the Earth Design System. It scans a file or directory, flags anti-patterns and a11y violations against a fixed rule catalog, and hands remediation off to co-author. No edits.

Core Principles

• Docs first, source second. Always consult earth.anywhere.co/llms.txt before reading packages/core. Never invent rules.
• Audit, don't edit. This skill never calls Edit or Write on consumer code. It reports.
• File-by-file, line-precise. Every finding cites path:line and the offending snippet.
• Severity, not noise. Findings come from the rule catalog below. No style nits outside the catalog.
• Hand off remediation. End every report with a pointer to the co-author skill.

Step-by-Step Workflow

Step 1 — Resolve scope

Determine what to audit:

• If the user named a file or directory, use that.
• If the user said "this file" while pointing at an open file in context, use that file.
• If the scope is ambiguous, ask once via AskUserQuestion — present the candidate file(s) you inferred plus an "Other" option.
• Refuse whole-repo scans unless the user explicitly confirms ("yes, the whole app").

Filter out non-EDS files up front: a file is in scope only if it imports from @adaptavant/eds-core or @adaptavant/eds-icons.

Step 2 — Load EDS knowledge (strict lookup order)

Same order as co-author. Stop at the earliest source that answers the question.

1. https://earth.anywhere.co/llms.txt — fetch with WebFetch. Map of foundations + every component with .md links.
2. Component .md page — https://earth.anywhere.co/components/<name>.md for each EDS component the target files import. Note: deprecated props (strikethrough or "⚠️ Deprecated"), accessibility props (accessibilityLabel, title, etc.), and required wrappers (Field, Root).
3. Foundation .md page — https://earth.anywhere.co/foundations/<name>.md for token names (color tones, spacing, typography).
4. Source at packages/core/src/components/<name>/ — only if docs are ambiguous about prop typing or runtime behavior. Read directly; do not spawn an Explore agent.

Rules:

• Do not read source before docs.
• Do not invent rules. If a behavior isn't documented and isn't in this skill's catalog, it isn't a violation.

Step 3 — Scan

For each file in scope:

1. Read the file with Read.
2. Walk the rule catalog (EDS001–EDS012, A11Y001–A11Y010). For each rule, apply its detection heuristic. Use Grep for repo-wide patterns where it's faster than re-reading.
3. Record findings as { file, line, rule, severity, snippet, suggested_fix }. Snippet is the literal offending text, trimmed to one line.
4. De-duplicate: if the same line triggers two overlapping rules (e.g. EDS006 + A11Y004 on a raw <input>), keep the higher-severity rule and reference the other in the suggested fix.

Step 4 — Report

Print findings grouped by file in this exact format:

EDS Usage Audit — <relative/path/to/file>

| Sev | Rule    | Line | Snippet                            | Suggested fix                          |
|-----|---------|------|------------------------------------|----------------------------------------|
| C   | EDS001  | 3    | <literal snippet>                  | <one-line fix>                         |
| H   | EDS004  | 42   | …                                  | …                                      |

Summary: <n> critical, <n> high, <n> medium, <n> low.

Severity letters: C (critical), H (high), M (medium), L (low).

If a file has zero findings, say so on one line: <path>: clean.

After all per-file tables, print one global summary line with the totals across all files.

Step 5 — Hand off

End with exactly one sentence:

Run the co-author skill on this file to apply the suggested fixes.

Do not call Edit, Write, or any other mutating tool on consumer code. The skill ends here.

Detection rules catalog

EDS rules

HTML accessibility rules

These catch a11y violations that EDS components prevent when used correctly — raw HTML or misused EDS components bypass the system's built-in guarantees. Before flagging, cross-check the component's .md page on earth.anywhere.co/components/<name> for component-specific a11y props (e.g. accessibilityLabel, title) — those satisfy the rule.

Guardrails (enforced)

The skill refuses to do any of the following:

1. No file edits. This skill never calls Edit, Write, or NotebookEdit on consumer code. Detection only.
2. No invented rules. A finding must trace to a rule in the catalog above. Don't flag style preferences, code-organization opinions, or rules pulled from training data.
3. No unreproducible findings. Each finding's snippet must be present at the cited path:line and must satisfy the rule's stated detection heuristic.
4. No whole-repo scans without confirmation. If scope is unclear or huge, ask before walking.
5. No remediation in-skill. When the user asks "fix it," respond by directing them to the co-author skill.

Rules Summary

When NOT to use this skill

• Authoring or migrating EDS code — use co-author.
• Fixing a bug inside packages/core itself — use bug-fix-workflow.
• Reviewing a teammate's PR — use pull-request-reviewer.
• General code review unrelated to EDS — use code-review.