Refine labels and descriptions for field types

I think that it would be good if we can consider the "File upload" group, which can be a bit confusing for users. The File and Image field types were separated for a long time, but now they are groupped together with a Label/Description that does not mention Images at all. I know that now there is also a Media field, which is preferred, but for example for migrating D7 users this concrete groupping can be a bit non-intuitive.

The file upload group was created based on a card sort exercise we ran earlier this year. The results we got from there were pretty clear that people tend to map both image uploads and file uploads together. That said, Media was a challenging one; some people listed it under reference and some people listed it under file upload. That's why we decided to move it to the main level to try to address this challenge.

One of the use cases we tested as part of the usability testing was image and media fields because we had similar concerns that it might not be intuitive. However, both existing and new users were able to find the fields and we didn't find any challenges with the current sorting so we decided to proceed with that.

We should decide also whether to use full stop for bullet points. This was raised as feedback in #3401464: Date range should be in the date_time category.

Plain text
Current: Text field that does not support markup.
Proposed: Text field without markup support.

Formatted text
Current: Text field with markup support and optional editor. ✅

Number
Current: Field to store number. I.e. id, price, or quantity.
Proposed: Field to store a number value.

Reference
Current: Field to reference other content. ✅

Media
Current: Field to reference media. Allows uploading and selecting from uploaded media.
Proposed: Field to reference media of any type.

Allows uploading and selecting from uploaded media.

Only if Media Library is enabled, which will not always be the case.

File upload
Current: Field to upload any type of files.
Proposed: Field to upload a file of any type.

Selection list =>> Select list
Current: Field to select from predefined options. ✅

Date and time
Current: Field to store date and time values. ✅

Boolean
Current: Field to store a true or false value. ✅

Comment
Current: This field manages configuration and presentation of comments on an entity.
Proposed: Field to manage the configuration and presentation of comments on an entity.

Email
Current: Field to store an email address. ✅

Link
Current: Stores a URL string, optional varchar link text, and optional blob of attributes to assemble a link.
Proposed: Field to store a URL string.

Telephone number =>> Telephone (as the 'Email' field is not 'Email address')
Current: This field stores a telephone number.
Proposed: Field to store a telephone number.

I agree with #3, for me the images/file thing was a hard stop for some hours.

