Skip to content

docs: add ADR 0015 — Figma component property naming convention - #5347

Merged
eddiman merged 2 commits into
mainfrom
docs/adr-0015-figma-component-property-naming
Aug 19, 2026
Merged

docs: add ADR 0015 — Figma component property naming convention#5347
eddiman merged 2 commits into
mainfrom
docs/adr-0015-figma-component-property-naming

Conversation

@eddiman

@eddiman eddiman commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

What

Adds ADR 0015 — Name Figma component properties by one internally consistent convention.

Numbered 0015 to stay clear of the ADR PRs already open: #5199 (0010), #5195 (0011), #5196 (0012), #5200 (0013), #5178 (0014).

Why

An audit of the whole EDS Core Components Figma library — 51 components, 210 properties — found 31% failing at least one mechanical rule:

  • The appearance axis had five names (Variant, Variants, Style, Type, Emphasis). Button carried two at once.
  • Type meant something different on all seven components using it.
  • Six spellings of two boolean values, one property mixing casing internally.
  • 17 properties declared but referenced by no layer — visible to every tool, doing nothing.
  • Two live properties on Button collapsed to the same identifier, separated only by a glyph that consumers strip.
  • The six inputs each named the same nine concepts differently — the typed value was Text area, including on Search and Select.

This matters because the library is increasingly read by machines — Code Connect, the Figma MCP server, codegen, AI tooling. Inconsistent names mean every consumer guesses and the mapping gets re-invented per component.

How

Title Case names plus one deterministic transform. Names and values are Title Case with single spaces; a single rule derives the code identifier — collapse the spaces, camelCase. Leading IconleadingIcon, High ContrasthighContrast.

Two framing points the ADR is explicit about:

  • Figma and code will never map 1:1. Figma needs pseudo-state axes, authoring presets and slot-visibility toggles that code has no equivalent for, and code has props Figma doesn't express. The mapping layer is permanent, not a gap to close.
  • Neither side simply follows the other. Design and implementation each move first at different times. So the ADR is about Figma being internally consistent, not about achieving parity.

The decision covers ten rules — casing and the transform, the five property types, decorator glyphs, uniqueness of derived identifiers, one canonical name per concept, value order as a functional property, mapping/Figma-only classification, not advertising unreachable states, the #id suffix, and property order as guidance only — plus a canonical glossary, the constraints Figma imposes, and how it gets enforced.

Two of the rules catch real defects, not style

  • Uniqueness. A slot and the boolean revealing it must not derive the same identifier. Leading Icon + Has Leading Icon, never Leading Icon + Leading Icon.
  • The property surface must not promise what doesn't exist. Checkbox exposed Checked and Indeterminate as independent booleans, advertising 32 combinations while implementing 24. It became Selection: Unchecked / Checked / Indeterminate.

Status

Applied to the library on a Figma branch already: 31% → 2 of 191 properties, and both remaining cases are deliberate Figma-only axes with no identifier to derive.

Relates to #4974

@eddiman eddiman linked an issue Aug 19, 2026 that may be closed by this pull request
3 tasks
@eddiman
eddiman requested a review from alexlvrs August 19, 2026 11:23
@eddiman
eddiman merged commit 3dd3429 into main Aug 19, 2026
16 checks passed
@eddiman
eddiman deleted the docs/adr-0015-figma-component-property-naming branch August 19, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Standardize Figma component property naming for AI-readability

2 participants