EDS Co-Author

A buddy skill for product engineers consuming the Earth Design System. It builds working, EDS-compliant JSX from a clear request — stating assumptions up front rather than stalling on questions — while enforcing EDS guardrails.

Core Principles

• Build-first. If the request is clear enough to produce something useful, build it. State your assumptions at the top of the reply. It's easier for the user to redirect from working code than from nothing.
• Docs first, source second. Always consult the local references/ (starting with references/llms.txt) before reading packages/core source. Never invent props or component names.
• Ask, don't guess — only when it matters. Ask before building only when the data shape is unknown, a meaningful design choice exists, or a referenced file isn't visible.
• Plan-gate big changes only. Multi-file work and migrations get a short plan + explicit go before editing. Single-file/small work is built immediately.
• Refuse guardrail violations. Surface and ask — never silently work around them.

Step-by-Step Workflow

Step 1 — Read project context

Before writing anything, orient:

• Check the target/related files and nearby EDS usage for conventions (import style, TS vs JS, local state patterns, file layout).
• Detect the mode:

Do not run pnpm install, framework detection scripts, or add dependencies — EDS is already wired in this monorepo.

Step 2 — Load EDS knowledge (strict lookup order)

Knowledge lives locally in this skill's references/ folder — generated from the EDS docs by pnpm --filter @adaptavant/docs generate. Read it with Read/grep; do not WebFetch earth.anywhere.co. Follow this order, stopping at the earliest source that answers the question:

1. references/llms.txt — entry map of foundations + every component with page links.
2. Component page — references/components/<name>.md. Props table, variants, deprecation notes.
3. Foundation page — references/foundations/<name>.md for color tones, spacing, typography.
4. Source at packages/core/src/components/<name>/ — only if docs are ambiguous about prop typing or runtime behavior. Use Read/grep (path is known — don't spawn Explore).

Rules: don't read source before docs; don't invent props/component names; if a needed component isn't in references/llms.txt, tell the user it may not exist in EDS yet and ask how to proceed. If references/ is missing, run pnpm --filter @adaptavant/docs generate to build it.

Step 3 — Decide: build now, or clarify/plan

• Small & clear (single file, request unambiguous): skip to Step 4 and build. State assumptions at the top of the reply.
• Ambiguous: ask 1–3 targeted questions via AskUserQuestion (skip any already answered). Then build.
• Big (multi-file or Migrate mode): show a short plan (≤10 lines): file(s) to change with full paths, EDS components grouped Layout (Box, Stack, Spacer) / Core (Heading, Text, Button, TextInput) / Icons (@adaptavant/eds-icons), any guardrail-driven before → after swaps, imports to add. End with:

> Reply go to apply, or tell me what to change.

Do not edit until the user replies go.

If any answer would force a guardrail violation, push back here — never carry it into the edit.

Step 4 — Build

Apply changes with Edit / Write following EDS build principles:

• Layout primitives, not nested Box. Reach for Stack / Grid / Spacer for structure; Box only when nothing semantic fits.
• Tokens, not raw values. Use EDS tone/variant/size/weight props and foundation tokens — never hardcoded colors, px, or hex.
• Forms structured correctly. Wire labels, inputs, help text, and error states through the documented field components — don't hand-roll <label>.
• Accessibility built in. aria-label on icon-only buttons, meaningful alt, semantic elements, labelled inputs.
• Abstract only on repetition. Extract a local component when a pattern repeats; don't pre-abstract single-use JSX.
• Match surrounding conventions (import grouping: EDS first, then local; TS/JS; existing state style).

Deliver complete, runnable code — no placeholders, no TODOs.

Do not: run pnpm install / typecheck / lint / tests, create .stories.tsx / .test.tsx, add changesets, or tidy unrelated code.

Step 5 — Report

One line: which file(s) changed, which EDS components were used, plus a 1–2 sentence note on any non-obvious design decision or stated assumption.

Guardrails (enforced)

Refuse to produce code that violates these. Raise conflicts in Step 3 — never work around them silently in Step 4.

1. No deprecated Icon / Symbol from @adaptavant/eds-core

No longer maintained. Import from @adaptavant/eds-icons instead, using icon names documented on earth.anywhere.co (don't invent names).

2. No className / classNames / style / styles overrides on EDS components

EDS components are styled via built-in props (variant, tone, size, weight, …). If built-in props can't express the need: stop, tell the user the EDS API doesn't cover it, and direct them to the EDS team — do not fall back to a style override. (Forwarding className to a wrapping non-EDS element the user owns is fine.)

3. No deprecated props

When reading a component's .md in Step 2, watch for strikethrough prop names and "⚠️ Deprecated" callouts. Never introduce deprecated props. If a deprecated prop is the only way, surface it and ask — don't use it silently.

Rules Summary

When NOT to use this skill

• Fixing a bug inside packages/core — use bug-fix-workflow.
• Writing a PR description — use pull-request-author.
• Reviewing someone else's PR — use pull-request-reviewer.
• Adding a new component to the EDS library — that's an EDS-maintainer task; this skill is for consumers.