It was not very clear to me if image fields are references or uploads (and there is a bug in the UI (#3415799) right now that makes it undiscoverable through try & error clicking in the UI).

After the usability meeting #3388943: Drupal Usability Meeting 2023-09-29 I've started a Google sheet based on the discussions during the meeting, did some additional testing of my own, and discussed the matter at the Drupal Dojo Austin twice. But I haven't posted it yet because the draft wasn't anywhere near finished and I haven't found any time revisiting the issue since then. But used the time over the Global Contribution Weekend and the following days to get to a rough draft as well as write up this comment summarizing the outcome.

In regards of the question raised in #5, I would say it depends on the bullet points. If they are full sentences use the ending punctuation, in case they are no complete sentence then don't use the ending punctuation - that would be my rule of thumb.
As in case of the options bullet points should provide an easy to scan overview to the user. I would vote to go with the no complete sentence variant, therefore no periods at the end. And the goal should be to make the bullet points as concise and skim-able as possible imho.

About #3 and #7. I had a similar experience like @hudri, at one point I needed to test something in regards of images and had a really hard time figuring out that images are actual within File upload - completely unexpected. Due to the term File in File upload I haven't associated the group with images at all.
And at first I also agreed with @lauriii in #4 that media is tricky to sort because it would fit into reference as well as file upload. But on second thought, and after investigating more into how File, Image, and Media reference fields function, I now think there might be another option. Move Media into the currently called File upload group. All three field types are reference fields (also see /admin/help/media) and all three provide the ability to upload an asset. In regards of the micro copy File upload was closely linked semantically to the File option, the reason Image was unexpected for me to find there. By renaming File upload to the more generic term Upload it would wrap the File, Image, and Media field types nicely. And by referencing the term media in the description of the group Upload it would also be taken care of that the context for Upload clearly is Media related.

The observations in regards of the microcopy:

Step 1 - Field type descriptions:

1. The label Choose a type of field could be shortened to Choose a field type
2. In most of the descriptions the front loaded phrase "Field to" is sort of redundant plus the term field should ideally be avoided if possible since the overall context is already set by the page title.
3. Another redundancy is between the title and the description. If you strike cases of "title", "field to", "field", and related from the description most often there is not much extra information left. A detail that was raised during the Drupal Dojo in Austin.
4. In regard of readability and plain language, latin as well as abbreviations should be avoided. One example is "i.e." in the description for the number field type.
5. Not directly micro copy related, but I've noticed it is sort of difficult to distinguish from the list of available options what is a group and what is a field. There is neither a visual nor a micro copy based cue. Might be helpful for people exploring the options, under which option you get to a list of field type options and under which you get to the field settings of the chosen field type.

Step 2 - Field type options:

1. The label Choose an option below is using directional language, instead simply Choose an option could be used. Technically Choose a field type would be more accurate her as well?
2. The readability of the option labels is sort of challenging. First you have the redundant field type label and then the information of interest wrapped in parenthesis. A potential fix might be to remove the label and the wrapping parenthesis and front load aka more or less reverse the order of the content in parenthesis. For example Text (formatted, long) becomes Long formatted. Or another option might be instead of removing the label outside the parenthesis to append it at the end so you would get Long formatted text. But the overall context is already set in the page title or dialog modal title so that "probably" would not the best choice and introduce another redundancy.
3. The order, style and components of bullet points differ across options. Not sure if it is a good idea to start off with what a field is ideal for as the first bullet point as not even all options contain it. How about the following order, provide an outline about noteworthy characteristics/details for an option, then an example (same like "ideal for" there aren't examples for every option), and then at the end what the field type is ideal for? Instead of providing an example, one idea and feedback that was brought up during the Drupal Dojo Austin, was to provide what would be the corresponding html tag that the chosen field type creates/puts out (problem with that suggestion, that information would be available and make sense only for a few of the available options). In combination with the points listed in step 1.2 and 1.3 it was considered challenging to immediately know which field to pick when building the fields for a content type.
4. One detail I've noticed while going through all field types for the draft Number (decimal) doesn't communicate in anywhere that the maximum precision is at 32 and scope at 10. You only get informed about that detail by an error message after you've tried to enter a bigger value on its field settings page. I've added a bullet point about that to the Number (decimal) option in the draft. But it might be also a good idea to add that information to the descriptions for precision and scale on the field settings page as well in a follow up?
5. The description for File upload and Media currently has two flaws. For one with #3397711: Move label and machine name fields to the field config edit form only File upload will have three steps with the description on the second step. And in general that description would be way more useful to the user before making the decision if File upload or Media is the right choice, not after the initial decision was drawn and the user already moved onto step 1. Perhaps it might make sense to remove the description from step 2 entirely. I've tried to spread the relevant information to the descriptions in step 1 and the descriptions for the corresponding options in step 2. Plus as noted in the other issue #3397711-16: Move label and machine name fields to the field config edit form it might make sense to add a description pointing to a to be created help topic providing an overview of all available field types and when to use which field type best on top of the page right before the Choose a type of field.
6. The Reference options might be considered to be removed. For one none of the options has any information with bullet points. Each of the options only stands for a different preselected referenced entity on the field settings edit form. Aside that there is no real apparent difference between the four. Plus the Other option references the same preselected option that Content also does. Content and Other are practical identical configuration wise. And the term Other is way too generic and meaningless. One option might be to at least rename Other to something like Custom. But the more reasonable approach might be to remove all four Reference options as initially suggested. Or is there a detail I've missed about those Reference options?
7. The examples provided for the three Selection list options are outdated, they are only suitable for the old UI that contained a textarea. The UI has fields in place instead now and the instructions for the old text area UI pattern therefore increase the cognitive load and create potential confusion how to apply those examples. In addition, in the current form the examples are challenging to skim and comprehend for screenreader users.

The link to the aforementioned Google sheet is: https://docs.google.com/spreadsheets/d/1Lx7L40eRHotr5KQGn6au5WxQO3lFv19a...
Everyone with the link has editor permissions. I've created a sheet for each step. On top of each sheet there is the list of potential issues listed in this comment. For the first step the first two columns, for the second step the first column contains the current state of the micro copy. The columns right next to them contain suggestion. I've copied the suggestions in #6 by @chris-matthews into a dedicated column on the Step 1 - Field type descriptions sheet. Having more than a single column for the draft has the advantage that you are able to spot any consistency and redundancy related issues easier across the spreadsheet, and having dedicated columns for the different suggestion makes it easier to get inspiration and iterate faster instead of getting the older version replaced on every iteration.

And I've also added the issue to the shortlist for one of the next usability meetings. Last Friday we haven't had time to get to it unfortunately.

Usability review

We discussed this issue at #3417104: Drupal Usability Meeting 2024-02-02. That issue will have a link to a recording of the meeting.

For the record, the attendees at the usability meeting were @benjifisher, @duncancm, @rkoller, @shaal, @simohell, and @worldlinemine.

We've covered only Step 1 - Field type descriptions<code> and agreed to iterate asynchronously on that step as well as do the same for the second step <code>Step 2 - Field type options. A few takeaways from the discussion about step 1:

• In general the group was in line with the problems and draft I've posted. But the consensus was to shorten draft of the descriptions further and drop even the front loaded verbs. That way the descriptions would be briefer and no full sentences anymore, therefore the period at the end cloud be dropped as well.
• One detail raised in the context of text fields was the idea to combine plain text and formatted text. In case a user isn't clear about the difference one might end up in the wrong group. With a combined group for text fields all available options for plain and formatted text would be available in the second step.
• One suggestion that was brought up, for inspiration taking a look how other CMSes describe their fields (the examples that were raised during the meeting for WIX and Contentful don't describe the functionality but simply provide examples instead). I still have many test sites installed from the navigational hierarchy spreadsheet https://docs.google.com/spreadsheets/d/1o8JV3Qck92mV3CtoGdiRdqeRiW2L3Jk6... . I 'll investigate over the weekend if i am able to find and come up with more examples to compare with.
• Another suggestion that was brought up was to use ChatGPT and or Bard. It was clarified that none of these LLM based strings should be used as is. They should solely provide some sort of different perspective and provide inspiration. @worldlinemine already added the examples for the field type label and the field type description for Bard in column F & G on Step 1 - Field type descriptions
• In the context of the Media field type @simohell provided the sheet for the field classification exercise https://docs.google.com/spreadsheets/d/15AtAgvHaYZ1FfjpGNpuRctZDsIRuCp1DQV6hoi9YqTI/edit#gid=0 (. We haven't really discussed the problem of the sorting of the Media field type but the need for a clarification raised here is in line with the comments in this issue as well as the points i've made in step 2.

Odd, I've uploaded the screenshots for Wix and Contentful already in the previous comment but somehow the two files weren't available in the files fieldset. And after posting only the wix.jpg got upload. Instead of editing the previous comment I'll add a new and add the images here as an addition to #3370326-9: Refine labels and descriptions for field types

Adding a new field in Wix:

Choose a field type in Contentful:

Adding related issues that cover part of the topic here, when we started this discussion in the realm of Media/File/Image fields and the confusion this generates:

#2862458: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing
#2930446: [PP-1] Improve field description texts for fields provided by core

Also wanted to point out that a media field can be used for remote video content (a Youtube video for example). In this case, the "Upload" term isn't quite a good fit, IMO. On the other hand, some sites might have the option to store the videos "locally", instead of relying on a 3rd party service, in which case it would make sense to "upload" a video file into a media field.

Changed the parent issue to #3346539: [Plan] Improve field creation experience,which is still active, in contrast to #3356894: Make field selection less overwhelming by introducing groups which is closed and fixed. for a while now. otherwise this issue might slip through.

Usability review

We discussed this issue at #3481737: Drupal Usability Meeting 2024-10-25. The link to the recording of the meeting is https://youtu.be/yuaPVd6Lgv0. For the record, the attendees at the usability meeting were @avani.bhut, @benjifisher, @rkoller, @rosendofig, @shaal, @simohell, and @worldlinemine.

And we have discussed this issue another time at #3495184: Drupal Usability Meeting 2025-01-03. That issue will have a link to a recording of the meeting. For the record, the attendees at todays usability meeting were @benjifisher, @rkoller, and @simohell.

In both meetings we’ve continued the wordsmithing of the micro copy for the field type options in the second step of the field creation flow. The work in progress can be found in column C in the spreadsheet (https://docs.google.com/spreadsheets/d/1Lx7L40eRHotr5KQGn6au5WxQO3lFv19a...). We plan to continue reviewing the current draft found in column B/D in the upcoming meetings in case no other issues come up.

At #3497184: Drupal Usability Meeting 2025-01-10, we continued work on the spreadsheet (see Comment #13). For the record, the attendees at the usability meeting were @benjifisher, @rkoller, and @simohell.

We continued the word-smithing at #3498619: Drupal Usability Meeting 2025-01-17: @aaronmchale, @benjifisher, @rkoller, @simohell, and @worldlinemine.

We continued the word-smithing at #3500411: Drupal Usability Meeting 2025-01-24: @benjifisher, @rkoller, @simohell, and @worldlinemine.

@rkoller, @worldlinemine, and I continued the word-smithing at #3503484: Drupal Usability Meeting 2025-02-07.

The draft of the MR is a work in progress, reflecting proposed changes we've discussed over the course of several ux meetings. The MR is not complete and ready for review yet - we plan to finalize the MR in the coming weeks. We've considered it helpful at this point being able to see all the changes in context. A few remarks:

• So far i've only added the discussed changes for the available field group options, but all those changes also rely on changes on the h1. At the moment the first two steps are just called Add fields across all field types and field groups. #3386762: Use modals in field creation and field edit flow has to get in first for that. After that the proposed changes for the h1 on second step could be added as well.
• While making the changes for the MR I've noticed that the changes on the field type/field group labels also entail necessary changes in help texts and tests. But those changes should happen after a final consensus was reached about the micro copy. Leave it here as a reminder.
• It has to be noted that at this point the description for every option available for the reference field group has an identical description defined in EntityReferenceItem.php. That way it is impossible to provide some sort of guidance to the user what the actual difference between the different reference options actually is and which option to pick in which scenario. So we probably need a separate issue to add the ability to provide individual descriptions for the different reference options.
• The file upload field group currently has no description yet and is still using the pattern starting with "field to..." we've removed on the description for every other field type and field group. But the entire question how to deal with the media field type is out of the scope for this issue and complicates everything. @benjifisher already opened #3500553: Add media reference to the same field type group as file and image a few weeks back - the general discussion and work should happen there.

We continued the discussion at #3505028: Drupal Usability Meeting 2025-02-14: @benjifisher, @rkoller, @simohell, and @worldlinemine.

It turns out that Selection List is more complicated that I anticipated.

At #3506740: Drupal Usability Meeting 2025-02-21, we discussed the text for Selection Lists: @aaronmchale, @benjifisher, @simohell, @worldlinemine.

There is already a MR for this issue, so I am setting the status to NW.

I was afraid that getting different messages on the various Entity Reference fields would be difficult, but it is actually pretty easy. I added a commit. Now, we just have to decide on what text to use. Personally, I think none of the options should have description text except for Other.

We discussed the text for the Date and Time option at #3508130: Drupal Usability Meeting 2025-02-28: @benjifisher, @rkoller, @simohell, and @worldlinemine.

I rebased the MR. The only conflict was from #3497410: Fix DrupalPractice.Objects.GlobalFunction in hooks, which replaced t() with $this->t().

@rkoller:

On Slack, I said

My commit changes core/lib/Drupal/Core/Field/PreconfiguredFieldUiOptionsInterface.php. Just search for the classes that implement that interface and add a description key to getPreconfiguredOptions(). (Or search for that function.)

I was wrong. It is more complicated than that.

I just pushed a commit that implements the Usability team's recommendations for reference fields. I mostly followed the example of hook_field_ui_preconfigured_options_alter() in core/modules/field/field.api.php.

thank you! that is definitely beyond my skill level to figure out on my own :D will add the rest of the strings tomorrow. need to get some sleep first.

I've pushed the remaining changes we've discussed over the course of the last few weeks. The are still strings on the google sheet that still need to go in:

1. I was not sure how to add a help text to the second step for selection lists. the proposed microcopy for the help text is: Each list item has a Name, with limited formatting, and a Value. Values that are in use cannot be changed, since they are stored in the database. The Names can be edited later.
2. it has to be kept in mind that this issue needs additional work after #3386762: Use modals in field creation and field edit flow goes in, cuz at the moment the h1 on the page isnt changed and adjusted but it has to (and we also prepared suggestion for what could/should be used in the title of the dialog modal.

A few more details about the current state i've noticed applying the changes and going through the interface again:

• for some field groups there is the problem on the second step that the order of options is alphabetical but it would be better to order them in a different manner. for example for plain text the labels were text(plain) and text(plain, long), so short was first and the more complex second. with the new labels short text and long text, long text comes first.
• for the long text option for formatted text it might make sense to make a characteristic for text areas more explicit. short text states that text fields are oneliners while long text just says it uses text areas for input instead. it might be reasonable to clearly communicated that text areas are multi-line?
• I've removed the periods at the end of each bullet point on the reference field options. we havent used periods on the bullet points for any other fields.
• would it be possible to add a bullet point to the other reference field? it looks odd without any.
• on date and time field types it is not entirely clear what the examples refer to. are those the format date and time has to be entered or is it the example in what way dates and time are stored in the database - it might be misinterpreted.

The MR needs a rebase after #3386762: Use modals in field creation and field edit flow went in

I rebased the MR. One change that got lost is replacing "Choose an option below" with "Choose an option". I think that #3386762 changed it to "Choose a field type":

I think that is good.

I did not test much, but I did look at the Reference options, and I think our changes are still there.

Based on Comment #27, the status should still be NW.

Usability review

We discussed this issue at #3524868: Drupal Usability Meeting 2025-05-23. That issue will have a link to a recording of the meeting.

For the record, the attendees at the usability meeting were @benjifisher, @rkoller, and @simohell.

In todays meeting we've discussed the remaining questions in #3370326-27: Refine labels and descriptions for field types, the changes we've agreed on were already committed by @benjifisher and myself. To contain the scope we've created three followup issues:

• #3526383: [PP-1] Add the option to customize the order of field types in field type groups
• #3526384: [PP-1] Make the titles for the field creation flow more consistent and communicate that it is a multipage form
• #3526385: [PP-1] Make field types and field groups distinguishable

the fourth point we touched today we've already opened another followup #3500553: Add media reference to the same field type group as file and image, it is about the question where to place the media field type and the potential confusing of the naming of the group that is containing the file and image field type ([in the same vein is #2862458: [META] Once media is enabled, having the File, Image and Media reference fields all listed is confusing raised in #11). and it has to be pointed out that #3397711: Move label and machine name fields to the field config edit form is also important in the context with this issue.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

Oops, I updated the wrong issue. Back to NW.

Added two screenshots so that they can be used in the to be updated issue summary. and i also adjusted the the issue title to the updated MR title, after the issue is not only about the descriptions but also about the labels. and the draft status got removed from the MR as well since all the changes are in and tests are passing thanks to @benjifisher

added before screenshots for selection list and reference and also added before and after screenshots for the first step to illustrate the change there (removing the mention of the concept of field as well as the periods at the end as well as the general streamlining of the descriptions)

I have added a change record. The automated tests pass. @rkoller and I have updated the issue summary. I think this issue is ready for review.

I am adding credit for @tstoeckler from #3524141: Adapt field type labels after switch to multi-step field creation. (Thanks to @rkoller for linking that issue to this one.)

I am adding credit for the users who contributed to #2930446: [PP-1] Improve field description texts for fields provided by core, which was closed as a duplicate of this issue.

I am giving credit for the related issue #3514939: Better help text for Date and Time Field.

I’ve demo’ed the current state of the MR at the weekly lean coffee table call from the Drupal User Group Munich on Tuesday. For the record the attendees were @drubb, @franz-m, @jurgenhaas, and @martin mayer - most experienced longtime backend developers). All in all, the first impression was a good one, an improvement over the current state. They had a few comments on certain field types and groups we’ve taken a look at, in no particular order:

• On the first step in the dialog modal, with the list of field types and groups, they commented that some field types might be placed more prominently, for example finding the link field type close to the end felt surprising - it was considered an important and often used field type, and with more additional field types listed it could get easily missed.
• In regard to the description of the group for Formatted text “…with option to assign text editor”, the with “option to assign” sounded odd and off for none native english speakers.
• Looking at the descriptions for the three field types within the Formatted text group their first remark was about the order of the descriptions.
  • They considered the detail about, if a field type is single row or multi row the most important detail, instead efficient storage was the first bullet point on the field type for short text.
  • Even though the group title is formatted text, short is explicitly mentioning that you have certain formatting options, the other two don’t have that mention. By explicitly naming it for one field type , the indirect assumption/conclusion is that it is not available on for the others.
  • Aside reconsidering the weighing of bullet points for the different field types by importance, they also suggested to reconsider the grouping of text related field types. Instead of going with Plain text and Formatted text, the suggestion was as already mentioned to make the single and multi row aspect more prominent by grouping by single row and multiple row.
• In regard to the description “Maximum values depend on the system” on the integer number field type, attendees have asked, where would it be possible to find that kind of information if it is mentioned here? A direct pointer is sort of missing.
• in the File upload group it was confusing to see the example of jpeg/png/webp/gif for the file as well as the image field type.
• Within the Reference group, why the “Other” field type label? It was considered confusing and sort of ambiguous.
• On a related note in general it would be helpful to provide clear and brief instructions for media/file/image when to use which

and while writing up the summary in the previous comment i've also noticed one other detail, for consistency reasons it might be worth a thought moving the help text on the field upload group on the second step right before the field types instead of after them, after we've enabled help text on for example the selection list group right before the field types.

I’ve demo’ed the current state of the MR at the monthly NWDUG meetup last Tuesday. For the record the attendees I am aware of their nickname on d.o were: @asherry, @bernardm28, @dydave, @h2cm, @mr_scumbag, and @philipnorton42. All in all, the first impression was also a good one, an improvement over the current state. They had a few comments on certain field types and groups we’ve taken a look at, in no particular order:

• On the first step the hyphenation used on the descriptions was considered distracting and making it harder to skim
• It was suggested to move the bullet point Recommended for to the top of the bulleted lists. It was argued that what a field type is recommended for is the most important information people are interested in, and they could then still read on in case they want to know more in-depth information.
• In regard to the bullet point Efficient storage on for example short plain text it was asked does that imply that the other ones listed are not efficient then?

At #3527306: Drupal Usability Meeting 2025-06-13, we continued work on this issue. For the record, the attendees at the usability meeting were @benjifisher, @rkoller, and @simohell.

Aside the commit with the discussed changes I've pushed we had four more points that are probably potential followups mostly:

• An option also to change the order of field types and groups in the first step
• Could it be managed in a dynamical manner to asses and display the maximum value for an integer field type
• Move the media description same as the file upload description to a summary
• Enable the addition of links to the summary line in yaml files

Clarification: one of the points in Comment #54 is

Enable the addition of links to the summary line in yaml files

That refers to text like the following:

Formatted text fields allow HTML markup. The field can be configured to allow one or more of the configured text formats.

It would be helpful to add a link to /admin/config/content/formats (the filter.admin_overview route). Unfortunately, it is technically difficult to add that link since the text is part of core/modules/text/text.field_type_categories.yml.

I am adding credit for the users mentioned in Comment #53.

I added a couple of commits, implementing field_type_category_info_alter:

1. The additional text for the file_upload group should only appear when the media module is enabled, so it cannot be in a static YAML file. It also needs a link to the help page if the help module is enabled.
2. At the usability meeting, we agreed that it would be good to add a link to the summary text for the formatted_text group. The most reliable way to generate the link is with PHP code, using the route name instead of the path.

I am adding credit for the users mentioned in Comment #51.

@Emma Horrel:

On #3526383: [PP-1] Add the option to customize the order of field types in field type groups (postponed on this issue), you asked,

Following up on a suggestion to do user testing on this. To design a test I would need to know:
• Type of Drupal user likely to use this functionality (and therefore impacted by a change to the interface)
• Typical scenario in which the user would encounter this interface (e.g. when would they need/want to change the order of fields types in field type groups?)
• Desirable outcome from the scenario and problem the change in interface has addressed (e.g. we want to ensure the Drupal user can distinguish between the field types and field groups because not being able to do so would result in [what are the tangible negative consequences of the problem not being addressed])
...

For this issue,

• A site builder, creating a new site or adding features to an existing site, will use this functionality. We have to consider both experienced users and less experienced ones. Experienced users are more interested in completing the task efficiently. Less experienced users (including those who do not have a lot of technical knowledge) need more guidance in deciding which field type to use.
• The scenario where this issue comes up is when adding a new field to a content type (or a taxonomy term, paragraph type, or other entity type).
• This issue aims to help less experienced users. The updated text should help them choose the right type of field without having too much trial and error.

@rkoller has brought up this issue at meetups. Even fairly experienced users are not aware of some of the information that we have added while working on this issue. See Comments #51 and #53 on this issue.

P.S. I added this comment during #3536866: Drupal Usability Meeting 2025-07-25. Also present: rkoller and simohell.

I participated in a usability review of the proposed changes to the Add field modal at DrupalCamp Colorado 2025 with fellow Drupal contributors matthews, treevis and timurtripp. Please add them as contributors.

Overall, we think this is a good improvement over the existing field descriptions. We find them to be more user friendly and like the updated formatting starting with an active verb.

There are some revisions we recommend,

* Reference
** Proposed description contains confusing jargon. Rephrase it to “Reference other content”
* Number
** Proposed description is redundant. Simplify it to “Numeric value”
* File upload
** Proposed description is confusing. Simplify it to “Upload any type of file”
* Link
** To be consistent with other field descriptions, rephrase the description to “Store a URL, with an output text option”

Usability review

We discussed this issue at #3538054: Drupal Usability Meeting 2025-08-01 and #3539211: Drupal Usability Meeting 2025-08-08. Those issues will have a link to a recording of the meetings.

For the record, the attendees at both usability meetings were @benjifisher, @rkoller, and @simohell.

We’ve discussed the changes proposed in #70

Reference other content

we went with the suggestion even though referring to just content is a bit imprecise, because in the field settings you are able to select content but also configuration entities for referencing. going with something like “entity” or “component” would also be too abstract, jargony, and/or expressionless. but we moved the detail about content and configuration to the second step. we added a second bullet point to the “other” option Any content or configuration entity could be referenced - that way things are communicated. out of the scope for this issue, we also came up with one or two potential followup issues:

1. if one of the reference presets, content, taxonomy term, or user is selected, disable the Type of item to reference select.
2. Add a description for every selected Type of item to reference option, to provide some context to the user

Numeric value

we’ve kept “numeric value like quantity or price” for now. reducing it to just “numeric value” felt redundant, but with the examples it aligns with the pattern used on plain text and formatted text that provided examples as well.

Upload any type of file

we didn’t know how we ended up on Create media type with the ability to upload assets, it was sort of building on the help text on the second step of the media field type and the file upload group. So we reverted it back to the initial variant: Upload any type of files, which is using the plural of the noun file.

Store a URL, with an output text option

we’ve considered store a url(we used that on our own suggestion as well) and output text option imprecise. our new suggestion would be A URL or internal path, with optional link text that way it communicates you can either enter external or internal link and it is also communicated that you also have the option to add a link text.

> numeric value like quantity or price

FWIW, the price thing could be confusing for people using commerce, because that has an actual price field type and you must use that, not numeric value. Unless that decides to make it part of the numeric value category, but that seems somewhat unlikely as it has more parts than just a number. Maybe use a different example, we often use numbers for a weight/order sorting field, both terms have multilple meanings as well, especially with translations.

@berdir:

That is a good point.

Both the commerce module and the physical module (Physical Fields) define their own field categories and put their fields under those categories. I disagree with that decision, but I do not know if I can persuade them to change.

During the usability meeting, we thought that many users would not think that "number plus unit" would be under the Number category, so we wanted to give an example to suggest that. The core fields are suitable for simple uses: in addition to the numeric value stored per field instance, the configuration can store a prefix or suffix to indicate a type of currency or a physical unit.

If we do not use price nor physical unit, in order to avoid confusion with those two contrib modules, then what else can we use as an example? I do not think that weight gets the point across. Do you have any other suggestions?

Reference #69 happy to test the changes with a less experienced site editor to gain perspective on this (in contrast to the views from more experienced builders as gathered by Ralf). Can anyone make me a test environment with the functionality that I can use to test with?

thank you! since you have ddev installed, do you also happen to have ngrok set up on your computer? if not just ping me. then the easiest most flexible approach also with regard to testing other issues in the future would simply be running and setting up a testing environment once with the following single line in the terminal in your Sites folder. during the install process you will have to confirm one or two times with y :

mkdir drupal11 && cd drupal11 && ddev config --project-type=drupal11 --docroot=web --database=mariadb:11.8 && ddev composer create-project joachim-n/drupal-core-development-project -y && ddev composer require drush/drush && cd repos/drupal && git remote add drupal-3370326 git@git.drupal.org:issue/drupal-3370326.git && git fetch drupal-3370326 && git checkout -b '3370326-refine-field-descriptions' --track drupal-3370326/'3370326-refine-field-descriptions' && cd .. && cd .. && ddev drush si --account-name=admin --account-pass=admin -y && ddev drush pmu toolbar && ddev drush en navigation datetime_range telephone media media_library -y && ddev share

copy the address you'll see in the ngrok share dialogue, should be something like https://4056a05eb8a3.ngrok-free.app. go to the login page of that address, i'll use the example address in the following, you'll have to replace with teh current:

https://4056a05eb8a3.ngrok-free.app/user/login

enter admin/admin and then go to

https://4056a05eb8a3.ngrok-free.app/admin/structure/types/manage/article

and let the tester press the Create a new field button.

If we close and open the MR, will we get a tugboat preview link?
That could be used to share a link to an environment where non-technical users can perform a test.

Usability review

We discussed this issue at #3540379: Drupal Usability Meeting 2025-08-15. That issues will have a link to a recording of the meeting.

For the record, the attendees at both usability meetings were @benjifisher, @rkoller, and @simohell.

We've agreed to the concern raised by @berdir in #72. Aside the concepts covered in the commerce module there are also the ones used in the physical fields module added by @benjifisher in #73. That narrowed down the potential candidates to use as examples further. In the end we've came up with the suggestion: radio frequency:

@berdir what do you think about that idea? would the new suggestion work for you or have you come up with another viable alternative? or does someone else has any thoughts or ideas in that regard? otherwise i would push the change up.

the other detail we've discussed is the overall consistency of the microcopy. while evaluating the raised concern in the commerce module it turned out that the difference between field types in core using the MR and field types in contrib module are significant.

none core related descriptions use periods at the end and or uses the term field or field type within the description, all things we've avoid.

the descriptions are missing bullet points and field groups could use help text on the second step which might be unapparent to maintainers. and in general we've tried to be educational and informative in the descriptions on the second step, and if appropriate providing examples and when best to use the particular field type.

over all we've agreed it would be a good thing to have at the very least a change record for this issue or ideally in addition to that create a follow up issue to work on a "style guide" for field types. so maintainers of contrib modules have coherent easy to find guidelines.

Completed a short test with one participant, non-technical, slightly familiar with Drupal but unfamiliar with the labels of field types.
Test required participant to make amendments to an article content type:
- to ensure they were able to add images when they published articles
- to ensure that when they published articles they could include teaser text
Successful completion of these tasks required selection of the image fieldtype and the plain text fieldtype.
Participant successfully completed both tasks indicating that the fieldtypes made sense. Reading the descriptions of the fieldtypes available, they said they did not know what varchar link text was, suggesting this term could be simplified

have you tested the state shown in the screenshot? based on the concern about the use of term varchar it looks like. but those strings in the screenshot are the old pre-MR strings. the description about the link field type for example is currently A URL or internal path, with optional link text not using the concept of varchar?

I would say if 'varchar' is no longer in the description following the MR, then that's clearer, no need to retest this, if varchar is removed then so is the point of confusion the participant experienced.

The Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".

This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.

Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.

The merge conflict is because this issue added a function to NodeHooks1.php, which was removed in #3511357: Clean up hook implementations in Node module. Following the recommendation in #3493453: [meta] Standardize and clean up hook classes in core (and the text file attached to that issue) I moved the implementation of field_ui_preconfigured_options_alter() to a new class, NodeFieldHooks.

I also moved the implementations of the same hook in the taxonomy and user modules to new classes (TaxonomyFieldHooks and UserFieldHooks). When the meta issue reaches those two modules, a little bit of the work will already be done.

i've noticed one problem, on the second step within the reference field group the description for the user looks broken (in EntityReferenceItem.php):

i was able to pull more changes on a second pull now the description for the user reference field type is correct again as well. apologies. setting it back to needs review.

I am adding credit for the contributors mentioned in Comment #70.

There was a request in the #ux Slack channel for a "technical" review. I tried my best. Couldn't help myself from also bikesheding on some of the new UI text. 😅 But I also tried to find any technical concerns.

This is mostly looking really good. Definitely some big improvements over what we've already got!

Disclaimer: I only reviewed the MR diff. I didn't try to apply locally, test in the UI, etc.

Thanks,
-Derek

I added #3550720: Refactor FieldUiJSTestTrait::fieldUIAddNewFieldJS() because it is brittle with just the changes to the test trait. I think that reduces the scope of this issue, making it easier to review. It also gives us a MR to prove that this change does not break anything.

If the child issue gets fixed, then we can remove (4) from the Proposed resolution of this issue.

We discussed this issue at #3550127: Drupal Usability Meeting 2025-10-10. That issue has a link to a recording of the meeting. I am giving issue credit here to the attendees at the usability meeting: benjifisher, jannafiester, joannajackson, rkoller, and simohell.

If you want more feedback from the usability team, a good way to reach out is in the #ux channel in Slack.

In preparation for the meeting, I went through all the text changes suggested or requested by dww, in the order they appear on the MR. I figured out where they appear in the UI and prepared the list below (copied from #3550127). During the meeting, we got through about half of the list: we got as far as Media. We will update the MR based on the discussion, but I do not plan to reply to each point on the MR. @dww, If you still object or have questions, then please either bump the thread (i.e., add another comment) or look at the recording. Or maybe it is simpler if you just resolve the threads where you are satisfied with our choice, and then I will reply to the unresolved threads.

With any luck, we should be able to finish the list at next week's meeting (2025-10-17). If so, then we will update the MR again and set this issue back to NR.

dww: There is something you may have missed by looking at the code, unless you also looked at the result in the UI. Each field-type category has an optional description: it applies to all the field types in the category. Under each field type, there is a bulleted list: these bullet points are used as differentiators. I think that might answer a few of the questions you had.

@dww reviewed the MR for #3370326: Refine labels and descriptions for field types. The review included some technical points and some suggestions for improving the interface text. The following sections summarize those suggestions. Each numbered list includes

1. The text in 11.x.
2. The text in the current MR.
3. The suggestion or comment from @dww.

File Upload > File

1. • For uploading files
   • Can be configured with options such as allowed file extensions and maximum upload size
2. • Downloadable files
   • Configure allowed file extensions, maximum upload size, and storage location
   • Examples: document (pdf, txt), audio (mp3), video (avi, mov), image (jpeg, png, webp, gif), etc.
3. Given we have a separate Image field type, why does the help text for this specifically recommend using a generic File to upload image file types?

Date and Time

1. Field to store date and time values.

• A date and/or time value
• The field types use different formats to store date and time in the database. All field types can be displayed in various ways using the Manage display tab.’

3. The 2nd sentence here is true of all fields, not just date_time, right? Do we want this here?

Formatted Text > Long text with summary

1. • Ideal for longer texts, like body or description with a summary
   • Allows specifying a summary for the text
   • Supports long text without specifying a maximum length
   • May use more storage and be slower for searching and sorting
2. • Extends Long text
   • Uses separate text areas (multiple rows) for input and summary
   • Summary defaults to a trimmed value of the long text
   • Recommended for content types that will be displayed in cards or teasers
3. I thought we’re trying to deprecate this field type. 😅 Not recommended for anything? 😆

I do not think this is a serious suggestion.

Telephone Number

To see this option, enable the telephone module.

1. This field stores a telephone number.
2. Store a telephone number with an output link option
3. Store a telephone number with an option to output as a link

Same concern as with email about what an "output link option" is.

Selection List > Text

1. • Values stored are text values
   • For example, ‘US States’: IL => Illinois, IA => Iowa, IN => Indiana
2. • Values (machine names) are text strings
   • By default, the Value is based on the Name
   • Example Name (Value): Apple (apple), Mango (mango), Black Cherry (black_cherry)
   • Example Name (Value): Most (0.9), Half (0.5), Some (0.3)
3. • Example: Apple (apple), Mango (mango), Black Cherry (black_cherry)

I know "0.9" is technically a "text string", but this seems confusing.

Selection List > Integer

The Name (Value) part of this is a bit confusing. Maybe just:

1. • Values stored are numbers without decimals
   • For example, ‘Lifetime in days’: 1 => 1 day, 7 => 1 week, 31 => 1 month
2. • Values are whole numbers
   • Example Name (Value): Disagree (-1), Neutral (0), Agree (1)
3. • Example: Disagree (-1), Neutral (0), Agree (1)

Reference > Content

1. An entity field containing an entity reference.
2. • Link content, such as Basic page or Article
   • Examples: related articles, next/previous links
3. • Link content

These node types may or may not exist on any given site. Is this a good idea?

Media

1. • Field to reference media. Allows uploading and selecting from uploaded media.
2. • Create media type with the ability to upload or link assets Maybe just this:
3. • Reference a media item, either a new upload or link existing

Date and Time

1. • Ideal when date and time needs to be input by users, like event dates and times
   • Date or date and time stored in a readable string format
   • Easy to read and understand for humans
2. • Human-readable string format
   • Input requires: date
   • Example: 2001-01-14T00:00:00
3. This is called a "Datetime", but "Input requires: date"? That’s confusing. Plus the example shows a time. What value is "Input requires: date" adding here? Less is more? Remove it?

Plain Text > Long Text

1. • Ideal for longer texts, like body or description
   • Supports long text without specifying a maximum length
   • May use more storage and be slower for searching and sorting
2. • Uses a text area (multiple rows) for input
   • No fixed maximum length
   • May use more storage and be slower searching and sorting
   • Recommended for longer texts, like body
3. I thought we’re generally moving away from a "body" field in core. Do we even need this line at all? This option is labeled "Long text". Doesn’t that imply it’s recommended for long text?

Number > Integer

1. • Number without decimals
   • For example, 123
2. • Whole numbers
   • Values are positive, negative, or zero
   • Maximum values depend on the system
   • Examples: 123, -123, 0, 3 (pi)
3. • Examples: 123, -123, 0

3 != pi. 🤓 😆 This is a weird example.

Isn’t the 2nd line ("Values are positive, negative, or zero") a definition of the 1st ("Whole numbers")? Do we need to say both?

Sorry, just double checked myself. "Whole number" is defined as a positive integer or 0.

Negative integers are not whole numbers. This new help text is definitely wrong. Perhaps the original text "Numbers without decimals" is the shortest, most clear.

@rkoller:

looking at https://www.britannica.com/dictionary/eb/qa/what-is-an-integer how about a small addition to yours and replace "Whole number" with "Number without decimal parts or fractions" instead?

Number > Float

In order to see this option, you have to remove the line

  no_ui: TRUE,

in core/lib/Drupal/Core/Field/Plugin/Field/FieldType/FloatItem.php.

1. • In most instances, it is best to use Number (decimal) instead, as decimal numbers stored as floats may contain errors in precision
   • This type of field offers faster processing and more compact storage, but the differences are typically negligible on modern sites
   • For example, 123.4 km when used in imprecise contexts such as a walking trail distance
2. • Numbers with decimal parts and exponents
   • Only limits provided by the system
   • Examples: 1.23, -1.23, 0.00e1, 1e100, 6.02214076e23
3. I don’t know what "Only limits provided by the system" means, using either new nor "old" eyes. 😆

Reference > ???

You only see this default value if a module declares a reference type to be "common" but does not provide a description. For testing purposes, you can remove the description from core/modules/node/src/Hook/NodeFieldHooks.php.

1. • An entity field containing an entity reference.
2. • A reference to a(n) @item
3. I know we don’t know what @item will be, but a(n) is a bit awkward. Again, not sure what to suggest.

Reference > Other

1. • An entity field containing an entity reference.
2. • Choose from all available options on the next screen
   • Any content or configuration entity could be referenced
3. Again, with "new eyes", WTF is a "configuration entity"? 😅 Not sure what to suggest here.

@rkoller:

we’ve simply used the terminology that is used in the next step on the field settings. if you take a look at the "type of item to reference" select then you see that the options are grouped by "content" and config". that was the reasoning why we went with "…content or configuration entity…"

Email

1. • Field to store an email address.
2. • An email address with an output link option
3. • An email address with an option to output as a link

I know we’re attempting to be terse, but trying to put on my "new eyes", I’m not sure I’d understand what "an output link option" is.

We discussed this issue at #3551491: Drupal Usability Meeting 2025-10-17. That issue will have a link to the recording of the meeting. For reference the attendees at the meeting were @benjifisher and @rkoller.

We've discussed the second batch of comments raised by @dww. The first batch was discussed during #3550127: Drupal Usability Meeting 2025-10-10 last week. The only noteworthy detail from todays discussion was that we've kept A reference to a(n) @item as is due to the fact that it is an extremely rare edge case most users will never run into and any effort trying to rephrase that string made things even worse. :/ I'll set the issue back to needs review

oh and thanks a lot to @dww for the in depth review. it surfaced quite a few rough edges!

push another small update to the MR. during the meeting on friday (#3551491: Drupal Usability Meeting 2025-10-17) we've changed one bullet point on the description of the datetime field. we've noticed some more inconsistencies with the descriptions of the other date and time field types. after a brief discussion on slack with @benjifisher we agreed on the folllowing changes:

adjust the second bullet point of datetime range to the new pattern used on datetime and change

Two Datetime values: start and end

to Choose either date and time, date only, or all day which are the settings on the field settings page.

while Input requires: date, time on the timestamp field type is simply wrong. the description of the input field for the timestamp states "Leave blank to use the time of form submission.". So the input is not required and we simply striked the bullet point

After #3550127: Drupal Usability Meeting 2025-10-10 and #3551491: Drupal Usability Meeting 2025-10-17, @rkoller and I updated the MR. We also replied here on the issue and on every open thread on the MR. (In Comment #91, I wrote, "I do not plan to reply to each point on the MR", but I changed my mind.

@dww, thanks again for your initial review. I hope you can find time for a second round.

The child issue #3550720: Refactor FieldUiJSTestTrait::fieldUIAddNewFieldJS() because it is brittle was just Fixed, and I have updated the MR here. Judging by line count, it is a small improvement: +381/-152 instead of +395/-175. But the part that is handled by the child issue is very different from the rest of the MR, so I think the actual simplification is more than the line count suggests.

I am also updating the issue summary, since the Proposed resolution section no longer has to mention the change that was handled by the child issue. While I am at it, I am updating the last paragraph of the Proposed resolution section based on recent updates to the MR. (To do: update the screenshot.)

updated the three after screenshots in the issue summary to reflect the latest changes

removed one slash too much from the path for the second picture... fixed now.

As mentioned before, I guess it would be a reasonable step to open up another follow up issue about creating some sort of style guide for the micro copy used on field types and field groups - basically the rules we've applied to the strings in this issue. otherwise the micro copy for any contrib field type will stand out in the interface. one individual example i ran into i've already filed an issue for is #3530845: Make the mermaid diagram field type presentation consistent by adding a description and an icon. to prevent that it might be good to a have central document about the general rules how those strings should look like that is easy to look up for maintainers. would it make sense to add a change record for this issue pointing to the to be created style guide?

Thanks for all the work in here since my last review!

Apologies I haven’t had a chance to re-review and RTBC. I’ve been super slammed, but just finished some intensive (transformational) work over the weekend, and should be able to circle back here in the next few days.

Re #98, sounds good. Perhaps a new CR is most clear. But what about editing the existing CR that introduced the new field UI stuff? On my phone, not easy to find right now.

Thanks again!
-Derek

yep i agree updating the existing CR might be good idea. and in regard to how to make developers in contrib aware of that change @jurgenhaas had the idea in todays lean coffee table to add tests to the drupal CI process. how many of those rules will be testable will be the question but things like to avoid periods at the end of the description of a field type or avoiding the term field in the description should be do able. and to sum up a brief follow up discussion with benji over in a thread in the ux channel on slack, he said phpcs might be the test to go with (the other suggestion from juergen was phpstan - he was uncertain about the right pick) and it would imply to add a new rule to the drupal coding standards. so it would definitely mean adding those tests in a follow up issue. and then to start with a test for "common" entity types (listed along with nodes, media, taxonomy terms) that do not have descriptions. other rules might be harder to test.

I updated the MR and fixed a merge conflict in a test file from #2409559: User should be able to identify required fields from field listing. See the extended commit message for details.

Thanks for addressing all my feedback!

I resolved nearly all of my own threads. I left 3 open that might still be viable.

The other threads are from lauriii and I don't feel comfortable resolving those.

I'm not going to formally RTBC this with 12 open threads. But it's definitely very close!

Note: latest pipelines are failing. If you rebase against 11.x, you'll get various fixes, including:

#3551373: [random test failure] ManageDisplayTest testFormatterUI() and testWidgetUI()
#3557585: Update to Composer 2.9.2

That will hopefully get us green pipelines again in here.

At #3562768: Drupal Usability Meeting 2025-12-19, we (@benjifisher and @rkoller) reviewed the recent comments on MR !11153 from @lauriii and @dww. I made some of the suggested changes and replied to others on the MR.

@dww, @lauriii:

At #3564044: Drupal Usability Meeting 2026-01-02, @rkoller, @simohell, and I agreed to accept the suggested changes. We changed "refer" to "reference" for grammatical reasons, and we decided to change the help text for email and telephone links instead of just shortening (or removing) it. Just now, I implemented those changes.

I think this is great now! Thank you so much @benjifisher, @rkoller, and @dww, as well as everyone else who has worked on this!

There are two commits that replace

  description: [
    new TranslatableMarkup("Choose any content or configuration type to reference on the next screen"),
  ],

with

  description: new TranslatableMarkup("Choose any content or configuration type to reference on the next screen"),

This has the effect of removing the bullet point for the "Other" option:

At the 2026-01-02 Usability meeting, we (@rkoller, @simohell, and I) considered this change and decided to keep the bullet point. Even though there is only one item in the list, we think it helps to be consistent with the other options:

So I have reverted those two commits, restoring the bullet point.

I am updating the "after" screenshots.

Great to finally get these updated, this is another nice incremental improvement to the field UI. Tagging as a highlight for 11.4.0.

Committed and pushed 73f1c59d389 to main and e22a8d8493b to 11.x. Thanks!