Agent access guide

This vocabulary supports some claims with sources and leaves the rest as editorial work

entry.definition

This is the only field that paraphrases the cited sources. Every source carries an editorial check date and links to a fixed Internet Archive snapshot, or states plainly that no snapshot is confirmed.

provenance.editorial

This names every field that is editorial judgement: the boundary, the signature, the consider-when and use-caution lists, the tradeoff, the conditional rules, the query requirements, the relationships, the implementation note and the type extension.

rules[].strength

This is the editorial advice level. The basis field of the same rule names its evidence. Neither one is a proven fact or a hard constraint.

provenance.ordered

This field is always false, in an entry file and in a list file. A list is an editorial selection, and a seat number is a position, not a rank.

This site has run no user research and no complete assistive-technology certification.

You can fetch these files

In these paths, locale is zh or en, and an entry ID is the same in both languages. Every JSON file carries X-Robots-Tag: noindex and Access-Control-Allow-Origin: *, and stays out of the sitemap, so an agent in a browser can fetch it directly. This site offers no whole-vocabulary download.

You read an entry file like this

The outer level holds the wrapper fields. Under entry sits a verbatim copy of that catalog entry, with no field removed.

schemaVersion

The version of the wrapper format. A new field arrives in a minor version. A renamed or removed field needs a major version.

kind

The kind of file: entry, list, entry-index or list-index.

page self alternates

The web page for this entry, this file itself, and the JSON files for both languages.

site

The catalog version, the entry count, and the addresses of the index, the query API, this guide and llms.txt.

provenance.sourceBacked

The path of the one field that paraphrases the sources.

provenance.editorial

Every field path on this entry whose content is editorial judgement, named one by one.

provenance.scope

The evidence scope: definitions reference the sources, while specimens, advice, relationships and recipes are editorial.

provenance.specimenNote

The statement that specimens are original fictional interfaces.

provenance.editorialStatus

The editorial status of this entry.

provenance.sources[]

One citation card per source. The next paragraph explains the card fields.

provenance.lists[]

Which seats this entry holds in which editorial lists. An entry in no list carries an empty array.

In a citation card, checkedAt is the editorial check date. It is never the archive capture date. The two are separate fields, so you never have to infer one from the other. The field archive.status has three values:

available

A fixed snapshot is confirmed. Then archive.confirmed is true, archive.url is the snapshot address, and archive.capturedAt is the capture instant.

pending

An archive request was submitted, but no capture is confirmed.

unconfirmed

No capture is known.

For the last two values, archive.confirmed is false, archive.url and archive.capturedAt are both null, and only the date-scoped archive.lookupUrl is available. A submitted archive job is not a completed capture, and this site does not record it as confirmed.

You read a list file like this

Under list sits a verbatim copy of that catalog list. The seats array holds resolved seats in seat order. Each seat gives the name, the type, the page address and the JSON address of its entry.

provenance.ordered provenance.selection

The first is always false and the second is always editorial. A seat number is a position, not a rank.

provenance.seatOrigins

This explains the two seat origins: a seat from the list ledger in plan issue #1, and a seat filled by editorial judgement in this repository. The origin field of each seat points at one of them.

provenance.nominalSize provenance.seatCount provenance.filled

In order: the largest seat number across all lists, the seat count of this list, and whether the two are equal. A list that is not filled keeps its gaps and is never padded.

provenance.titleNote

This states that “Top” and “Trending” in the title are search conventions, not adoption or ranking measurements.

seats[].reason

This sentence says what the seat covers. It does not say why the seat ranks where it is.

You call the query API like this

The query API uses lexical matching with explicit constraints. It runs no language model and no vector search. It answers which entries match, which stay unresolved for a missing fact, and which are excluded and why.

The method is POST and the address is /api/query. The lang parameter selects en or zh. Without lang, the answer is Chinese. The body is one JSON object, and it accepts these seven fields only:

text

The search text, at most 1000 characters.

type

The entry type: visual, layout, interaction, micro, principle, philosophy or anti.

intent

The intent identifier, at most 1000 characters.

must

A capability the specimen must have verified: keyboard or reduced_motion.

avoid

Something to avoid: modal or motion.

facts

An object of boolean facts, keyed by measurable_progress, known_structure or short_field.

mode

Either select or audit. The value audit returns anti-patterns only.

An unlisted field, an unsupported value or a non-boolean fact answers 400 with one sentence of explanation. A body above 16 KB answers 413.

curl -X POST 'https://designvocabulary.com/api/query?lang=en' \
  -H 'content-type: application/json' \
  -d '{"intent":"track-progress","facts":{"measurable_progress":true}}'

The answer carries schemaVersion, locale, engine, mode and scope, plus the three arrays matched, unresolved and excluded. The value of engine is always lexical-with-explicit-constraints. Every candidate carries reasons for the group it landed in, and missingFacts for the facts it still needs.

{
  "schemaVersion": "0.1.0",
  "locale": "en",
  "engine": "lexical-with-explicit-constraints",
  "mode": "select",
  "scope": "Capability checks cover the local specimen ...",
  "matched": [{ "id": "determinate-progress", "reasons": ["..."], "missingFacts": [] }],
  "unresolved": [],
  "excluded": []
}

This site has these limits

• Retrieval is lexical matching with explicit constraints, and there is no semantic search. People maintain the synonym table by hand, so its coverage is incomplete.
• The request body stops at 16 KB. A larger body answers 413.
• The code holds no rate limit and needs no API key. This site runs no telemetry, keeps no accounts and charges nothing.
• This site offers no whole-vocabulary download. Complete coverage costs one fetch per entry file and per list file, from the indexes.
• This repository has no LICENSE file today, so the reuse terms are undefined. This page describes access, not rights to redistribute.

These identifiers stay stable

• An entry ID is the same in both languages, in every file and in every query result, and it does not change.
• The schemaVersion of the wrapper format is 1.0.0 today. A new field arrives in a minor version. A renamed or removed field needs a major version.
• The entry.version field of each entry records the version of that entry content.
• The site.catalogSchemaVersion field records the version of the catalog format.

You can continue from here

• llms.txt: the root discovery file, which lists every entry and list in both languages.
• entries/index.json: the entry table of contents, with identifiers and links only.
• lists/index.json: the list table of contents, with identifiers and links only.
• GitHub: every file on this site is generated from data/ in the repository, together with the build and check scripts.
• issue #75: the design discussion behind this agent access.