Source-role taxonomy

Every input you give /extract-ds-skill falls into one of ten roles. The role decides how the source is read, how much it is trusted, and whether it can override another source.

Why the roles matter

The skill is not allowed to invent props, tokens, icons, or wiring. Every extracted rule has to cite a source by file:line or carry a [VERIFY] marker. That contract works only if the agent knows which sources to trust, which are only examples, and which to leave alone. The role is the answer.

When two sources disagree, the role hierarchy decides. Code beats docs. Types beat prose. A real consumer app beats a reconstructed example.

The ten roles at a glance

Role	Tag	Use it for
Design-system code	`[code]`	Prop signatures, types, behaviour
Asset package	`[code]`	Icon, logo, illustration inventory
Product or example app	`[code]`	Real-world wiring and patterns
Reference project	`[example:project]`	Verbatim wiring lift (provider, CSS, root attrs)
Internal AGENTS or CLAUDE files	`[code]`	Guidance the DS team already wrote for agents
Docs site	`[docs]`	"When to use", "common mistakes", citations
Docs:foundation	`[docs:foundation]`	Prose foundation rules extracted into `token/*`
Storybook	`[storybook]`	Composition examples
Figma	`[figma]`	Tokens and visual rules
Private or inaccessible	`[private-blocker]`	Logged as a soft blocker, not extracted

The roles in detail

Design-system code `[code]`

What it is: The package source: types file, component implementations, token exports.

Authority: Highest. Wins on conflict.

Notes: Joint-read with docs. This role also covers the DS's hosted component repo when it ships per-component machine-readable docs or story files. Those are raw-fetched per file and scoped to the proposing slate, never the full export surface. A separately published tokens repo falls into the same role.

Asset package `[code]`

What it is: Icons, logos, illustrations shipped as a separate package (for example heroicons, geist-icons).

Authority: High for inventory questions ("does this icon exist?").

Notes: Treat the package exports as the inventory. Do not invent icon names because they "feel like" they should exist.

Product or example app `[code]`

What it is: A real consumer of the DS (a marketing site, a dashboard, an internal tool).

Authority: The best source for wiring: provider mount, font setup, globals CSS, install scripts.

Notes: Copy wiring verbatim from here when available. Reconstructing wiring from memory is one of the most common silent-fabrication failures.

Reference project `[example:project]`

What it is: A real consumer app you supply as a URL or local path at Phase 1 input time, explicitly tagged for wiring extraction.

Authority: Authoritative for the wiring it shows.

Notes: Phase 2 auto-detects the framework (Vite, Next.js App, Next.js Pages, CRA), reads the root entry file, and lifts the provider mount, CSS imports, and root-element attributes verbatim. When no reference project is supplied and a [docs:foundation] URL is in scope, the Setup section falls back to the verbatim docs setup snippet.

Internal AGENTS or CLAUDE files `[code]`

What it is: Guidance the DS team has already written for agents working with their system.

Authority: Inherit liberally. Cite by file:line.

Notes: If the DS team has already encoded "always wrap inputs in FormControl", do not re-derive it. Quote it.

Docs site `[docs]`

What it is: Prose-and-example documentation.

Authority: Useful for "when to use" and "common mistakes". Lower authority than types on prop signatures.

Notes: Cited, not extracted. Foundation pages are the exception (see next role). Hard rule: when a live docs site exists, crawl the live site. Do not crawl its archived backing repo.

Docs:foundation `[docs:foundation]`

What it is: Specific prose foundation pages on the DS docs site (colour systems, dark mode, theming, spacing) that you want extracted into token/* rules, not just cited.

Authority: Opt-in. You name the URLs. The skill crawls each accepted root depth-1 within its path prefix.

Notes: Phase 2 iterates the union of accepted and crawled URLs via WebFetch. It extracts five prose rule shapes (token-pairing, mode-aware, contrast-minimum, semantic-role, fallback-element) and writes one file per source URL under references/foundations/<slug>.md. Wiring is never extracted from foundation prose. Wiring comes from a reference project or the docs setup snippet.

Storybook `[storybook]`

What it is: Standard variant examples.

Authority: Useful for composition examples. Not always authoritative on prop names if the stories lag the package.

Notes: A JS-rendered Storybook catalog that a plain fetch cannot read is not a valid input. The story content lives as source in the component repo. Fetch that via [code] instead.

Figma `[figma]`

What it is: Design-time source.

Authority: Use for tokens and visual rules.

Notes: Never use for prop names or API contracts. Figma layer names are not React APIs.

Private or inaccessible `[private-blocker]`

What it is: A repo, package, or docs URL the skill cannot read (private GitHub, paywalled package, unreachable host).

Authority: None, but logged rather than ignored.

Notes: Recorded in the discovery summary tagged [private-blocker]. The run proceeds with whatever is accessible. Inputs that may become available later are soft blockers. Inputs you fabricated from memory are hard ones.

The default input shape for a public DS

Most public design systems fit one shape: a component repo, a tokens repo (sometimes part of the component repo), a live docs site, and an optional reference project. That maps to:

[code]            @acme/ui                       # component repo
[code]            @acme/tokens                   # tokens repo (or part of @acme/ui)
[docs]            https://acme.dev/docs          # live docs site
[docs:foundation] https://acme.dev/docs/colors   # opt-in extraction
[example:project] apps/marketing/                # opt-in wiring lift

A local wrapper surface (an in-house ds/components/*.tsx layer over an upstream package) is still supported. It is no longer the assumed primary shape.

The conflict-resolution rule

Joint-read code and docs. Code wins on conflict. A docs page that claims a prop the types file does not export is a docs bug. Log the divergence in the discovery summary so the DS team can fix it. Do not extract the phantom prop.

Two scope rules that ride alongside the taxonomy

Copy rules route out. Title Case button labels, action-oriented placeholder phrasing, microcopy style. These are recognised during extraction but never written into a DS skill. They show up in the discovery summary as candidates for a sibling copy skill.
Design-craft ships verbatim. Generic taste guidance (layout, hierarchy, typography, colour, spacing, motion, interactive states, anti-slop restraint) is copied byte-for-byte from the meta-skill into every produced skill as references/design-craft.md. It is static material, not extraction output. The DS always wins on conflict.

What to take away

Roles decide what gets read and how much it is trusted.
[code] beats [docs]. Types beat prose. A real app beats a reconstructed example.
[docs:foundation] and [example:project] are opt-in. They unlock prose-rule extraction and verbatim wiring lift.
[private-blocker] is a soft blocker. The run continues with what is reachable.
Copy and craft never enter the DS skill. Copy routes to a sibling skill. Craft ships verbatim from the meta-skill.

Primary source: .claude/skills/extract-ds-skill/SKILL.md, Source-role taxonomy section. The fuller taxonomy and the per-role nuances live in references/discovery.md.

Source-role taxonomy

Why the roles matter

The ten roles at a glance

The roles in detail

Design-system code [code]

Asset package [code]

Product or example app [code]

Reference project [example:project]

Internal AGENTS or CLAUDE files [code]

Docs site [docs]

Docs:foundation [docs:foundation]

Storybook [storybook]

Figma [figma]

Private or inaccessible [private-blocker]